docs(readme): 收敛公开定位表述

Author: sincerely90

README.en.md

@@ -31,9 +31,15 @@
 
 **Aisee** stands for **AI-Enhanced Software Engineering**.
 
-Aisee Plugin is an AI software engineering plugin for OpenSpec workflows. It helps teams turn ambiguous ideas into reviewable requirements, UI content specifications, architecture context, schema-aware OpenSpec changes, implementation briefs, verification checks, and archive guardrails.
+Aisee Plugin is an AI software engineering plugin for OpenSpec workflows. It helps teams turn ambiguous ideas into reviewable requirements, UI content specifications, architecture context, OpenSpec changes, project memory, team knowledge guardrails, implementation briefs, verification checks, and archive guardrails.
 
-Aisee **does not replace OpenSpec**. OpenSpec remains the specification state machine and baseline source of truth. Aisee adds structured skills, schema packs, JSON context tooling, and engineering handoff rules around OpenSpec.
+Aisee **does not replace OpenSpec**. OpenSpec remains the specification state machine and baseline source of truth. Aisee adds structured skills, project memory, team knowledge, JSON context tooling, and engineering handoff rules around OpenSpec.
+
+## OpenSpec Boundary
+
+Aisee does not replace OpenSpec and does not maintain a second schema state machine. Aisee reads the current schema declaration only when handling OpenSpec changes, context packs, or schema pack checks; project memory and team knowledge remain guidance / guardrails.
+
+When Aisee handles OpenSpec artifacts, it acts only as a parser / checker / projector. `openspec validate` and `openspec archive` remain OpenSpec responsibilities.
 
 ## Why Aisee?
 
@@ -43,10 +49,10 @@ Aisee makes that context explicit:
 
 - clarify business requirements before implementation;
 - separate requirements, UI content, architecture context, and change planning;
-- create and complete OpenSpec changes with schema-aware guidance;
+- create and complete OpenSpec changes while reading required artifacts from the current schema;
 - keep OpenSpec as the only persistent specification source of truth;
 - generate machine-readable context packs for implementation, verification, and review;
-- constrain document-local numbering through schemas and skills to reduce invented or duplicated labels;
+- constrain document-local numbering through skills/templates to reduce invented or duplicated labels;
 - check whether artifacts, tasks, source maps, tests, and review evidence are closed before archive.
 
 ## Agile Delivery Model
@@ -198,7 +204,7 @@ codex plugin marketplace add AISEE-LAB/aisee-plugin --ref main
 codex plugin add aisee-plugin@aisee-plugin
 ```
 
-Check CLI-only state and marketplace setup hints:
+Check CLI and plugin content status:
 
 ```bash
 aisee plugin inspect --json
@@ -248,7 +254,7 @@ openspec init . --tools none --profile core
 openspec config profile core
 ```
 
-Schema packs come from the marketplace-installed plugin. `aisee schemas list/check` only reports project-installed schema state or source-checkout development schema state; it does not install schemas from the PyPI wheel.
+Schema packs come from the marketplace-installed plugin. `aisee schemas list/check` only reports project-installed schema state or source-checkout development schema state; it does not install schemas automatically.
 
 Check the project state again:
 
@@ -458,7 +464,7 @@ aisee knowledge promote-batch --curation <path> --team-path ../aisee-team-knowle
 Rules:
 
 - `aisee:knowledge` guides day-to-day CLI usage for onboarding, sync, retrieval, and promote.
-- `install`, `update`, and `promote-batch` are experimental. The PyPI CLI no longer provides local default scaffolding. PR automation and MCP service support are still unsettled.
+- `install`, `update`, and `promote-batch` are experimental. Team knowledge examples come from the marketplace plugin or external repositories; PR automation and MCP service support are still unsettled.
 - Query through the CLI instead of letting AI scan `knowledge/cards/**/*.md` directly.
 - Return a small number of bounded matches as implementation, review, or verification reminders.
 - Project-local `aisee/docs/reflect/knowledge-candidates/` remains a candidate area and is not promoted automatically.
@@ -477,10 +483,8 @@ plugins/aisee-plugin/
   references/        Cross-skill contracts and references
 bin/                 Local CLI entrypoint
 src/aisee_cli/       Aisee Python CLI
-src/aisee_plugin_assets/
-                     Minimal compatibility package; no bundled skills, schemas, references, or plugin metadata
-docs/                User workflow, best practices, architecture, plans, and review docs
-docs/architecture/   Architecture and historical decision docs
+docs/                User workflow, best practices, architecture, and release docs
+docs/architecture/   Architecture docs
 docs/plans/          Development plans
 docs/reviews/        Audit and review records
 scripts/             Development and release helper scripts
@@ -537,7 +541,7 @@ python scripts/smoke_release.py --with-pipx
 - OpenSpec is the canonical specification source.
 - Do not create parallel sources of truth in Aisee docs, CLI cache, or chat summaries.
 - Keep skills single-purpose: requirements, UI content, architecture, change planning, implementation bridge, verify, and archive guard.
-- Prefer schema-aware checks over hardcoded artifact assumptions.
+- When processing OpenSpec changes, read the current schema declaration instead of hardcoding app artifact assumptions.
 - Keep `SKILL.md` concise and put long rules in references or architecture docs.
 - Treat hardware and embedded workflows as dedicated extensions instead of forcing them into the app schema.
 
@@ -551,12 +555,12 @@ python scripts/smoke_release.py --with-pipx
 
 ### Ongoing Compatibility Governance
 
-- Keep CLI JSON, schema packs, context packs, marketplace plugin content, and skill contracts aligned with the Compatibility Policy; when a public contract changes, update tests, migration notes, and release notes together.
-- Add more real-world lifecycle fixtures beyond the app scenario, starting with quick-fix, quick-research, docsite, and infra-change.
+- Keep CLI JSON, project memory, team knowledge, context packs, marketplace plugin content, and skill contracts aligned with the Compatibility Policy; when a public contract changes, update tests, migration notes, and release notes together.
+- Use real-project dogfood to verify memory retrieval, context pack handoffs, and knowledge guardrails instead of expanding abstract flows just to cover schema types.
 
 ### Later
 
-- Expand cross-repository contract collaboration examples.
+- Improve project memory conflict hints, stale-entry policy, and low-context injection rules.
 - Tighten team knowledge remote sync, promote workflows, lifecycle management, and optional MCP wrapping.
 
 ## License

README.md

@@ -31,18 +31,15 @@
 
 **Aisee** 是 **AI-Enhanced Software Engineering** 的缩写。
 
-Aisee Plugin 是一个面向 OpenSpec 工作流的 AI 软件工程插件。它帮助团队把模糊想法整理成可审查的需求、UI 内容规格、技术架构上下文、schema-aware OpenSpec changes、实现交接 brief、验证检查和归档门禁。
+Aisee Plugin 是一个面向 OpenSpec 工作流的 AI 软件工程插件。它帮助团队把模糊想法整理成可审查的需求、UI 内容规格、技术架构上下文、OpenSpec changes、项目记忆、团队知识 guardrails、实现交接 brief、验证检查和归档门禁。
 
-Aisee **不替代 OpenSpec**。OpenSpec 仍然是规范状态机和 baseline 事实源。Aisee 在 OpenSpec 周围补充结构化 skills、schema packs、JSON context tooling 和工程交接规则。
+Aisee **不替代 OpenSpec**。OpenSpec 仍然是规范状态机和 baseline 事实源。Aisee 在 OpenSpec 周围补充结构化 skills、project memory、team knowledge、JSON context tooling 和工程交接规则。
 
-## Schema Capability Boundary
+## OpenSpec Boundary
 
-Aisee CLI 现在按当前 schema 声明工作，而不是把 `aisee-app-spec-driven` 当作隐藏默认模型：
+Aisee 不替代 OpenSpec，也不维护第二套 schema 状态机。只有在处理 OpenSpec change、context pack 或 schema pack 检查时，Aisee 才读取当前 schema 声明；project memory 和 team knowledge 始终只是 guidance / guardrails。
 
-- schema 必须显式声明 `capabilities`、artifact `requiredness`、`na_requires_reason`、`apply.tracks` 和 `archive.tracks`；
-- CLI 只做 parser / checker / projector，不根据 artifact 名称猜 app 语义；
-- `source-map.md`、contracts 和领域证据都只在 schema 或 capability 明确声明时参与门禁；
-- `openspec validate` / `openspec archive` 仍由 OpenSpec 负责，Aisee 只消费证据和输出补充风险。
+当 Aisee 处理 OpenSpec artifacts 时，它只做 parser / checker / projector；`openspec validate` / `openspec archive` 仍由 OpenSpec 负责。
 
 ## 为什么需要 Aisee？
 
@@ -52,10 +49,10 @@ Aisee 的目标是让这些上下文显式化：
 
 - 在实现前澄清业务需求；
 - 分离需求、UI 内容、技术架构和 change planning；
-- 以 schema-aware 的方式创建和补齐 OpenSpec changes；
+- 创建和补齐 OpenSpec changes，并按当前 schema 读取必要 artifacts；
 - 保持 OpenSpec 作为唯一持久规范事实源；
 - 为实现、验证和审查生成机器可读的 context pack；
-- 用 schema 和 skill 约束文档内编号，减少临时发明和重复命名；
+- 用 skill/template 约束文档内编号，减少临时发明和重复命名；
 - 检查 artifacts、tasks、source-map、测试和 review evidence 是否闭环。
 
 ## 敏捷开发模型
@@ -207,7 +204,7 @@ codex plugin marketplace add AISEE-LAB/aisee-plugin --ref main
 codex plugin add aisee-plugin@aisee-plugin
 ```
 
-检查 CLI-only 状态和 marketplace 提示：
+检查 CLI 与插件内容状态：
 
 ```bash
 aisee plugin inspect --json
@@ -257,7 +254,7 @@ openspec init . --tools none --profile core
 openspec config profile core
 ```
 
-Schema packs 来自 marketplace-installed plugin。`aisee schemas list/check` 只报告项目已安装 schema 状态或开发期源码 schema 状态；不会从 PyPI wheel 安装 schema。
+Schema packs 来自 marketplace-installed plugin。`aisee schemas list/check` 只报告项目已安装 schema 状态或开发期源码 schema 状态；不会由 CLI 自动安装 schema。
 
 再次检查项目状态：
 
@@ -466,7 +463,7 @@ aisee knowledge promote-batch --curation <path> --team-path ../aisee-team-knowle
 使用原则：
 
 - `aisee:knowledge` 负责引导这些 CLI 的日常使用，降低初始化、同步、检索和 promote 的门槛。
-- `install`、`update` 和 `promote-batch` 是实验性能力；本地默认 scaffold 不再由 PyPI CLI 提供。PR 自动化和 MCP 服务仍未稳定。
+- `install`、`update` 和 `promote-batch` 是实验性能力；team knowledge 示例来自 marketplace plugin 或外部仓库。PR 自动化和 MCP 服务仍未稳定。
 - 通过 CLI 查询，不让 AI 直接扫描 `knowledge/cards/**/*.md`。
 - 只返回少量带边界的 matches，作为实现、review 或 verify 的提醒。
 - 项目内 `aisee/docs/reflect/knowledge-candidates/` 仍是候选区，不自动进入 team knowledge。
@@ -485,10 +482,8 @@ plugins/aisee-plugin/
   references/        跨 skill contracts 和 references
 bin/                 本地 CLI 入口
 src/aisee_cli/       Aisee Python CLI
-src/aisee_plugin_assets/
-                     最小兼容 package；不再携带 skills、schemas、references 或 plugin metadata
-docs/                用户 workflow、最佳实践、架构、计划和 review 文档
-docs/architecture/   架构与历史决策文档
+docs/                用户 workflow、最佳实践、架构和发布文档
+docs/architecture/   架构文档
 docs/plans/          开发计划
 docs/reviews/        审计和 review 记录
 scripts/             开发和发布辅助脚本
@@ -545,7 +540,7 @@ python scripts/smoke_release.py --with-pipx
 - OpenSpec 是 canonical specification source。
 - 不在 Aisee docs、CLI cache 或聊天总结中创建平行事实源。
 - Skill 保持单一职责：需求、UI 内容、架构、change planning、implementation bridge、verify、archive guard。
-- 优先使用 schema-aware 检查，而不是硬编码 artifact 假设。
+- 处理 OpenSpec change 时读取当前 schema 声明，不硬编码 app artifact 假设。
 - `SKILL.md` 保持精简，长规则放到 references 或 architecture docs。
 - 硬件和嵌入式流程作为专用扩展处理，不强行套入 app schema。
 
@@ -559,12 +554,12 @@ python scripts/smoke_release.py --with-pipx
 
 ### 持续兼容治理
 
-- 继续按 Compatibility Policy 维护 CLI JSON、schema packs、context packs、marketplace plugin content 和 skill contracts；新增或破坏公开契约时同步补测试、迁移说明和 release notes。
-- 增加 app 场景之外的真实生命周期 fixtures，优先覆盖 quick-fix、quick-research、docsite 和 infra-change。
+- 继续按 Compatibility Policy 维护 CLI JSON、project memory、team knowledge、context packs、marketplace plugin content 和 skill contracts；新增或破坏公开契约时同步补测试、迁移说明和 release notes。
+- 用真实项目 dogfood 验证 memory 检索、context pack 交接和 knowledge guardrails，不为了覆盖 schema 类型扩展抽象流程。
 
 ### 后续
 
-- 扩展跨仓库契约协作示例。
+- 完善 project memory 的冲突提示、过期策略和低上下文注入规则。
 - 收敛 team knowledge 的远程同步、promote workflow、生命周期管理和可选 MCP 包装。
 
 ## License

docs/compatibility-policy.en.md

@@ -90,8 +90,8 @@ The following are public contracts:
 
 - `plugins/aisee-plugin/.codex-plugin/plugin.json`, `plugins/aisee-plugin/skills/`, `plugins/aisee-plugin/references/`, and schema pack directories in the GitHub repository remain loadable by the Codex marketplace plugin;
 - the core / optional / knowledge / hardware layering defined in `plugins/aisee-plugin/references/skill-taxonomy.md`, including the core set of 10 workflow skills;
-- `aisee plugin inspect --json` returns stable status and setup hints in CLI-only installs;
-- the PyPI wheel only promises CLI capabilities; skills, references, schema packs, team knowledge templates, and plugin metadata are distributed through the marketplace plugin or external repositories.
+- `aisee plugin inspect --json` returns stable status and setup hints in PyPI / pipx installs;
+- the PyPI / pipx channel only promises CLI capabilities; skills, references, schema packs, team knowledge templates, and plugin metadata are distributed through the marketplace plugin or external repositories.
 
 Breaking changes include renaming the plugin, removing the Codex manifest, breaking the marketplace plugin root layout, or changing the core workflow skill set.
 
@@ -116,7 +116,7 @@ The following are public contracts:
 - the planning-doc frontmatter contract and the read-only diagnostics exposed through `aisee doctor --json` and `aisee context pack --json`;
 - the basic semantics of planning-doc fields such as `status`, `doc_type`, `source_refs`, and `change_refs`;
 - `resolve_project_root` preferring the nearest Aisee/OpenSpec project marker before falling back to the Git top-level;
-- release smoke checks for CLI-only wheels, marketplace setup hints, the public command surface, and root-resolver fixtures.
+- release smoke checks for the PyPI / pipx CLI, marketplace setup hints, the public command surface, and root-resolver fixtures.
 
 Breaking changes include turning planning-doc diagnostics into write commands or changing root resolution so monorepo subprojects are silently interpreted as repository roots.
 

docs/compatibility-policy.md

@@ -90,8 +90,8 @@
 
 - GitHub 仓库中的 `plugins/aisee-plugin/.codex-plugin/plugin.json`、`plugins/aisee-plugin/skills/`、`plugins/aisee-plugin/references/` 和 schema pack 目录保持可被 Codex marketplace plugin 加载；
 - `plugins/aisee-plugin/references/skill-taxonomy.md` 中 core / optional / knowledge / hardware 分层，以及 core 10 skill 集合；
-- `aisee plugin inspect --json` 在 CLI-only 安装中返回稳定状态和 setup hint；
-- PyPI wheel 只承诺 CLI 能力；skills、references、schema packs、team knowledge templates 和 plugin metadata 通过 marketplace plugin 或外部仓库分发。
+- `aisee plugin inspect --json` 在 PyPI / pipx 安装中返回稳定状态和 setup hint；
+- PyPI / pipx 通道只承诺 CLI 能力；skills、references、schema packs、team knowledge templates 和 plugin metadata 通过 marketplace plugin 或外部仓库分发。
 
 破坏性变更包括重命名插件、移除 Codex manifest、破坏 marketplace plugin root 布局，或改变 core workflow skill 集合。
 
@@ -116,7 +116,7 @@
 - 普通 planning docs 的 frontmatter 合同和 `aisee doctor --json` / `aisee context pack --json` 的只读 diagnostics；
 - `status`、`doc_type`、`source_refs`、`change_refs` 等 planning doc 索引字段的基本语义；
 - `resolve_project_root` 以最近的 Aisee/OpenSpec project marker 优先，再 fallback 到 Git 顶层的语义；
-- release smoke 对 CLI-only wheel、marketplace setup hint、公开命令面和 root resolver fixture 的检查重点。
+- release smoke 对 PyPI / pipx CLI、marketplace setup hint、公开命令面和 root resolver fixture 的检查重点。
 
 破坏性变更包括把 planning doc diagnostics 变成写入命令，或改变 root resolution 使 monorepo 子项目误读为仓库顶层。
 

docs/plugin-marketplace.en.md

@@ -13,7 +13,7 @@ PyPI / pipx
   -> provides project-local JSON context tooling, OpenSpec companion checks, project memory, team knowledge, and version/distribution governance commands
 ```
 
-Marketplace installation does not install the `aisee` CLI. PyPI / pipx installation does not install bundled skills, schema packs, references, or team knowledge templates.
+Marketplace installation does not install the `aisee` CLI. PyPI / pipx installation provides only the CLI; skills, schema packs, references, and team knowledge templates come from the marketplace plugin.
 
 ## Codex Install
 
@@ -79,7 +79,7 @@ Recommended relationship:
 Not recommended:
 
 - letting the CLI write Codex marketplace or plugin cache state;
-- bundling a second copy of skills, references, schema packs, or team knowledge templates in the PyPI wheel;
+- copying skills, references, schema packs, or team knowledge templates into the PyPI / pipx distribution channel;
 - treating marketplace listings as project sources of truth for OpenSpec, schemas, source-map, or team knowledge;
 - forcing Codex marketplace fields onto Claude / Cursor metadata.
 
@@ -91,7 +91,7 @@ The following are Aisee public contracts:
 - Codex manifest `skills` points to a loadable skills directory;
 - Codex marketplace setup commands;
 - base JSON semantics for CLI `status`, `issues`, `summary`, `meta`, and setup hints;
-- public legacy commands return stable deprecation/blocker JSON during migration instead of silently writing old wheel assets.
+- public legacy commands return stable deprecation/blocker JSON during migration instead of silently writing old content assets.
 
 The following are not stable:
 
@@ -113,4 +113,4 @@ Also confirm manually:
 
 - `plugins/aisee-plugin/.codex-plugin/plugin.json` has no unsupported fields;
 - `.agents/plugins/marketplace.json` points at the `./plugins/aisee-plugin` plugin root;
-- `pipx install aisee-plugin` validates the CLI only and does not assume plugin content exists inside the wheel.
+- `pipx install aisee-plugin` validates the CLI only and does not assume PyPI / pipx installation also provides plugin content.