| name | code-wiki |
| description | 为代码仓库增量构建中文 wiki（./wiki/ 目录），梳理架构、数据流，辅助理解和重构。
触发词：理解代码仓库、梳理架构、生成文档/wiki、读懂代码、分析项目结构。
即使未提及"wiki"，只要意图是系统性理解代码仓库或为重构做准备，都应触发。
命令：init, scan, deep, query, lint。
|
| argument-hint | init | scan | deep | query | lint |
| allowed-tools | ["Bash","Read","Write","Edit","AskUserQuestion","Grep","Glob","Agent"] |
命令解析
从 $ARGUMENTS 中解析用户意图，映射到以下子命令：
| 用户输入(示例) | 子命令 |
|---|
init, 初始化, 开始建 wiki, 帮我分析这个仓库, 理解这个代码仓库, 梳理项目架构, 给这个项目生成文档 | init |
init <路径>(如 init core/ 或 init core/dag/executor.py) | init,附带 --folder 或 --file(详见下方) |
scan, 扫描, 扫一下, 继续扫, 扫剩余文件, 增量扫描 | scan |
deep, 深度, 深入, 详细分析 xxx, 深挖 xxx, 深入看 xxx 的数据流, 详细分析 xxx 的算法 | deep |
query, 查询, 问问, xxx 是怎么工作的, xxx 和 yyy 是什么关系 | query |
lint, 健康检查, 检查 wiki, 检查一下 wiki 的一致性, lint 一下 | lint |
歧义消解： 如果没有提供子命令且无法判断意图，wiki/ 目录不存在时默认走 init，已存在时默认走 query。如果用户输入包含"深入"/"详细"/"深挖"等词且 wiki/ 已存在，走 deep。
路径参数提取： 如果 $ARGUMENTS 中包含以 / 分隔的路径片段，提取为 --folder 或 --file 参数。路径含 . 和扩展名映射为 --file，否则映射为 --folder。这些参数只用于 init 和 deep 阶段（init 传给 scan.py init，deep 用来确定深度扫描范围）。
确定子命令后，必须先读取对应的 reference 文件再继续：
init → 读取 references/workflow-init.mdscan → 读取 references/workflow-scan.mddeep → 读取 references/workflow-deep.mdquery → 读取 references/workflow-query-lint.md（查询部分）lint → 读取 references/workflow-query-lint.md（健康检查部分）
未读取对应 reference 文件前不得继续执行。
Code Wiki：为代码仓库构建可持续维护的中文 Wiki
这个 skill 在做什么
这个 skill 把 "LLM Wiki" 的思路应用到代码仓库上：不是在每次提问时临时检索代码，而是增量式地构建并持续维护一个位于 ./wiki/ 目录下的结构化中文 markdown 知识库。这个 wiki 是一个会不断累积的工件——交叉引用、架构提炼、数据流梳理、重构建议都已经沉淀在里面，不需要每次重新推导。
用户的使用场景通常是：面对一个陌生的或结构不清晰的代码仓库，他们想在动手重构之前先把它摸清楚。本 skill 就是用来干这件事的。
核心分工：
- 用户：决定扫描范围、指导重点、审阅结果、提出问题
- 你（Claude）：阅读源码、提炼架构、写 wiki 页面、维护索引和交叉引用
- wiki 本身：用户理解代码的"地图"，也是重构的起点
三层架构
<代码仓库根目录>/
├── <源码> ← **只读，永远不改**
├── wiki/ ← 本 skill 维护的全部产物
│ ├── README.md ← wiki 入口页，整体概览
│ ├── index.md ← 页面目录（内容导向）
│ ├── log.json ← 处理日志（JSON 数组，append-only）
│ ├── hypothesis.md ← agent 的工作假设（心智模型），每批扫描后更新
│ ├── architecture.md ← 架构总览 + 数据流
│ ├── refactor.md ← 重构建议清单（坏味道、耦合点等）
│ ├── files/ ← 每个被扫描的源码文件对应一页
│ │ └── <路径映射>.md
│ ├── modules/ ← 每个模块/目录一页
│ │ └── <模块名>.md
│ ├── concepts/ ← 静态结构：数据结构、领域实体、设计模式、术语
│ │ └── <概念名>.md
│ ├── algorithm/ ← 动态过程：核心算法、数据处理流水线、关键计算逻辑
│ │ └── <算法名>.md
│ └── deep/ ← 深度分析：针对特定主题的算法/数据流纵深剖析
│ └── <主题名>.md
└── .code-wiki/ ← 脚本和状态
├── scan.py ← 扫描器脚本
└── state.json ← 增量状态（文件哈希、最后处理时间）
四类页面的区别很重要，务必遵守：
- files/：以"这个文件是做什么的"为中心。对于只做数据转换、胶水代码、样板代码的文件，一小段甚至一句话就够了，不要浪费篇幅。对于承载核心逻辑的文件，提炼关键函数/类和它们的职责，而不是抄代码。
- modules/：以"这个模块对外承担什么职责"为中心。模块是用户理解项目的主要单位，这一层要写得扎实：对外接口、内部结构、和其他模块的关系、数据流入流出。
- concepts/：静态结构。跨文件的领域实体、核心数据结构、术语定义、重要的设计模式。帮助用户"跳出文件看系统骨架"。
- algorithm/：动态过程。核心算法（通用或业务特有）、数据处理流水线、关键计算逻辑。以"输入 X 经过什么步骤变成输出 Y"为中心，包含步骤、复杂度、关键不变量、边界条件、为什么这么设计。这是"核心处理"的归宿——凡是"有一定计算复杂度、值得把步骤写清楚"的逻辑都往这里放。
concepts/ 和 algorithm/ 的分工规则：优先放 algorithm/。如果一个东西同时是概念又是算法（例如"任务调度"既是个领域术语也是一段有状态的处理逻辑），把主体写到 algorithm/，在 concepts/ 里只留一段 1-3 行的短指针指过去。不要两边都写详细版，会漂移。
什么时候不写 algorithm/ 页："宁缺毋滥"只在确实没有的时候适用——典型的 CRUD/胶水项目可能整个 algorithm/ 都空着是合理的。但当项目里出现复杂处理逻辑（状态机、并发模型、插值/采样、调度算法、复杂解析、数学计算等）时，必须建 algorithm 页。判断标准：如果你在 architecture.md 里给某个机制写了超过 5 行的解释，这个机制就值得一个独立的 algorithm 页（architecture.md 只放 1-2 行的指针指过去）。
modules 页不可省略：modules 页是用户理解项目的主干路径，不能省略。规则：任何被扫描的、包含 ≥ 2 个有实质内容的源文件的目录，必须有对应的 modules 页。这条是硬约束，不受"宁缺毋滥"约束。
工作流总览
整个 skill 有五种操作，对应五种用户意图：
- init（初始化）——第一次面对一个仓库：分析仓库概貌、和用户确认扫描范围、搭建 wiki 骨架、生成扫描清单。不立刻开始扫描文件，先让用户确认计划。
- scan（扫描）——基于 hypothesis.md 驱动的分层阅读。每批 sub-agent 完成后强制走反思步骤（见
references/reflection-checklist.md），更新 hypothesis、检查老页面一致性、决定下一批读什么。这是主力操作。
- deep（深度扫描）——针对用户指定的内容或目录，进行算法和数据流的深度扫描。两阶段循环：深度阅读（逐函数展开、数据命名变更、hardcode 分析）→ 串联验证（从头到尾串联，发现遗漏则回退补充）。最终产出保存到
wiki/deep/。详见 references/workflow-deep.md。
- query（查询）——用户针对已建好的 wiki 提问。优先读
index.md 和 architecture.md 定位，再读具体页面。好答案应该回填到 concepts/ 或 refactor.md。
- lint（健康检查）——检查 wiki 内部的矛盾、过时内容、孤儿页、缺失的交叉引用、应该但还没建的概念页，并给出补扫建议。
详细指南见各 references/workflow-*.md 文件，命令解析段已指定了每个子命令对应的文件。不要凭记忆——这些文件里有具体的检查项和模板。
语言约定
所有 wiki 产出一律使用中文（简体）。代码标识符（类名、函数名、变量名、文件名、路径）保持原样不翻译。技术术语如果有公认的中文译法就用中文，否则保留英文（例如 "middleware"、"closure" 可以直接用）。注释引用代码中的英文注释时，可以原样引用再附一句中文解释。
整体感原则：hypothesis 驱动
这个 skill 的扫描不是线性文件遍历，而是假设驱动的阅读：
- init 阶段产出 hypothesis v1（对项目的粗糙但全局的猜测）
- 每批扫描由 hypothesis 决定"读哪些文件最能压缩不确定性"
- 每批扫描后走反思步骤，更新 hypothesis（可能整段重写核心抽象/数据流）
- sub-agent 读文件时会拿到当前 hypothesis 作为 preamble，带着假设去读，并在汇报里明确说"证实/推翻/新观察"
- 老页面在每次反思时被检查一致性，必要时整段重写（不是追加）
详见 references/hypothesis-guide.md 和 references/reflection-checklist.md。
提炼原则：架构和数据流优先
这个 skill 的一个核心定位是：帮助用户理解结构复杂或缺乏文档的代码仓库。
architecture.md 是目录式鸟瞰图，不是详解仓库
architecture.md 的角色是目录式的鸟瞰图，不是详解仓库。每个章节最多 5-10 行，具体内容用链接指向 modules/、concepts/、algorithm/ 页。如果 agent 发现自己在 architecture.md 里某个章节写了超过 10 行，必须把超出部分拆出去建独立页（modules/concepts/algorithm），architecture.md 里只留 1-2 行的指针指过去。
提炼架构和数据流，不是逐行解说
你的任务不是复述代码，而是还原设计意图和数据流动。具体来说：
- 识别核心路径：数据是从哪里进来的？经过哪些关键变换？到哪里去？把这条主干画出来（可以用 mermaid 流程图，或纯文字步骤）。
- 识别架构骨架：哪些类/模块是"脊柱"？它们之间怎么调用？
- 对无聊代码只给一句话：纯粹的 DTO、getter/setter、格式转换、字符串拼接、日志包装——这些在 files 页里一句"做 X 到 Y 的字段映射"就够了，不要展开，不要让它们稀释你对核心逻辑的描述。
- 对核心代码给细致描述：业务规则、状态机、并发控制、缓存策略、错误恢复、关键算法——这些要写透，包括"为什么这样写"和"哪里看起来可疑"。
- 可疑点要记下来：看到明显的 bug、死代码、可疑的错误处理、TODO、注释和实现不一致——都记到
refactor.md，不要让它们淹没在文件说明里。
详细的提炼方法见 references/refactor-guide.md。
