SuperAPI AI 工具集

Architecture Patterns

编程与开发

查看项目

更新于 10-16 06:28

技能介绍

用途

Architecture Patterns 是一个面向架构设计与文档编写的技能,主要帮助用户脚手架化架构文档、生成 Mermaid 图表、校验图表语法,并提供常见架构风格(微服务、RAG 系统、全栈应用等)的模式库。它被用于架构设计、系统规划以及文档工具中,例如 planning:architecture 命令、architecture-designer 智能体、文档工具和代码生成等场景。

主要能力

  • 创建架构文档:使用 bash scripts/create-architecture.sh <project-path> <architecture-type> 脚手架化项目文件(README、roadmap/*.json、specs/)。支持的架构类型包括 nextjs、fastapi、fullstack、microservices、rag、generic。会生成包含 Mermaid 图表的完整架构概览,创建 docs/architecture/ 目录结构(overview、components、data-flow、deployment),并包含目录和交叉引用。
  • 校验 Mermaid 图表:使用 bash scripts/validate-mermaid.sh <markdown-file> 检查 Mermaid 语法。校验的图表类型包括 graph、flowchart、sequenceDiagram、classDiagram、erDiagram、stateDiagram,检查语法错误、无效节点定义、断开的连接,报告错误行号并提供常见修复建议。
  • 生成图表占位符:使用 bash scripts/generate-diagrams.sh <output-dir> <diagram-types> 创建图表模板。图表类型包括 component、data-flow、deployment、api、security、all,生成带有正确格式 Mermaid 代码块的 markdown 文件,包含解释图表各部分的注释以及示例节点和关系。
  • 更新现有架构:使用 bash scripts/update-architecture.sh <architecture-file> <section> 添加新章节。章节包括 component、api、security、deployment、data-flow,会插入具有正确标题层级的章节、添加 Mermaid 图表占位符,并保留现有内容和格式。
  • 导出图表到文件:使用 bash scripts/export-diagrams.sh <markdown-file> <output-dir> 提取图表。从文档中提取所有 Mermaid 代码块,为每个图表创建单独的 .mmd 文件,根据图表标题或章节标题命名文件,并生成列出所有导出图表的 index.md。

使用方式

该技能通过 bash 脚本调用,主要脚本包括:

  • create-architecture.sh:脚手架化完整的架构文档与图表
  • validate-mermaid.sh:校验 Mermaid 图表语法与结构
  • generate-diagrams.sh:创建图表模板占位符
  • update-architecture.sh:向现有项目文件(README、roadmap/*.json、specs/)添加新章节
  • export-diagrams.sh:将 Mermaid 图表提取为独立文件

模板

技能提供以下模板:architecture-overview.md(带目录的主架构文档模板)、component-diagram.md(组件架构与关系)、data-flow-diagram.md(数据流与处理管道)、deployment-diagram.md(基础设施与部署架构)、api-architecture.md(API 设计、端点与认证)、security-architecture.md(安全模式、认证流程、数据保护)。

架构模式

技能涵盖以下架构模式:组件架构模式(定义系统组件与边界、展示组件关系与依赖、识别共享服务与库、记录组件职责)、数据流模式(映射数据在系统中的移动、展示转换与处理阶段、识别数据源与目标、记录数据格式与协议)、部署模式(定义基础设施组件、展示服务部署拓扑、识别扩展与冗余策略、记录环境配置)、API 架构模式(设计 API 结构与端点、定义认证与授权、展示请求/响应流程、记录限流与缓存)、安全架构模式(定义安全层与边界、展示认证与授权流程、识别威胁向量与缓解措施、记录加密与数据保护)。

Mermaid 图表类型

技能支持多种 Mermaid 图表类型,包括 Graph/Flowchart 图、Sequence 图、Class 图、Entity Relationship 图、State 图。

输出标准

所有图表使用 Mermaid(确保可渲染),包含图表标题和描述,添加解释关键组件的注释,遵循一致的命名约定,使用正确的 markdown 标题层级,包含文档间的交叉引用。

校验检查

脚本执行以下校验:Mermaid 语法正确性、节点和边定义、图表类型兼容性、标签中的字符转义、正确的代码块格式、完整的关系定义。

最佳实践

从高层概览图开始;为每个架构关注点创建单独的图表;跨图表使用一致的组件命名;为符号和颜色包含图例;保持图表聚焦可读(最多 15-20 个节点);记录假设和约束;对架构文档进行版本管理;系统变更时更新图表。

适用场景

适用于设计系统架构、创建架构文档、生成架构图表、校验 Mermaid 图表语法、脚手架化项目架构文件等场景。

限制

资料中未提供关于收费、价格、平台支持范围、性能效果等方面的信息,暂未提供。