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 個源代碼鏈接，確保它們指向真實存在的文件。