跳到主要内容

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
相关 skillcodebase-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-inspection skill)。

如何运行​

通过 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:每个顶层包目录
  • 混合/不熟悉的项目:包含源代码的顶层目录(不包括配置、不包括测试)

对于非常大的仓库,按以下方式确定优先级:

  1. 被导入次数(被大量导入的模块是核心模块)
  2. 代码行数(更大的模块通常值得单独记录文档)
  3. 在 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 个反引号的内层 ```mermaid doesn'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:

  1. 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
  2. All expected files exist —
    ls "$OUTPUT_DIR"/{README.md,architecture.md,getting-started.md,.codewiki-state.json} \
    "$OUTPUT_DIR"/modules/ "$OUTPUT_DIR"/diagrams/
  3. 模块数量与你的预期一致 — ls "$OUTPUT_DIR/modules" | wc -l 应与你在第 3 步中承诺的模块数量相同。
  4. 不要捏造路径 — 抽查 2–3 个源代码链接,确认它们指向真实文件。