project-docs-gen

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

项目文档生成与维护

定位

管理 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"          → 错误码定义

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

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

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

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

A4.1 仓库级文档

README.md / CLAUDE.md

扫描项目结构，填写：

# [工程名]

## 简介
[目录名]，包含 <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

从代码推断分层：

## 分层架构
```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. 扫描代码 → 对比文档

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

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

### 新增（代码有，文档无）
- 模块 `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. 输出摘要

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

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

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

### 无变更（K项）

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

---

通用规则

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

来源标注

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