Code Wiki

为任何代码库生成 Wiki 文档 + Mermaid 图表。

技能元数据

来源	可选 — 使用 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
相关技能	codebase-inspection, github-repo-management

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Code Wiki 技能

为任何代码库生成全面的 Wiki — 概述、架构、每个模块的深度解析、Mermaid 类图和序列图。灵感来源于 Google CodeWiki，但适用于本地仓库、私有仓库以及任何编程语言。仅使用现有的 Hermes 工具（terminal、read_file、search_files、write_file）；无需 Docker、无需外部服务、无额外依赖。

此技能生成参考文档（是什么/怎么做）。它不生成战略叙述（为什么 — 那是另一个技能的任务）。

何时使用

• 用户说“为此代码库编写文档”、“生成 Wiki”、“制作架构图”
• 入职不熟悉的项目仓库并需要结构化参考
• 用户指向一个 GitHub URL 并要求提供文档
• 需要一个稳定的产物（Markdown + Mermaid），可在 GitHub 上渲染

不要用于以下情况：

• 单文件或单函数文档 — 直接回答即可
• 某个特定端点的 API 参考 — 使用 read_file 并内联回答
• 战略性的“为什么存在”叙述 — 不同的技能，不同的目的
• 用户在此会话中积极开发的代码库 — 随问随答

先决条件

• 无需环境变量。
• PATH 中需有 git，用于仓库 SHA 跟踪和远程克隆。
• 可选：pygount 用于语言分解统计（参见 codebase-inspection 技能）。

如何运行

从目标仓库的根目录通过 terminal 工具调用，然后使用 read_file / search_files / write_file 生成 Wiki。默认输出位置为 ~/.hermes/wikis/<repo-name>/。仅当用户明确要求时，才写入仓库内部（docs/wiki/）。

快速参考

步骤	操作
1	确定目标 — 本地当前工作目录、给定路径，或 git clone --depth 50 <url> 到临时目录
2	扫描结构 — ls、find -maxdepth 3、清单文件、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)

对于本地路径（如果未给出，则为当前工作目录）：

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. 扫描仓库结构

使用 terminal 工具进行 shell 操作，使用 read_file 读取清单文件：

# 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 相关的清单文件（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>，顶层工作区目录
• Rust：工作区中的每个 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/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>) — <what runs when you start it>
- [`path/to/cli.py`](https://github.com/NousResearch/hermes-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/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/architecture).

## Module Map

| Module | Purpose |
|---|---|
| [`<module>`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/modules/<module>) | <one-line purpose> |

## Getting Started

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

在本地模式下，链接目标使用相对路径。对于克隆的仓库，使用 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/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/modules/<module>).

## System Diagram

```mermaid
flowchart TD
    User([用户]) --> Entry[入口点]
    Entry --> Core[核心引擎]
    Core --> StorageA[(数据库)]
    Core --> ExternalAPI{{外部 API}}
```

## Data Flow

1. **<Step>** — [`<file>`](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
2. **<Step>** — [`<file>`](https://github.com/NousResearch/hermes-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/NousResearch/hermes-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）：使用该图表表示结构体关系，或者跳过 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/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/<link>)
2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](https://github.com/NousResearch/hermes-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
<确切命令>
```

## First Run

```bash
<让系统执行有用操作的最小命令>
```

## 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/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/architecture)
- Module reference: [README.md#module-map](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/README#module-map)

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

仅当项目是库或 API 服务器时才编写此项。如果是：

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

12. 向用户报告

准确说明生成了什么以及位置：

Generated wiki at ~/.hermes/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 万行代码的单仓库生成完整的 wiki 会极其消耗 token。默认采用有限范围：

• 初始扫描：最大目录深度为 3
• 每个模块的文档：除非用户扩大范围，否则限制在 10 个模块以内
• 每个文件的读取：优先使用 search_files 查找符号 + 带有 offset/limit 的 read_file，而不是完整读取
• 跳过供应商代码（vendor/、third_party/、生成的代码、_pb2.py、.min.js）

如果用户说“彻底地完成整个事情”，请相信他们——但首先估算成本：“这个仓库约有 ~340 个源文件，全面覆盖将非常昂贵——确认吗？”

重新运行 / 更新

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

• 读取它以获取之前的 SHA 和模块列表
• 如果源 SHA 匹配：询问用户是否要重新生成或跳过
• 如果 SHA 不同：提供仅重新生成包含更改文件的模块的选项（git diff --name-only <old-sha> HEAD）

完全增量重新生成是未来的增强功能——目前，重新生成整个内容是可以接受的。

陷阱

• 编造组件。 每个图表节点和声称的函数调用都必须存在于源代码中。在写入之前先执行 read_file。自动生成文档最大的失败模式是听起来合理的编造内容。
• 通用的 AI 式散文。 “此模块负责...” 这类表述缺乏实质内容。请使用领域特定术语说明模块实际执行的操作。
• 将代码重述为散文。 如果模块文档写着“process 函数通过对每个项目调用 process_item 来处理事物”，这还不如直接链接到该函数。
• Mermaid 节点数 > 50。 它们无法清晰渲染。请将其拆分。
• 将测试、生成的代码或第三方依赖（vendored deps）当作产品代码进行文档化。 请跳过这些内容。
• 未经询问即在仓库内输出文件。 默认输出路径为 ~/.hermes/wikis/。仅当用户明确请求时，才写入仓库中。
• Mermaid 特殊字符需要引号： 使用 A["Tool / Agent"] 而非 A[Tool / Agent]。节点内的换行使用 <br>。
• SKILL.md 中的嵌套代码块。 当编写包含 Mermaid 块的 Markdown 示例时，外层使用 4 个反引号，以便内层的 3 个反引号 ``` 能正确解析。

for f in "$OUTPUT_DIR"/diagrams/*.md "$OUTPUT_DIR"/architecture.md; do
  opens=$(grep -c '^```mermaid' "$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/

3. 模块数量与预期一致 — ls "$OUTPUT_DIR/modules" | wc -l 的结果应等于你在步骤 3 中承诺的模块数量。
4. 无编造的路径 — 随机检查 2–3 个源代码链接，确保它们指向真实存在的文件。