@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/software-development/code-wiki/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: code-wiki
+description: "为任何代码库生成 wiki 文档及 Mermaid 图表。"
+version: 0.1.0
+author: Teknium (teknium1), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Documentation, Mermaid, Architecture, Diagrams, Wiki, Code-Analysis]
+    related_skills: [codebase-inspection, github-repo-management]
+---
+
+# 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，目的不同
+- 用户在当前会话中正在积极开发的代码库 —— 有问必答即可
+
+## 前置条件
+
+- 无需环境变量。
+- PATH 中需要包含 `git`，用于 repo SHA 追踪和远程克隆。
+- 可选: `pygount`，用于语言分布统计（参见 `codebase-inspection` skill）。
+
+## 如何运行
+
+在目标 repo 的根目录下通过 `terminal` 工具调用，然后使用 `read_file` / `search_files` / `write_file` 来生成 wiki。 默认输出位置为 `~/.hermes/wikis/<repo-name>/`。仅当用户明确要求时，才将其写入 repo（`docs/wiki/`）。
+
+## 快速参考
+
+| Step | Action |
+|---|---|
+| 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：
+
+```bash
+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）：
+
+```bash
+cd <path>
+REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
+REPO_NAME=$(basename "$PWD")
+```
+
+然后设置输出目录：
+
+```bash
+OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
+mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"
+```
+
+### 2. 扫描 repo 结构
+
+使用 `terminal` 工具执行 shell 命令，使用 `read_file` 查看 manifests：
+
+```bash
+# 先看浅层树结构
+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` 读取相关的 manifests（`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: 每个顶级 package 目录
+- 混合/不熟悉：包含源代码的顶级目录（排除配置和测试文件）
+
+对于非常大的代码库，优先级排序依据：
+1. 被引用次数（被大量导入的模块通常是核心）
+2. LOC（代码行数，越大的模块通常越值得拥有独立文档）
+3. 在 README / 顶级文档中被提及的频率
+
+在大型 repo 中生成各模块文档前，先向用户展示模块列表 —— 给他们一个调整方向的机会。
+
+### 4. 编写 `README.md`
+
+使用 `read_file` 读取实际的项目 README 以及排名前 2–3 的入口文件。然后使用 `write_file`：
+
+````markdown
+# <Project Name>
+
+<段落：它是什么，有什么用。保持独立完整 —— 不要假设读者手头有源码 README。>
+
+## 核心概念
+
+- **<Concept 1>** — <单行描述>
+- **<Concept 2>** — <单行描述>
+
+## 入口
+
+- [`path/to/main.py`](<link>) — <启动时运行的内容>
+- [`path/to/cli.py`](<link>) — <CLI 表面>
+
+## 高层架构
+
+<2-3句话。细节见 architecture.md。>
+
+参见 [architecture.md](architecture.md)。
+
+## 模块映射
+
+| Module | Purpose |
+|---|---|
+| [`<module>`](modules/<module>.md) | <单行用途> |
+
+## 快速开始
+
+参见 [getting-started.md](getting-started.md)。
+````
+
+在本地模式下，链接目标请使用相对路径。对于克隆的 repo，请使用 `https://github.com/<owner>/<repo>/blob/<sha>/<path>`，这样链接即使在未来提交后依然有效。
+
+### 5. 编写 `architecture.md`
+
+````markdown
+# 架构
+
+<2-3段话：系统的形态。什么在与什么通信。数据从哪里进入，从哪里输出，状态存在于何处。>
+
+## 组件
+
+- **<Component>** — <1-2句话>. 参见 [`modules/<module>.md`](modules/<module>.md).
+
+## 系统图
+
+```mermaid
+flowchart TD
+    User([User]) --> Entry[Entry Point]
+    Entry --> Core[Core Engine]
+    Core --> StorageA[(Database)]
+    Core --> ExternalAPI{{External API}}
+```
+
+## 数据流
+
+1. **<Step>** — [`<file>`](<link>)
+2. **<Step>** — [`<file>`](<link>)
+
+## 核心设计决策
+
+- <读者需要知道的任何关键性信息>
+````
+
+**Mermaid 形状语义：**
+- `[]` = 组件
+- `[()]` = 数据库 / 存储
+- `{{}}` = 外部服务
+- `(())` = 入口点或终端
+- `-->` = 同步调用, `-.->` = 异步/事件
+
+每张图的节点上限约为 20 个。如果规模更大，请拆分为子图。
+
+### 6. 在 `modules/` 中编写各模块文档
+
+对于选定的每个模块，使用 `ls` 检查其布局，找出 3–5 个最重要的文件（根据大小、是否命名为 `core.py` / `main.py` / `__init__.py`、被大量导入的情况来判断），然后使用 `read_file` 读取这些文件（利用 `offset` / `limit` 只读取所需内容；对于特定符号，优先使用 `search_files`）。
+
+````markdown
+# Module: `<module>`
+
+<1-2 句用途说明。>
+
+## 职责
+
+- <bullet>
+- <bullet>
+
+## 关键文件
+
+- [`<module>/<file>`](<link>) — <它的作用>
+
+## 公共 API
+
+<其他代码会调用的函数/类/常量。将相关项分组。展示签名，而不是完整的实现。>
+
+## 内部结构
+
+<模块内部的组织方式。状态管理。>
+
+## 依赖
+
+- **被引用方:** <其他模块>
+- **引用方:** <其他模块 + 外部库>
+
+## 显著模式 / 陷阱
+
+- <任何不明显的细节>
+````
+
+### 7. 编写 `diagrams/class-diagram.md`
+
+挑选 5–10 个最重要的类/类型。使用 `read_file` 读取它们，然后编写：
+
+````markdown
+# 类图
+
+## 核心类型
+
+```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）：使用图表展示结构体关系，或者跳过 class-diagram.md 并直接在 architecture.md 中用文字解释。不要生搬硬套。
+
+### 8. 编写 `diagrams/sequences.md`
+
+挑选 2–4 个最重要的工作流。在代码中追踪每个调用路径（阅读入口点，跟踪函数调用），然后：
+
+````markdown
+# 时序图
+
+## 工作流: <Name>
+
+<一句话描述它的功能及运行时机。>
+
+```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. **User input** — [`cli.py:HermesCLI.run_session`](<link>)
+2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](<link>)
+````
+
+不要凭空捏造参与者。每个框都必须对应读者能在代码中找到的真实组件。
+
+### 9. 编写 `getting-started.md`
+
+````markdown
+# 快速开始
+
+## 前置条件
+
+<来自 manifest 文件和 README。要具体 —— 如果锁定了版本请列出。>
+
+## 安装
+
+```bash
+<精确的命令>
+```
+
+## 首次运行
+
+```bash
+<用于观察系统执行有用操作的最简命令>
+```
+
+## 常用工作流
+
+### <Workflow 1>
+<commands>
+
+## 配置
+
+- `<config-file>` — <它控制什么>
+- 环境变量 `<VAR>` — <它控制什么>
+
+## 后续阅读建议
+
+- 架构: [architecture.md](architecture.md)
+- 模块参考: [README.md#module-map](README.md#module-map)
+````
+
+### 10. 编写 `api.md` （如果不适用则跳过）
+
+仅当项目是一个库或 API 服务器时才编写此文档。如果是：
+
+- 找到公共 API 表面（`__init__.py` 导出项、OpenAPI 规范、路由处理程序、导出的类型）
+- 记录每个公共条目的签名、参数、返回类型和单行描述
+- 按类别分组
+
+### 11. 编写状态文件
+
+```bash
+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 万行代码 (LOC) 的单体仓库生成完整的 wiki 会消耗海量 token。 默认采用有边界的范围：
+
+- 初始扫描：最深 3 层目录
+- 模块文档：除非用户扩大范围，否则最多限制在 10 个模块
+- 单文件读取：优先使用 `search_files` 查找符号，并通过带 `offset`/`limit` 的 `read_file` 读取，而不是整篇读取
+- 跳过第三方售卖代码（`vendor/`, `third_party/`, 自动生成的代码, `_pb2.py`, `.min.js`）
+
+如果用户说“全面详尽地处理整个项目”，相信他们 —— 但要先估算成本：“此 repo 大约有 ~340 个源文件，全面覆盖将非常昂贵 —— 是否确认？”
+
+## 重新运行 / 更新
+
+如果目标路径中已经存在 `.codewiki-state.json`：
+
+- 读取它以获取之前的 SHA 和模块列表
+- 如果源 SHA 匹配：询问用户是要重新生成还是跳过
+- 如果 SHA 不同：提议仅重新生成文件发生变更的模块（`git diff --name-only <old-sha> HEAD`）
+
+完整的增量重生成是未来的增强功能 —— 目前，重新生成整个项目是可以接受的。
+
+## 常见陷阱
+
+- **捏造组件。** 每个图表节点和声称的函数调用必须存在于源代码中。编写前务必使用 `read_file` 确认。自动生成文档最大的败笔就是听起来很合理但属于捏造的内容。
+- **毫无营养的 AI 描述。** “该模块负责……” 是空洞的废话。请使用特定领域的术语说明模块实际做了什么。
+- **把代码重述为文字。** 如果一个模块文档说“`process` 函数通过对每个 item 调用 `process_item` 来处理事情”，这比直接链接到该函数还要糟糕。
+- **超过 50 个节点的 Mermaid。** 它们会无法清晰渲染。请拆分它们。
+- **把测试、生成的代码或第三方依赖当成产品代码来写文档。** 跳过它们。
+- **未经询问直接输出到 repo 中。** 默认目录是 `~/.hermes/wikis/`。仅当用户明确要求时才写入 repo。
+- **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 块数量平衡** —— 每个文件的开闭数量相等：
+   ```bash
+   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. **所有预期的文件都存在** ——
+   ```bash
+   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 个源码链接，确保它们指向真实的文件。

package/extensions/skills/optional/software-development/code-wiki/templates/README.md

@@ -0,0 +1,31 @@
+# {{PROJECT_NAME}}
+
+{{ONE_PARAGRAPH_DESCRIPTION}}
+
+## 核心概念
+
+- **{{CONCEPT_1}}** — {{ONE_LINE}}
+- **{{CONCEPT_2}}** — {{ONE_LINE}}
+- **{{CONCEPT_3}}** — {{ONE_LINE}}
+
+## 入口点
+
+- [`{{PATH_1}}`]({{LINK_1}}) — {{WHAT_IT_DOES}}
+- [`{{PATH_2}}`]({{LINK_2}}) — {{WHAT_IT_DOES}}
+
+## 高层架构
+
+{{TWO_TO_THREE_SENTENCES}}
+
+完整架构请参阅 [architecture.md](architecture.md)。
+
+## 模块映射
+
+| 模块 | 用途 |
+| --- | --- |
+| [`{{MODULE_1}}`](modules/{{MODULE_1}}.md) | {{ONE_LINE_PURPOSE}} |
+| [`{{MODULE_2}}`](modules/{{MODULE_2}}.md) | {{ONE_LINE_PURPOSE}} |
+
+## 快速开始
+
+请参阅 [getting-started.md](getting-started.md)。

package/extensions/skills/optional/software-development/code-wiki/templates/architecture.md

@@ -0,0 +1,30 @@
+# 架构
+
+{{TWO_TO_THREE_PARAGRAPHS_SHAPE_OF_SYSTEM}}
+
+## 组件
+
+- **{{COMPONENT_1}}** — {{ONE_TO_TWO_SENTENCES}} 参见 [`modules/{{MODULE}}.md`](modules/{{MODULE}}.md)。
+- **{{COMPONENT_2}}** — {{ONE_TO_TWO_SENTENCES}}
+
+## 系统图
+
+```mermaid
+flowchart TD
+    User([User]) --> Entry[Entry Point]
+    Entry --> Core[Core Engine]
+    Core --> StorageA[(Database)]
+    Core --> ExternalAPI{{External API}}
+```
+
+## 数据流
+
+1. **{{STEP_1}}** — [`{{FILE}}`]({{LINK}})
+2. **{{STEP_2}}** — [`{{FILE}}`]({{LINK}})
+3. **{{STEP_3}}** — [`{{FILE}}`]({{LINK}})
+
+## 关键设计决策
+
+- {{DECISION_1}}
+- {{DECISION_2}}
+- {{DECISION_3}}

package/extensions/skills/optional/software-development/code-wiki/templates/getting-started.md

@@ -0,0 +1,47 @@
+# 入门指南
+
+## 前置条件
+
+- {{LANGUAGE_RUNTIME_VERSION}}
+- {{DEPENDENCY}}
+
+## 安装
+
+```bash
+{{INSTALL_COMMANDS}}
+```
+
+## 首次运行
+
+```bash
+{{FIRST_RUN_COMMAND}}
+```
+
+你应该会看到 {{EXPECTED_OUTPUT}}。
+
+## 常用工作流
+
+### {{WORKFLOW_1}}
+
+```bash
+{{COMMANDS}}
+```
+
+### {{WORKFLOW_2}}
+
+```bash
+{{COMMANDS}}
+```
+
+## 配置
+
+主要配置文件与设置：
+
+- `{{CONFIG_FILE}}` — {{WHAT_IT_CONTROLS}}
+- 环境变量 `{{VAR}}` — {{WHAT_IT_CONTROLS}}
+
+## 接下来去哪
+
+- 架构概览：[architecture.md](architecture.md)
+- 模块参考：[README.md#module-map](README.md#module-map)
+- 图表：[diagrams/](diagrams/)

package/extensions/skills/optional/software-development/code-wiki/templates/module.md

@@ -0,0 +1,38 @@
+# 模块：`{{MODULE_NAME}}`
+
+{{ONE_TO_TWO_SENTENCE_PURPOSE}}
+
+## 职责
+
+- {{BULLET_1}}
+- {{BULLET_2}}
+- {{BULLET_3}}
+
+## 关键文件
+
+- [`{{PATH_1}}`]({{LINK_1}}) — {{WHAT_IT_DOES}}
+- [`{{PATH_2}}`]({{LINK_2}}) — {{WHAT_IT_DOES}}
+
+## Public API
+
+### `{{FUNCTION_NAME}}({{SIGNATURE}})`
+
+{{ONE_LINE_DESCRIPTION}}
+
+**参数：**
+- `{{PARAM}}` ({{TYPE}}) — {{DESCRIPTION}}
+
+**返回：** {{TYPE}} — {{DESCRIPTION}}
+
+## 内部结构
+
+{{HOW_THE_MODULE_IS_ORGANIZED}}
+
+## 依赖
+
+- **被使用于：** {{OTHER_MODULES}}
+- **使用：** {{OTHER_MODULES_AND_LIBS}}
+
+## 特殊模式 / 注意事项
+
+- {{ANYTHING_NON_OBVIOUS}}