Technical Solution Document Generator

本技能帮助用户从项目目录中收集信息，分析需求，设计系统架构，并生成专业的技术解决方案文档。

使用场景

当用户提出类似以下请求时触发此技能：

"了解$dir这个项目，并帮我生成一份技术解决方案"
"为项目$dir创建一个技术方案文档"
"分析$dir项目并输出系统架构设计"

前置条件

用户应将所有项目相关信息放置在指定的$dir目录下，包括：

背景调查报告
需求文档（.docx, .pptx, .xlsx, .pdf等）
设计文档
交互原型
其他相关资料

执行流程

Phase 1: 背景调查 (Discovery)

扫描项目目录
- 使用glob扫描$dir目录结构
- 识别所有文档文件（.md, .docx, .pptx, .xlsx, .pdf等）
- 列出发现的文件清单
收集背景信息 从可用文档中提取以下信息：
- 参与者：用户、客户、利益相关者
- 目标：项目旨在实现的核心目标
- 挑战：可能遇到的障碍或限制
- 进度：项目当前在真实世界中的推进情况
- 预算：项目的财务资源
- 其他相关信息
信息缺口识别
- 如文档中缺少关键背景信息，主动向用户提问
- 示例提问：
  - "请问这个项目的客户/甲方是谁？"
  - "项目的目标交付时间是什么时候？"
  - "是否有预算限制需要考虑？"

Phase 2: 需求分析 (Analysis)

文档内容提取
- 对于文本文件(.md, .txt)：直接读取内容
- 对于非文本文件：
  - .pptx → 使用pptx skill分析
  - .docx → 使用docx skill分析
  - .xlsx → 使用xlsx skill分析
  - .pdf → 使用pdf skill分析
需求整理 将收集到的需求分类为：
- 功能需求：系统应该做什么
- 非功能需求：性能、安全、可扩展性等
- 约束条件：技术栈、时间、预算限制
需求验证
- 向用户确认理解是否正确
- 澄清模糊或不明确的需求点

Phase 3: 架构及功能设计 (Design)

系统架构设计
- 确定系统的主要组件
- 定义组件之间的关系和交互
- 考虑系统的可扩展性、可维护性和性能
创建架构图
- 使用Mermaid语法创建图表
- 支持的图表类型：
  - 系统架构图 (graph TB/LR)
  - 数据流图
  - 时序图 (sequenceDiagram)
  - 类图 (classDiagram)
示例：
```
graph TB
    A[用户界面] --> B[API网关]
    B --> C[业务服务层]
    C --> D[数据访问层]
    D --> E[(数据库)]
```
组件详细设计
- 前端：技术栈、设计模式、UI框架
- 后端：API设计、业务逻辑、中间件
- 数据库：数据模型、存储方案
创建交互式原型 (Interactive Prototype)
- 识别架构中的关键交互或复杂数据流
- 使用 web-artifacts-builder 或 frontend-design 技能创建交互式原型
- 使用模板 references/demo-prompt-template.md 构建提示词
- 将生成的HTML原型保存至 $dir/prototypes/ 目录
捕获原型截图
- 使用 playwright 技能（或 dev-browser）打开生成的HTML原型
- 截取关键交互状态的屏幕截图
- 将截图保存至 $dir/assets/ 目录，命名清晰（如 auth-flow-demo.png）

Phase 4: 文档创建 (Drafting)

使用模板
- 加载references/technical-solution-template.md作为基础模板
- 根据项目具体情况填充各章节内容
文档结构 按照模板结构组织内容：
- 执行摘要
- 背景与需求
- 系统架构（在此处插入Mermaid图表和原型截图）
  - 插入截图示例：![交互原型：用户登录流程](./assets/auth-flow-demo.png)
  - 添加说明文字：*图：用户登录流程的交互原型截图。完整演示请查看 [HTML文件](./prototypes/login.html)*
- 实施计划
- 风险评估
格式要求
- 使用Markdown格式
- 插入Mermaid图表（使用```mermaid代码块）
- 使用表格展示对比信息
- 保持专业、清晰的技术写作风格

Phase 5: 文档转换 (Delivery)

Markdown转DOCX

使用提供的脚本进行转换：

./scripts/convert_doc.sh <input.md> [output.docx]

或直接运行Pandoc命令：

pandoc "source.md" \
  --lua-filter=scripts/mermaid-filter.lua \
  -o "output.docx"

验证输出
- 检查生成的DOCX文件
- 确认图表正确渲染
- 验证格式符合预期
交付
- 向用户展示生成的文档
- 提供下载链接或文件路径
- 根据反馈进行调整

依赖检查

在执行文档转换前，请确认以下依赖已安装：

Pandoc: 文档转换工具
```
pandoc --version
```
Mermaid CLI (mmdc): Mermaid图表渲染
```
mmdc --version
```

如果依赖缺失，请提示用户先安装：

Pandoc: https://pandoc.org/installing.html
Mermaid CLI: npm install -g @mermaid-js/mermaid-cli

资源文件

模板文件

references/technical-solution-template.md - 技术解决方案文档模板
references/demo-prompt-template.md - 交互式原型请求模板

脚本文件

scripts/mermaid-filter.lua - Pandoc Lua过滤器，用于处理Mermaid图表
scripts/convert_doc.sh - 文档转换辅助脚本

最佳实践

信息收集要全面：不要遗漏任何项目相关文档
架构设计要合理：考虑可扩展性、性能和可维护性
图表要清晰：使用Mermaid创建易于理解的架构图
文档要专业：遵循技术写作规范，语言准确、结构清晰
与用户确认：关键决策点和最终输出都要与用户确认

示例输出

生成的技术解决方案文档应类似于：

examples/系统解决方案示例.md （如存在）

故障排除

问题：Pandoc命令失败

检查Pandoc是否已安装
确认脚本路径正确

问题：Mermaid图表未渲染

确认mmdc已安装并可访问
检查Mermaid语法是否正确

问题：文档格式错乱

检查Markdown语法
确认使用标准Markdown扩展