wiki

Wiki 生成

读取一个代码仓库，然后生成一组相互关联的文档页面，说明代码的功能及各部分如何协同工作。输出为 droid-wiki/ Markdown 文件目录，并通过 droid wiki-upload 上传到 Factory。

1. 调研代码仓库

开始编写前，先建立对代码库的整体认识。调研分为两轮：结构扫描和深入代码扫描。

第 1 轮：结构扫描

阅读以下文件（如果存在）：

• README.md、AGENTS.md、CONTRIBUTING.md——项目目标和约定
• package.json、Cargo.toml、go.mod、pyproject.toml——依赖项和脚本
• docs/ 目录——现有文档
• 入口文件（src/index.ts、main.go、app.py 等）——应用如何启动
• CI/CD 配置（.github/workflows/、.gitlab-ci.yml、Jenkinsfile、azure-pipelines.yml 等）
• 构建工具配置（webpack.config.*、vite.config.*、Makefile、build/、Gulpfile.* 等）
• Lint／质量配置（eslint.config.*、自定义 lint 插件、rustfmt.toml、.golangci.yml 等）
• 项目根目录和关键子目录的目录列表

梳理以下内容：

• 项目功能——用一到两句话说明项目的用途
• 主要子系统——代码库中的主要部分（例如 API 层、数据库模型、CLI、前端组件）
• 关键数据流——数据如何在系统中流动（请求 → 处理器 → 数据库 → 响应）
• 外部依赖——数据库、API、消息队列、第三方服务
• 构建和测试命令——如何构建、测试和运行项目

第 2 轮：深入代码扫描

结构扫描能发现目录名称和配置文件中显而易见的信息，深入扫描则能发现只有通过代码本身才能了解的功能、领域和能力。探查代码库中可揭示结构扫描遗漏主题的线索：

• 在常量文件中搜索功能开关名称——每个开关通常代表一项值得记录的独立能力
• 扫描前端路由定义和页面组件——每组路由都对应一项面向用户的功能
• 扫描 API 端点分组——每个控制器或路由器文件都代表一个领域
• 查看 src/features/、src/modules/、src/domains/ 或同类目录——目录名称和内容能揭示产品能力
• 扫描服务类、事件处理器和作业／Worker 定义——这些揭示了后台系统
• 检查名称不明显、且不属于常见顶层目录的领域专用目录

目标是找出 Wiki 应涵盖的完整主题列表。结构扫描搭建骨架；深入扫描则充实细节。像“分析”这样的功能可能没有自己的顶层目录，而是位于 src/features/analytics/ 中，或通过一组功能开关和 API 端点体现出来。

穷尽式子系统发现

完成两轮扫描后，遍历每个顶层源代码目录（以及其下一级目录），检查是否遗漏子系统。对于每个包含自身服务、模块或功能的目录，决定其级别：

• 第 1 级——大多数贡献者都会接触到的核心子系统。编写完整的独立页面。
• 第 2 级——重要但较为专门的子系统。编写较短的独立页面。
• 第 3 级——小众子系统或薄封装。在“其他子系统”页面中用一段话介绍，并提供目录路径。

小型仓库可能只需要几个领域页面。大型仓库则应根据代码库的实际情况创建足够多的页面。不要随意设定上限——覆盖范围应由代码仓库的实际结构决定。

容易遗漏的领域

扫描完源代码树后，请检查以下常被忽略的领域：

• 自定义 lint／分析规则 — 用于强制执行项目特定约定的插件或配置
• 自动化工作流 — CI/CD、机器人、定时任务、代码生成脚本
• CLI 或开发工具 — 内部工具、scripts/、tools/ 或 bin/ 中的脚本
• 测试基础设施 — 标准测试运行器之外的自定义测试框架、fixture 或自动化测试工具
• 多语言组件 — 如果仓库包含第二种语言的代码（例如 TypeScript 项目中的 Rust CLI），请将其记录下来

如果其中任何一项并非简单内容，就值得涵盖——可以单独成页，也可以作为相关页面中的一个章节。

调研输出

调研结束时，请生成一份调研上下文文档，作为简明摘要与子 Agent 共享。文档应包括：

• 仓库摘要 — 用 3-5 句话说明项目的用途、技术栈和整体结构
• 架构概览 — 主要组件及其连接方式
• 已发现主题 — 两轮扫描中发现的功能、系统、应用、包和基础构件的完整列表
• 关键模式 — 编码约定、错误处理模式、测试模式
• 术语表种子 — 扫描期间遇到的项目专用术语
• 目录与用途映射 — 源代码目录分别对应哪些主题

覆盖范围交叉检查

开始规划前，请对照两个独立的主题来源进行核查，确保没有遗漏：

来源 A：已发现主题。 第 1 轮（结构扫描）和第 2 轮（深入代码扫描）中发现的主题。这些主题包括无法对应到单个目录的横切功能（例如，跨越多个包的“大模型集成”，以及涉及前端、后端和 CLI 的“身份验证”）。

来源 B：目录枚举。 对于适用于仓库的每个视角，请运行 ls 查看对应源代码目录，并列出其中的每个子目录：

• 对于应用：列出 apps/（或仓库中的对应目录）下的每个目录
• 对于包：列出每个工作区包目录
• 对于功能：列出功能目录下的每个子目录（例如 src/features/、packages/frontend/src/features/，或仓库组织功能代码的其他目录）
• 对于系统：列出包含服务或模块代码的顶层源代码目录

对照核查： 合并两份列表。对于其中的每一项，请决定：

1. Wiki 页面 — 将该项列为计划页面（或页面中的一个章节）
2. 说明理由后跳过 — 明确说明有意排除该项的具体原因（例如“空目录——没有源文件”“已弃用——仅剩测试 fixture”“薄封装——已在父包页面中介绍”“内部工具——只有 3 个文件，不值得单独成页”）

已发现主题能捕捉目录无法体现的内容（横切关注点、逐渐显现的模式）。目录枚举能捕捉发现过程遗漏的内容（Agent 未在已阅读文件中遇到的功能）。两者结合可实现全面覆盖。

不允许默默遗漏。如果存在包含非简单代码的源代码目录，却没有对应的 Wiki 主题，这就是一个必须说明理由的缺口。

2. 规划目录结构

在编写任何正文前，先设计页面树。Wiki 内容分为三个层级：始终存在的页面、组织视角，以及条件性章节。

始终包含的页面

每个 wiki 都会按以下顺序包含这些页面：

1. overview/ — 按一个章节分组的介绍材料
   • index.md — 项目概览：项目的用途、使用者，以及快速链接
   • architecture.md — 系统架构，包含 Mermaid 图表
   • getting-started.md — 前置条件、安装、构建、测试和运行
   • glossary.md — 项目专用术语和领域词汇
2. by-the-numbers.md — 代码库统计快照（见下文）
3. lore.md — 代码库时间线和历史（见下文）
4. how-to-contribute/ — 如何在此代码库中开展工作
   • index.md — 任务领取、PR 流程、评审预期和完成定义
   • development-workflow.md — 分支、编码、测试、PR、合并周期
   • testing.md — 框架、模式，以及如何运行、模拟和覆盖测试
   • debugging.md — 日志、常见错误、故障排查手册
   • patterns-and-conventions.md — 错误处理、编码风格、横向关注点
   • tooling.md — 构建系统、代码检查工具、代码生成器、CI 工具（如果仓库的工具链本身就是产品，则将此项提升为顶级章节）

数据一览

创建顶级页面 by-the-numbers.md，以量化数据概览代码库。页面开头应注明“数据收集日期：[日期]”，让读者了解数据的时效性。

包含以下章节：

• 规模 — 按语言统计代码行数（使用 Mermaid 水平条形图）、源文件、测试文件和配置文件总数，以及单体仓库的包／模块数量
• 活动情况 — 每周／每月提交次数（近期趋势）、过去 90 天内变更最频繁的文件／目录（变更热点）
• 归因于机器人的提交 — 由机器人共同署名的提交所占百分比（例如 Co-authored-by: factory-droid[bot]、dependabot[bot]、github-actions[bot]、copilot[bot]）。由于 Copilot 等内联 AI 工具不会在 Git 历史中留下痕迹，这只是 AI 辅助工作的下限。请明确说明统计口径。
• 复杂度 — 按目录统计的平均文件大小、最长导入链，以及每个包导出的符号数量

使用 Mermaid xychart-beta（水平条形图）展示语言分布，以及其他适合可视化的统计数据。不要使用 Mermaid pie 图表——渲染器不支持。文件／目录列表请使用表格。

切勿纳入个人贡献者统计数据（顶级提交者、每人代码行数、排行榜）。数据一览页面应关注代码库，而不是人员。个人指标会引发有害的比较，不应出现在团队文档中。所有权映射由 maintainers.md 页面单独处理。

在其他页面中嵌入统计数据： 除此汇总页面外，也应在现有页面中穿插相关统计数据：

• 在 architecture.md 中列出语言分布
• 在 cleanup-opportunities/ 中列出变更热点（如果存在该章节）
• 在每个领域页面中列出子系统的文件数量、总线因子（独立提交者人数）和测试与代码的比例
• 在 reference/dependencies.md 中列出依赖项数量

Lore

顶层的 lore.md 页面，讲述代码库的演变历程。这是一段历史叙述，而非技术参考。它回答“这里发生过什么，发生在什么时候？”

与其他部分的界限：

• by-the-numbers.md = 当前快照（代码库如今的样子）
• lore.md = 时间线与历史（发生了哪些变化，何时发生）
• fun-facts.md = 轻松趣闻（隐藏彩蛋、有趣的发现）
• background/ = 技术决策依据（为什么会做出这些决策）

每个事件、时期和里程碑都必须注明日期或月份（例如，“2023 年 3 月”“2024 年第 4 季度”）。根据 git 提交时间戳、标签日期和文件创建日期推断日期。如果无法确定确切日期，则使用最早相关提交所在的月份。

请包含以下部分：

• 时期 — 将代码库历史划分为 3–8 个主要阶段，每个阶段都要有简短的叙述性说明和关键事件要点。根据 git 历史推断：标签日期、大型合并提交、贡献者模式、目录创建日期。例如：“TypeScript 迁移（2023 年 3 月至 8 月）：整个后端在 5 个月内从 JavaScript 重写为 TypeScript……”
• 历史最悠久的功能 — 经历最多次重构且仍在积极使用的代码或子系统。注明它们首次引入的时间，以及经历了多少次变更。
• 已弃用的功能 — 曾经构建、使用，后来被移除或替换的功能。从目录名称、README 提及、明显的 @deprecated 注解和已移除的路由中识别。功能是什么、何时引入、何时弃用，以及由什么替代。
• 重大重写 — 涉及大量文件的大型变更。说明原先是什么、由什么替代，以及发生时间。根据 git 历史推断（大型 PR、分支名称中包含“migration”或“rewrite”的分支）。
• 增长轨迹 — 代码库如何随时间扩展：何时添加了软件包或应用，以及 git log 中反映贡献者增长的信号。

推测： 如果提交记录未能明确说明变更背后的“原因”，请使用自然的保留措辞（例如“似乎是为了……”“很可能是因为……而替换”）。推测内容无需特殊格式。

组织视角

可以使用五种视角来组织代码库深入介绍。根据仓库的实际内容选择任意组合即可。至少需要一种视角。大多数仓库使用 2～3 种。features 视角尤为推荐——它是新工程师最直观的入门方式（“这个东西是做什么的？”）。即使是小型仓库，通常也有值得记录的、用户可见或开发者可见的功能。只有当仓库是用途单一、没有不同功能的库时，才跳过此视角。

概念	默认标签	也称为	适用情况
可部署单元	applications/	services/、apps/	仓库包含多个不同的运行时
内部构建模块	systems/	services/、modules/、subsystems/	无法映射到单个应用或包的架构组件
横向功能	features/	capabilities/、workflows/	跨多个系统的、用户可见或开发者可见的功能
工作区包	packages/	libraries/、crates/、modules/	包含值得单独记录的共享库的单体仓库
基础领域对象	primitives/	core-concepts/、domain-models/、entities/	出现在 3 个以上系统中的类型或概念（例如，session、user、message）

**选择标签：**沿用仓库自身的术语。如果仓库有 apps/ 目录，就将该部分命名为 apps/，而不是 applications/。如果仓库将相关内容称为“services”，就使用 services/。当仓库没有既有约定时，再使用默认标签。

归属规则：

• 根据仓库结构，将每个概念放在合适的位置。如果 Agent 逻辑位于 packages/droid-core，就将其记录在 packages 下，而不是 systems 下。
• systems 视角用于在 apps 或 packages 中没有自然归属的内容——涌现出的架构模式、跨包系统，以及横跨多个目录的基础设施。
• 不要在多个视角下重复内容。如果某项内容已在 packages 下记录，相关应用页面应链接到该内容，而不是重复描述。

识别各视角的经验法则：

• 如果有自己的入口点和部署流程，就是一个应用
• 如果是其他包会导入的工作区包，就是一个包
• 如果是具有内部逻辑和明确边界、无法映射到单个包的模块，就是一个系统
• 如果某个类型或概念出现在 3 个以上系统中，就是一个基础对象
• 如果理解它需要追踪多个系统或应用，就是一个功能

条件章节

调研仓库后，根据判断决定是否包含以下章节。不适用的章节可以跳过。

• api/ — 如果仓库提供 REST、GraphQL、WebSocket 或其他 API
• deployment/ — 如果部署流程并不简单（CI/CD、环境、回滚、基础设施）
• security/ — 如果存在重要的信任边界（身份验证、授权、机密、输入验证）
• background/ — 如果仓库有值得记录的历史（设计决策、陷阱或危险区域、迁移背景）
• how-to-monitor/ — 如果仓库作为服务运行，并配有日志、指标、追踪或告警基础设施
• cleanup-opportunities/ — 如果仓库存在死代码、积累的 TODO/FIXME、过大的文件或过时依赖。仅在确实有内容可报告时才包含（见下文）
• fun-facts.md — 彩蛋、起源故事、最早的代码、命名由来

如何监控

本条件章节介绍如何查看系统正在执行的操作。仅为配备日志记录、指标或追踪基础设施的服务型仓库生成此章节。库、CLI 工具或软件包不适用。

子页面：

• logging.md — 日志的去向、查询方法、日志级别和约定、结构化日志模式，以及如何添加新的日志语句
• metrics.md — 跟踪的指标、关键 SLI/SLO、可用的仪表板，以及如何添加新指标
• tracing.md — 分布式追踪设置、如何端到端追踪请求、跨度命名约定，以及如何为新的代码路径添加检测
• alerting.md — 现有告警、告警阈值及其依据、升级路径、已知的嘈杂告警，以及如何添加新告警

跳过仓库没有相应基础设施的子页面。如果只有一个子页面有内容，请将 how-to-monitor/ 合并为单个 how-to-monitor.md 文件，而不是创建目录。

清理机会

本条件章节列出可采取行动的维护工作。仅在扫描发现有意义的内容时生成。可包含的子页面：

• dead-ends.md — 没有任何内容导入的文件、导出项或模块。相当于代码中的鬼城。
• todos-and-fixmes.md — 汇总 TODO、FIXME 和 HACK 注释及其文件位置。包括最早的注释。
• complexity-hotspots.md — 最大的源文件、最深的嵌套层级或最复杂的函数。温和地提醒进行重构。
• dependency-freshness.md — 过时或无人维护的依赖项。仍在使用的最旧依赖项。

跳过没有发现问题的子页面。如果只有一个子页面有内容，请将 cleanup-opportunities/ 合并为单个 cleanup-opportunities.md 文件，而不是创建目录。

维护者

添加顶层 maintainers.md 页面，将子系统与熟悉它们的人员对应起来。此页面使用两个数据来源：

• CODEOWNERS 文件（如果存在）— 官方所有权分配
• Git blame / git log — 每个目录或子系统中最近提交或提交最频繁的 2-3 位贡献者

以表格形式呈现：

| Subsystem | Official owners (CODEOWNERS) | Recent contributors (git history) | Last activity |
|---|---|---|---|
| Authentication | @alice | alice, bob | 2 weeks ago |
| CLI | @charlie, @dave | charlie, eve | 3 days ago |

如果仓库没有 CODEOWNERS 文件，请省略该列，并从 git 历史记录中获取所有数据。如果仓库的贡献者很少（例如个人项目），请完全跳过此页面。

各页面的活跃贡献者

每个领域页面（apps、systems、features、packages、primitives）都应在页面标题后的第一行添加“活跃贡献者”署名，并置于 Purpose 部分之前：

# Authentication

Active contributors: alice, bob

## Purpose
...

根据 CODEOWNERS（如果可用）以及该子系统目录中 git blame 显示的近期提交最活跃的 2-3 位贡献者来确定姓名。使用名字或 GitHub 用户名，不要加 @ 符号。

从贡献者列表中排除机器人账户——过滤掉以 [bot] 结尾的用户名（例如 factory-droid[bot]、dependabot[bot]、github-actions[bot]）。机器人不是可以联系并提问的人。这同时适用于各页面的活跃贡献者署名和维护者页面。

使用默认分支获取贡献者数据。 根据 git blame 或 git log 确定贡献者时，始终查询默认分支（main 或 dev），而不是当前分支。功能分支会使贡献者数据偏向该分支上的工作者。使用 git log origin/main -- <path> 或 git log origin/dev -- <path> 获取准确的贡献者历史记录。

底部章节

这些章节会出现在每个 wiki 的末尾：

• reference/ — 配置、数据模型、外部依赖项
• maintainers.md — 子系统所有权表（条件性内容，个人项目跳过；始终作为最后一个页面）

页面排序

侧边栏顺序对导航至关重要。每个页面都必须出现在指定位置——不要把没有子页面的页面集中到顶部或底部。

Wiki 中的完整顺序如下：

1. overview/（index、architecture、getting-started、glossary）
2. by-the-numbers.md（如果存在）
3. lore.md（如果存在）
4. fun-facts.md（如果存在）
5. how-to-contribute/
6. [组织视角，顺序可按实际情况安排]
7. [条件式章节：api、deployment、security、how-to-monitor、background、cleanup-opportunities]
8. reference/
9. maintainers.md（如适用，始终放在最后）

排序规则：

• 每个页面都应保留在指定位置，不受其是否有子页面影响。by-the-numbers.md 应位于 overview/ 之后，即使它没有子页面，也不能放到其他无子页面的页面前面。
• .wiki-meta.json 中的 pageOrder 数组必须严格遵循此顺序。它决定侧边栏的显示顺序。
• 在一个视角章节（例如 apps/）中，页面应按重要性从高到低排序。index.md 始终排在第一位。
• 条件式章节应按上述顺序排列（api → deployment → security → how-to-monitor → background → cleanup-opportunities），而非按字母顺序排列。

嵌套规则

• 除了 overview/ 中的四个页面（index.md、architecture.md、getting-started.md、glossary.md）始终为单个文件外，任何页面都可以扩展为包含子页面的目录
• 最大深度：从任何视角根目录起最多 2 层（例如 apps/cli.md，或 apps/cli/index.md + apps/cli/tui-rendering.md）。不得更深。
• 每个目录都必须包含一个 index.md
• 对于大型代码库（50 个以上源目录或 10 个以上不同子系统），应倾向于拆分页面，而不是把内容塞在一起。用一篇 3000 字的页面介绍整个子系统，不如用三篇重点明确的页面分别介绍其不同方面。关键子 Agent 应根据代码中的发现决定是否创建子页面。
• 对于小型代码库，默认使用单个页面，仅在主题有明显不同的子领域时才拆分
• Deployment 和 security 应从单个页面开始；只有当代码库内容足够丰富时，才扩展为目录

命名规则

• 文件名使用小写字母并以连字符分隔：使用 getting-started.md，而非 GettingStarted.md
• 文件名使用小写字母并以连字符分隔。不得包含空格或大写字母。

页面标题规则

页面标题（每个 .md 文件顶部的 # Heading）应为简洁的名词短语，并与团队对该事物的称呼一致。章节层级已提供上下文，因此标题中不要重复这些信息。

• 不要添加目录路径前缀。 标题应为 "CLI"，而非 "apps/cli — CLI Architecture"。
• 不要添加泛化的后缀。 标题应为 "Apps"，而非 "Apps Overview"。标题应为 "Packages"，而非 "Packages — Overview"。唯一例外是 overview/index.md，其中可以包含项目名称（例如 "Factory platform overview"）。
• 不要重复父章节名称。 features/sessions.md 中的页面标题应为 "Sessions"，而非 "Features — Sessions"。
• 使用团队的惯用词汇。 如果团队称其为 "the daemon"，标题就应为 "Daemon"，而非 "Background Service Process"。
• 保持简短。 以 1-3 个词为宜。如果标题需要更多词，该页面可能涵盖内容过多，应考虑拆分。

3. 生成页面（委派给子 Agent）

页面生成由顶层 Agent 负责协调和编写基础页面，然后将领域页面委派给子 Agent，以深入分析并并行处理。

执行 DAG

1. SURVEY (top-level)
   Structural scan + deep code scan
   Produce: survey_context
        │
        ▼
2. PLAN (top-level)
   Decide lens sections, list all pages, mark criticality
   Produce: page_plan (JSON with per-page briefs)
        │
        ▼
3. FOUNDATION PAGES (top-level, sequential)
   Write: overview/*, how-to-contribute/patterns-and-conventions
   These establish shared vocabulary and conventions
        │
        ├────────────────────────────────────────┐
        ▼                                        ▼
4a. LENS PAGES (sub-agents, parallel)     4b. DATA PAGES (sub-agents, parallel)
    Critical pages: 1 agent each               by-the-numbers
    Normal pages: batched 3-5                  lore
    Each agent writes its page(s)              fun-facts
    + sub-pages if warranted
        │                                        │
        ├────────────────────────────────────────┘
        ▼
5. REMAINING PAGES (sub-agents, parallel)
   how-to-contribute/ (remaining pages)
   Conditional sections: api, deployment, security,
     how-to-monitor, background, cleanup-opportunities
   reference/ + maintainers.md
        │
        ▼
6. ASSEMBLY (top-level)
   Cross-link audit, .wiki-meta.json
        │
        ▼
7. UPLOAD

第 2 步：规划与委派

调研完成后，顶层 Agent 会生成一份页面计划——列出 Wiki 将包含的所有页面。计划会为每个页面列出：

• 路径 — 文件路径（例如，apps/cli/index.md）
• 标题 — 页面标题
• 重要性 — critical（分配专属子 Agent）或 normal（与相关页面合并处理）
• 内容简介 — 用 2-3 句话说明页面应涵盖的内容以及需要阅读哪些代码路径
• 相关源路径 — 子 Agent 应阅读的具体文件/目录
• 相关页面 — 其他正在编写的页面的标题、路径和一句话摘要，让 Agent 知道应链接到哪些页面，而不是重复说明

重要性指南： 涉及代码库规模大、变动频繁或在架构中承担核心角色的应用、包或功能的页面，适合分配专属 Agent。例如：包含 50 个以上源文件的 CLI、被大多数其他包导入的核心库，或涉及 5 个以上目录的功能。Agent 会根据调研结果自行判断——这些是指南，并非硬性规定。

子 Agent 的深度指南： 单个页面不应试图端到端地涵盖复杂子系统。遇到以下情况时，子 Agent 应创建子页面：

• 子系统包含 3 个以上明显不同的内部领域（例如，一个 CLI 包含 TUI 渲染、exec 模式、技能系统、会话管理——每个领域都值得单独成页）
• 要充分涵盖主题，单个页面将超过约 2000 字
• 子系统有多个入口点或不同的面向用户的模式

适合拆分的示例：

• 包含 50 个以上源文件且入口文件超过 4000 行的 CLI 应用 → 为每个主要子系统创建子页面（例如，cli/tui-rendering.md、cli/exec-mode.md、cli/skills.md、cli/session-management.md）
• 具有不同 API 组、认证系统和作业运行器的后端 → 为每个部分创建子页面
• 包含 10 个以上功能模块的前端包 → 为最复杂的模块创建子页面

不适合拆分的示例：

• 只有 5 个文件且用途单一的实用工具包 → 一个页面
• 只有一个处理程序的简单微服务 → 一个页面
• 配置包或常量包 → 一个页面

第 3 步：基础页面

顶层 Agent 会在启动任何子 Agent 之前，依次编写以下页面：

1. overview/index.md — 项目概览
2. overview/architecture.md — 使用 Mermaid 图表说明系统架构
3. overview/getting-started.md — 前置条件、安装、构建、测试和运行
4. overview/glossary.md — 项目专用术语
5. how-to-contribute/patterns-and-conventions.md — 编码模式与约定

这些页面会建立子 Agent 需要参考的通用词汇和架构背景。委派开始前，这些页面必须全部完成。

第 4 步：委派子 Agent（并行）

两组子 Agent 并行运行：

4a. 透镜页面 — 所有组织维度的透镜页面（应用、系统、功能、包、基本构件）：

• 重要页面各由一个专属子 Agent 负责。子 Agent 会阅读相关代码、编写页面，并自主判断是否需要子页面。如果某个主题包含明显不同的子领域，Agent 会创建子页面（最多 2 层：section/page.md）。顶层 Agent 不会预先规划重要页面的子页面——子 Agent 会自行探索并作出决定。
• 普通页面按关联程度分组，每个子 Agent 处理 3-5 个页面（例如，将 3 个小型包放在一起，或将 2 个相关功能放在一起）。合并处理的页面通常各为单个文件，不含子页面。

4b. 数据页面 — 与透镜页面并行处理，因为这些页面只需要 Git 历史记录和源文件结构：

• by-the-numbers.md
• lore.md
• fun-facts.md

步骤 5：其余页面（并行）

所有 lens 页面完成后，为以下内容启动子代理：

• 将 how-to-contribute/ 中的其余页面（development-workflow、testing、debugging、tooling）作为一批处理
• 每个条件章节分别由一个子代理或一个小批次处理：api、deployment、security、how-to-monitor、background、cleanup-opportunities
• 将 reference/ + maintainers.md 作为一批处理

此时这些页面可以交叉引用已完成的 lens 页面。

步骤 6：汇总

顶层 Agent 进行最后检查：

• 审核页面之间的交叉链接（修复失效引用，补充缺失链接）
• 编写 .wiki-meta.json，列出最终页面及其顺序
• 确认所有目录均包含 index.md 文件

子代理提示词模板

每个子代理都会收到一份采用以下结构的提示词：

You are writing wiki page(s) for [repo].

## Shared Context
[The survey_context document from Step 1 — compact repo overview,
architecture, key patterns, glossary terms. Same for all agents.]

## Your Assignment
Pages: [list of pages this agent is responsible for]
Criticality: [critical or normal]
Content brief: [2-3 sentences per page describing what to cover]
Relevant source paths: [specific files/directories to read]

## Related Pages (link to these, don't duplicate their content)
- apps/cli (apps/cli/index.md): "CLI architecture, entry points, and TUI rendering"
- features/llm-integration (features/llm-integration.md): "LLM provider abstraction and streaming"
- ...

## Rules
- Follow the page template (sections 3a-3e in the skill)
- Maximum nesting: 2 levels (section/page.md)
- For critical pages: explore the code and create sub-pages if the topic
  has clearly distinct sub-areas. Write both the index.md and sub-pages.
- For normal pages: write single-file pages unless complexity demands splitting
- Use Mermaid diagrams when they help explain data flows or component relationships
- Cross-link to related pages listed above instead of re-explaining their topics
- Write output to [wiki_dir path]

所有代理使用相同的共享上下文——精简的调研文档。单页说明由顶层 Agent 在规划期间按需定制。这样可以确保子代理不会重复调研文档中已有的发现，也不会解释其他页面负责涵盖的内容。

每个页面：

3a. 阅读相关代码

打开并阅读你要编写的章节所对应的实际源文件。不要猜测或臆造文件内容。如果文件太大，请阅读与当前章节相关的部分。

3b. 撰写说明文字

用通俗易懂的语言说明代码的作用。先介绍总体目的，再深入具体细节。每项描述都应能追溯到特定文件或函数。

每个领域页面都应包含以下章节（不适用于该子系统的章节可跳过）：

0. 活跃贡献者——紧跟标题之后的一行署名（参见第 2 节中的“每页活跃贡献者”）
1. 用途——用 2-3 句话说明该子系统的作用
2. 目录结构——展示关键文件和文件夹的文件树
3. 关键抽象——列出最重要类型（类、接口、trait、结构体、函数）的表格，包含其文件路径和一行说明
4. 工作原理——主要数据流/控制流；涉及 3 个或更多组件时，添加 Mermaid 图
5. 集成点——该子系统如何与其他部分连接（导入什么、由什么调用、发出/监听什么事件）
6. 修改入口——用 2-3 句话告诉开发者，若要修改或扩展该子系统，应从哪里着手

页面长度应由子系统的复杂程度决定。轻量包装器可能只需包含第 1、3 和 5 节。复杂子系统则可能需要全部六节和多张图。

3c. 添加 Mermaid 图

使用 Mermaid 图说明：

• 架构——系统组件及其连接方式
• 数据流——请求生命周期、事件管道、处理阶段
• 状态机——身份验证流程、订单状态、构建管道

Mermaid 图指南：

• 架构图和流程图使用 graph TD 或 graph LR
• 服务之间的请求/响应流程使用 sequenceDiagram
• 状态机使用 stateDiagram-v2
• 图示应保持简洁——最多 5 到 15 个节点。较大的图应拆分成多个小图
• 在边上标注传递的操作或数据
• 使用子图对相关组件进行分组

示例：

```mermaid
graph LR
    Client -->|HTTP request| APIGateway
    APIGateway -->|validate + route| Handler
    Handler -->|query| Database
    Database -->|rows| Handler
    Handler -->|JSON response| Client
```

对于一句话就能说明的简单关系，不要使用 Mermaid。图示应当能呈现难以用文字描述的内容，才能体现其价值。

3d. 添加文件引用

每个领域页面都必须包含一个 “关键源文件” 表格，列出该子系统最重要的文件：

| File | Purpose |
|---|---|
| `src/auth/middleware.ts` | Validates JWT tokens, attaches user to request |
| `src/auth/token-service.ts` | Token creation, refresh, and revocation |

表格应涵盖所有重要文件——不要用无关紧要的文件凑数，也不要仅仅因为文件较少就遗漏文件。

在说明文字中提及的每个文件都应添加引用。首次提及类、接口、函数或类型时，应使用反引号标出其文件路径。读者应能从文档一步找到对应代码。

3e. 页面间交叉链接

使用相对 Markdown 链接在页面间建立链接：

For details on how the auth middleware integrates with the API layer,
see [API authentication](../api/authentication.md).

每个页面都应至少链接到另一个页面。读者无需使用侧边栏，也应能够浏览 Wiki。

3f. 趣闻内容

fun-facts.md 页面为可选内容，但建议添加。从以下列表中为特定仓库挑选 3-5 个最有趣的主题：

• 现存最古老的代码 — 通过 git blame 查找最古老的文件或函数。它有多古老？它变化大吗？
• 依赖考古 — 仍在使用的最古老依赖，或主要版本升级次数最多的依赖
• 命名由来 — 项目或其内部工具为何这样命名？工程师起名常常很奇特，背后通常有故事
• TODO/FIXME 数量 — 有多少条 TODO/FIXME/HACK 注释？最古老的一条是什么时候写的？
• 最长的文件 — 哪个源文件的行数最多？温和地指出这一点，也为重构提供参考

不要强行把所有主题都塞进每个 Wiki。只挑选仓库确实有值得一说内容的主题。如果没有什么特别之处，就完全跳过趣闻部分。

4. 编写元数据文件

生成所有页面后，在 Wiki 目录根目录中创建 .wiki-meta.json。pageOrder 数组至关重要——它决定了页面在 Wiki 侧边栏中的显示顺序。按期望的显示顺序列出每个生成文件的路径。否则，页面会按字母顺序排序。

{
  "generatedAt": "2025-01-15T10:30:00Z",
  "pageCount": 42,
  "topLevelSections": ["overview", "by-the-numbers", "lore", "fun-facts", "how-to-contribute", "apps", "systems", "features", "packages", "primitives", "api", "deployment", "security", "how-to-monitor", "background", "cleanup-opportunities", "reference", "maintainers"],
  "pageOrder": [
    "overview/index.md",
    "overview/architecture.md",
    "overview/getting-started.md",
    "overview/glossary.md",
    "by-the-numbers.md",
    "lore.md",
    "fun-facts.md",
    "how-to-contribute/index.md",
    "how-to-contribute/development-workflow.md",
    "how-to-contribute/testing.md",
    "how-to-contribute/debugging.md",
    "how-to-contribute/patterns-and-conventions.md",
    "how-to-contribute/tooling.md",
    "apps/index.md",
    "apps/cli/index.md",
    "apps/cli/command-structure.md",
    "apps/cli/tui-rendering.md",
    "apps/daemon.md",
    "systems/index.md",
    "systems/auth.md",
    "features/index.md",
    "features/wiki-generation.md",
    "packages/index.md",
    "packages/common.md",
    "primitives/index.md",
    "primitives/session.md",
    "api/index.md",
    "api/rest-endpoints.md",
    "deployment.md",
    "security.md",
    "how-to-monitor/index.md",
    "how-to-monitor/logging.md",
    "how-to-monitor/metrics.md",
    "how-to-monitor/tracing.md",
    "how-to-monitor/alerting.md",
    "background/index.md",
    "background/design-decisions.md",
    "background/pitfalls.md",
    "background/migration-context.md",
    "cleanup-opportunities/index.md",
    "cleanup-opportunities/dead-ends.md",
    "cleanup-opportunities/todos-and-fixmes.md",
    "cleanup-opportunities/complexity-hotspots.md",
    "cleanup-opportunities/dependency-freshness.md",
    "reference/index.md",
    "reference/configuration.md",
    "reference/data-models.md",
    "reference/dependencies.md",
    "maintainers.md"
  ]
}

上面的示例有所省略。实际操作中，请列出 Wiki 目录中的每个 .md 文件。顺序必须与第 2 节中定义的页面顺序一致：overview → by-the-numbers → lore → fun-facts → how-to-contribute → lenses → conditional → reference → maintainers。

5. 上传

标准上传（本地 Wiki 目录）

当用户希望保留本地副本时（默认情况）：

droid wiki-upload \
  --repo-url "$REPO_URL" \
  --wiki-dir ./droid-wiki

参数：

• --repo-url — 仓库 URL（远程源，例如 https://github.com/org/repo）
• --wiki-dir — 包含生成的 Markdown 文件的目录路径
• --cleanup —（可选）成功上传后删除 Wiki 目录

仅远程上传（--no-local 处理方式）

当用户要求生成 Wiki，但不在磁盘上留下文件时（例如用户说“不要在本地留下文件”或传入 --no-local 标志）：

# Create a temporary directory
WIKI_TMPDIR=$(mktemp -d)

# Write all wiki files to the temporary directory instead of ./droid-wiki
# ... generate pages into $WIKI_TMPDIR ...

# Upload with --cleanup to remove the temp directory after success
droid wiki-upload \
  --repo-url "$REPO_URL" \
  --wiki-dir "$WIKI_TMPDIR" \
  --cleanup

--cleanup 标志会指示 CLI 在成功上传后删除 --wiki-dir 目录。如果上传失败，则会保留该目录，以便用户重试。

内容原则

渐进式呈现

每个页面都以 1–3 句摘要开头，说明该页面涵盖的内容。接着添加概述部分，解释主要概念。实现细节、边缘情况和配置选项应放在页面后面的部分。

读者只需浏览每个页面的第一段，就应能对整个系统有所了解。

页面大小限制

单个页面应小于 500KB。如果页面接近此限制，请将其拆分为多个子页面。例如，较大的 API 参考页面可以拆分成一个目录，每个端点组各有一个页面。

人类写作规则

撰写文档时，要像真人写的一样。技术文档的主题往往比较枯燥，尤其容易显得像 AI 生成的。请避免这种倾向。

具体规则：

1. 删去夸大的重要性描述。 不要写“是……的见证”“在不断演变的领域中发挥关键作用”“为……奠定基础”或“凸显了……的重要性”。直接说明事物的作用。

   不佳：“身份验证模块是应用安全体系中的关键支柱。” 良好：“身份验证模块会验证 JWT 令牌，并将用户上下文附加到请求中。”

2. 删去宣传性语言。 不要写“拥有”“充满活力”“丰富”“深刻”“展现”“体现”“致力于”“突破性”“知名”或“令人叹为观止”。技术文档应描述事实，而不是推销。

   不佳：“代码库拥有一套丰富且充满活力的实用工具，展现了团队对开发者体验的重视。” 良好：“utils/ 目录包含用于字符串格式化、日期解析和重试逻辑的辅助函数。”

3. 避免肤浅的 -ing 分析。 不要在句子后面加上“突出……”“确保……”“反映……”“象征……”“展现……”或“有助于……”来营造深度。

   不佳：“该服务异步处理事件，确保可扩展性，同时凸显系统稳健的架构。” 良好：“该服务异步处理事件。它从 SQS 队列中拉取事件，每个实例每秒可处理约 500 个事件。”

4. 避免使用 AI 常用词。 以下词语在 AI 生成的文本中出现频率过高：此外、至关重要、深入探讨、强调、持久、提升、促进、获得、相互作用、错综复杂／复杂性、（抽象意义上的）格局、关键、展现、（抽象意义上的）织锦、见证、凸显（动词）、充满活力。请换成更朴实的表达。

5. 不要强行凑成三项。 不要为了显得全面而把内容硬凑成三项（例如“创新、灵感和行业洞见”）。有两项就列两项，有四项就列四项。

6. 不要刻意避用系动词。 使用“X 是 Y”或“X 有 Y”，不要写“X 充当 Y”“X 是 Y 的代表”“X 象征 Y”“X 拥有 Y”“X 具有 Y”或“X 提供 Y”。

   不佳：“配置模块是环境变量管理的中心枢纽。” 良好：“配置模块读取环境变量，并导出类型化常量。”

7. 不要使用否定式平行结构。 避免使用“它不只是 X，而是 Y”或“不仅 X，还 Y”这样的结构。

8. 标题使用句首字母大写格式。 写“身份验证入门”，不要写“身份验证入门指南”。

9. 删去填充语。 将“为了”改为“以”，将“由于……这一事实”改为“因为”，将“需要注意的是”直接删掉，只陈述事实。

10. 具体，不要含糊。 用具体出处替换“行业专家认为”。用实际组件名称替换“多个组件”。用实际配置选项替换“各种配置”。

11. 避免过度使用长破折号。 大多数情况下，用逗号或句号代替长破折号（—）。每页用一个长破折号可以接受，用三个或更多就显得过多。

12. 不要使用聊天机器人套话。 不要写“希望这能帮到你”“如果需要，请告诉我”“以下是概述”“当然！”或“好问题！”。这些是对话用语，不适合文档。

具体文件引用

每项关于代码的事实都必须指向源文件。不要只说“系统处理身份验证”，却不说明代码位置。不要只说“数据库架构包含 users 表”，却不指明迁移文件或模型文件。

如果找不到实现某项功能的文件，请明确说明：“重试逻辑在 config.ts 中有所提及，但在当前代码库中未找到其实现。”

Mermaid 图表用法

在架构页面中至少包含一个 Mermaid 图表。在有助于说明数据流或组件关系的领域页面中包含图表。不要在每个页面都添加图表——介绍配置选项或环境变量的页面通常不需要图表。

文件结构规范

生成的 wiki 遵循以下布局：

droid-wiki/
├── .wiki-meta.json

# Always present (in this order)
├── overview/                             # Introductory material
│   ├── index.md                          # Project overview
│   ├── architecture.md                   # System architecture with Mermaid diagrams
│   ├── getting-started.md                # Prerequisites, install, build, test, run
│   └── glossary.md                       # Project-specific terms and vocabulary
├── by-the-numbers.md                     # Codebase statistics snapshot
├── lore.md                      # Timeline, eras, deprecated features, rewrites
├── fun-facts.md                          # Easter eggs, origin stories, oldest code
├── how-to-contribute/                    # How to work in this codebase
│   ├── index.md
│   ├── development-workflow.md
│   ├── testing.md
│   ├── debugging.md
│   ├── patterns-and-conventions.md
│   └── tooling.md

# Organizational lenses (use any combination, at least one required)
# Labels mirror the repo's own vocabulary
├── <apps|services|applications>/         # Deployable units
│   ├── index.md
│   ├── <simple-app>.md                   # Single page for simple apps
│   └── <complex-app>/                    # Directory for complex apps
│       ├── index.md
│       └── <sub-topic>.md
├── <systems|modules|subsystems>/         # Internal building blocks
│   ├── index.md
│   ├── <simple-system>.md
│   └── <complex-system>/                 # 3rd level for complex subsystems
│       ├── index.md
│       └── <sub-topic>.md
├── <features|capabilities|workflows>/    # Cross-cutting capabilities
│   ├── index.md
│   ├── <simple-feature>.md
│   └── <complex-feature>/                # Features that span many systems deserve sub-pages
│       ├── index.md
│       └── <sub-topic>.md
├── <packages|libraries|crates>/          # Workspace packages
│   ├── index.md
│   ├── <simple-package>.md
│   └── <complex-package>/
│       ├── index.md
│       └── <sub-topic>.md
├── <primitives|core-concepts|entities>/  # Foundational domain objects
│   ├── index.md
│   └── *.md

# Conditional sections (LLM judgment)
├── api/                                  # If the repo exposes APIs
│   ├── index.md
│   └── *.md
├── deployment.md                         # Single page or directory
├── security.md                           # Single page or directory
├── how-to-monitor/                        # Logging, metrics, tracing, alerting (services only)
│   ├── index.md
│   ├── logging.md                        # Where logs go, how to query, log levels
│   ├── metrics.md                        # What's tracked, dashboards, SLIs
│   ├── tracing.md                        # Distributed tracing, request tracing
│   └── alerting.md                       # Alerts, thresholds, escalation, noisy alerts
├── background/                           # Design decisions, pitfalls, migration context
│   ├── index.md
│   └── *.md
├── cleanup-opportunities/                # Dead code, TODOs, complexity hotspots, stale deps
│   ├── index.md
│   ├── dead-ends.md                      # Unused files, exports, modules
│   ├── todos-and-fixmes.md               # Accumulated TODO/FIXME/HACK comments
│   ├── complexity-hotspots.md            # Largest files, deepest nesting
│   └── dependency-freshness.md           # Outdated or unmaintained dependencies

# Always present (bottom)
├── reference/
│   ├── index.md
│   ├── configuration.md
│   ├── data-models.md
│   └── dependencies.md
└── maintainers.md                        # Subsystem ownership table (conditional, always last)

规则：

• 每个 .md 文件都必须以一级标题（# Title）开头。上传工具会从此标题提取标题。
• 每个目录都必须包含一个 index.md。
• 文件名使用小写字母和连字符。不能包含空格或大写字母。
• .wiki-meta.json 文件用于跟踪，不会作为页面上传。
• overview/ 中的四个页面（index.md、architecture.md、getting-started.md、glossary.md）始终为单个文件。其他所有页面都可以扩展为包含子页面的目录。
• 最大树深度：从任意 lens 根目录起为 2 层（例如 apps/cli/command-structure.md）。不能更深。
• 对于大型仓库，由关键子 Agent 决定是否拆分为子页面。像编辑器核心或扩展宿主这样的复杂子系统，应有自己的目录并包含重点明确的子页面，而不是写成单个冗长页面。
• 每次 wiki 运行最多 200 个页面。如果项目需要更多页面，应优先处理最重要的子系统。