软件设计文档生成

根据上传需求文档自动生成详细的软件设计文档，包含架构、模块、接口及通信协议等内容，且关键步骤需用户确认。

Install

openclaw skills install skill-doc-design

Skill: 依据文档生成软件设计文档

根据上传的需求文档/技术说明，自动生成可指导开发的设计文档

触发条件

用户说（任意一项）：

「依据xxx写设计文档」
「根据xx文档生成设计说明」
「帮我做个设计文档」
「依据上传的文件写软件设计」
其他明确要求生成设计文档的表达

工作流程

Step 1: 识别新上传的文件

执行: ls -la /root/.openclaw/media/inbound/
筛选: 最近5分钟内上传的文件（排除临时文件）
输出: 文件列表

Step 2: 分析文件名，询问用户确认文件夹名

分析:
  - 提取所有文件的公共关键词
  - 生成候选文件夹名（如：飞奕多联机空调集中控制和计费软件）
  
询问用户:
  "检测到 X 个文件:
   - file1.docx
   - file2.docx
   
   建议文件夹名: XXX
   确认用这个名？还是你另外起一个？"

⚠️ 必须确认，不自行决定

Step 3: 移动文件到新文件夹

执行:
  mkdir -p /workspace/{文件夹名}
  mv /inbound/xxx.docx /workspace/{文件夹名}/

Step 4: 提取文件内容

根据文件扩展名选择解析方式：

扩展名	解析方式
.docx	unzip + 解析 document.xml
.doc	提示用户转换为 docx
.pdf	使用 pdftotext 或提示用户
.txt / .md	直接读取
其他	提示用户转换格式

输出: 提取的文本内容（关键章节：功能需求、技术架构、模块设计、通信协议等）

Step 5: 分析内容，列出关键发现，询问用户确认

分析并总结:
  - 项目类型（嵌入式/Web/API/桌面应用...）
  - 技术栈（语言、框架、数据库...）
  - 核心功能模块
  - 通信协议
  - 存储方案
  
询问用户:
  "从文档中分析出以下信息，请确认：
   
   项目类型: 嵌入式系统
   处理器: Rockchip RK3506
   编程语言: C
   操作系统: Linux
   通信: 4G / RS485 / 蓝牙
   协议: MQTT / Modbus
   ...
   
   以上正确吗？有补充或修正？"

⚠️ 必须确认，不自行假设

Step 6: 询问文档范围

询问用户:
  "设计文档需要包含哪些章节？
   
   可选章节：
   ✓ 功能需求
   ✓ 系统架构
   ✓ 模块设计（含接口定义）
   ✓ 数据结构定义
   ✓ 通信协议（MQTT/Modbus/蓝牙）
   ✓ 存储设计（Flash分区/数据库）
   ✓ API设计
   ✓ 接口定义
   ✓ 错误处理
   ✓ 部署方案
   
   需要哪些？需要补充什么？"

⚠️ 必须确认

Step 7: 开始生成，每分钟发送进度通知

开始前:
  "好的，开始生成设计文档。预计需要3-5分钟，每分钟我会向你汇报进度。"
  
执行过程中（每60秒）:
  "⏳ 正在撰写中，请稍候...
   - 已完成：模块设计章节
   - 进度：约60%
   - 预计还需：2分钟"
   
最后:
  "即将完成，正在整理目录结构..."

✅ 每分钟主动发送进度，避免用户以为卡死

Step 8: 生成目录结构 + 空文件

目录结构示例:
{项目名}/
├── DESIGN.md                 # 设计文档主文件
├── docs/
│   ├── 01-概述.md
│   ├── 02-功能需求.md
│   ├── 03-系统架构.md
│   ├── 04-模块设计/
│   │   ├── 通讯模块.md
│   │   ├── 协议处理模块.md
│   │   ├── 计量计费模块.md
│   │   └── 升级模块.md
│   ├── 05-通信协议.md
│   ├── 06-存储设计.md
│   └── 07-接口定义.md
├── src/
│   ├── main.c
│   ├── config/
│   │   └── config.h
│   ├── modules/
│   │   ├── comm.c / comm.h
│   │   ├── protocol.c / protocol.h
│   │   ├── billing.c / billing.h
│   │   └── upgrade.c / upgrade.h
│   └── include/
│       └── types.h
├── include/                   # 头文件目录
├── docs/                     # 文档目录
└── README.md

执行:
  mkdir -p /workspace/{项目名}/{子目录}
  touch /workspace/{项目名}/docs/01-概述.md  # 创建空文件
  ...

Step 9: 生成 DESIGN.md 主文档

内容结构:
  # {项目名}软件设计文档
  
  ## 一、引言
    - 编写目的
    - 项目背景
    - 术语定义
  
  ## 二、系统概述
    - 系统目标
    - 运行环境
    - 技术架构
  
  ## 三、功能需求
    - 设备控制功能
    - 计量计费功能
    - 通信功能
    - ...
  
  ## 四、详细设计
    - 模块划分
    - 模块间接口
    - 核心数据结构
    - API定义
  
  ## 五、通信协议
    - MQTT主题格式
    - Modbus寄存器
    - 蓝牙协议
  
  ## 六、存储设计
    - Flash分区
    - 数据结构
  
  ## 七、错误处理
    - 错误码
    - 告警定义
  
  ## 八、附录
    - 版本历史
    - 参考资料

Step 10: 完成通知

通知用户:
  "✅ 设计文档生成完成！
   
   📁 位置: /workspace/{项目名}/DESIGN.md
   📂 目录: /workspace/{项目名}/
   
   包含内容:
   - DESIGN.md (主设计文档，33KB)
   - docs/ (各章节拆分文件)
   - src/ (代码框架目录)
   
   请查看，有需要修改或补充的地方告诉我。"

特殊处理

文件名分析规则

输入: ["飞奕多联机空调集中控制和计费软件登记技术交底文件.docx", "飞奕多联机空调集中控制和计费软件设计说明.docx"]
处理:
  1. 提取最长公共子串
  2. 去掉"登记技术交底文件"、"设计说明"等后缀
  3. 候选: "飞奕多联机空调集中控制和计费软件"
  
如果无法提取:
  询问用户: "你想用什么文件夹名？"

内容提取失败

如果无法提取docx内容:
  提示用户: "无法自动解析xxx.docx，请将内容粘贴给我，或转换为txt/md格式"

用户未响应

如果用户在任一步骤超过5分钟未回复:
  发送提醒: "还在等你确认信息，请告诉我你的选择～"
  
超过10分钟:
  发送: "我先暂停，有需要时说「继续」继续生成"

约束

所有关键决策必须先询问用户：文件夹名、技术栈、文档章节
每分钟发送进度通知：即使还没完成
完成后必须通知用户：告知位置和包含内容
不支持的文件格式：明确提示用户转换

依赖工具

ls, mkdir, mv, touch - 文件操作
unzip - 解析docx
message - 发送进度通知