wiki · diff
git:20261030.1326a85 to git:20261030.ed65f43
16 added, 18 removed. Audit A to A.
---
name: wiki
- description: 独立处理开发 Wiki 的阅读、创建、维护、同步与检查，用户或 agent 均可调用。依据当前代码、配置和工程脚本讲清架构、业务实现、部署与运维，检查来源、新鲜度和文档结构。不作为其他技能执行中或收尾时附带的维护步骤，不承担产品确认、代码修复或发布。
+ description: 为代码仓库生成并维护项目 Wiki（项目文档、知识库、代码导读、架构说明、模块说明、开发指南），既供 Agent 按目录查阅，也供人阅读；Markdown 提交在仓库 docs/wiki/，以当前代码为准、关键结论附源码来源，目录与正文按项目语言生成。用户或 agent 均可独立调用。不处理飞书知识库（lark-wiki），也不是 zread CLI 的 .zread/wiki 产物；不修复代码、不发布。
user-invocable: true
---
- # 项目开发知识
-
- 为开发人员和编码 Agent 讲清项目如何工作、如何修改。以代码、配置和工程脚本为主，解释用途、流程、条件、异常、依赖及修改影响；关键结论附来源文件，必要时定位符号。已有目录、术语、人工解释和检查约定优先。
+ # 项目 Wiki
- Wiki新增文件和文件夹沿用项目现有文档的命名语言与风格，不根据本次对话语言自行翻译；`modules`、`README.md`、`reviews.json`、`wiki.config.json` 保留固定名称。已有路径不自动重命名，模板内部英文名称不决定输出文件名；命名与类型配置见 `references/templates.md`。
+ 为开发人员和编码 Agent 讲清项目如何工作、如何修改。产物是 `docs/wiki/` 下的 Markdown：`catalog.json` 是目录真源，`README.md` 是入口和导航，每页开头一行摘要、页尾列出来源。
## 任务入口
- Wiki 可由用户或 agent 作为独立任务调用，不限定调用者。按本次操作确定范围：阅读／检查保持只读，创建／维护／同步才修改相关内容。其他技能不调度 Wiki，也不在执行期间或收尾时夹带 Wiki 更新；参考已有文档不构成维护任务。
-
- | 任务 | 按需读取 |
+ | 任务 | 做法 |
|---|---|
- | 阅读或解释 | 项目知识入口；已配置时先按 `references/freshness.md` 检查相关模块，再核实关键来源 |
- | 初始化 | `references/initialization.md` 确定覆盖与模块，`references/templates.md` 选择布局 |
- | 维护或同步 | 读取相关正文和实际代码 diff，按下方流程更新；Git比较范围见 `references/tools.md` |
- | 机械检查 | `references/tools.md`；新鲜度、复核声明与候选检查见 `references/freshness.md` |
+ | 生成 | 按 `references/generate.md`：`scan` → 规划 `catalog.json` 并请用户确认 → 逐页生成 → 写 README 导航 → `check` |
+ | 阅读 | 先读 `README.md` 与 `catalog.json`，按 `summary` 选页；关键结论按页面来源回到代码核实。只读，不顺带修改 |
+ | 更新 | 读受影响页面全文和实际代码 diff，按 `references/writing.md` 的“修订”改原文；目录变化同步 catalog；最后 `check` |
+ | 检查 | `check` 报告链接、锚点、catalog 与文件一致性、摘要和语言问题；命令见 `references/tools.md` |
- ## 编写与复审
+ 没有 `catalog.json` 的旧版 Wiki 继续按 `references/freshness.md` 与 `references/tools.md` 的旧流程维护；新结构的迁移在后续版本提供。
- 1. **定范围**：读取项目指令、现有知识及相关未提交内容，确定要维护的模块和文件。实质性多模块任务在宿主可委派时按 `references/module-workflow.md` 分工编写与独立复审；运行中的子Agent合计最多3个，编写、复审及返工共用上限，由主Agent排队调度。小修正或无委派工具时自行完成，说明实际复核方式。
- 2. **读代码、写知识**：按 `references/content-verification.md` 追真实入口、调用方和配置覆盖，直接修正错误原句、表格或步骤。已有映射时可用 `mapping --document` 直接查看来源覆盖、缺口和歧义，命令见工具参考。
- 3. **复审与整合**：核对代码依据、遗漏条件、范围扩大及操作风险；按正文核对方法通读受影响整页，将新增内容融入合适章节，整理过时描述、重复内容及格式，统一跨模块概念与重复结论。读回最终正文和 diff，运行项目约定检查，仅为实际核对范围保存复核记录，交付文档、关键变化与必要技术缺口。
+ ## 写作原则
- 正文按当前实现编写，不等待PRD或产品批准；文档/注释不同则核实执行路径，必要时简注差异。测试代码不等于测试已通过，部署脚本不等于已上线。已知边界、未运行与建议在相关位置说明，待确认项只留查证后仍影响开发或本次操作的技术问题。
+ 1. **以代码为准**：追真实入口、调用方和配置生效链；文档与代码不一致时按实际执行路径写。测试代码不等于测试通过，部署脚本不等于已上线。
+ 2. **关键结论附来源**：就近链接源码文件和行号，页尾来源与 catalog `sources` 一致。
+ 3. **语言一致**：确定顺序为用户指定 > 已有 catalog > `scan` 建议 > 对话语言。正文、标题、图中文字用 `language`，新文件名用 `pathLanguage`，代码标识符和命令原样保留。派发子 Agent 时必须传入 `language`。
+ 4. **按开发问题组织**：一页回答一类问题，不照搬目录，不用文件清单代替解释；推断就近标注。
+ 5. **修订而非追加**：更新时改错误的原句，把新知识融入对应章节，不在末尾追加补丁段。
- 维护任务中完成范围内文档，不自动修复代码、部署、读取凭据或改造CI。机械通过不证明知识语义正确；技能不常驻监听，新鲜度触发取决于项目实际接入。行为评估见 `references/evaluation-cases.md`，日常任务无需逐项执行。
+ 脚本只做扫描和机械检查，不调用模型；`check` 通过不证明正文语义正确。Wiki 任务只修改文档，不修改代码、部署或读取凭据。其他技能不调度本技能。