# Project Docs Gen

> 项目文档的全生命周期管理。支持：初始化文档（按阶段+范围选择性生成）、更新文档（扫描代码对比，输出差异并更新）。范围可指定仅仓库级/指定子工程/全部。与 project-structure-init 配合使用但不强制依赖。当用户说"初始化文档"、"更新文档"、"生成文档"、"补文档"、"刷新文档"、"同步文档与代码"、"检查文档"、"只初始化仓库级"、"只更新某个文档"时触发。

- Skill: `herxinsasa/project-docs-gen` (Agent Skill)
- Install (CLI): `npx skillmds@latest add herxinsasa/project-docs-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/herxinsasa/project-docs-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: herxinsasa (https://skillmd.com/u/herxinsasa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/herxinsasa/project-docs-gen

---


# 项目文档生成与维护

## 定位

管理 docs/ 下文档的两种操作：

**初始化模式**：有模板但无内容 → 按阶段+范围生成缺失文档。适用项目刚搭好骨架时。
**更新模式**：有文档但可能过时 → 扫描代码对比 → 输出差异 → 选择性更新。适用代码改动后同步文档。

前置：推荐由 `project-structure-init` 先创建文档骨架，非必须。

---

## 工作流程

### Step 0: 确认操作模式

询问用户：

```
(1) 目标路径：[用户指定或当前目录]
(2) 操作类型：初始化文档 / 更新文档
```

→ **初始化文档**走 Step 1A，**更新文档**走 Step 1B。

---

## 分支 A：初始化文档

### A1. 检查项目结构

检查目标路径 `docs/`：

| 状态 | 处理 |
|------|------|
| 存在且有规范子目录（01-总览/02-需求...）| 正常，读取 `project-structure-init` 的 reference 模板 |
| 存在但结构不规范 | 建议先执行 `project-structure-init` 创建规范骨架 |
| 不存在 | 建议先执行 `project-structure-init` |

读取模板路径：

```
.../project-structure-init/references/软件工程目录规范_v1.0.md    # 规范全文
.../project-structure-init/references/仓库级/                     # 仓库级模板
.../project-structure-init/references/工程级/                     # 工程级模板
```

### A2. 确认范围与阶段

**范围**：

| 范围 | 处理 |
|------|------|
| **仅仓库级** | 只处理 `docs/`，不碰 `projects/*/docs/` |
| **指定子工程** | 只处理 `projects/<name>/docs/`，用户指定工程名 |
| **全部** | 仓库级 → 用户确认 → 逐个工程级 |

**阶段**：

| 阶段 | 仓库级新增文档 | 工程级（C++）新增文档 |
|------|-------------|---------------------|
| 初始化 | README, CLAUDE, 目录结构, 系统架构总览, 工程说明(client/server/robot) | README, CLAUDE, 目录结构, 架构总览 |
| 需求分析 | 需求规格说明书*, 需求影响分析矩阵* | (同初始化) |
| 概要设计 | 客户端概要设计*, 服务端概要设计* | 设计文档模板*(工程级模板) |
| 协议定义 | 通信协议, 数据格式规范, 全局错误码 | 错误码 |
| UI设计 | UI设计规范* | (同协议定义) |
| 编码 | (同UI设计) | 模块索引 |
| 测试 | 测试方案*, 测试报告* | (同编码) |

> `*` 不可自动生成，仅填充模板框架 + `<!-- TODO: 需人工补充 -->`。

### A3. 工具检查与数据获取

优先使用代码索引工具，避免直接读取大量源文件。

**优先级**：

```
gitnexus（最优先，AST级精确，token最低）
  ↓ 不可用
codegraph（备选，文件级结构）
  ↓ 不可用
文件遍历 + 正则提取（回退，标注准确度: 中）
```

**使用 gitnexus 的核心原则**：按需查询，不读源文件。AI 根据当前具体任务（查模块/查接口/查依赖/查错误码）自行组合查询，查询结果结构化且数据量小，远低于逐个读取源文件的开销。例如：

```
gitnexus query "modules"              → 列出所有模块清单
gitnexus query "module X interfaces"  → 模块的接口签名
gitnexus query "module X deps"        → 模块的依赖关系
gitnexus query "inheritance tree"     → 继承/实现关系（Mermaid 用）
gitnexus query "error codes"          → 错误码定义
```

**回退标注**：使用文件遍历时，生成的文档首行添加：

```markdown
> 基于文件结构扫描生成，建议使用 gitnexus 获取更高准确度的模块索引。
```

### A4. 文档生成（按范围+阶段过滤）

只生成当前阶段及之前阶段的文档。生成逻辑：

#### A4.1 仓库级文档

**README.md / CLAUDE.md**

扫描项目结构，填写：

```markdown
# [工程名]

## 简介
[目录名]，包含 <N> 个子工程。

## 技术栈
| 子工程 | 语言 | 框架 |
|--------|------|------|
| [从 projects/*/CLAUDE.md 提取] | [从构建文件推断] | [从构建文件推断] |

## 子工程清单
| 子工程 | 类型 | 职责 |
|--------|------|------|
| [目录名] | [类型] | [从CLAUDE.md首段提取] |
```

**目录结构.md**

递归扫描实际文件树，排除 `.git/`、`node_modules/`、`build/`、`bin/` 等，输出规范格式的树。如 `projects/` 下的 `details/` 过多则折叠显示。

**系统架构总览.md**

从代码结构推断：

- 工程间通信拓扑图（Mermaid graph TB）→ 从子工程间依赖关系推断
- 技术栈表 → 从 `xmake.lua`/`go.mod`/`package.json` 提取
- 版本架构变更 + 关键设计约束 → `<!-- TODO: 需人工补充 -->`

**工程说明（client.md / server.md / robot.md）**

从 `projects/<name>/CLAUDE.md` 提取工程概述，从构建文件提取技术栈，从 `docs/03-模块依赖/` 提取核心模块清单。缺少内容标记 `<!-- TODO -->`。

**通信协议.md**

- 有 `projects/*/proto/` 或 `.proto` 文件 → 解析消息格式、RPC 方法、版本号
- 有自定义协议头文件（`protocol.h` 等）→ 提取消息ID、字段结构
- 用 Mermaid sequenceDiagram 画主要交互流程
- 均无 → 标记 `<!-- TODO: 需补充 -->`

**全局错误码.md**

从代码提取跨工程共享的错误码定义：

- 有 gitnexus → 精确提取 `enum` / `static const int` 及注释
- 无 → 遍历头文件中的错误码枚举
- 格式：分段范围表 + 通用错误码表 + 版本变更(留空)

**数据格式规范.md**

从代码中的关键结构体/JSON schema/协议字段提取共享数据格式，生成表格说明字段名/类型/含义。

**其他文档**

需求规格说明书、需求影响分析矩阵、概要设计、UI设计规范、测试方案/报告 → 模板框架 + `<!-- TODO: 需人工补充 -->`。

#### A4.2 工程级文档

**目录结构.md**

同仓库级方法，递归扫描子工程实际目录树。输出标准格式，标注各目录职责。

**架构总览.md**

从代码推断分层：

```markdown
## 分层架构
```mermaid
graph TB
    subgraph 应用层
        MAIN[main.cpp]
    end
    subgraph 业务组件层
        [从 components/business/ 扫描得到模块列表]
    end
    subgraph 平台抽象层
        [从 platform/ 扫描]
    end
```

## 模块职责边界
| 层 | 目录 | 职责 | 禁止行为 |
|----|------|------|---------|
| 应用层 | applications/ | 启动、组装 | 不含业务逻辑 |
| 业务组件层 | components/business/ | [职责描述] | 不调OS API |
```

**模块索引.md**

**优先级最高**——这是 AI 进入代码的第一站。生成内容：

- 模块拓扑 Mermaid 图
- 模块清单表（模块/职责/头文件路径/实现路径/关键接口/依赖/被依赖）
- 功能 → 模块速查表
- 间接影响速查表

有 gitnexus 时优先通过其获取精确的模块列表和依赖关系。无 gitnexus 时从头文件提取接口签名，标注 `准确度: 中`。

**错误码.md**

仅提取本工程特定错误码（与全局错误码区分），格式同全局错误码。

**其他文档**（编码规范、测试规范、设计文档模板、设计说明）→ `<!-- TODO: 需人工补充 -->`。

### A5. 输出摘要

```markdown
## 初始化完成

| 项 | 值 |
|----|----|
| 阶段 | [阶段名] |
| 范围 | [仅仓库级/指定子工程/全部] |
| 工具 | [gitnexus/文件扫描] |

### 已生成
- [文件] — `<!-- auto-generated -->`

### 已跳过（后续阶段）
- [文件] — 属于 [阶段] 阶段

### 需人工补充
- [文件] — [原因]
```

后续动作：

| 范围 | 后续 |
|------|------|
| 仅仓库级 | 流程结束 |
| 指定子工程 | 对该工程执行 A4.2 |
| 全部 | 等用户确认后，逐个处理子工程 |

---

## 分支 B：更新文档

### B1. 确认更新范围

```
更新范围：
  ├── 全部文档
  ├── 指定层级（仓库级 docs/ / 子工程 docs/）
  └── 指定文档（输入路径）
```

### B2. 扫描代码 → 对比文档

对每个在范围内的文档，获取其代码当前状态并与文档内容对比：

```markdown
## 更新报告：[文件名]

### 新增（代码有，文档无）
- 模块 `xxx` — 头文件 `include/xxx/xxx_interface.h` 中声明 — 建议添加到[章节]

### 过时（文档有，代码无）
- `errors.h` 中 `ERR_OLD=3005` 已删除 — 建议从[错误码章]移除

### 不一致
- [文档描述] — 实际代码中为[正确状态] — 建议修正
```

### B3. 对比粒度

仅对可自动校验的文档类型做对比，不可校验的跳过：

| 文档 | 校验对象 | 可靠度 | 可否直修 |
|------|---------|--------|---------|
| 目录结构.md | 文件树与文档树 | 高 | 是 |
| 全局/工程错误码.md | 枚举值/名称 | 高 | 是 |
| 模块索引.md | 模块清单、接口签名（gitnexus优先） | 高(gitnexus)/中(扫描) | 是(gitnexus) |
| 系统架构总览.md | 子工程清单、技术栈 | 高 | 表可直接修，描述需确认 |
| README/CLAUDE.md | 子工程清单 | 高 | 是 |
| 工程说明.md | 子工程存在性 | 高 | 是 |
| 其他 | 无法自动验证 | — | 报告"需人工审核" |

### B4. 执行更新

| 模式 | 行为 |
|------|------|
| 仅报告差异 | 输出差异 + 建议，不修改文件 |
| 报告并修复 | 可直修的标注 `<!-- auto-fixed -->` 并修改，须确认项列出建议等待手动处理 |

### B5. 输出摘要

```markdown
## 更新完成 — [修复模式/报告模式]

### 已修复（N项）
- [文件]: [变更]

### 待确认（M项）
- [文件]: [建议+理由]

### 无变更（K项）

### 跳过（J项）— 不可自动校验
```

---

## 通用规则

| 场景 | 初始化模式 | 更新模式 |
|------|-----------|---------|
| 已有真实内容 | 跳过，不覆盖 | 与代码对比 |
| 只有模板 | 补充内容 `<!-- auto-filled -->` | 对比，更新过时部分 |
| 不存在 | 按阶段创建 | 若代码中有，建议新增 |
| 不可自动处理 | `<!-- TODO: 需人工补充 -->` | "需人工审核" |

## 来源标注

| 标记 | 含义 |
|------|------|
| `<!-- auto-generated -->` | 完全自动生成 |
| `<!-- auto-filled -->` | 模板基础上补充 |
| `<!-- auto-fixed -->` | 与代码差异自动修复 |
| `<!-- TODO: 需人工补充 -->` | 无法自动处理 |
| `<!-- tool: gitnexus -->` | 基于 gitnexus 生成 |