Code Wiki
为任意代码库生成 wiki 文档 + Mermaid 图表。
Skill 元数据
| 来源 | Optional(可选)— 使用 kopi skills install official/software-development/code-wiki 安装 |
| 路径 | optional-skills/software-development/code-wiki |
| 版本 | 0.1.0 |
| 作者 | Teknium (teknium1), KOPI AI AGENT |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | Documentation, Mermaid, Architecture, Diagrams, Wiki, Code-Analysis |
| 相关 skill | codebase-inspection, github-repo-management |
参考:完整 SKILL.md
以下是当此 skill 被触发时 Kopi Agent 加载的完整 skill 定义。这就是 skill 处于激活状态时 agent 所看到的指令。
Code Wiki Skill
为任意代码库生成全面的 wiki — 概览、架构、逐模块深入解析、Mermaid 类图和时序图。灵感来自 Google CodeWiki,但适用于本地仓库、私有仓库以及任何语言。仅使用 Kopi Agent 现有工具(terminal、read_file、search_files、write_file);无需 Docker、无需外部服务、无额外依赖。
此 skill 生成参考文档(是什么/如何做)。它不生成战略性的叙述性内容(为什么 — 那属于另一个 skill)。
何时使用
- 用户说“为这个代码库写文档”、“生成 wiki”、“绘制架构图”
- 正在熟悉一个陌生仓库,需要结构化的参考资料
- 用户指向一个 GitHub URL 并请求生成文档
- 需要一个稳定的产物(markdown + Mermaid),可在 GitHub 上渲染
请勿在以下场景使用:
- 单文件或单函数的文档 — 直接回答即可
- 某个特定端点的 API 参考 — 使用
read_file并在回答中直接给出 - 战略性的“为什么它会存在”叙述 — 不同的 skill,不同的目的
- 用户在本次会话中正在积极开发的代码库 — 就在问题出现时逐一回答
前提条件
- 无需环境变量。
- PATH 中需要
git,用于仓库 SHA 跟踪和远程克隆。 - 可选:
pygount,用于语言占比统计(参见codebase-inspectionskill)。
如何运行
通过 terminal 工具从目标仓库的根目录发起调用,然后使用 read_file / search_files / write_file 来生成 wiki。默认输出位置是 ~/.kopi/wikis/<repo-name>/。只有当用户明确要求时,才写入仓库(docs/wiki/)。
快速参考
| 步骤 | 操作 |
|---|---|
| 1 | 确定目标 — 本地 cwd、给定路径,或 git clone --depth 50 <url> 到临时目录 |
| 2 | 扫描结构 — ls、find -maxdepth 3、manifest 文件、README |
| 3 | 选择 8–10 个模块进行文档化 |
| 4 | 编写 README.md(概览 + 模块地图) |
| 5 | 编写 architecture.md,包含 Mermaid 流程图 |
| 6 | 在 modules/ 中编写各模块文档 |
| 7 | 编写 diagrams/class-diagram.md(Mermaid classDiagram) |
| 8 | 编写 diagrams/sequences.md(Mermaid sequenceDiagram,2–4 个工作流) |
| 9 | 编写 getting-started.md |
| 10 | 如适用则编写 api.md,否则跳过 |
| 11 | 编写 .codewiki-state.json |
| 12 | 向用户报告路径 |
操作步骤
1. 确定目标
对于 GitHub URL:
WIKI_TMP=$(mktemp -d)
git clone --depth 50 <url> "$WIKI_TMP/repo"
cd "$WIKI_TMP/repo"
REPO_SHA=$(git rev-parse HEAD)
REPO_NAME=$(basename <url> .git)
对于本地路径(若未指定,则使用当前工作目录):
cd <path>
REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
REPO_NAME=$(basename "$PWD")
然后设置输出目录:
OUTPUT_DIR="$HOME/.kopi/wikis/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"
2. 扫描仓库结构
使用 terminal 工具处理 shell 操作,使用 read_file 处理 manifest:
# Shallow tree first
ls -la
# Deeper tree, noise filtered
find . -type d \
-not -path '*/\.*' \
-not -path '*/node_modules*' \
-not -path '*/venv*' \
-not -path '*/__pycache__*' \
-not -path '*/dist*' \
-not -path '*/build*' \
-not -path '*/target*' \
-maxdepth 3 | sort
# Language breakdown (skip if pygount unavailable)
pygount --format=summary \
--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \
. 2>/dev/null || true
然后 read_file 相关的 manifest(package.json、pyproject.toml、setup.py、Cargo.toml、go.mod、pom.xml、build.gradle)以及项目 README。使用 search_files target='files' 来查找这些文件,而不要靠猜测文件名。
3. 选择要记录文档的模块
首轮限定在 8–10 个模块以内。按语言采用的启发式规则:
- Python:顶层包(包含
__init__.py的目录),加上子系统目录 - JS/TS:
src/<subdir>、顶层 workspace 目录 - Rust:workspace 中的每个 crate,或顶层
src/<module>目录 - Go:每个顶层包目录
- 混合/不熟悉的项目:包含源代码的顶层目录(不包括配置、不包括测试)
对于非常大的仓库,按以下方式确定优先级:
- 被导入次数(被大量导入的模块是核心模块)
- 代码行数(更大的模块通常值得单独记录文档)
- 在 README/顶层文档中被提及的次数
在大型仓库上生成各模块文档之前,先向用户说明模块列表 —— 这样他们有机会调整方向。
4. 编写 README.md
read_file 实际的项目 README 以及前 2–3 个入口文件。然后 write_file:
# <Project Name>
<One paragraph: what it is and what it's for. Self-contained — don't assume the
reader has the source README.>
## Key Concepts
- **<Concept 1>** — <one line>
- **<Concept 2>** — <one line>
## Entry Points
- [`path/to/main.py`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>) — <what runs when you start it>
- [`path/to/cli.py`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>) — <CLI surface>
## High-Level Architecture
<2-3 sentences. Detail goes in architecture.md.>
See [architecture.md](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/architecture.md).
## Module Map
| Module | Purpose |
|---|---|
| [`<module>`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/modules/<module>.md) | <one-line purpose> |
## Getting Started
See [getting-started.md](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/getting-started.md).
本地模式下的链接目标请使用相对路径。对于克隆的仓库,使用 https://github.com/<owner>/<repo>/blob/<sha>/<path>,这样链接在未来的提交中依然有效。
5. 编写 architecture.md
# Architecture
<2-3 paragraphs: shape of the system. What talks to what. Where data enters,
where it exits, where state lives.>
## Components
- **<Component>** — <1-2 sentences>. See [`modules/<module>.md`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/modules/<module>.md).
## System Diagram
```mermaid
flowchart TD
User([User]) --> Entry[Entry Point]
Entry --> Core[Core Engine]
Core --> StorageA[(Database)]
Core --> ExternalAPI{{External API}}
```
## Data Flow
1. **<Step>** — [`<file>`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
2. **<Step>** — [`<file>`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
## Key Design Decisions
- <Anything load-bearing the reader should know>
Mermaid 图形语义:
[]= 组件[()]= 数据库/存储{{}}= 外部服务(())= 入口点或终端-->= 同步调用,-.->= 异步/事件
每个图最多约 20 个节点。如果超出,请拆分为多个子图。
6. 在 modules/ 中编写各模块文档
对于每个选定的模块,使用 ls 查看其布局,找出 3–5 个最重要的文件(按大小、按命名为 core.py/main.py/__init__.py、按被大量导入来判断),然后 read_file 这些文件(使用 offset/limit 只读取需要的内容;针对特定符号优先使用 search_files)。
# Module: `<module>`
<1-2 sentence purpose.>
## Responsibilities
- <bullet>
- <bullet>
## Key Files
- [`<module>/<file>`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>) — <what it does>
## Public API
<Functions/classes/constants other code uses. Group related items. Show
signatures, not full implementations.>
## Internal Structure
<How the module is organized internally. State management.>
## Dependencies
- **Used by:** <other modules>
- **Uses:** <other modules + external libs>
## Notable Patterns / Gotchas
- <Anything non-obvious>
7. 编写 diagrams/class-diagram.md
选出 5–10 个最重要的类/类型。read_file 它们,然后编写:
# Class Diagram
## Core Types
```mermaid
classDiagram
class Agent {
+string name
+list~Tool~ tools
+chat(message) string
}
class Tool {
<<interface>>
+name string
+execute(args) any
}
Agent --> Tool : uses
Tool <|-- TerminalTool
Tool <|-- WebTool
```
## Notes
<Anything the diagram can't express — lifecycle, threading, etc.>
对于没有类的语言(Go、C、Rust):使用该图表示 struct 之间的关系,或者跳过 class-diagram.md,改在 architecture.md 中用文字说明。不要强行套用。
8. 编写 diagrams/sequences.md
选出 2–4 个最重要的工作流。沿着代码追踪每条调用路径(阅读入口点,跟进函数调用),然后:
# Sequence Diagrams
## Workflow: <Name>
<1 sentence describing what this does and when it runs.>
```mermaid
sequenceDiagram
participant User
participant CLI
participant Agent
participant LLM
User->>CLI: types message
CLI->>Agent: chat(message)
Agent->>LLM: API call
LLM-->>Agent: response + tool_calls
Agent->>Agent: execute tools
Agent-->>CLI: final response
```
### Walkthrough
1. **User input** — [`cli.py:HermesCLI.run_session`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
不要虚构参与者。每个方框都必须对应读者能在代码中找到的真实组件。
9. 编写 getting-started.md
# Getting Started
## Prerequisites
<From manifest files + README. Be specific — versions if pinned.>
## Installation
```bash
<exact commands>
```
## First Run
```bash
<minimum command to see the system do something useful>
```
## Common Workflows
### <Workflow 1>
<commands>
## Configuration
- `<config-file>` — <what it controls>
- Env var `<VAR>` — <what it controls>
## Where to Go Next
- Architecture: [architecture.md](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/architecture.md)
- Module reference: [README.md#module-map](https://github.com/LINYIQ66/kopi-ai-agent/blob/main/optional-skills/software-development/code-wiki/README.md#module-map)
10. 编写 api.md(如不适用则跳过)
仅当项目是库或 API server 时才编写此文档。如果是:
- 找出公共 API 表面(
__init__.py导出项、OpenAPI 规范、路由处理器、导出的类型) - 为每个公共入口记录签名、参数、返回类型和一行描述
- 按类别分组
11. 编写状态文件
cat > "$OUTPUT_DIR/.codewiki-state.json" <<EOF
{
"repo_name": "$REPO_NAME",
"source_path": "$PWD",
"source_sha": "$REPO_SHA",
"generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"generator": "kopi-ai-agent code-wiki skill v0.1.0",
"modules_documented": []
}
EOF
12. 向用户汇报
准确说明生成了什么以及生成位置:
Generated wiki at ~/.kopi/wikis/<repo-name>/:
README.md project overview, module map
architecture.md system architecture + flowchart
getting-started.md setup, first run, workflows
modules/<N files> per-module deep-dives
diagrams/architecture.md Mermaid flowchart
diagrams/class-diagram.md Mermaid class diagram
diagrams/sequences.md Mermaid sequence diagrams
如果你将仓库克隆到了临时目录,请提醒用户在审阅完 wiki 后可以将其删除(rm -rf "$WIKI_TMP")。
范围控制
为一个 50 万行代码的 monorepo 生成完整 wiki 会消耗极其高昂的 token 成本。默认采用有界的范围:
- 初始扫描:目录深度最多 3 层
- 各模块文档:除非用户扩大范围,否则最多 10 个模块
- 单文件读取:优先使用
search_files获取符号信息,并配合read_file加上offset/limit,而不是完整读取 - 跳过第三方代码(
vendor/、third_party/、生成的代码、_pb2.py、.min.js)
如果用户说"全都彻底做完",就相信他们 —— 但要先估算大致成本:"这个仓库约有 340 个源文件,全面覆盖会很昂贵 —— 确认继续吗?"
重新运行/更新
如果 .codewiki-state.json 已存在于目标路径:
- 读取它以获取之前的 SHA 和模块列表
- 如果源 SHA 一致:询问用户是要重新生成还是跳过
- 如果 SHA 不同:提出只重新生成包含变更文件的模块(
git diff --name-only <old-sha> HEAD)
完整的增量重新生成是未来的增强功能 —— 目前,重新生成整个 wiki 是可以接受的。
陷阱(Pitfalls)
- 捏造组件。 图中的每个节点和提到的函数调用都必须能在源代码中找到。编写前先
read_file。自动生成文档最大的失败模式就是编造出看似合理的内容。 - 千篇一律的 AI 套话。 “本模块负责……”这种说法毫无信息量。要用领域相关的术语说明该模块实际做了什么。
- 把代码改写成散文。 如果模块文档写着“
process函数通过在每个条目上调用process_item来处理内容”,那还不如直接链接到该函数。 - Mermaid 节点数超过 50 个。 这样的图无法清晰渲染,请将其拆分。
- 把测试、生成的代码或 vendored 依赖当作产品代码来文档化。 跳过它们。
- 未经询问就输出到仓库中。 默认是
~/.kopi/wikis/。只有用户明确要求时才写入仓库。 - Mermaid 中的特殊字符需要加引号: 用
A["Tool / Agent"],而不是A[Tool / Agent]。节点内换行用<br>。 - SKILL.md 中嵌套的代码围栏。 编写包含 Mermaid 代码块的 markdown 示例时,请使用 4 个反引号的外层围栏,以便 3 个反引号的内层
```mermaiddoesn't close the outer. (This SKILL.md does it.) - classDiagram generics render as
~T~(e.g.List~Tool~), not<T>. - GitHub Mermaid theme is fixed — don't include
%%{init: ...}%%blocks; they're stripped on render.
Verification
After writing, verify:
- Mermaid blocks balance — opens equal closes per file:
for f in "$OUTPUT_DIR"/diagrams/*.md "$OUTPUT_DIR"/architecture.md; do
opens=$(grep -c '^```mermaid' "$f")
total=$(grep -c '^```' "$f")
echo "$f: $opens mermaid blocks, $total total fences (expect total = opens*2)"
done - All expected files exist —
ls "$OUTPUT_DIR"/{README.md,architecture.md,getting-started.md,.codewiki-state.json} \
"$OUTPUT_DIR"/modules/ "$OUTPUT_DIR"/diagrams/ - 模块数量与你的预期一致 —
ls "$OUTPUT_DIR/modules" | wc -l应与你在第 3 步中承诺的模块数量相同。 - 不要捏造路径 — 抽查 2–3 个源代码链接,确认它们指向真实文件。