wiki-from-code

基于代码的 Wiki

产品当前工作方式的 Wiki：每项功能一个页面，列出其行为，以及代码与仓库中其他声明之间的差异。

输出文件夹：

• 默认：wiki/（位于仓库根目录）
• 或由调用技能或用户指定
• 所有路径均相对于输出文件夹
• 如果存在 features-catalog/ 目录 → 将其移至 features/.catalog/

差异是指代码与关于代码的声明（注释、文档字符串、开发者文档、API 规范、配置、基础设施、测试）不一致。它们可能有所不同、尚未实现、未被使用等。

模式

模式	适用情况
build	根目录的 README.md 中没有 features/ 或基线、没有 git，或用户要求重新构建
update	存在 features/ 和基线：只更改自基线以来代码发生变更的部分

步骤

- [ ] 1. Catalog
- [ ] 2. Indexes
- [ ] 3. Feature pages (one subagent per area)
- [ ] 4. Merge
- [ ] 5. Validate
- [ ] 6. Report

编写文件前，阅读 references/behaviors.md 和 references/layout.md。

规则

• 信息来源仅限仓库。
• 以当前代码为准，而非各种声明（注释、文档字符串、开发者文档、API 规范、配置、测试等）。将这些声明与代码不符或代码中不存在的内容仅写入 mismatches/，绝不可在功能页面中写成“应该”。
• 只写仓库中存在的路径。绝不可猜测或构造路径。
• 从产品和用户的角度命名领域和功能，而非从代码、技术栈、文件、类等角度命名。
• 领域术语（优先采用文档中的术语），每个概念在整个 Wiki 中使用一个术语。
• 随着对功能了解的深入，更新目录文件名和内容。
• 将功能视为端到端流程或用例来处理和描述，而不仅仅是代码中的“操作”。

1. 目录

在仓库上运行 catalog-features 技能，使用相同模式，输出文件夹为 features/.catalog/。

update：获取基线提交 > git diff --name-status -M {baseline}..HEAD > 相应处理已更新/已移除的文件。

2. 索引

编写任何功能页面之前，先编写 features/ 索引。

layout.md

3. 功能页面

每个领域安排一个子 Agent，并行执行（update：仅处理受影响的领域）。每个子 Agent 获取：该领域、其子领域和目录功能（YAML 文件）、允许访问的代码路径、features/.catalog/README.md 中的领域定义、上述规则、references/behaviors.md、references/layout.md。update 还需提供：该领域现有页面和差异，以及变更的功能。

子 Agent 对每项功能执行以下操作，从其目录链接开始：

1. 在目录功能 YAML 中：将实现文件添加到 code，并添加 tests。
2. 编写功能页面（layout.md › 功能页面）：先写描述，再写行为（behaviors.md）。
3. 对每处差异返回一条记录：注明差异类型及差异页面的所有章节（layout.md › 差异）。

子 Agent 仅在 features/ 和 features/.catalog/ 中编写该领域内的文件。发现目录功能缺失、命名不当或位置不当时 → 修复该领域的目录文件。该领域之外的内容（差异页面、目录 README、其他领域）→ 返回。

子 Agent 返回：新增、变更和移除的文件；差异（update 时还包括已解决的差异）；该领域之外的变更；未决问题；目录错误；领域定义中缺少的术语。

4. 合并

1. 在子 Agent 的负责范围之外应用其返回的更改，包括指向已重命名或移动页面的链接。领域缺少的术语 → 添加到 features/.catalog/README.md 中的领域目录。
2. 更新 features/ 中的每个 README.md，列出现在已有的功能页面。编写根目录 README.md：为每个文件夹（不包括 .catalog/）添加链接和用途，并注明基线提交。
3. 编写子 Agent 返回的不匹配页面。多个领域有相同分歧 → 合并为一个不匹配页面。
4. 同一概念有两个术语 → 保留一个，并修正使用另一个术语的页面。
5. update：移除已解决的不匹配项。
6. 在 mismatches/README.md 中编写不匹配项列表（layout.md › 不匹配项）。

5. 验证

Structure
- [ ] README.md is a sitemap with the baseline commit
- [ ] Every catalog feature has a feature page, and its feature YAML lists the rest of its implementation files in `code` and its tests in `tests`; `features/` mirrors the catalog's areas and subareas
- [ ] Every `links`, `code`, and `tests` path exists in the repo

Content
- [ ] Every feature page has a Description and at least one behavior under Behaviors; every behavior passes the check in [references/behaviors.md](references/behaviors.md)
- [ ] Every disagreement between code and claims has a mismatch page
- [ ] update: resolved mismatches removed; nothing left for deleted code

6. 报告

从何处开始。结果（update：新增、变更、移除的功能）。按类型列出不匹配项，按用户影响从高到低排序。目录错误。未决问题。

后续操作

• 与问题、需求、用户文档进行比较 → detect-product-mismatches
• 用 QA 语言解释某项功能 → qa-explain-behavior
• 为某项功能编写测试用例 → qa-write-test-cases