code-wiki

Code Wiki 技能

为任意代码库生成完整的 Wiki，包括概览、架构、各模块深入介绍，以及 Mermaid 类图和时序图。灵感来自 Google CodeWiki，但支持本地仓库、私有仓库和任何语言。仅使用现有的 Hermes 工具（terminal、read_file、search_files、write_file）；无需 Docker、外部服务或额外依赖。

此技能生成的是参考文档（内容是什么、如何运作），不会生成策略性叙述（为什么存在——那是另一项技能）。

适用场景

• 用户说“为这个代码库编写文档”“生成 Wiki”或“制作架构图”
• 用户要熟悉一个陌生仓库，并希望获得结构化参考资料
• 用户提供 GitHub URL 并要求编写文档
• 需要生成可在 GitHub 上渲染的稳定文档（Markdown + Mermaid）

不要用于：

• 单个文件或单个函数的文档——直接回答即可
• 某个特定端点的 API 参考——使用 read_file 并直接在对话中回答
• 策略性地叙述“为什么会有这个项目”——这是另一项用途不同的技能
• 用户正在本次会话中积极开发的代码库——用户提问时直接回答即可

前提条件

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

运行方法

从目标仓库根目录通过 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、清单文件、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. 扫描仓库结构

使用 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. LOC（较大的模块通常值得单独编写文档）
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`](<link>) — <what runs when you start it>
- [`path/to/cli.py`](<link>) — <CLI surface>

## High-Level Architecture

<2-3 sentences. Detail goes in architecture.md.>

See [architecture.md](architecture.md).

## Module Map

| Module | Purpose |
|---|---|
| [`<module>`](modules/<module>.md) | <one-line purpose> |

## Getting Started

See [getting-started.md](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`](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>`](<link>)
2. **<Step>** — [`<file>`](<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>`](<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`](<link>)
2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](<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](architecture.md)
- Module reference: [README.md#module-map](README.md#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"）。

范围控制

为包含 500K 行代码的单体仓库生成完整 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）

完整的增量重新生成是未来计划实现的增强功能——目前重新生成全部内容也可以接受。

常见陷阱

• 臆造组件。 图表中的每个节点和声称的函数调用都必须在源代码中有依据。写入前先 read_file。自动生成文档时，最常见也最严重的失败原因就是编造听起来合理的内容。
• 泛泛而谈的 AI 文案。 “此模块负责……”这类表述没有实际内容。应使用领域特定的术语，说明模块实际执行的操作。
• 把代码改写成文字。 如果模块文档写着“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: ...}%% 块；渲染时这些内容会被剥除。

验证

写入后，请检查：

1. 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
   

2. 所有预期文件均已存在——

   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 个源代码链接，确认它们指向真实文件。