Project Docs Gen

项目文档生成与维护

定位

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

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

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

工作流程

Step 0: 确认操作模式

询问用户：

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

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

分支 A：初始化文档

A1. 检查项目结构

检查目标路径 docs/：

读取模板路径：

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

A2. 确认范围与阶段

范围：

阶段：

* 不可自动生成，仅填充模板框架 + <!-- 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

模块职责边界

**模块索引.md**

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

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

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

**错误码.md**

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

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

### A5. 输出摘要

```markdown
## 初始化完成

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

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

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

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

后续动作：

分支 B：更新文档

B1. 确认更新范围

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

B2. 扫描代码 → 对比文档

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

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

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

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

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

B3. 对比粒度

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

B4. 执行更新

B5. 输出摘要

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

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

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

### 无变更（K项）

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

通用规则

来源标注