oh-pdd-design-doc-generator（哦 pdd 设计文档生成器）

设计文档生成器

基于 PRD 文档自动生成鸿蒙系统（HarmonyOS/OpenHarmony）设计文档，包括架构设计文档和功能设计文档。

快速开始

提供 PRD 文档路径：

基于 {PRD文档} 生成设计文档

指定输出类型：

生成架构设计文档和功能设计文档，基于 {PRD文档路径}

OpenHarmony 代码分析

在生成设计文档前，需要分析 OpenHarmony 存量代码结构，确保新设计与现有架构兼容。

分析步骤

1. 发现代码结构

使用 Glob 工具快速发现目录结构和关键文件：

2. 搜索关键信息

使用 Grep 工具搜索关键字提取组件信息：

3. 读取关键配置

使用 Read 工具读取关键配置文件：

• bundle.json: 部件定义和子系统归属
• BUILD.gn: 构建依赖和编译选项
• sa_profile/*.json: SA 配置和启动参数
• README.md: 模块说明和使用指南
• *.idl: 接口定义和数据结构

4. 智能探索

使用 Task 工具启动 Explore 代理进行多轮探索：

• 发现相关模块的目录结构
• 查找相似功能的实现参考
• 提取接口设计和数据结构

命名模式推断

通过文件和目录命名推断功能：

分析输出

代码分析完成后生成：

1. 现有 SA 清单: 已分配的 SA ID 和服务名称
2. 子系统组织: 子系统和部件的层次结构
3. 依赖关系图: 组件间的依赖关系
4. 接口参考: 相似功能的接口设计参考
5. 代码风格参考: 命名规范、目录结构等

竞品方案分析章节要求

架构设计文档 第2章必须为竞品方案分析，位于需求背景之后、鸿蒙系统架构分析之前。

章节结构

2. 竞品方案分析

2.1 竞品识别

• 列出主要竞品（至少2-3个）
• 说明竞品选择理由
• 竞品类型：同类产品、技术方案、行业标准

2.2 竞品技术方案分析

对每个竞品分析：

• 核心技术架构
• 关键技术组件
• 通信机制
• 数据流程
• 关键流程图、时序图

2.3 技术对比表格

2.4 差异化设计

• 本方案相对于竞品的创新点
• 解决的竞品痛点
• 技术优势说明
• 借鉴与改进

输出要求

• 使用4+1视图、流程图、时序图呈现竞品技术方案
• 至少包含2个竞品的详细分析
• 必须有技术对比表格
• 必须明确差异化设计点

章节顺序验证

生成架构设计文档时，验证章节顺序：

标准顺序：需求背景 → 竞品方案分析 → 鸿蒙系统架构分析 → 架构设计...

验证规则：

• ✅ 第1章必须是"需求背景"
• ✅ 第2章必须是"竞品方案分析"（必需）
• ✅ 竞品方案分析必须在需求背景之后
• ✅ 竞品方案分析必须在架构设计之前
• ❌ 如顺序错误，提示用户调整

验证逻辑：

1. 提取文档中所有一级标题（# 开头）
2. 验证第1章是否为"需求背景"
3. 验证第2章是否为"竞品方案分析"或"竞品分析"
4. 如缺失第2章或顺序错误，返回错误提示

生成内容

架构设计文档 (architecture_vX.md)

包含以下标准章节（按顺序）：

功能设计文档 (functiondesign_vX.md)

包含以下标准章节：

架构层次

┌─────────────────────────────────────────┐
│              应用层 (Application)         │
│         设置应用 | 文件管理 | 磁盘工具      │
└─────────────────────────────────────────┘
                    ↓ NAPI/IPC
┌─────────────────────────────────────────┐
│               服务层 (Service)            │
│      DiskManagement SA (5001)            │
│  DiskInfo | Format | Repair | Status     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│               工具层 (Tools)              │
│    FormatTool | FsckTool | PartedTool    │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│              系统层 (System)              │
│  Storage SA | OsAccount SA | HiSysEvent   │
└─────────────────────────────────────────┘

SA 划分规则

状态机设计

使用 V11.0 状态机规范：

stateDiagram-v2
    [*] --> UNKNOWN
    UNKNOWN --> NORMAL: 检测成功
    UNKNOWN --> ABNORMAL: 检测失败
    NORMAL --> CHECKING: 开始检测
    CHECKING --> NORMAL: 检测完成
    CHECKING --> REPAIRING: 需要修复
    CHECKING --> ABNORMAL: 检测失败
    REPAIRING --> NORMAL: 修复成功
    REPAIRING --> ABNORMAL: 修复失败
    ABNORMAL --> CHECKING: 重新检测

时序图示例

sequenceDiagram
    participant App as 应用
    participant Kit as DiskManagementKit
    participant SA as DiskManagement SA
    participant Tool as FormatTool

    App->>Kit: formatDisk(diskId, fsType)
    Kit->>SA: format(diskId, fsType)
    SA->>SA: 权限校验
    SA->>SA: 状态验证
    SA->>Tool: executeFormat()
    Tool-->>SA: onProgress(percent)
    SA-->>Kit: onFormatProgress()
    Kit-->>App: progress callback
    Tool-->>SA: result
    SA-->>Kit: result
    Kit-->>App: format result

参考文档

• 架构设计模板: references/architecture_template.md
• 功能设计模板: references/functional_template.md
• 状态机规范: references/state_machine_spec.md
• 接口设计指南: references/interface_guide.md

与 PRD 的映射关系

依赖服务映射

输出目录结构

output/
├── architecture_v1.md      # 架构设计文档
├── functiondesign_v1.md     # 功能设计文档
├── code_paths_v1.md        # 代码路径文档
└── diagrams/               # 生成的图表文件
    ├── architecture.png
    ├── state_machine.png
    └── sequence.png

使用示例

生成完整设计文档：

基于 {PRD文档} 生成架构和功能设计文档

仅生成架构设计：

只生成架构设计文档，基于 {PRD文档}

指定 SA ID：

生成设计文档，SA ID 使用 {SA_ID}，基于 {PRD文档}

指定产品名称和版本：

为 {产品名} {版本} 生成设计文档，版本 {文档版本}，基于 {PRD文档}

指定输出目录：

生成设计文档到 ./design_docs 目录，基于 {PRD文档}

命名规范

版本管理规则

图表格式

使用 Mermaid 语法绘制图表。支持的图表类型：

• 流程图: graph TD 或 flowchart TD
• 状态图: stateDiagram-v2
• 时序图: sequenceDiagram
• 类图: classDiagram
• 组件图: graph LR

错误处理