软件架构图生成器

概述

任务目标

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

能力组成

能力流程描述

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

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

技能能力组成流程图

前置准备

• 凭证：配置 ShowAPI AppKey，凭证名称：showapi_appkey
  • 获取方式：访问 https://www.showapi.com 注册账号(注册即送2元可用余额。)，登录后进入 https://www.showapi.com/console#/myApp 获取 appKey
• 依赖：仅使用 Python 标准库，无需安装第三方包

操作步骤

标准流程（强制异步执行）

1. 收集用户需求

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

1. 异步提交生成任务

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

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

1. 轮询查询任务结果（必选）

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

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

1. 等待结果完成

必须轮询直到完成。

1. 结果解析与落地应用

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

1. 生成html页面

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

使用示例

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

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

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

• 输入：描述某 SaaS 平台的微服务划分与数据流向文本
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：微服务组件关系图 + 服务解耦度分析报告
• 配置要点：raw_text 需尽量包含完整的模块与交互描述

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

• 输入：软著申请中的系统功能描述文本
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：符合软著技术材料要求的架构图及说明文档
• 配置要点：可配合 aspect_ratio 为 1:1 生成正方形架构图适配表格

生成效果示例

描述

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

输出案例

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

{
  "showapi_res_body": {
    "architecture_diagram_url": "https://oss.showapi.com/.../generated_architecture.png",
    "mermaid_code": "graph TDn  A[表现层] --> B[业务逻辑层]n  B --> C[数据访问层]",
    "final_document": {
      "overview": "本系统采用 B/S 架构与前后端分离设计...",
      "detailed_design": "1. 用户中心模块：...n2. 商品管理模块：...",
      "analysis_section": "系统整体职责清晰，低耦合高内聚，但在高并发场景下需关注数据库事务...",
      "optimization_plan": "建议引入分布式缓存与消息队列解耦订单处理流程...",
      "architecture_diagram_code": "graph TDn  A[表现层] --> B[业务逻辑层]n  B --> C[数据访问层]"
    }
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

资源索引

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

响应数据结构

1. 异步任务提交响应

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

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

{
  "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,
  "showapi_fee_num": 1
}

注意事项

1. raw_text 为必填项，需尽可能完整地描述软件功能、架构模式与技术栈，以保证解析准确度。
2. 所有任务强制异步执行，不支持同步模式。
3. 轮询查询过程中，每次获取接口返回数据后，立即将主要内容反馈给用户。
4. 生成的架构图宽高比支持 1:1、3:4、4:3、16:9、9:16，默认为 16:9。