wiki

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wiki generation

Wiki生成

Read a repository, then produce a set of interconnected documentation pages that explain what the code does and how it fits together. The output is a

droid-wiki/

directory of markdown files, uploaded to Factory via

droid wiki-upload

读取代码仓库，生成一组相互关联的文档页面，解释代码功能及各部分的协作方式。输出为包含Markdown文件的

droid-wiki/

目录，可通过

droid wiki-upload

命令上传至Factory。

1. Survey the repository

1. 调研代码仓库

Before writing anything, build a mental model of the codebase. The survey has two passes: a structural scan and a deep code scan.

在撰写文档前，先建立对代码库的认知模型。调研分为两个阶段：结构扫描和深度代码扫描。

Pass 1: Structural scan

第一阶段：结构扫描

Read these files (when they exist):

```
README.md
```
,
```
AGENTS.md
```
,
```
CONTRIBUTING.md
```
— project intent and conventions

package.json

Cargo.toml

go.mod

pyproject.toml

— dependencies and scripts

```
docs/
```
directory — existing documentation
Entry points (
```
src/index.ts
```
,
```
main.go
```
,
```
app.py
```
, etc.) — how the application starts

CI/CD config (

.github/workflows/

.gitlab-ci.yml

Jenkinsfile

azure-pipelines.yml

, etc.)

Build tool config (

webpack.config.*

vite.config.*

Makefile

build/

Gulpfile.*

, etc.)

Lint/quality config (
```
eslint.config.*
```
, custom lint plugins,
```
rustfmt.toml
```
,
```
.golangci.yml
```
, etc.)
Directory listing of the project root and key subdirectories

Build a map of:

What the project does — its purpose in one or two sentences
Major subsystems — the main areas of the codebase (e.g., API layer, database models, CLI, frontend components)
Key data flows — how data moves through the system (request → handler → database → response)
External dependencies — databases, APIs, message queues, third-party services
Build and test commands — how to build, test, and run the project

读取以下存在的文件：

```
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.*

等）

代码质量检查配置（
```
eslint.config.*
```
、自定义lint插件、
```
rustfmt.toml
```
、
```
.golangci.yml
```
等）
项目根目录及关键子目录的文件列表

梳理以下信息：

项目用途 —— 用1-2句话说明项目的核心功能
主要子系统 —— 代码库的核心模块（如API层、数据库模型、CLI、前端组件）
关键数据流 —— 数据在系统中的流转路径（请求→处理器→数据库→响应）
外部依赖 —— 数据库、API、消息队列、第三方服务
构建与测试命令 —— 项目的构建、测试及运行方式

Pass 2: Deep code scan

第二阶段：深度代码扫描

The structural scan catches what's visible from directory names and config files. The deep scan catches features, domains, and capabilities that are only visible in the code itself. Probe the codebase for signals that reveal topics the structural scan missed:

Grep for feature flag names in constants files — each flag often represents a distinct capability worth documenting
Scan frontend route definitions and page components — each route group is a user-facing feature
Scan API endpoint groups — each controller or router file represents a domain area
Look inside
```
src/features/
```
,
```
src/modules/
```
,
```
src/domains/
```
, or equivalent directories — the names and contents reveal product capabilities
Scan for service classes, event handlers, and job/worker definitions — these reveal background systems
Check for domain-specific directories that don't map to obvious top-level names

The goal is to discover the complete list of topics the wiki should cover. The structural scan gives you the skeleton; the deep scan fills in the muscle. A feature like "Analytics" might not have its own top-level directory but lives inside

src/features/analytics/

or is revealed by a set of feature flags and API endpoints.

结构扫描能从目录名称和配置文件中获取信息，深度扫描则可发现仅在代码中体现的功能、领域和能力。探查代码库，找出结构扫描遗漏的线索：

在常量文件中搜索功能标识名称 —— 每个标识通常对应一个值得记录的独立功能
扫描前端路由定义和页面组件 —— 每个路由组对应一个面向用户的功能
扫描API端点分组 —— 每个控制器或路由文件对应一个业务领域
查看
```
src/features/
```
、
```
src/modules/
```
、
```
src/domains/
```
或类似目录 —— 目录名称和内容可揭示产品功能
扫描服务类、事件处理器及任务/工作器定义 —— 这些内容可揭示后台系统
检查与顶级名称不匹配的特定领域目录

目标是找出wiki需要覆盖的完整主题列表。结构扫描搭建骨架，深度扫描填充细节。例如“Analytics”功能可能没有独立的顶级目录，但存在于

src/features/analytics/

中，或通过一组功能标识和API端点体现。

Exhaustive subsystem discovery

全面发现子系统

After both passes, walk every top-level source directory (and one level below) to check for subsystems you missed. For each directory that contains its own service, module, or feature, decide:

Tier 1 — core subsystems most contributors will encounter. Full dedicated page.
Tier 2 — important but specialized. Shorter dedicated page.
Tier 3 — niche or thin wrapper. A paragraph in an "Other subsystems" page with directory pointers.

Small repos may only need a few domain pages. Large repos should have as many as the codebase warrants. Do not cap arbitrarily — let the repo's actual structure determine coverage.

完成两个阶段的扫描后，遍历所有顶级源码目录（及下一级目录），检查是否遗漏子系统。对于包含独立服务、模块或功能的目录，判断：

一级子系统 —— 核心子系统，大多数贡献者都会接触到，需单独创建完整页面
二级子系统 —— 重要但专业性较强，需创建简短的独立页面
三级子系统 —— 小众或轻量封装，在“其他子系统”页面中用一段文字说明并指向对应目录

小型仓库可能仅需几个领域页面，大型仓库则需根据代码库实际结构生成足够多的页面，不要随意限制数量。

Often-missed areas

易遗漏的领域

After scanning the source tree, check for these commonly overlooked areas:

Custom lint/analysis rules — plugins or config that enforce project-specific conventions
Automation workflows — CI/CD, bots, scheduled jobs, code generation scripts
CLI or dev tools — internal tools, scripts in
```
scripts/
```
,
```
tools/
```
, or
```
bin/
```
Test infrastructure — custom test frameworks, fixtures, or automation harnesses beyond standard test runners
Multi-language components — if the repo has code in a second language (e.g., Rust CLI in a TypeScript project), document it

If any of these are non-trivial, they deserve coverage — either as their own page or as a section in a related page.

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

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

若上述内容具有一定复杂度，需单独创建页面或在相关页面中添加章节。

Survey output

调研输出

At the end of the survey, produce a survey context document — a compact summary that will be shared with sub-agents. This document should include:

Repo summary — 3-5 sentences: what the project is, its tech stack, and high-level structure
Architecture overview — major components and how they connect
Discovered topics — the complete list of features, systems, apps, packages, and primitives found during both scan passes
Key patterns — coding conventions, error handling patterns, testing patterns
Glossary seeds — project-specific terms encountered during the scan
Directory-to-purpose map — which source directories map to which topics

调研结束后，生成一份调研上下文文档 —— 一份简洁的摘要，将共享给子Agent。文档应包含：

仓库摘要 —— 3-5句话：项目定位、技术栈及高层结构
架构概述 —— 主要组件及其关联方式
已发现主题 —— 两个扫描阶段中发现的所有功能、系统、应用、包及基础组件
关键模式 —— 编码约定、错误处理模式、测试模式
术语表雏形 —— 调研中遇到的项目特定术语
目录-用途映射 —— 源码目录与对应主题的映射关系

Coverage cross-check

覆盖范围交叉校验

Before moving to planning, reconcile two independent topic sources to ensure nothing is missed:

Source A: Discovered topics. The topics found during Pass 1 (structural scan) and Pass 2 (deep code scan). These include cross-cutting features that don't map to a single directory (e.g., "LLM integration" spanning multiple packages, "authentication" touching frontend, backend, and CLI).

Source B: Directory enumeration. For each lens that applies to the repo, run

ls

on the corresponding source directories and list every subdirectory:

For apps: list every directory under
```
apps/
```
(or the repo's equivalent)
For packages: list every workspace package directory
For features: list every subdirectory under the feature directory (e.g.,
```
src/features/
```
,
```
packages/frontend/src/features/
```
, or wherever the repo organizes features)
For systems: list the top-level source directories that contain service or module code

Reconciliation: Merge both lists. For every item on either list, decide:

Wiki page — the item becomes a planned page (or section within a page)
Skip with reason — the item is intentionally excluded, with a specific reason (e.g., "empty directory — 0 source files", "deprecated — only test fixtures remain", "thin wrapper — covered in parent package page", "internal tooling — 3 files, not worth a standalone page")

The discovered topics catch things that directories miss (cross-cutting concerns, emergent patterns). The directory enumeration catches things that discovery misses (features the agent didn't encounter in the files it read). Together they produce comprehensive coverage.

Silent omissions are not acceptable. If a source directory exists with non-trivial code and has no wiki topic, that's a gap that must be justified.

进入规划阶段前，需整合两个独立的主题来源，确保无遗漏：

来源A：已发现主题 —— 第一阶段（结构扫描）和第二阶段（深度代码扫描）中发现的主题，包括跨多个目录的功能（如跨多个包的“LLM集成”、涉及前端、后端和CLI的“认证”功能）。

来源B：目录枚举 —— 根据仓库类型，列出对应源码目录下的所有子目录：

应用类：列出
```
apps/
```
或类似目录下的所有子目录
包类：列出所有工作区包目录
功能类：列出功能目录下的所有子目录（如
```
src/features/
```
、
```
packages/frontend/src/features/
```
或仓库中组织功能的其他目录）
系统类：列出包含服务或模块代码的顶级源码目录

整合步骤：合并两个列表。对于每个条目，决定：

创建Wiki页面 —— 该条目成为规划中的页面（或页面中的章节）
跳过并说明原因 —— 有意排除该条目，并给出具体原因（如“空目录——无源码文件”、“已废弃——仅保留测试夹具”、“轻量封装——在父包页面中说明”、“内部工具——仅3个文件，无需独立页面”）

已发现主题可覆盖目录枚举遗漏的内容（跨领域关注点、新兴模式），目录枚举可覆盖主题发现遗漏的内容（Agent未在文件中发现的功能）。两者结合可确保覆盖全面。

禁止无理由遗漏。若存在包含非 trivial 代码的源码目录但未对应Wiki主题，需说明原因。

2. Plan the table of contents

2. 规划目录结构

Design a page tree before writing any prose. The wiki has three tiers of content: always-present pages, organizational lenses, and conditional sections.

撰写文档前先设计页面树。Wiki包含三个层级的内容：必选页面、组织视角和条件章节。

Always-present pages

必选页面

These pages appear in every wiki, in this order:

```
overview/
```
— introductory material grouped under one section
- ```
index.md
```
  — project overview: what it does, who uses it, quick links
- ```
architecture.md
```
  — system architecture with Mermaid diagrams
- ```
getting-started.md
```
  — prerequisites, install, build, test, run
- ```
glossary.md
```
  — project-specific terms and domain vocabulary
```
by-the-numbers.md
```
— codebase statistics snapshot (see below)
```
lore.md
```
— timeline and history of the codebase (see below)
```
how-to-contribute/
```
— how to work in this codebase
- ```
index.md
```
  — work pickup, PR process, review expectations, definition of done
- ```
development-workflow.md
```
  — branch, code, test, PR, merge cycle
- ```
testing.md
```
  — frameworks, patterns, how to run, mock, and cover
- ```
debugging.md
```
  — logs, common errors, troubleshooting runbook
- ```
patterns-and-conventions.md
```
  — error handling, coding style, cross-cutting concerns
- ```
tooling.md
```
  — build system, linters, code generators, CI tooling (if the repo's tooling is the product itself, promote this to a top-level section instead)

以下页面会出现在所有Wiki中，顺序如下：

```
overview/
```
—— 入门内容汇总
- ```
index.md
```
  —— 项目概述：功能、用户群体、快速链接
- ```
architecture.md
```
  —— 系统架构，含Mermaid图
- ```
getting-started.md
```
  —— 前置条件、安装、构建、测试、运行
- ```
glossary.md
```
  —— 项目特定术语及领域词汇
```
by-the-numbers.md
```
—— 代码库统计快照（见下文）
```
lore.md
```
—— 代码库时间线与历史（见下文）
```
how-to-contribute/
```
—— 代码贡献指南
- ```
index.md
```
  —— 任务领取、PR流程、评审要求、完成标准
- ```
development-workflow.md
```
  —— 分支、编码、测试、PR、合并流程
- ```
testing.md
```
  —— 测试框架、模式、运行方式、Mock与覆盖率
- ```
debugging.md
```
  —— 日志、常见错误、故障排查手册
- ```
patterns-and-conventions.md
```
  —— 错误处理、编码风格、跨领域关注点
- ```
tooling.md
```
  —— 构建系统、代码检查工具、代码生成器、CI工具（若仓库本身是工具类项目，将此章节提升为顶级章节）

By the numbers

数据统计页面

A top-level

by-the-numbers.md

page that gives a quantitative snapshot of the codebase. Start the page with a "Data collected on [date]" note so readers know how current the numbers are.

Include these sections:

Size — lines of code by language (with a Mermaid horizontal bar chart), total source files vs test files vs config files, package/module count for monorepos
Activity — commits per week/month (recent trend), most actively changed files/directories in the last 90 days (churn hotspots)
Bot-attributed commits — percentage of commits with bot co-authorship (e.g.,
```
Co-authored-by: factory-droid[bot]
```
,
```
dependabot[bot]
```
,
```
github-actions[bot]
```
,
```
copilot[bot]
```
). This is a lower bound on AI-assisted work since inline AI tools like Copilot leave no trace in git history. Be transparent about what's counted.
Complexity — average file size by directory, deepest import chains, number of exported symbols per package

Use Mermaid

xychart-beta

(horizontal bar charts) for language breakdown and any other stat where a visual helps. Do NOT use Mermaid

pie

charts — they are not supported by the renderer. Use tables for lists of files/directories.

Never include individual contributor stats (top committers, lines per person, leaderboards). The by-the-numbers page is about the codebase, not the people. Per-person metrics create toxic comparisons and don't belong in team documentation. The

maintainers.md

page handles ownership mapping separately.

Inline stats in other pages: In addition to this summary page, weave relevant stats into existing pages:

Language breakdown in
```
architecture.md
```
Churn hotspots in
```
cleanup-opportunities/
```
(if that section exists)
File counts, bus factor (unique committers), and test-to-code ratio per subsystem on each domain page
Dependency counts in
```
reference/dependencies.md
```

顶级页面

by-the-numbers.md

提供代码库的量化快照。页面开头需添加“数据收集于[日期]”说明，让读者了解数据时效性。

包含以下章节：

规模 —— 按语言统计代码行数（用Mermaid水平条形图展示）、源码文件/测试文件/配置文件总数、单仓项目的包/模块数量
活跃度 —— 每周/每月提交次数（近期趋势）、过去90天内变更最频繁的文件/目录（变更热点）
机器人提交占比 —— 机器人共同提交的代码占比（如
```
Co-authored-by: factory-droid[bot]
```
、
```
dependabot[bot]
```
、
```
github-actions[bot]
```
、
```
copilot[bot]
```
）。这是AI辅助开发的下限，因为Copilot等内嵌AI工具不会在git历史中留下痕迹。需明确说明统计范围。
复杂度 —— 各目录的平均文件大小、最深导入链、每个包的导出符号数量

使用Mermaid

xychart-beta

（水平条形图）展示语言分布及其他需要可视化的统计数据。禁止使用Mermaid饼图——渲染器不支持。用表格展示文件/目录列表。

禁止包含个人贡献统计（顶级提交者、个人代码行数、排行榜）。数据统计页面聚焦代码库，而非个人。个人指标会引发不良竞争，不属于团队文档范畴。

maintainers.md

页面单独记录职责归属。

在其他页面中嵌入统计数据：除汇总页面外，需将相关统计数据整合到现有页面中：

```
architecture.md
```
中嵌入语言分布
```
cleanup-opportunities/
```
中嵌入变更热点（若该章节存在）
每个领域页面中嵌入子系统的文件数量、总线因子（独立提交者数量）及测试代码比率
```
reference/dependencies.md
```
中嵌入依赖数量

Lore

历史页面

A top-level

lore.md

page that tells the story of how the codebase evolved. This is a narrative history, not a technical reference. It answers "what happened here and when?"

Boundaries with other sections:

```
by-the-numbers.md
```
= current snapshot (what the codebase looks like today)
```
lore.md
```
= timeline and history (what changed and when)
```
fun-facts.md
```
= light trivia (easter eggs, amusing discoveries)
```
background/
```
= technical rationale (why decisions were made)

Every event, era, and milestone must include a date or month (e.g., "Mar 2023", "Q4 2024"). Derive dates from git commit timestamps, tag dates, and file creation dates. If an exact date isn't available, use the month of the earliest relevant commit.

Include these sections:

Eras — group the codebase history into 3-8 major phases, each with a short narrative description and key event bullet points. Derive from git history: tag dates, large merge commits, contributor patterns, directory creation dates. Example: "The TypeScript Migration (Mar–Aug 2023): The entire backend was rewritten from JavaScript to TypeScript over 5 months..."
Longest-standing features — code or subsystems that have survived the most refactors and are still actively used. Include when they were first introduced and how many changes they've weathered.
Deprecated features — things that were built, used, and then removed or replaced. Identify from directory names, README mentions, obvious
```
@deprecated
```
annotations, and removed routes. What was the feature, when was it introduced, when was it deprecated, and what replaced it.
Major rewrites — large changes that touched many files. What existed before, what replaced it, and when. Derive from git history (large PRs, branch names with "migration" or "rewrite").
Growth trajectory — how the codebase expanded over time: when packages/apps were added, contributor growth signals from git log.

Speculation: When the "why" behind a change isn't clear from commits, use natural hedging language ("appears to have been", "likely replaced due to"). No special formatting for speculative content.

顶级页面

lore.md

讲述代码库的演进历程。这是叙事性历史，而非技术参考。需回答“这里发生了什么，何时发生？”

与其他章节的边界：

```
by-the-numbers.md
```
= 当前快照（代码库现状）
```
lore.md
```
= 时间线与历史（变更内容与时间）
```
fun-facts.md
```
= 轻松 trivia（彩蛋、有趣发现）
```
background/
```
= 技术背景（决策原因）

每个事件、阶段和里程碑必须包含日期或月份（如“2023年3月”、“2024年第四季度”）。日期来源于git提交时间戳、标签日期和文件创建日期。若无法获取精确日期，使用最早相关提交的月份。

包含以下章节：

发展阶段 —— 将代码库历史划分为3-8个主要阶段，每个阶段包含简短叙事描述和关键事件要点。从git历史中提取：标签日期、大型合并提交、贡献者模式、目录创建日期。示例：“TypeScript迁移阶段（2023年3月–8月）：耗时5个月将整个后端从JavaScript重写为TypeScript……”
长期存在的功能 —— 经历多次重构仍在活跃使用的代码或子系统。包含首次引入时间及变更次数。
已废弃功能 —— 曾被开发、使用后被移除或替换的功能。从目录名称、README提及内容、明显的
```
@deprecated
```
注解及已移除路由中识别。需说明功能内容、引入时间、废弃时间及替代方案。
重大重写 —— 涉及大量文件的大型变更。说明重写前的状态、替代方案及时间。从git历史中提取（大型PR、含“migration”或“rewrite”的分支名称）。
增长轨迹 —— 代码库的扩张过程：包/应用的添加时间、从git日志中提取的贡献者增长信号

推测性内容：若从提交记录中无法明确变更原因，使用模糊表述（“似乎是”、“可能因……被替换”）。推测内容无需特殊格式。

Organizational lenses

组织视角

Five lenses are available for organizing the codebase deep-dives. Use any combination based on what the repo actually contains. At least one lens is required. Most repos use 2-3. The features lens is strongly encouraged -- it's the most intuitive entry point for new engineers ("what does this thing do?"). Even small repos typically have user-visible or developer-visible capabilities worth documenting. Only skip it if the repo is a single-purpose library with no distinct features.

Concept	Default label	Also called	When to use
Deployable units	`applications/`	`services/` , `apps/`	Repo ships multiple distinct runtimes
Internal building blocks	`systems/`	`services/` , `modules/` , `subsystems/`	Architectural components that don't map to a single app or package
Cross-cutting capabilities	`features/`	`capabilities/` , `workflows/`	User-visible or developer-visible things that span multiple systems
Workspace packages	`packages/`	`libraries/` , `crates/` , `modules/`	Monorepo with shared libraries worth documenting individually
Foundational domain objects	`primitives/`	`core-concepts/` , `domain-models/` , `entities/`	Types/concepts that appear across 3+ systems (e.g., session, user, message)

Choosing labels: Mirror the repo's own vocabulary. If the repo has an

apps/

directory, call the section

apps/

, not

applications/

. If the repo calls things "services," use

services/

. The default labels are fallbacks for when the repo has no existing convention.

Placement rules:

Place each concept where the repo's structure suggests it belongs. If agent logic lives in
```
packages/droid-core
```
, document it under packages, not systems.
The systems lens is for things that don't have a natural home in apps or packages -- emergent architectural patterns, cross-package systems, infrastructure that spans multiple directories.
Do not duplicate content across lenses. If something is documented under packages, the relevant app page should cross-link to it, not repeat it.

Heuristics for identifying each lens:

If it has its own entry point and deployment, it's an application
If it's a workspace package that other packages import, it's a package
If it's a module with internal logic and clear boundaries that doesn't map to a single package, it's a system
If it's a type or concept that appears in 3+ systems, it's a primitive
If understanding it requires tracing through multiple systems or apps, it's a feature

提供五种视角用于组织代码库深度解析内容。可根据仓库实际情况组合使用，至少选择一种。大多数仓库使用2-3种。强烈推荐使用“功能”视角——这是新工程师最直观的切入点（“这个系统能做什么？”）。即使小型仓库通常也有面向用户或开发者的功能值得记录。仅当仓库是单一用途的库且无独立功能时才跳过该视角。

概念	默认标签	别名	使用场景
可部署单元	`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个以上系统中出现的类型或概念，属于基础组件
若需跨多个系统或应用追踪才能理解，属于功能

Conditional sections

条件章节

Include these based on your judgment after surveying the repo. Skip any that don't apply.

```
api/
```
— if the repo exposes REST, GraphQL, WebSocket, or other APIs
```
deployment/
```
— if there's a non-trivial deployment process (CI/CD, environments, rollback, infrastructure)
```
security/
```
— if there are meaningful trust boundaries (auth, authorization, secrets, input validation)
```
background/
```
— if the repo has meaningful history (design decisions, pitfalls/danger zones, migration context)
```
how-to-monitor/
```
— if the repo runs as a service with logging, metrics, tracing, or alerting infrastructure
```
cleanup-opportunities/
```
— if the repo has dead code, accumulated TODOs/FIXMEs, oversized files, or outdated dependencies. Only include if there is actual content to report (see below)
```
fun-facts.md
```
— easter eggs, origin stories, oldest code, naming origins

根据调研结果判断是否包含以下章节，跳过不适用的章节：

```
api/
```
—— 若仓库暴露REST、GraphQL、WebSocket或其他API
```
deployment/
```
—— 若存在非 trivial 的部署流程（CI/CD、环境、回滚、基础设施）
```
security/
```
—— 若存在重要的信任边界（认证、授权、密钥、输入验证）
```
background/
```
—— 若仓库有重要历史（设计决策、陷阱/危险区域、迁移背景）
```
how-to-monitor/
```
—— 若仓库作为服务运行，包含日志、指标、链路追踪或告警基础设施
```
cleanup-opportunities/
```
—— 若仓库存在死代码、累积的TODO/FIXME、过大文件或过时依赖。仅当有实际内容时才包含（见下文）
```
fun-facts.md
```
—— 彩蛋、起源故事、最古老的代码、命名由来

How to monitor

监控指南

This conditional section documents how to see what the system is doing. Only generate it for repos that run as services with logging, metrics, or tracing infrastructure. Not applicable to libraries, CLI tools, or packages.

Sub-pages:

```
logging.md
```
— where logs go, how to query them, log levels and conventions, structured logging patterns, how to add new log statements
```
metrics.md
```
— what metrics are tracked, key SLIs/SLOs, available dashboards, how to add new metrics
```
tracing.md
```
— distributed tracing setup, how to trace a request end-to-end, span naming conventions, how to instrument new code paths
```
alerting.md
```
— what alerts exist, alert thresholds and rationale, escalation paths, known noisy alerts, how to add new alerts

Skip any sub-page the repo has no infrastructure for. If only one sub-page has content, collapse

how-to-monitor/

into a single

how-to-monitor.md

file instead of a directory.

该条件章节记录如何查看系统运行状态。仅为作为服务运行且包含日志、指标或链路追踪基础设施的仓库生成。不适用于库、CLI工具或包。

子页面：

```
logging.md
```
—— 日志存储位置、查询方式、日志级别与约定、结构化日志模式、添加新日志语句的方法
```
metrics.md
```
—— 追踪的指标、关键SLI/SLO、可用仪表盘、添加新指标的方法
```
tracing.md
```
—— 分布式追踪配置、端到端请求追踪方法、Span命名约定、为新代码路径添加埋点的方法
```
alerting.md
```
—— 告警列表、告警阈值与原因、升级路径、已知误告警、添加新告警的方法

跳过仓库无对应基础设施的子页面。若仅一个子页面有内容，将

how-to-monitor/

合并为单个

how-to-monitor.md

文件，而非目录。

Cleanup opportunities

优化机会

This conditional section surfaces actionable maintenance work. Only generate it if the scan finds meaningful content. Possible sub-pages:

```
dead-ends.md
```
— files, exports, or modules that nothing imports. The code equivalent of a ghost town.
```
todos-and-fixmes.md
```
— accumulated TODO, FIXME, and HACK comments with file locations. Include the oldest ones.
```
complexity-hotspots.md
```
— the largest source files, deepest nesting, or most complex functions. A gentle nudge toward refactoring.
```
dependency-freshness.md
```
— outdated or unmaintained dependencies. The oldest dependency still in use.

Skip any sub-page that has no findings. If only one sub-page has content, collapse

cleanup-opportunities/

into a single

cleanup-opportunities.md

file instead of a directory.

该条件章节列出可执行的维护工作。仅当扫描发现有意义的内容时才生成。可能的子页面：

```
dead-ends.md
```
—— 无任何引用的文件、导出或模块。相当于代码中的“鬼城”。
```
todos-and-fixmes.md
```
—— 累积的TODO、FIXME和HACK注释及文件位置。包含最古老的注释。
```
complexity-hotspots.md
```
—— 最大的源码文件、最深嵌套或最复杂的函数。温和提示需要重构。
```
dependency-freshness.md
```
—— 过时或无人维护的依赖。包含仍在使用的最古老依赖。

跳过无发现的子页面。若仅一个子页面有内容，将

cleanup-opportunities/

合并为单个

cleanup-opportunities.md

文件，而非目录。

Maintainers

维护者页面

Include a top-level

maintainers.md

page that maps subsystems to the people who know them. This page uses two data sources:

CODEOWNERS file (if it exists) — official ownership assignments
Git blame / git log — the 2-3 most recent or frequent committers per directory or subsystem

Present as a table:

markdown

| 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 |

If the repo has no CODEOWNERS file, omit that column and derive all data from git history. If the repo has very few contributors (e.g., a solo project), skip this page entirely.

添加顶级页面

maintainers.md

，映射子系统与对应负责人。页面使用两个数据源：

CODEOWNERS文件（若存在）—— 官方职责分配
Git blame / git log —— 每个目录或子系统的2-3位最新或最频繁提交者

以表格形式呈现：

markdown

| 子系统 | 官方负责人（CODEOWNERS） | 近期贡献者（git历史） | 最后活动时间 |
|---|---|---|---|
| 认证 | @alice | alice, bob | 2周前 |
| CLI | @charlie, @dave | charlie, eve | 3天前 |

若仓库无CODEOWNERS文件，省略该列，所有数据从git历史中提取。若仓库贡献者极少（如个人项目），跳过该页面。

Per-page active contributors

每页活跃贡献者

Each domain page (apps, systems, features, packages, primitives) should include an "Active contributors" byline as the very first line after the page heading, before the Purpose section:

markdown

undefined

每个领域页面（apps、systems、features、packages、primitives）在标题后、Purpose章节前需添加“活跃贡献者”一行：

markdown

undefined

Authentication

认证

Active contributors: alice, bob

活跃贡献者: alice, bob

Purpose

用途

...


Derive the names from CODEOWNERS (if available) merged with the top 2-3 recent committers from git blame for that subsystem's directory. Use first names or GitHub usernames, no @ symbols.

**Exclude bot accounts** from contributor lists — filter out usernames ending in `[bot]` (e.g., `factory-droid[bot]`, `dependabot[bot]`, `github-actions[bot]`). Bots are not people you'd reach out to with questions. This applies to both the per-page active contributors byline and the maintainers page.

**Use the default branch for contributor data.** When deriving contributors from git blame or git log, always query against the default branch (`main` or `dev`), not the current branch. Feature branches skew contributor data toward whoever is working on that branch. Use `git log origin/main -- <path>` or `git log origin/dev -- <path>` to get accurate contributor history.

...


贡献者名称来源于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>`获取准确的贡献者历史。

Bottom sections

底部章节

These appear at the end of every wiki:

```
reference/
```
— configuration, data models, external dependencies
```
maintainers.md
```
— subsystem ownership table (conditional, skip for solo projects; always the very last page)

以下章节出现在所有Wiki的末尾：

```
reference/
```
—— 配置、数据模型、外部依赖
```
maintainers.md
```
—— 子系统职责表（条件性，个人项目跳过；始终为最后一页）

Page ordering

页面排序

The sidebar ordering is critical for navigation. Every page must appear in its defined position — do NOT group childless pages together at the top or bottom.

The full ordering in the wiki is:

overview/ (index, architecture, getting-started, glossary)
by-the-numbers.md (if present)
lore.md (if present)
fun-facts.md (if present)
how-to-contribute/
[organizational lenses, in whatever order makes sense]
[conditional sections: api, deployment, security, how-to-monitor, background, cleanup-opportunities]
reference/
maintainers.md (if applicable, always last)

Ordering rules:

Each page stays in its defined position regardless of whether it has children.
```
by-the-numbers.md
```
appears after
```
overview/
```
even though it has no children, not at the top with other childless pages.
The
```
pageOrder
```
array in
```
.wiki-meta.json
```
must exactly follow this ordering. It controls the sidebar display order.
Within a lens section (e.g.,
```
apps/
```
), order pages from most important to least important. The
```
index.md
```
is always first.
Conditional sections appear in the order listed above (api → deployment → security → how-to-monitor → background → cleanup-opportunities), not alphabetically.

侧边栏排序对导航至关重要。每个页面必须位于指定位置——不要将无子页面的页面集中在顶部或底部。

Wiki的完整排序如下：

overview/（index、architecture、getting-started、glossary）
by-the-numbers.md（若存在）
lore.md（若存在）
fun-facts.md（若存在）
how-to-contribute/
[组织视角，按合理顺序排列]
[条件章节：api、deployment、security、how-to-monitor、background、cleanup-opportunities]
reference/
maintainers.md（若适用，始终最后）

排序规则：

无论是否有子页面，每个页面都保持在指定位置。
```
by-the-numbers.md
```
即使无子页面，也出现在
```
overview/
```
之后，而非与其他无子页面一起放在顶部。
```
.wiki-meta.json
```
中的
```
pageOrder
```
数组必须严格遵循此排序。它控制侧边栏的显示顺序。
在视角章节内（如
```
apps/
```
），页面按重要性从高到低排序。
```
index.md
```
始终排在第一位。
条件章节按上述顺序出现（api → deployment → security → how-to-monitor → background → cleanup-opportunities），而非按字母顺序。

Nesting rules

嵌套规则

Any page can expand into a directory with sub-pages, except the four pages inside
```
overview/
```
(
```
index.md
```
,
```
architecture.md
```
,
```
getting-started.md
```
,
```
glossary.md
```
) which are always single files
Maximum depth: 2 levels from any lens root (e.g.,
```
apps/cli.md
```
or
```
apps/cli/index.md
```
+
```
apps/cli/tui-rendering.md
```
). No deeper.
Every directory must contain an
```
index.md
```
For large repos (50+ source directories or 10+ distinct subsystems), lean toward splitting pages rather than cramming. A 3000-word page covering an entire subsystem is less useful than three focused pages covering its distinct aspects. Critical sub-agents decide whether to create sub-pages based on what they find in the code.
For small repos, default to single pages and only split when a topic has clearly distinct sub-areas
Deployment and security start as single pages; expand to directories only if the repo has enough substance

除
```
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初始为单个页面；仅当仓库有足够内容时才扩展为目录

Naming rules

命名规则

Use lowercase filenames with hyphens:
```
getting-started.md
```
, not
```
GettingStarted.md
```
File names use lowercase with hyphens. No spaces, no uppercase.

文件名使用小写字母和连字符：
```
getting-started.md
```
，而非
```
GettingStarted.md
```
文件名使用小写和连字符，不允许空格和大写字母

Page title rules

页面标题规则

Page titles (the

# Heading

at the top of each

.md

file) should be concise noun phrases that match how the team refers to the thing. The section hierarchy already provides context, so titles should not repeat it.

Don't prepend directory paths. Title is "CLI", not "apps/cli — CLI Architecture".
Don't append generic suffixes. Title is "Apps", not "Apps Overview". Title is "Packages", not "Packages — Overview". The only exception is
```
overview/index.md
```
which may include the project name (e.g., "Factory platform overview").
Don't repeat the parent section name. A page at
```
features/sessions.md
```
is titled "Sessions", not "Features — Sessions".
Match the team's vocabulary. If the team calls it "the daemon", title is "Daemon", not "Background Service Process".
Keep it short. Aim for 1-3 words. If a title needs more, the page probably covers too much and should be split.

页面标题（每个

.md

文件顶部的

# Heading

）应为简洁的名词短语，与团队对该内容的称呼一致。章节层级已提供上下文，标题无需重复。

不要添加目录路径前缀。标题为“CLI”，而非“apps/cli — CLI架构”。
不要添加通用后缀。标题为“Apps”，而非“Apps Overview”。标题为“Packages”，而非“Packages — Overview”。唯一例外是
```
overview/index.md
```
，可包含项目名称（如“Factory平台概述”）。
不要重复父章节名称。
```
features/sessions.md
```
页面的标题为“Sessions”，而非“Features — Sessions”。
匹配团队词汇。若团队称其为“daemon”，标题为“Daemon”，而非“后台服务进程”。
保持简短。目标为1-3个单词。若标题需要更多单词，说明页面涵盖内容过多，应拆分。

3. Generate pages (with sub-agent delegation)

3. 生成页面（子Agent委托）

Page generation uses a top-level agent for orchestration and foundation pages, then delegates domain pages to sub-agents for depth and parallelism.

页面生成由顶级Agent负责编排和基础页面编写，然后将领域页面委托给子Agent以实现深度和并行处理。

Execution 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

1. 调研（顶级Agent）
   结构扫描 + 深度代码扫描
   输出: survey_context
        │
        ▼
2. 规划（顶级Agent）
   确定视角章节，列出所有页面，标记优先级
   输出: page_plan（包含每页摘要的JSON）
        │
        ▼
3. 基础页面（顶级Agent，顺序执行）
   编写: overview/*, how-to-contribute/patterns-and-conventions
   这些页面建立共享词汇和约定
        │
        ├────────────────────────────────────────┐
        ▼                                        ▼
4a. 视角页面（子Agent，并行执行）     4b. 数据页面（子Agent，并行执行）
    关键页面：每个页面分配一个Agent               by-the-numbers
    普通页面：3-5个页面批量分配一个Agent          lore
    每个Agent负责编写页面及必要的子页面           fun-facts
        │                                        │
        ├────────────────────────────────────────┘
        ▼
5. 剩余页面（子Agent，并行执行）
   how-to-contribute/（剩余页面）
   条件章节: api, deployment, security,
     how-to-monitor, background, cleanup-opportunities
   reference/ + maintainers.md
        │
        ▼
6. 组装（顶级Agent）
   交叉链接检查, .wiki-meta.json
        │
        ▼
7. 上传

Step 2: Planning and delegation

步骤2：规划与委托

After the survey, the top-level agent produces a page plan — a structured list of every page the wiki will contain. For each page, the plan includes:

Path — the file path (e.g.,
```
apps/cli/index.md
```
)
Title — the page heading
Criticality —
```
critical
```
(gets a dedicated sub-agent) or
```
normal
```
(batched with related pages)
Content brief — 2-3 sentences describing what the page should cover and what code paths to read
Relevant source paths — specific files/directories the sub-agent should read
Related pages — titles, paths, and one-line summaries of other pages being written, so the agent knows what to link to instead of explaining

Criticality guidelines: Pages covering apps, packages, or features with large codebases, high churn, or central architectural roles are strong candidates for dedicated agents. Examples: a CLI with 50+ source files, a core library imported by most other packages, a feature that spans 5+ directories. The agent uses its judgment from the survey — these are guidelines, not hard rules.

Depth guidelines for sub-agents: A single page should not try to cover a complex subsystem end-to-end. Sub-agents should create sub-pages when:

The subsystem has 3+ clearly distinct internal areas (e.g., a CLI has TUI rendering, exec mode, skills system, session management — each deserves its own page)
A single page would exceed ~2000 words to cover the topic adequately
The subsystem has multiple entry points or distinct user-facing modes

Examples of when to split:

A CLI app with 50+ source files and 4000+ line entry points → sub-pages for each major subsystem (e.g.,
```
cli/tui-rendering.md
```
,
```
cli/exec-mode.md
```
,
```
cli/skills.md
```
,
```
cli/session-management.md
```
)
A backend with distinct API groups, auth system, and job runner → sub-pages for each
A frontend package with 10+ feature modules → sub-pages for the most complex ones

Examples of when NOT to split:

A utility package with 5 files and a single purpose → one page
A simple microservice with one handler → one page
A config or constants package → one page

调研结束后，顶级Agent生成页面计划 —— wiki包含的所有页面的结构化列表。每个页面包含：

路径 —— 文件路径（如
```
apps/cli/index.md
```
）
标题 —— 页面标题
优先级 ——
```
critical
```
（分配独立子Agent）或
```
normal
```
（与相关页面批量分配）
内容摘要 —— 2-3句话说明页面应涵盖的内容及需读取的代码路径
相关源码路径 —— 子Agent需读取的特定文件/目录
相关页面 —— 其他页面的标题、路径及一句话摘要，以便Agent知道应链接而非重复说明

优先级指南：覆盖大型代码库、高变更率或核心架构角色的应用、包或功能页面，适合分配独立Agent。示例：包含50个以上源码文件的CLI、被大多数其他包导入的核心库、跨5个以上目录的功能。Agent根据调研结果判断——这些是指南，而非硬性规则。

子Agent深度指南：单个页面不应试图全面覆盖复杂子系统。当出现以下情况时，子Agent应创建子页面：

子系统有3个以上明显独立的内部领域（如CLI包含TUI渲染、执行模式、技能系统、会话管理——每个都应拥有独立页面）
单个页面需超过约2000字才能充分覆盖主题
子系统有多个入口或不同的面向用户模式

拆分示例：

包含50个以上源码文件和4000+行入口文件的CLI应用 → 为每个主要子系统创建子页面（如
```
cli/tui-rendering.md
```
、
```
cli/exec-mode.md
```
、
```
cli/skills.md
```
、
```
cli/session-management.md
```
）
包含独立API组、认证系统和任务运行器的后端 → 为每个部分创建子页面
包含10个以上功能模块的前端包 → 为最复杂的模块创建子页面

不拆分示例：

包含5个文件且单一用途的工具包 → 单个页面
仅一个处理器的简单微服务 → 单个页面
配置或常量包 → 单个页面

Step 3: Foundation pages

步骤3：基础页面

The top-level agent writes these pages sequentially before any sub-agents run:

```
overview/index.md
```
— project overview
```
overview/architecture.md
```
— system architecture with Mermaid diagrams
```
overview/getting-started.md
```
— prerequisites, install, build, test, run
```
overview/glossary.md
```
— project-specific terms

how-to-contribute/patterns-and-conventions.md

— coding patterns and conventions

These pages establish the shared vocabulary and architectural context that sub-agents reference. They must be complete before delegation begins.

顶级Agent在子Agent运行前顺序编写以下页面：

```
overview/index.md
```
—— 项目概述
```
overview/architecture.md
```
—— 系统架构，含Mermaid图
```
overview/getting-started.md
```
—— 前置条件、安装、构建、测试、运行
```
overview/glossary.md
```
—— 项目特定术语

how-to-contribute/patterns-and-conventions.md

—— 编码模式与约定

这些页面建立子Agent需参考的共享词汇和架构上下文。必须在委托前完成。

Step 4: Sub-agent delegation (parallel)

步骤4：子Agent委托（并行执行）

Two groups of sub-agents run in parallel:

4a. Lens pages — all organizational lens pages (apps, systems, features, packages, primitives):

Critical pages get a dedicated sub-agent each. The sub-agent reads the relevant code, writes the page, and autonomously decides whether sub-pages are warranted. If a topic has clearly distinct sub-areas, the agent creates sub-pages (capped at 2 levels:
```
section/page.md
```
). The top-level agent does NOT pre-plan sub-pages for critical pages — the sub-agent explores and decides.
Normal pages are batched 3-5 per sub-agent, grouped by relatedness (e.g., 3 small packages together, or 2 related features). Batched pages are typically single files without sub-pages.

4b. Data pages — run in parallel with lens pages since they only need git history and source file structure:

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

两组子Agent并行运行：

4a. 视角页面 —— 所有组织视角页面（apps、systems、features、packages、primitives）：

关键页面每个分配一个独立子Agent。子Agent读取相关代码，编写页面，并自主决定是否需要子页面。若主题有明显独立子领域，Agent创建子页面（限制为2层：
```
section/page.md
```
）。顶级Agent不预先规划关键页面的子页面——子Agent自行探索并决定。
普通页面按相关性批量分配，3-5个页面分配一个子Agent（如3个小包、2个相关功能）。批量页面通常为无子页面的单个文件。

4b. 数据页面 —— 与视角页面并行运行，因为仅需git历史和源码文件结构：

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

Step 5: Remaining pages (parallel)

步骤5：剩余页面（并行执行）

After all lens pages complete, spawn sub-agents for:

```
how-to-contribute/
```
remaining pages (development-workflow, testing, debugging, tooling) as one batch
Each conditional section as its own sub-agent or small batch: api, deployment, security, how-to-monitor, background, cleanup-opportunities
```
reference/
```
+
```
maintainers.md
```
as one batch

These pages can now cross-reference lens pages since they're complete.

所有视角页面完成后，为以下内容分配子Agent：

```
how-to-contribute/
```
剩余页面（development-workflow、testing、debugging、tooling）作为一个批次
每个条件章节作为一个子Agent或小批次：api、deployment、security、how-to-monitor、background、cleanup-opportunities
```
reference/
```
+
```
maintainers.md
```
作为一个批次

这些页面现在可交叉引用已完成的视角页面。

Step 6: Assembly

步骤6：组装

The top-level agent does a final pass:

Audit cross-links between pages (fix broken references, add missing links)
Write
```
.wiki-meta.json
```
with final page list and ordering
Verify all directories have
```
index.md
```
files

顶级Agent进行最终检查：

检查页面间的交叉链接（修复无效引用，添加缺失链接）
编写
```
.wiki-meta.json
```
，包含最终页面列表和排序
验证所有目录都有
```
index.md
```
文件

Sub-agent prompt template

子Agent提示模板

Every sub-agent receives a prompt with this structure:

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

每个子Agent收到以下结构的提示：

你正在为[repo]编写wiki页面。

Shared Context

共享上下文

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

[步骤1的survey_context文档——简洁的仓库概述、架构、关键模式、术语表。所有Agent共享相同内容。]

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]

页面: [该Agent负责的页面列表] 优先级: [critical或normal] 内容摘要: [每个页面2-3句话说明需覆盖的内容] 相关源码路径: [需读取的特定文件/目录]

Related Pages (link to these, don't duplicate their content)

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]


The **shared context** is the same for all agents — the compact survey document. The **per-page brief** is tailored by the top-level agent during planning. This ensures no sub-agent re-discovers what the survey already found, and no sub-agent explains what another page covers.

For each page:

遵循页面模板（技能中的3a-3e章节）
最大嵌套深度: 2层（section/page.md）
关键页面：探索代码，若主题有明显独立子领域，创建子页面。编写index.md和子页面。
普通页面：编写单个文件页面，除非复杂度要求拆分
当Mermaid图有助于解释数据流或组件关系时使用
链接上述相关页面，而非重复说明其主题
将输出写入[wiki_dir路径]


**共享上下文**对所有Agent相同——简洁的调研文档。**每页摘要**由顶级Agent在规划阶段定制。这确保子Agent无需重复调研已发现的内容，也无需重复说明其他页面已覆盖的内容。

对于每个页面：

3a. Read the relevant code

3a. 读取相关代码

Open and read the actual source files for the section you are writing. Do not guess or hallucinate file contents. If a file is too large, read the parts that matter for the current section.

打开并读取当前章节对应的实际源码文件。不要猜测或虚构文件内容。若文件过大，读取与当前章节相关的部分。

3b. Write prose

3b. 编写文档

Explain what the code does in plain language. Start with the high-level purpose, then drill into specifics. Every claim should be traceable to a specific file or function.

Each domain page should include these sections (skip any that don't apply to the subsystem):

Active contributors — a one-line byline immediately after the heading (see "Per-page active contributors" in Section 2)
Purpose — what this subsystem does, in 2-3 sentences
Directory layout — a file tree showing the key files and folders
Key abstractions — a table of the most important types (classes, interfaces, traits, structs, functions) with their file path and a one-line description
How it works — the main data/control flow, with a Mermaid diagram if it involves 3+ components
Integration points — how this subsystem connects to others (what it imports, what calls it, what events it emits/listens to)
Entry points for modification — 2-3 sentences telling a developer where to start if they need to change or extend this subsystem

Let the complexity of the subsystem determine how long the page is. A thin wrapper might only need sections 1, 3, and 5. A complex subsystem might need all six with multiple diagrams.

用通俗易懂的语言解释代码功能。从高层用途开始，再深入细节。每个声明都应可追溯到特定文件或函数。

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

活跃贡献者 —— 标题后立即添加一行（见第2节“每页活跃贡献者”）
用途 —— 2-3句话说明该子系统的功能
目录结构 —— 展示关键文件和文件夹的文件树
核心抽象 —— 表格列出最重要的类型（类、接口、trait、结构体、函数）及其文件路径和一句话描述
工作原理 —— 主要数据/控制流，若涉及3个以上组件，添加Mermaid图
集成点 —— 该子系统与其他系统的连接方式（导入的内容、调用它的内容、发送/监听的事件）
修改入口 —— 2-3句话告诉开发者若需修改或扩展该子系统应从何处开始

根据子系统的复杂度决定页面长度。轻量封装可能仅需第1、3、5章节。复杂子系统可能需要所有六个章节及多个图表。

3c. Add Mermaid diagrams

3c. 添加Mermaid图

Use Mermaid diagrams to illustrate:

Architecture — system components and how they connect
Data flows — request lifecycle, event pipelines, processing stages
State machines — authentication flows, order states, build pipelines

Mermaid diagram guidelines:

Use
```
graph TD
```
or
```
graph LR
```
for architecture and flow diagrams
Use
```
sequenceDiagram
```
for request/response flows between services
Use
```
stateDiagram-v2
```
for state machines
Keep diagrams focused — 5 to 15 nodes maximum. Split larger diagrams into multiple smaller ones
Label edges with the action or data being passed
Use subgraphs to group related components

Example:

markdown

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

Do not use Mermaid for simple relationships that a sentence can explain. A diagram should earn its place by showing something that is hard to describe in words.

使用Mermaid图展示：

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

Mermaid图指南：

使用
```
graph TD
```
或
```
graph LR
```
展示架构和流程图
使用
```
sequenceDiagram
```
展示服务间的请求/响应流
使用
```
stateDiagram-v2
```
展示状态机
保持图的聚焦——最多5-15个节点。将大图拆分为多个小图
为边标注传递的动作或数据
使用subgraph分组相关组件

示例：

markdown

```mermaid
graph LR
    Client -->|HTTP请求| APIGateway
    APIGateway -->|验证 + 路由| Handler
    Handler -->|查询| Database
    Database -->|行数据| Handler
    Handler -->|JSON响应| Client
```

不要用Mermaid图展示简单到一句话就能说明的关系。图应展示难以用文字描述的内容，才值得添加。

3d. Add file references

3d. 添加文件引用

Each domain page must include a "Key source files" table listing the most important files for that subsystem:

markdown

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

The table should cover whatever files are important — don't pad it with trivial files and don't skip files just because there are few.

Reference every file you mention in prose. When mentioning a class, interface, function, or type, include its file path in backticks on first mention. Readers should be able to go from the documentation to the code in one step.

每个领域页面必须包含**“核心源码文件”**表格，列出该子系统最重要的文件：

markdown

| 文件 | 用途 |
|---|---|
| `src/auth/middleware.ts` | 验证JWT令牌，将用户信息附加到请求 |
| `src/auth/token-service.ts` | 令牌创建、刷新与吊销 |

表格应覆盖所有重要文件——不要用无关文件填充，也不要遗漏重要文件。

在文档中提及的每个文件都要添加引用。首次提及类、接口、函数或类型时，在反引号中包含其文件路径。读者应能从文档一步跳转到代码。

3e. Cross-link pages

3e. 交叉链接页面

Link between pages using relative markdown links:

markdown

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

Each page should link to at least one other page. The reader should be able to navigate the wiki without using the sidebar.

使用相对Markdown链接在页面间跳转：

markdown

关于认证中间件如何与API层集成的详细信息，
请查看[API认证](../api/authentication.md)。

每个页面应至少链接到一个其他页面。读者应无需使用侧边栏即可导航wiki。

3f. Fun facts content

3f. 趣味内容

The

fun-facts.md

page is optional but encouraged. Pick the 3-5 most interesting topics for the specific repo from this list:

Oldest surviving code — find the oldest file or function via git blame. How old is it? Has it changed much?
Dependency archaeology — the oldest dependency still in use, or the one with the most major version bumps
Naming origins — why is the project or its internal tools named what they are? Engineers name things weirdly and there's usually a story
TODO/FIXME count — how many TODO/FIXME/HACK comments exist? What's the oldest one?
The longest file — which source file has the most lines? A gentle call-out that doubles as a refactoring hint

Do not force all of these into every wiki. Pick only the ones where the repo has something genuinely interesting to say. If nothing stands out, skip fun-facts entirely.

fun-facts.md

页面可选但推荐。从以下列表中为特定仓库选择3-5个最有趣的主题：

最古老的代码 —— 通过git blame找到最古老的文件或函数。存在多久？变更频繁吗？
依赖溯源 —— 仍在使用的最古老依赖，或主版本更新次数最多的依赖
命名由来 —— 项目或内部工具的命名原因？工程师的命名通常很特别，背后通常有故事
TODO/FIXME数量 —— 存在多少TODO/FIXME/HACK注释？最古老的注释是什么？
最长文件 —— 哪个源码文件行数最多？既是提示也是重构建议

不要强行将所有主题添加到每个wiki中。仅选择仓库有真正有趣内容的主题。若没有突出内容，跳过趣味页面。

4. Write the meta file

4. 编写元文件

After generating all pages, create

.wiki-meta.json

in the wiki directory root. The

pageOrder

array is critical -- it controls the display order of pages in the wiki sidebar. List every generated file path in the exact order you want them to appear. Without this, pages sort alphabetically.

json

{
  "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"
  ]
}

The example above is abbreviated. In practice, list every

.md

file in the wiki directory. The order must match the page ordering defined in Section 2: overview → by-the-numbers → lore → fun-facts → how-to-contribute → lenses → conditional → reference → maintainers.

.wiki-meta.json

。

pageOrder

数组至关重要——它控制wiki侧边栏的页面显示顺序。按期望的显示顺序列出所有生成的文件路径。若没有该数组，页面将按字母顺序排序。

json

{
  "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 → 视角 → 条件章节 → reference → maintainers。

5. Upload

5. 上传

Standard upload (local wiki directory)

标准上传（本地wiki目录）

When the user wants to keep a local copy (the default):

bash

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

Arguments:

```
--repo-url
```
— the repository URL (the remote origin, e.g.,
```
https://github.com/org/repo
```
)
```
--wiki-dir
```
— path to the directory containing the generated markdown files
```
--cleanup
```
— (optional) delete the wiki directory after a successful upload

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

bash

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

参数：

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

Remote-only upload (--no-local handling)

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

When the user asks to generate the wiki without leaving files on disk (e.g., the user says "don't leave files locally" or passes a

--no-local

flag):

bash

undefined

当用户要求生成wiki但不在磁盘上保留文件（如用户说“不要在本地保留文件”或传递

--no-local

标志）：

bash

undefined

Create a temporary directory

创建临时目录

WIKI_TMPDIR=$(mktemp -d)

Write all wiki files to the temporary directory instead of ./droid-wiki

将所有wiki文件写入临时目录，而非./droid-wiki

... generate pages into $WIKI_TMPDIR ...

... 将页面生成到$WIKI_TMPDIR ...

Upload with --cleanup to remove the temp directory after success

使用--cleanup标志在成功上传后删除临时目录

droid wiki-upload
--repo-url "$REPO_URL"
--wiki-dir "$WIKI_TMPDIR"
--cleanup


The `--cleanup` flag tells the CLI to delete the `--wiki-dir` directory after a successful upload. If the upload fails, the directory is preserved so the user can retry.

droid wiki-upload
--repo-url "$REPO_URL"
--wiki-dir "$WIKI_TMPDIR"
--cleanup


`--cleanup`标志告诉CLI在成功上传后删除`--wiki-dir`目录。若上传失败，目录将保留以便用户重试。

Content principles

内容原则

Progressive disclosure

渐进式披露

Start every page with a 1–3 sentence summary of what the page covers. Follow with an overview section that explains the main concepts. Put implementation details, edge cases, and configuration options later in the page.

A reader skimming the first paragraph of each page should get a useful overview of the entire system.

每个页面开头用1-3句话总结页面内容。接着用概述章节解释核心概念。将实现细节、边缘情况和配置选项放在页面后半部分。

读者浏览每个页面的第一段应能了解整个系统的有用概述。

Page size limit

页面大小限制

Keep individual pages under 500KB. If a page approaches this limit, split it into sub-pages. For example, a large API reference page could become a directory with one page per endpoint group.

单个页面大小不超过500KB。若页面接近该限制，拆分为子页面。例如，大型API参考页面可拆分为按端点分组的目录。

Human writing rules

人性化写作规则

Write documentation that reads like a person wrote it. Technical docs are especially prone to AI-sounding patterns because the subject matter is dry. Fight that tendency.

Specific rules to follow:

Cut inflated significance. Do not write "serves as a testament to," "pivotal role in the evolving landscape," "setting the stage for," or "underscores the importance of." Just state what the thing does.

Bad: "The authentication module serves as a critical pillar in the application's security landscape." Good: "The authentication module validates JWT tokens and attaches user context to requests."
Cut promotional language. Do not write "boasts," "vibrant," "rich," "profound," "showcasing," "exemplifies," "commitment to," "groundbreaking," "renowned," or "breathtaking." Technical docs describe; they do not sell.
Bad: "The codebase boasts a rich set of vibrant utilities that showcase the team's commitment to developer experience." Good: "The
```
utils/
```
directory has helpers for string formatting, date parsing, and retry logic."
Kill superficial -ing analyses. Do not tack "highlighting," "ensuring," "reflecting," "symbolizing," "showcasing," or "contributing to" onto sentences to add fake depth.

Bad: "The service processes events asynchronously, ensuring scalability while highlighting the system's robust architecture." Good: "The service processes events asynchronously. It pulls from an SQS queue and can handle ~500 events/second per instance."
Avoid AI vocabulary words. These words appear far more often in AI-generated text: additionally, crucial, delve, emphasizing, enduring, enhance, fostering, garner, interplay, intricate/intricacies, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore (verb), vibrant. Replace them with plainer alternatives.
Skip the rule of three. Do not force ideas into groups of three to sound comprehensive (e.g., "innovation, inspiration, and industry insights"). If there are two things, list two. If there are four, list four.
Do not use copula avoidance. Write "X is Y" or "X has Y" instead of "X serves as Y," "X stands as Y," "X represents Y," "X boasts Y," "X features Y," or "X offers Y."

Bad: "The config module serves as the central hub for environment variable management." Good: "The config module reads environment variables and exports typed constants."
Do not use negative parallelisms. Avoid "It's not just X, it's Y" and "Not only X but Y" constructions.
Use sentence case in headings. Write "Getting started with authentication," not "Getting Started With Authentication."
Cut filler phrases. Replace "in order to" with "to," "due to the fact that" with "because," "it is important to note that" with nothing (just state the fact).
Be specific, not vague. Replace "industry experts believe" with a concrete reference. Replace "several components" with the actual component names. Replace "various configurations" with the actual config options.
Avoid em dash overuse. Use commas or periods instead of em dashes (—) in most cases. One em dash per page is fine; three or more is a pattern.
Do not use chatbot artifacts. Never write "I hope this helps," "Let me know if," "Here is an overview of," "Certainly!", or "Great question!" These are conversation patterns, not documentation.

编写看起来像人写的文档。技术文档尤其容易出现AI生成的生硬风格，因为主题本身枯燥。需避免这种倾向。

具体规则：

避免夸大表述。不要写“作为……的证明”、“在不断演变的格局中发挥关键作用”、“为……奠定基础”或“强调……的重要性”。直接说明事物的功能。

错误示例：“认证模块是应用安全格局的关键支柱。” 正确示例：“认证模块验证JWT令牌并将用户上下文附加到请求。”
避免宣传性语言。不要写“拥有”、“充满活力的”、“丰富的”、“深刻的”、“展示”、“体现”、“致力于”、“开创性的”、“著名的”或“惊人的”。技术文档用于描述，而非推销。
错误示例：“代码库拥有一套丰富的实用工具，展示了团队对开发者体验的承诺。” 正确示例：“
```
utils/
```
目录包含字符串格式化、日期解析和重试逻辑的辅助函数。”
避免表面化的-ing分析。不要在句子末尾添加“突出”、“确保”、“反映”、“象征”、“展示”或“有助于”来制造虚假深度。

错误示例：“服务异步处理事件，确保可扩展性同时突出系统的强大架构。” 正确示例：“服务异步处理事件。它从SQS队列拉取数据，每个实例每秒可处理约500个事件。”
避免AI常用词汇。这些词汇在AI生成文本中出现频率远高于人类写作：additionally, crucial, delve, emphasizing, enduring, enhance, fostering, garner, interplay, intricate/intricacies, landscape（抽象义）, pivotal, showcase, tapestry（抽象义）, testament, underscore（动词）, vibrant。用更平实的词汇替代。
避免强制三分法。不要为了显得全面而将想法强行分成三组（如“创新、灵感、行业洞察”）。若有两个点，列出两个；若有四个点，列出四个。
避免冗余表述。用“X是Y”或“X有Y”替代“X作为Y”、“X代表Y”、“X拥有Y”、“X具备Y”或“X提供Y”。

错误示例：“配置模块是环境变量管理的中心枢纽。” 正确示例：“配置模块读取环境变量并导出类型化常量。”
避免否定平行结构。避免使用“不仅是X，更是Y”和“不仅X而且Y”的结构。
标题使用句子大小写。写“Getting started with authentication”，而非“Getting Started With Authentication”。
删除填充短语。用“to”替代“in order to”，用“because”替代“due to the fact that”，删除“it is important to note that”（直接陈述事实）。
具体而非模糊。用具体引用替代“行业专家认为”。用实际组件名称替代“多个组件”。用实际配置选项替代“各种配置”。
避免过度使用破折号。大多数情况下用逗号或句号替代破折号（—）。每页使用一个破折号即可；三个或以上属于不良模式。
避免聊天机器人痕迹。永远不要写“希望这对你有帮助”、“若有疑问请告知”、“以下是……概述”、“当然！”或“好问题！”。这些是对话模式，不属于文档。

Concrete file references

具体文件引用

Every factual claim about the code should point to the source file. Do not say "the system handles authentication" without saying where. Do not say "the database schema includes a users table" without pointing to the migration or model file.

If you cannot find the file that implements something, say so: "The retry logic is referenced in

config.ts

but the implementation was not found in the current codebase."

关于代码的每个事实性声明都应指向源码文件。不要只说“系统处理认证”而不说明位置。不要只说“数据库模式包含users表”而不指向迁移或模型文件。

若找不到实现某功能的文件，如实说明：“重试逻辑在

config.ts

中被引用，但未在当前代码库中找到实现。”

Mermaid diagram usage

Mermaid图使用

Include at least one Mermaid diagram in the architecture page. Include diagrams in domain pages when they help explain data flows or component relationships. Do not add diagrams to every page — a page about configuration options or environment variables probably does not need one.

架构页面至少包含一个Mermaid图。当Mermaid图有助于解释数据流或组件关系时，在领域页面中添加。不要为每个页面都添加图——关于配置选项或环境变量的页面可能不需要图。

File structure specification

文件结构规范

The generated wiki follows this layout:

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

生成的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

├── overview/ # 入门内容 │ ├── index.md # 项目概述 │ ├── architecture.md # 系统架构，含Mermaid图 │ ├── getting-started.md # 前置条件、安装、构建、测试、运行 │ └── glossary.md # 项目特定术语及词汇 ├── by-the-numbers.md # 代码库统计快照 ├── lore.md # 时间线、发展阶段、已废弃功能、重写记录 ├── fun-facts.md # 彩蛋、起源故事、最古老的代码 ├── how-to-contribute/ # 代码贡献指南 │ ├── 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

├── <apps|services|applications>/ # 可部署单元 │ ├── index.md │ ├── <simple-app>.md # 简单应用的单个页面 │ └── <complex-app>/ # 复杂应用的目录 │ ├── index.md │ └── <sub-topic>.md ├── <systems|modules|subsystems>/ # 内部构建块 │ ├── index.md │ ├── <simple-system>.md │ └── <complex-system>/ # 复杂子系统的第三层目录 │ ├── index.md │ └── <sub-topic>.md ├── <features|capabilities|workflows>/ # 跨领域功能 │ ├── index.md │ ├── <simple-feature>.md │ └── <complex-feature>/ # 跨多个系统的功能需子页面 │ ├── index.md │ └── <sub-topic>.md ├── <packages|libraries|crates>/ # 工作区包 │ ├── index.md │ ├── <simple-package>.md │ └── <complex-package>/ │ ├── index.md │ └── <sub-topic>.md ├── <primitives|core-concepts|entities>/ # 基础领域对象 │ ├── index.md │ └── *.md

Conditional sections (LLM judgment)

条件章节（LLM判断）

├── 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

├── api/ # 若仓库暴露API │ ├── index.md │ └── *.md ├── deployment.md # 单个页面或目录 ├── security.md # 单个页面或目录 ├── how-to-monitor/ # 日志、指标、链路追踪、告警（仅服务类项目） │ ├── index.md │ ├── logging.md # 日志位置、查询方式、日志级别 │ ├── metrics.md # 追踪指标、仪表盘、SLI │ ├── tracing.md # 分布式追踪、请求追踪 │ └── alerting.md # 告警、阈值、升级路径、误告警 ├── background/ # 设计决策、陷阱、迁移背景 │ ├── index.md │ └── *.md ├── cleanup-opportunities/ # 死代码、TODO、复杂度热点、过时依赖 │ ├── index.md │ ├── dead-ends.md # 未使用的文件、导出、模块 │ ├── todos-and-fixmes.md # 累积的TODO/FIXME/HACK注释 │ ├── complexity-hotspots.md # 最大文件、最深嵌套 │ └── dependency-freshness.md # 过时或无人维护的依赖

Always present (bottom)

必选内容（底部）

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


**Rules:**

- Every `.md` file must start with a level-1 heading (`# Title`). The upload tool extracts the title from this heading.
- Every directory must contain an `index.md`.
- File names use lowercase with hyphens. No spaces, no uppercase.
- The `.wiki-meta.json` file is for tracking purposes and is not uploaded as a page.
- The four pages inside `overview/` (`index.md`, `architecture.md`, `getting-started.md`, `glossary.md`) are always single files. All other pages can expand into directories with sub-pages.
- Maximum tree depth: 2 levels from any lens root (e.g., `apps/cli/command-structure.md`). No deeper.
- For large repos, critical sub-agents decide whether to split into sub-pages. A complex subsystem like an editor core or extension host should have its own directory with focused sub-pages, not a single monolithic page.
- Maximum 200 pages per wiki run. If a project needs more, prioritize the most important subsystems.

├── reference/ │ ├── index.md │ ├── configuration.md │ ├── data-models.md │ └── dependencies.md └── maintainers.md # 子系统职责表（条件性，始终最后）


**规则**：

- 每个`.md`文件必须以一级标题（`# Title`）开头。上传工具从该标题提取页面标题。
- 每个目录必须包含`index.md`。
- 文件名使用小写字母和连字符，不允许空格和大写字母。
- `.wiki-meta.json`文件用于追踪，不上传为页面。
- `overview/`中的四个页面（`index.md`、`architecture.md`、`getting-started.md`、`glossary.md`）始终为单个文件。其他页面均可扩展为包含子页面的目录。
- 最大树深度：从任何视角根目录开始最多2层（如`apps/cli/command-structure.md`）。不允许更深嵌套。
- 对于大型仓库，关键子Agent决定是否拆分为子页面。编辑器核心或扩展宿主等复杂子系统应有独立目录和聚焦的子页面，而非单个庞大页面。
- 每次wiki运行最多生成200个页面。若项目需要更多页面，优先覆盖最重要的子系统。

wiki

Original

Translation

Wiki generation

Wiki生成

1. Survey the repository

1. 调研代码仓库

Pass 1: Structural scan

第一阶段：结构扫描

Pass 2: Deep code scan

第二阶段：深度代码扫描

Exhaustive subsystem discovery

全面发现子系统

Often-missed areas

易遗漏的领域

Survey output

调研输出

Coverage cross-check

覆盖范围交叉校验

2. Plan the table of contents

2. 规划目录结构

Always-present pages

必选页面

By the numbers

数据统计页面

Lore

历史页面

Organizational lenses

组织视角

Conditional sections

条件章节

How to monitor

监控指南

Cleanup opportunities

优化机会

Maintainers

维护者页面

Per-page active contributors

每页活跃贡献者

Authentication

认证

Purpose

用途

Bottom sections

底部章节

Page ordering

页面排序

Nesting rules

嵌套规则

Naming rules

命名规则

Page title rules

页面标题规则

3. Generate pages (with sub-agent delegation)

3. 生成页面（子Agent委托）

Execution DAG

执行流程图

Step 2: Planning and delegation

步骤2：规划与委托

Step 3: Foundation pages

步骤3：基础页面

Step 4: Sub-agent delegation (parallel)

步骤4：子Agent委托（并行执行）

Step 5: Remaining pages (parallel)

步骤5：剩余页面（并行执行）

Step 6: Assembly

步骤6：组装

Sub-agent prompt template

子Agent提示模板

Shared Context

共享上下文

Your Assignment

你的任务

Related Pages (link to these, don't duplicate their content)

相关页面（链接这些页面，不要重复内容）

Rules

规则

3a. Read the relevant code

3a. 读取相关代码

3b. Write prose