{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Code Wiki

为任意代码库生成 wiki 文档 + Mermaid 图。

Skill 元数据


来源	可选——使用 `hermes skills install official/software-development/code-wiki` 安装
路径	`optional-skills/software-development/code-wiki`
版本	`0.1.0`
作者	Teknium (teknium1), Hermes Agent
许可证	MIT
平台	linux, macos, windows
标签	`Documentation`, `Mermaid`, `Architecture`, `Diagrams`, `Wiki`, `Code-Analysis`
相关 skill	`codebase-inspection`、`github`

参考：完整 SKILL.md

INFO

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。

Code Wiki Skill

为任意代码库生成完整 wiki——概览、架构、逐模块深入、Mermaid 类图和时序图。灵感来自 Google CodeWiki，但可用于本地仓库、私有仓库和任何语言。只用现有的 Hermes 工具（terminal、read_file、search_files、write_file）；无需 Docker、外部服务或额外依赖。

本 skill 产出参考文档（是什么/怎么用）。它不产出战略叙事（为什么——那是另一个 skill）。

使用时机

用户说"给这个代码库写文档"、"生成一个 wiki"、"画架构图"
上手一个陌生仓库，想要结构化参考
用户指一个 GitHub URL 要文档
需要一个在 GitHub 上渲染的稳定产物（markdown + Mermaid）

不要用于：

单文件或单函数文档——直接答
单个特定端点的 API 参考——用 read_file 内联回答
战略层面"它为什么存在"的叙事——不同 skill、不同目的
用户本会话正在 actively 开发的代码库——问题来了直接答

前提条件

无需环境变量。
PATH 上有 git，用于仓库 SHA 跟踪和远程克隆。
可选：pygount 用于语言占比统计（见 codebase-inspection skill）。

运行方式

从目标仓库根目录通过 terminal 工具调用，然后用 read_file / search_files / write_file 产出 wiki。默认输出位置是 ~/.hermes/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	写带 Mermaid 流程图的 `architecture.md`
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)

对于本地路径（或未给定时用 cwd）：

cd <path>
REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
REPO_NAME=$(basename "$PWD")

然后设输出目录：

OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"

2. 扫描仓库结构

shell 工作用 terminal 工具，manifest 用 read_file：

# 先看浅层树
ls -la

# 更深的树，过滤噪音
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

# 语言占比（pygount 不可用则跳过）
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：每个顶层包目录
混合/陌生：含源代码的顶层目录（不是配置、不是测试）

对超大仓库，按以下优先级：

被引用次数（被很多地方 import 的模块是核心）
LOC（更大的模块通常值得自己一篇文档）
README / 顶层文档中的提及

在大仓库上生成逐模块文档前，先把模块清单告诉用户——给他们纠偏的机会。

4. 写 `README.md`

read_file 实际的项目 README 加最顶 2–3 个入口文件。然后 write_file：

# <项目名>

<一段话：它是什么、用来干嘛。自包含——不要假设读者有源 README。>

## 关键概念

- **<概念 1>**——<一行>
- **<概念 2>**——<一行>

## 入口点

- [`path/to/main.py`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)——<启动它时跑什么>
- [`path/to/cli.py`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)——<CLI 界面>

## 高层架构

<2-3 句话。细节进 architecture.md。>

见 [architecture.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/architecture.md)。

## 模块地图

| 模块 | 用途 |
|---|---|
| [`<module>`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/modules/<module>.md) | <一行用途> |

## 上手

见 [getting-started.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/getting-started.md)。

本地模式下链接目标用相对路径。克隆的仓库用 https://github.com/<owner>/<repo>/blob/<sha>/<path>，让链接扛得住未来提交。

5. 写 `architecture.md`

# 架构

<2-3 段：系统形状。谁和谁通信。数据从哪进、从哪出、状态存哪。>

## 组件

- **<组件>**——<1-2 句>。见 [`modules/<module>.md`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/modules/<module>.md)。

## 系统图

```mermaid
flowchart TD
    User([User]) --> Entry[Entry Point]
    Entry --> Core[Core Engine]
    Core --> StorageA[(Database)]
    Core --> ExternalAPI{{External API}}
```

## 数据流

1. **<步骤>**——[`<file>`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
2. **<步骤>**——[`<file>`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)

## 关键设计决策

- <读者该知道的任何承重决策>

Mermaid 形状语义：

[] = 组件
[()] = 数据库 / 存储
{{}} = 外部服务
(()) = 入口点或终端
--> = 同步调用，-.-> = 异步/事件

每张图最多约 20 个节点。更大就拆成子图。

6. 在 `modules/` 写逐模块文档

对每个选中的模块，用 ls 看布局，找出 3–5 个最重要的文件（按大小、按命名 core.py / main.py / __init__.py、按被大量引用），然后 read_file 那些文件（用 offset / limit 只读需要的；特定符号优先 search_files）。

# 模块：`<module>`

<1-2 句用途。>

## 职责

- <条目>
- <条目>

## 关键文件

- [`<module>/<file>`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)——<它做什么>

## 公共 API

<其他代码用到的函数/类/常量。把相关项分组。展示
签名，不是完整实现。>

## 内部结构

<模块内部怎么组织。状态管理。>

## 依赖

- **被谁用：** <其他模块>
- **用了：** <其他模块 + 外部库>

## 值得注意的模式 / 坑

- <任何不显而易见的>

7. 写 `diagrams/class-diagram.md`

选 5–10 个最重要的类/类型。read_file 它们，然后写：

# 类图

## 核心类型

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

## 备注

<图表达不了的任何东西——生命周期、线程等。>

对没有类的语言（Go、C、Rust）：用图表达 struct 关系，或跳过 class-diagram.md 在 architecture.md 里用 prose 解释。不要硬凑。

8. 写 `diagrams/sequences.md`

选 2–4 个最重要的工作流。在代码里追踪每条调用路径（读入口、顺函数调用走），然后：

# 时序图

## 工作流：<名>

<1 句话说明它做什么、何时跑。>

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

### 走查

1. **用户输入**——[`cli.py:HermesCLI.run_session`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
2. **消息分发**——[`run_agent.py:AIAgent.chat`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)

不要编造参与者。每个框都必须对应读者能在代码里找到的真实组件。

9. 写 `getting-started.md`

# 上手

## 前提条件

<来自 manifest + README。具体——固定了版本就写版本。>

## 安装

```bash
<确切命令>
```

## 首次运行

```bash
<看到系统做出有用事情的最小命令>
```

## 常见工作流

### <工作流 1>
<命令>

## 配置

- `<config-file>`——<它控制什么>
- 环境变量 `<VAR>`——<它控制什么>

## 下一步去哪

- 架构：[architecture.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/architecture.md)
- 模块参考：[README.md#module-map](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/README.md#module-map)

10. 写 `api.md`（不适用则跳过）

仅当项目是库或 API 服务器时才写。若是：

找公共 API 面（__init__.py 导出、OpenAPI spec、路由处理器、导出的类型）
用签名、参数、返回类型、一行描述文档化每个公共入口
按类别分组

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": "hermes-agent code-wiki skill v0.1.0",
  "modules_documented": []
}
EOF

12. 向用户报告

确切说明生成了什么、在哪：

已在 ~/.hermes/wikis/<repo-name>/ 生成 wiki：
  README.md                   项目概览、模块地图
  architecture.md             系统架构 + 流程图
  getting-started.md          配置、首次运行、工作流
  modules/<N files>           逐模块深入
  diagrams/architecture.md    Mermaid 流程图
  diagrams/class-diagram.md   Mermaid 类图
  diagrams/sequences.md       Mermaid 时序图

如果你克隆到了临时目录，提醒用户审阅完 wiki 后可删除（rm -rf "$WIKI_TMP"）。

范围控制

给一个 50 万行的 monorepo 生成完整 wiki 在 token 上极贵。默认有界范围：

初始扫描：最大目录深度 3
逐模块文档：除非用户扩大范围，否则限 10 个模块
逐文件读取：优先 search_files 找符号 + 带 offset/limit 的 read_file，而非全读
跳过 vendored 代码（vendor/、third_party/、生成代码、_pb2.py、.min.js）

如果用户说"穷尽地做整个仓库"，信他们——但先粗估成本："这个仓库约 340 个源文件，全覆盖会很贵——确认？"

重跑 / 更新

如果目标路径已存在 .codewiki-state.json：

读它拿上次的 SHA 和模块清单
如果源 SHA 一致：问用户要重新生成还是跳过
如果 SHA 不同：提议只重新生成有变更文件的模块（git diff --name-only <old-sha> HEAD）

完整增量重生成是未来的增强——目前重新生成整个是可接受的。

常见陷阱

编造组件。 每个图节点和声称的函数调用都必须在源里。写之前 read_file。自动生成文档最大的失败模式就是听起来合理的编造。
泛泛的 AI 套话。 "这个模块负责……"是没有内容的。用领域术语说这个模块实际做什么。
把代码复述成 prose。 一个模块文档说"process 函数通过对每个条目调用 process_item 来处理东西"，比直接链到函数还糟。
Mermaid 超过 50 节点。 渲染不清。拆开。
把测试、生成代码或 vendored 依赖当产品代码文档化。 跳过它们。
不问就写进仓库。 默认是 ~/.hermes/wikis/。仅当用户明确要求才写进仓库。
Mermaid 特殊字符要加引号： A["Tool / Agent"] 而非 A[Tool / Agent]。节点内换行用 <br>。
SKILL.md 里嵌套代码围栏。 写一个含 Mermaid 块的 markdown 示例时，外层用 4 反引号围栏，让内层 3 反引号的 ```mermaid 不会闭合外层。（本 SKILL.md 就是这么做的。）
classDiagram 泛型渲染为 ~T~（如 List~Tool~），不是 <T>。
GitHub Mermaid 主题是固定的——不要加 %%{init: ...}%% 块；它们渲染时被剥掉。

验证

写完后验证：

Mermaid 块配平——每个文件开闭相等：

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

所有预期文件存在——

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 个源链接解析到真实文件。

Code Wiki

Skill 元数据

参考：完整 SKILL.md

Code Wiki Skill

使用时机

前提条件

运行方式

快速参考

流程

1. 解析目标

2. 扫描仓库结构

3. 选要文档化的模块

4. 写 README.md

5. 写 architecture.md

6. 在 modules/ 写逐模块文档

7. 写 diagrams/class-diagram.md

8. 写 diagrams/sequences.md

9. 写 getting-started.md

10. 写 api.md（不适用则跳过）

11. 写状态文件

12. 向用户报告

范围控制

重跑 / 更新

常见陷阱

验证

4. 写 `README.md`

5. 写 `architecture.md`

6. 在 `modules/` 写逐模块文档

7. 写 `diagrams/class-diagram.md`

8. 写 `diagrams/sequences.md`

9. 写 `getting-started.md`

10. 写 `api.md`（不适用则跳过）