code-wiki

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.md
• scan → 读取 references/workflow-scan.md
• deep → 读取 references/workflow-deep.md
• query → 读取 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 有五种操作，对应五种用户意图：

1. init（初始化）——第一次面对一个仓库：分析仓库概貌、和用户确认扫描范围、搭建 wiki 骨架、生成扫描清单。不立刻开始扫描文件，先让用户确认计划。
2. scan（扫描）——基于 hypothesis.md 驱动的分层阅读。每批 sub-agent 完成后强制走反思步骤（见 references/reflection-checklist.md），更新 hypothesis、检查老页面一致性、决定下一批读什么。这是主力操作。
3. deep（深度扫描）——针对用户指定的内容或目录，进行算法和数据流的深度扫描。两阶段循环：深度阅读（逐函数展开、数据命名变更、hardcode 分析）→ 串联验证（从头到尾串联，发现遗漏则回退补充）。最终产出保存到 wiki/deep/。详见 references/workflow-deep.md。
4. query（查询）——用户针对已建好的 wiki 提问。优先读 index.md 和 architecture.md 定位，再读具体页面。好答案应该回填到 concepts/ 或 refactor.md。
5. lint（健康检查）——检查 wiki 内部的矛盾、过时内容、孤儿页、缺失的交叉引用、应该但还没建的概念页，并给出补扫建议。

详细指南见各 references/workflow-*.md 文件，命令解析段已指定了每个子命令对应的文件。不要凭记忆——这些文件里有具体的检查项和模板。

语言约定

所有 wiki 产出一律使用中文（简体）。代码标识符（类名、函数名、变量名、文件名、路径）保持原样不翻译。技术术语如果有公认的中文译法就用中文，否则保留英文（例如 "middleware"、"closure" 可以直接用）。注释引用代码中的英文注释时，可以原样引用再附一句中文解释。

整体感原则：hypothesis 驱动

这个 skill 的扫描不是线性文件遍历，而是假设驱动的阅读：

1. init 阶段产出 hypothesis v1（对项目的粗糙但全局的猜测）
2. 每批扫描由 hypothesis 决定"读哪些文件最能压缩不确定性"
3. 每批扫描后走反思步骤，更新 hypothesis（可能整段重写核心抽象/数据流）
4. sub-agent 读文件时会拿到当前 hypothesis 作为 preamble，带着假设去读，并在汇报里明确说"证实/推翻/新观察"
5. 老页面在每次反思时被检查一致性，必要时整段重写（不是追加）

详见 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。