用途
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 图表语法、脚手架化项目架构文件等场景。
限制
资料中未提供关于收费、价格、平台支持范围、性能效果等方面的信息,暂未提供。