docs: 新增13.1开发者使用助手生成规范，AI自动产出API手册
This commit is contained in:
+188
-28
@@ -32,34 +32,35 @@
|
||||
23. [11. 反馈迭代](#11-反馈迭代)
|
||||
24. [12. 技术债务管理](#12-技术债务管理)
|
||||
25. [13. 知识管理](#13-知识管理)
|
||||
26. [14. 文件驱动设计生产（DDD）](#14-文件驱动设计生产ddd)
|
||||
27. [附录A: 安全开发生命周期](#附录a-安全开发生命周期)
|
||||
28. [附录B: 合规性管理](#附录b-合规性管理)
|
||||
29. [附录C: 供应链安全](#附录c-供应链安全)
|
||||
30. [附录D: 无障碍访问规范](#附录d-无障碍访问规范)
|
||||
31. [附录E: 依赖升级管理](#附录e-依赖升级管理)
|
||||
32. [附录F: 团队沟通与知识传递](#附录f-团队沟通与知识传递)
|
||||
33. [附录G: AI Agent 自主开发操作规范（PA 章）](#附录g-ai-agent-自主开发操作规范)
|
||||
34. [PA.0 核心概念与能力模型](#pa0-核心概念与能力模型)
|
||||
35. [PA.0.3 环境自检](#pa03-环境自检--启动前必执行)
|
||||
36. [PA.0.4 文档读取策略](#pa04-文档读取策略--ai-启动后必读清单)
|
||||
37. [PA.1 项目状态文件](#pa1-项目状态文件-project_stateyaml)
|
||||
38. [PA.2 上下文窗口管理](#pa2-上下文窗口管理策略)
|
||||
39. [PA.3 AI 执行权限](#pa3-ai-执行权限与自主决策边界)
|
||||
40. [PA.4 每阶段 AI 执行标准 SOP](#pa4-每阶段-ai-执行标准-sop)
|
||||
41. [PA.5 AI 版编码规范](#pa5-ai-版编码规范与代码生成模板)
|
||||
42. [PA.6 AI 质量自检门禁](#pa6-ai-质量自检门禁)
|
||||
43. [PA.7 失败恢复与阻塞处理](#pa7-失败恢复与阻塞处理)
|
||||
44. [PA.8 人类反馈级联传播](#pa8-人类反馈级联传播)
|
||||
45. [PA.9 多 Agent 协作](#pa9-多-agent-协作协议)
|
||||
46. [PA.10 提示词工程规范](#pa10-提示词工程规范)
|
||||
47. [PA.11 项目初始化 AI 流程](#pa11-项目初始化-ai-标准流程)
|
||||
48. [PA.12 人类通信格式](#pa12-人类通信格式规范)
|
||||
49. [PA.13 中断处理协议](#pa13-中断处理协议)
|
||||
50. [PA.14 异常场景处理](#pa14-异常场景处理)
|
||||
51. [PA.15 端到端走查示例](#pa15-端到端走查示例)
|
||||
52. [PA.16 持续改进机制](#pa16-持续改进机制)
|
||||
53. [附录H: AI 辅助设计开发规范](#附录h-ai-辅助设计开发规范)
|
||||
26. [13.1 开发者使用助手生成规范](#131-开发者使用助手生成规范)
|
||||
27. [14. 文件驱动设计生产（DDD）](#14-文件驱动设计生产ddd)
|
||||
28. [附录A: 安全开发生命周期](#附录a-安全开发生命周期)
|
||||
29. [附录B: 合规性管理](#附录b-合规性管理)
|
||||
30. [附录C: 供应链安全](#附录c-供应链安全)
|
||||
31. [附录D: 无障碍访问规范](#附录d-无障碍访问规范)
|
||||
32. [附录E: 依赖升级管理](#附录e-依赖升级管理)
|
||||
33. [附录F: 团队沟通与知识传递](#附录f-团队沟通与知识传递)
|
||||
34. [附录G: AI Agent 自主开发操作规范（PA 章）](#附录g-ai-agent-自主开发操作规范)
|
||||
35. [PA.0 核心概念与能力模型](#pa0-核心概念与能力模型)
|
||||
36. [PA.0.3 环境自检](#pa03-环境自检--启动前必执行)
|
||||
37. [PA.0.4 文档读取策略](#pa04-文档读取策略--ai-启动后必读清单)
|
||||
38. [PA.1 项目状态文件](#pa1-项目状态文件-project_stateyaml)
|
||||
39. [PA.2 上下文窗口管理](#pa2-上下文窗口管理策略)
|
||||
40. [PA.3 AI 执行权限](#pa3-ai-执行权限与自主决策边界)
|
||||
41. [PA.4 每阶段 AI 执行标准 SOP](#pa4-每阶段-ai-执行标准-sop)
|
||||
42. [PA.5 AI 版编码规范](#pa5-ai-版编码规范与代码生成模板)
|
||||
43. [PA.6 AI 质量自检门禁](#pa6-ai-质量自检门禁)
|
||||
44. [PA.7 失败恢复与阻塞处理](#pa7-失败恢复与阻塞处理)
|
||||
45. [PA.8 人类反馈级联传播](#pa8-人类反馈级联传播)
|
||||
46. [PA.9 多 Agent 协作](#pa9-多-agent-协作协议)
|
||||
47. [PA.10 提示词工程规范](#pa10-提示词工程规范)
|
||||
48. [PA.11 项目初始化 AI 流程](#pa11-项目初始化-ai-标准流程)
|
||||
49. [PA.12 人类通信格式](#pa12-人类通信格式规范)
|
||||
50. [PA.13 中断处理协议](#pa13-中断处理协议)
|
||||
51. [PA.14 异常场景处理](#pa14-异常场景处理)
|
||||
52. [PA.15 端到端走查示例](#pa15-端到端走查示例)
|
||||
53. [PA.16 持续改进机制](#pa16-持续改进机制)
|
||||
54. [附录H: AI 辅助设计开发规范](#附录h-ai-辅助设计开发规范)
|
||||
|
||||
---
|
||||
|
||||
@@ -123,6 +124,12 @@ docs/
|
||||
│ ├── 30-补充设计要点.md # 日志、错误处理、配置管理、备份
|
||||
│ └── 31-开发进度跟踪.md # 项目仪表盘、Phase 进度、任务状态
|
||||
│
|
||||
├── api/ # 使用助手（AI 自动生成）
|
||||
│ ├── README.md # 模块总览 + 目录索引
|
||||
│ ├── {module}.md # 每个模块的 API 手册
|
||||
│ ├── examples.md # 常见用法速查
|
||||
│ └── call-graph.md # 调用关系图
|
||||
│
|
||||
└── plan/
|
||||
├── README.md # 计划方法论、进度约定
|
||||
└── {Phase名}-执行计划.md # 具体 Phase 的任务分解、依赖图、里程碑
|
||||
@@ -2579,8 +2586,161 @@ Major (1.0.0): 每 12 月 架构变更 / 里程碑
|
||||
|
||||
---
|
||||
|
||||
### 13.1 开发者使用助手生成规范
|
||||
|
||||
> **本节作用**：要求 AI 在编码阶段同步生成一份可浏览的"使用助手"文档，类似 Qt Assistant，让开发者能快速查阅每个模块、类、函数的用法和示例。
|
||||
|
||||
#### 目标
|
||||
|
||||
AI 在完成编码后，自动扫描源代码，生成一份**结构化的 API 使用手册**，包含：
|
||||
|
||||
1. **模块总览** — 每个模块的职责、对外接口、依赖关系
|
||||
2. **类/结构体参考** — 每个公开类的字段、方法、构造方式
|
||||
3. **函数/方法字典** — 每个公开函数的签名、参数说明、返回值、异常、使用示例
|
||||
4. **调用关系图** — 模块间的调用链路（文本形式）
|
||||
5. **常见用法速查** — 按场景组织的代码片段（如"如何创建对象"、"如何查询数据"）
|
||||
|
||||
#### 产出物
|
||||
|
||||
| 产出 | 格式 | 说明 | 对应文件 |
|
||||
|------|------|------|----------|
|
||||
| 使用助手主文档 | Markdown | 模块总览 + 目录索引 | `docs/api/README.md` |
|
||||
| 模块 API 手册 | Markdown | 每个模块一个文件 | `docs/api/{module}.md` |
|
||||
| 类参考 | Markdown | 每个核心类一个章节 | 内嵌于模块手册 |
|
||||
| 函数字典 | Markdown | 按模块分组 | 内嵌于模块手册 |
|
||||
| 使用示例集 | Markdown + 代码块 | 按场景组织 | `docs/api/examples.md` |
|
||||
| 调用关系图 | Markdown + ASCII | 模块间依赖 | `docs/api/call-graph.md` |
|
||||
|
||||
#### 使用助手文档模板
|
||||
|
||||
```markdown
|
||||
# {项目名} 使用助手
|
||||
|
||||
> AI 自动生成，基于源代码扫描。最后更新: {日期}
|
||||
|
||||
---
|
||||
|
||||
## 快速导航
|
||||
|
||||
| 模块 | 说明 | 手册 |
|
||||
|------|------|------|
|
||||
| {module-a} | {一句话说明} | [查看](#module-a) |
|
||||
| {module-b} | {一句话说明} | [查看](#module-b) |
|
||||
|
||||
---
|
||||
|
||||
## {module-name} 模块
|
||||
|
||||
### 职责
|
||||
|
||||
{模块做什么、解决什么问题}
|
||||
|
||||
### 依赖
|
||||
|
||||
{本模块依赖哪些其他模块}
|
||||
|
||||
### 公开 API
|
||||
|
||||
#### 类: {ClassName}
|
||||
|
||||
| 方法 | 签名 | 说明 |
|
||||
|------|------|------|
|
||||
| {methodName} | `{returnType} {methodName}({params})` | {一句话说明} |
|
||||
|
||||
**{methodName} 详解**
|
||||
|
||||
```cpp
|
||||
// 函数签名
|
||||
ReturnType ClassName::methodName(ParamType param1, ParamType param2);
|
||||
|
||||
// 参数说明
|
||||
// param1 — {参数含义、取值范围、默认值}
|
||||
// param2 — {参数含义}
|
||||
|
||||
// 返回值
|
||||
// {返回值含义}
|
||||
|
||||
// 异常
|
||||
// {可能抛出的异常及条件}
|
||||
|
||||
// 使用示例
|
||||
auto result = obj.methodName(value1, value2);
|
||||
```
|
||||
|
||||
**调用示例**
|
||||
|
||||
```cpp
|
||||
// 场景: {描述使用场景}
|
||||
#include "{module}/{header}.h"
|
||||
|
||||
void example() {
|
||||
// 1. 创建对象
|
||||
ClassName obj;
|
||||
|
||||
// 2. 调用方法
|
||||
auto result = obj.methodName(value1, value2);
|
||||
|
||||
// 3. 处理结果
|
||||
if (result.isValid()) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见用法速查
|
||||
|
||||
### 场景: {如"创建并初始化"}
|
||||
|
||||
```cpp
|
||||
// 步骤 1: ...
|
||||
// 步骤 2: ...
|
||||
```
|
||||
|
||||
### 场景: {如"查询数据"}
|
||||
|
||||
```cpp
|
||||
// 步骤 1: ...
|
||||
// 步骤 2: ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 调用关系图
|
||||
|
||||
```
|
||||
ModuleA ──调用──► ModuleB ──调用──► ModuleC
|
||||
│
|
||||
└──调用──► ModuleD
|
||||
```
|
||||
```
|
||||
|
||||
#### AI 生成规则
|
||||
|
||||
1. **扫描范围**: 所有 `public` / `export` 的类、函数、枚举、常量
|
||||
2. **忽略**: `private` / `internal` / `test` 文件、自动生成的代码
|
||||
3. **参数推断**: 从函数签名和注释中提取参数含义；若无注释，标注 `{待补充}`
|
||||
4. **示例生成**: 每个公开函数至少一个使用示例；复杂函数至少两个（简单场景 + 高级场景）
|
||||
5. **类型标注**: 所有参数和返回值必须标注类型
|
||||
6. **异常标注**: 如果函数可能抛出异常或返回错误码，必须说明
|
||||
|
||||
#### 更新时机
|
||||
|
||||
- 每次编码阶段完成后，AI 重新扫描并更新使用助手
|
||||
- 每次 API 变更后，同步更新对应模块的手册
|
||||
- 每次 Phase 完成后，生成完整版本
|
||||
|
||||
#### 检查清单
|
||||
|
||||
- [ ] 每个公开模块都有对应的 API 手册文件
|
||||
- [ ] 每个公开类都有字段和方法说明
|
||||
- [ ] 每个公开函数都有签名、参数、返回值、示例
|
||||
- [ ] 常见用法速查覆盖了主要使用场景
|
||||
- [ ] 调用关系图准确反映模块间依赖
|
||||
- [ ] 所有代码示例可编译通过
|
||||
- [ ] 文档在 API 变更后同步更新
|
||||
|
||||
---
|
||||
|
||||
## 14. 文件驱动设计生产（DDD）
|
||||
|
||||
Reference in New Issue
Block a user