软件架构图生成器

技能文档

---
name: software-architecture-diagram-generator-showapi
title: 软件架构图生成器
category: 开发工具
description: 输入软件说明书或软著文本，自动解析架构意图、抽取组件与层级，生成 Mermaid 架构代码与高清架构图，并输出含架构概览、详细设计、分析与优化建议的完整架构设计文档。当用户需要「画架构图」「生成软件架构设计文档」「软著申报材料」「架构评审」时触发。
---

# 软件架构图生成器

## 任务目标

- 自动解析软件说明书或软著文本，提取系统架构层级与组件关系
- 生成标准 Mermaid 架构图代码，并渲染输出高清架构图
- 输出包含架构概览、详细设计、架构分析与优化建议的完整架构设计文档
- 适用场景：编写软件设计文档、申请软著、技术方案评审、系统重构分析

## 能力组成

该技能以软件说明书或软著文本作为输入，经过以下五个核心阶段串行处理，最终产出图文并茂的架构设计文档：

1. **意图深度解析**：分析输入文本，识别软件的核心架构风格（如 B/S 架构、微服务、前后端分离等）。
2. **结构化抽取**：基于识别的架构风格，从文本中抽取系统层级（如表现层、业务逻辑层、数据访问层）及核心组件。
3. **Mermaid 代码生成**：根据抽取的层级与组件依赖关系，自动生成符合 Mermaid 语法的架构图源代码。
4. **专业评审与建议**：模拟架构师视角对抽取的结构进行评审，生成架构分析报告及高可用、可扩展等方面的优化建议。
5. **文档融合与图像渲染**：将分析报告、优化建议、Mermaid 代码融合为完整设计文档，同时调用图像渲染服务将 Mermaid 代码转化为高清架构图，通过异步轮询获取图片地址。

## 前置准备

- 凭证：需要自备 ShowAPI AppKey，通过环境变量 `SHOWAPI_APP_KEY` 注入，禁止硬编码到任何文件
  - 获取方式：访问 https://www.showapi.com 注册账号，登录后进入控制台「我的应用」页面获取 appKey
- 依赖：仅使用 Python 标准库，无需安装第三方包

## 技能工作流

### 步骤1：收集用户需求

梳理用户提供的软件说明书、需求文档或软著文本，确认生成架构图的宽高比（选填，可选 1:1、3:4、4:3、16:9、9:16，默认 16:9）。

### 步骤2：异步提交生成任务

调用脚本异步执行架构解析、文档生成与图像渲染任务，**仅返回唯一 task_id**，不阻塞等待。

```bash
python scripts/execute_task.py --raw-text "本软件为一款基于B/S架构的电商订单管理系统..." --aspect-ratio 16:9 --async
```

### 步骤3：轮询查询任务结果

使用 task_id 循环查询任务状态，**每一轮轮询后，即时将当前返回的核心资料同步反馈给用户**，直至获取完整结果。

```bash
python scripts/query_task.py --task-id "返回的task_id值"
```

必须轮询直到任务完成。

### 步骤4：结果解析与落地应用

提取生成的高清架构图 URL、Mermaid 源代码以及结构化的架构设计文档。可直接应用于技术方案汇报或研发协同。

### 步骤5：生成 HTML 汇总页面

生成一个简单的 HTML 页面来融合返回的主要信息，特别是架构图图片。

## 使用示例

### 示例1：电商系统架构图生成

- 输入：一段电商订单管理系统的软件说明书全文
- 流程：异步提交任务 → 获取 task_id → 轮询查询（每轮反馈进度/数据）
- 产出：B/S 架构高清图 + Mermaid 代码 + 包含模块职责与优化建议的完整文档
- 配置要点：`aspect_ratio` 设置为 16:9 适合文档排版

### 示例2：微服务架构设计辅助

- 输入：描述某 SaaS 平台的微服务划分与数据流向文本
- 产出：微服务组件关系图 + 服务解耦度分析报告
- 配置要点：`raw_text` 需尽量包含完整的模块与交互描述

### 示例3：软著申报材料快速生成

- 输入：软著申请中的系统功能描述文本
- 产出：符合软著技术材料要求的架构图及说明文档
- 配置要点：可设置 `aspect_ratio` 为 1:1 生成正方形架构图适配表格

## 输出结果说明

技能运行后，将输出一张高清软件架构图、对应的 Mermaid 源代码，以及一份结构化的架构设计文档。文档包含架构概览、详细设计、架构分析与优化计划四个核心模块。架构图直观展示系统层级与组件间的调用关系，可直接嵌入到 Word 或 Markdown 文档中。

若输出结果包含图片，优先插入对应图片资源，之后再输出 JSON / Markdown 格式的文本内容。

### 异步任务提交响应

```json
{
  "showapi_res_body": {
    "task_id": "唯一任务ID",
    "status": "pending",
    "msg": "任务已提交，正在异步处理中"
  },
  "showapi_res_code": 0
}
```

### 任务查询响应（单轮轮询返回数据，需实时同步给用户）

```json
{
  "showapi_res_body": {
    "architecture_diagram_url": "生成的高清软件架构图访问地址",
    "mermaid_code": "生成的Mermaid架构图源代码",
    "final_document": {
      "overview": "架构概览",
      "detailed_design": "详细设计",
      "analysis_section": "架构分析",
      "optimization_plan": "优化计划",
      "architecture_diagram_code": "架构图代码"
    }
  },
  "showapi_res_code": 0
}
```

## 资源索引

- [scripts/execute_task.py](scripts/execute_task.py)：异步提交架构图及文档生成任务
- [scripts/query_task.py](scripts/query_task.py)：轮询查询异步任务结果

## 注意事项

1. `raw_text` 为必填项，需尽可能完整地描述软件功能、架构模式与技术栈，以保证解析准确度。
2. 所有任务**强制异步执行**，不支持同步模式。
3. 轮询查询过程中，每次获取接口返回数据后，立即将主要内容反馈给用户。
4. AppKey 必须通过环境变量 `SHOWAPI_APP_KEY` 提供，用户需自备 key。

使用说明

# 软件架构图生成器

输入软件说明书或软著文本，自动解析架构意图并抽取组件层级，生成 Mermaid 架构代码、高清架构图与完整架构设计文档。

## 使用

1. 配置凭证（需自备 ShowAPI AppKey）：

```bash
export SHOWAPI_APP_KEY="你的AppKey"
```

2. 异步提交生成任务：

```bash
python scripts/execute_task.py --raw-text "软件说明书或软著全文" --aspect-ratio 16:9 --async
```

3. 用返回的 task_id 轮询查询结果：

```bash
python scripts/query_task.py --task-id "返回的task_id值"
```

轮询完成后可获得架构图 URL、Mermaid 源代码与结构化设计文档。

## 工作原理

技能串行执行五个阶段：解析架构意图（识别 B/S、微服务等风格）→ 抽取系统层级与组件 → 生成 Mermaid 代码 → 架构评审与优化建议 → 融合文档并异步渲染高清架构图。所有任务强制异步执行，仅依赖 Python 标准库。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。