文档生成

输入要求

代码/项目（必填）：需要生成文档的代码或项目描述
文档类型（必填）：函数文档/README/API文档/架构文档
输出格式（可选）：Markdown/HTML/reStructuredText，默认Markdown
目标读者（可选）：开发者/用户/运维，默认开发者
语言（可选）：中文/英文，默认中文

执行流程

第一步：Spec一致性检查

编写文档前检查与spec的一致性：

如有spec：确保文档描述与spec中的scenario一致
发现不一致：标注文档与spec的偏差，建议同步更新

无spec：文档中标注"基于当前实现，建议补充spec"

✓ Spec一致性检查:
- 文档描述 vs Spec: [一致/不一致]
- 需要同步更新: [是/否]

第二步：内容分析

分析目标受众（开发者/用户/维护者）
确定文档类型和深度
识别关键信息点

第三步：结构设计

设计文档大纲和章节
确定示例和图示
规划交叉引用

第四步：内容编写

编写清晰简洁的说明
添加代码示例和截图
包含使用场景和最佳实践
引用Spec：在相关章节引用spec中的scenario作为行为依据

第五步：引用来源与溯源

文档中的关键结论、行为说明、接口字段、配置项和限制条件必须可追溯；无法验证的内容必须标注"待确认"，不得虚构来源。

来源类型	引用格式	使用场景
本地代码	`来源：path/to/file.ext:line`	函数行为、参数、默认值、错误处理
Spec/Scenario	`来源：spec.md / Scenario: xxx`	业务行为、验收标准、边界条件
API/OpenAPI	`来源：openapi.yaml#/paths/...`	接口路径、请求参数、响应字段、错误码
配置/环境	`来源：.env.example / config/*.php`	环境变量、部署参数、默认配置
测试用例	`来源：tests/...`	示例输入输出、回归场景、异常路径
官方文档	`来源：官方文档 URL + 访问日期`	框架/API/依赖行为说明
项目记忆	`来源：project_memory.md / Decision: xxx`	既有约定、历史决策、团队规范

推荐在文档末尾追加“资料来源”章节：

## 资料来源

- `src/OrderService.php:42-88`：订单状态流转逻辑
- `spec.md / Scenario: cancel-paid-order`：已支付订单取消规则
- `openapi.yaml#/paths/~1orders~1{id}/post`：接口请求和响应结构

第六步：质量检查

检查准确性和完整性
验证代码示例可运行
确认格式一致性
Spec同步：确认文档与spec无冲突

第七步：记录到项目记忆

文档生成完成后，将关键决策记录到项目记忆（参见 project-memory-management.md）：

记录文档结构和模板选择理由
记录 API 文档规范约定
更新项目文档索引，确保后续文档保持一致性

输出格式

函数文档示例

## [函数名]

**功能**：[一句话说明]

**签名**：

```[语言]
[函数签名]
```

参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | [参数] | [类型] | [是/否] | [说明] |

返回值： | 类型 | 说明 | |------|------| | [类型] | [说明] |

异常： | 异常 | 说明 | |------|------| | [异常] | [触发条件] |

示例：

[使用示例]


### README示例

```markdown
# [项目名]

[项目简介]

## 功能特性

- [特性1]
- [特性2]

## 安装

```bash
[安装命令]

使用

[使用示例]

API文档

自动由代码注解/JSDoc/Python docstrings 提取生成。如项目接入 Swagger/OpenAPI，同时导出机器可读接口定义。

贡献

[贡献指南]


## 质量标准

- 文档必须准确反映代码功能，不能虚构不存在的功能
- 参数说明必须包含类型、必填性和取值范围
- 示例代码必须可直接运行，不能是伪代码
- README必须包含安装和使用说明，不能只有功能列表
- API文档必须包含错误码和异常情况
- 不得遗漏关键信息（如必要的配置项、环境要求）
- 关键结论必须有来源；缺少来源时必须标注"待确认"和下一步验证方法

## 失败回退机制

| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |
| - | - | - | - | - |
| 第一步：Spec一致性检查 | 无spec或spec与代码严重不一致 | 标注"基于当前实现反推"，跳过一致性检查 | 1 | 建议先走 Spec驱动开发 补全spec |
| 第二步：内容分析 | 代码量大，关键信息点超出单次分析能力 | 按模块分批分析，每批输出局部文档 | 0 | 建议缩小文档范围或分章节生成 |
| 第三步：结构设计 | 文档类型与目标读者组合产生结构冲突 | 优先服务主要读者，次要读者用附录补充 | 1 | 输出两套结构方案，由用户选择 |
| 第四步：内容编写 | 代码示例无法直接运行 | 标注"示例待验证"，提供伪代码框架 | 2 | 输出最小可运行示例 + 待补全标记 |
| 第五步：引用来源与溯源 | 关键结论找不到来源 | 标注"待确认"，列出需补充的代码/Spec/文档证据 | 1 | 不把该结论写成已确认事实 |
| 第六步：质量检查 | 发现文档与代码功能不一致 | 退回第四步修订内容 | 2 | 标注不一致清单，建议代码与文档同步评审 |
| 第七步：记录到项目记忆 | 项目记忆系统不可用 | 输出文档索引到本地文件 | 1 | 标注"索引未沉淀"，提示用户手动保存 |

## 关联 reference

- **frontend-design**（前端设计）— 生成设计系统、组件规范、页面交互说明时参考 `frontend-design`
- **code-review**（代码审查）— 生成前可用 `code-review` 确保代码逻辑正确
- **api-design**（API设计）— API设计完成后可用 `doc-generation` 生成接口文档
- **code-generation**（代码生成）— 生成代码后可用 `doc-generation` 生成配套文档
- **project-memory-management**（项目记忆管理）— 记录文档结构、模板选择理由、API 文档规范约定并更新文档索引

doc-generation.md 6.4 KB Постоянная ссылка История Исходник