# 图表流程 ## 目的 “图表流”技能可自动创建和管理技术文档的美人鱼图。它将图表源文件与主文档分开以提高渲染性能，提供自动 SVG 转换以供人类查看，并保持父文档和图表文件之间的可追溯性。 **主要优点**： * **性能**：单独的图表文件在文档查看器中加载速度更快 * **双格式**：AI 助手的美人鱼源，人类的 SVG 预览 * **可追溯性**：图表链接到具有正确 ID 命名的父文档 * **迁移** ：将现有内联图提取到单独的文件中 * **一致性**：标准化图表文件结构和元数据 ## 何时使用此技能 **当**时使用图表流： * 创建PRD、BRD、ADR、SYS或其他技术文档的架构图 * 将现有内联美人鱼图迁移到单独的文件 * 由于图表复杂，主文档渲染速度变慢 * 图表需要在多个文档中重复使用 * 创建流程图、组件图、部署图、序列图、状态机或类图 **当**时不要使用图表流： * 创建简单的表格或基于文本的列表（使用 markdown） * 图表 < 20 行，主文档渲染速度快 * 创建数据可视化图表（使用适当的图表库） * 使用非架构图（甘特图、饼图 - 超出范围） ## 技能输入 ### 所需的输入输入|描述 |示例 ---|---|--- **父文件路径** |主文档的绝对路径 | `{project_root}/docs/PRD/PRD-01_multi_agent_system_architecture.md` **图表说明** |图表的简称 | `3_tier_agent_hierarchy` **图表类型** |架构图类型 | `流程图`、`序列`、`类`、`状态`、`组件`、`部署` ### 可选输入输入|描述 |默认 ---|---|--- **迁移模式** |从文档中提取现有图表 | `false`（创建新的） **图表标题** |人类可读的标题 |源自描述 **造型偏好** |配色方案、布局方向|项目默认值 ## 技能工作流程 ### 模式 1：创建新图表 **第 1 步：解析父文档** * 从文件名中提取父文档 ID（例如，从 `PRD-01_multi_agent_system_architecture.md` 中提取 `PRD-01`） * 识别父文档类型（PRD、BRD、ADR、SYS 等） * 确定正确的“diagrams/”子文件夹位置 **第2步：生成图表文件路径** * 格式：`{parent_folder}/diagrams/{PARENT-ID}-diag_{description}.md` * `diagrams/` 子文件夹创建在与父文档相同的目录中 * 按文件类型划分的示例： * BRD：`docs/BRD/diagrams/BRD-01-diag_workflow.md` * PRD：`docs/PRD/diagrams/PRD-01-diag_3_tier_agent_hierarchy.md` * ADR：`docs/ADR/diagrams/ADR-005-diag_cloud_deployment.md` * SYS: `docs/SYS/diagrams/SYS-002-diag_data_flow.md` * IMPL: `docs/IMPL/diagrams/IMPL-010-diag_implementation_phases.md` * 如果“diagrams/”文件夹不存在，则创建该文件夹 **步骤 3：创建图表文件** * 使用图表文件模板（参见下面的模板部分） * 包括链接到父级的文档控制部分 * 添加图表类型元数据 * 使用适合图表类型的语法创建 Mermaid 代码块 **步骤 4：生成 SVG** * 尝试 `mmdc` CLI 转换：`mmdc -i 图.md -o 图.svg` * 后备：如果 CLI 不可用，请使用 Mermaid Live API * 验证 SVG 输出（检查错误，大小 < 1MB） **步骤 5：将 SVG 编码为 Base64** * 读取生成的SVG文件 * 转换为Base64字符串 * 准备数据URI：`data:image/svg+xml;base64,{BASE64_STRING}` **第 6 步：更新父文档** * 添加图表文件的参考链接 * 在可折叠的“

”块中嵌入 Base64 SVG * 置于父文档的适当部分 **第 7 步：验证** * 验证图表文件存在且可读 * 检查 Mermaid 语法有效性 * 确认SVG正确渲染 * 验证交叉引用解析 ### 模式 2：迁移现有图表 **第 1 步：扫描父文档** * 搜索````mermaid` 代码块 * 提取每个图表及其周围的上下文 * 保留图表内容和样式 **第 2 步：创建图表文件** * 对于每个提取的图表，请遵循模式 1 中的步骤 1-4 * 根据图表内容或上下文自动生成描述 * 对多个图表进行编号：`_diagram_1`、`_diagram_2`等。 **步骤 3：在父文档中替换** * 删除原来的“美人鱼”方块 * 在同一位置插入 SVG + 参考链接 * 维护文档流程和可读性 **第 4 步：验证迁移** * 确认提取的所有图表 * 验证没有损坏的参考 * 检查视觉保真度（SVG 与原始美人鱼匹配） ## 模板 ### 图表文件模板 # {PARENT-ID}-diag: {图表标题} ## 文件控制 |项目 |详情 | |------|---------| | **图 ID** | {PARENT-ID}-诊断 | | **父文档** | [{PARENT-ID}: {父标题}](../{PARENT-FILE}.md) | | **图表类型** | {流程图|序列|类|状态|组件|部署} | | **状态** |活跃| | **版本** | 1.0.0 | | **创建** | {年-月-日} | | **最后更新** | {年-月-日} | | **维护者** | {角色} | ## 概述 {此图所代表内容的简要说明} ## {图表标题} ``美人鱼 {美人鱼图代码} ## 图说明 {图表元素、流程和目的的详细说明} ## 关键要素 {重要节点、组件、参与者、状态或流程的列表或表格} ## 参考文献 * **父文档** : [{PARENT-ID}: {父标题}]() * **相关图表**：{相关图表文件的链接（如果适用）} * **相关文档**：{相关要求、ADR、策略文档的链接} ** ** **图版本**：1.0.0 **创建**：{YYYY-MM-DD} **维护者**：{角色} ### 父文档参考模板 ``降价 **可视化图表**：[{PARENT-ID}-diag: {图表标题}](diagrams/{PARENT-ID}-diag_{描述}.md) <详情>

查看图表（SVG 预览）

![{图表标题}](数据:image/svg+xml;base64,{BASE64_SVG_STRING}) ## 支持的图表类型 ### 流程图/图表图TB A[开始] --> B{决定} B -->|是| C[行动1] B -->|否| D[行动2] **用途**：流程、决策树、工作流程 ### 序列图序列图演员->>系统：请求系统->>数据库：查询数据库-->>系统：结果系统-->>参与者：响应 **用途**：代理交互、API 调用、消息流 ### 类图类图类代理{ +状态：状态 +执行() +验证() } Agent <|-- StrategyAgent **用途**：对象关系、系统组件 ### 状态图状态图-v2 [*] --> 扫描扫描 --> 活动主动-->防御防御 --> [*] **用途**：状态机、生命周期流程 ### 组件图（使用流程图）图LR 子图“1 级” SO[系统协调器] 结束子图“2 级” IS[项目选择] 结束所以-->是 **用途**：系统架构、组件关系 ### 部署图（使用流程图）图TB 子图“云跑” A[代理容器] 结束子图“Cloud SQL” B[（数据库）] 结束甲-->乙 **用途**：基础架构、部署拓扑 ## 工具使用 ### 检查 Mermaid CLI 哪个mmdc **如果未安装**： npm install -g @mermaid-js/mermaid-cli **替代**：使用 Puppeteer npm install -g 傀儡师 ### 从美人鱼生成 SVG mmdc -i 输入.md -o 输出.svg -b 透明 **参数**： * `-i`: 输入文件 (Mermaid markdown) * `-o`: 输出文件 (SVG) * `-b`: 背景颜色(推荐`透明`) ### 将 SVG 转换为 Base64 base64 -w 0 图.svg **macOS**： base64 -i 图.svg ## 质量门（完成的定义） * **文件已创建**：图表文件存在于正确的“diagrams/”子文件夹中 * **命名约定** ：文件名遵循 `{PARENT-ID}-diag_{description}.md` 模式 * **文档控制**：元数据部分带有父链接反向引用 * **Mermaid Syntax** ：图表语法验证无错误 * **SVG 生成** ：SVG 文件创建成功（如果使用文件方法） * **SVG 嵌入**：Base64 SVG 嵌入到父文档中 * **添加参考**：指向父文档中添加的图表文件的链接 * **交叉引用**：所有链接正确解析（双向） * **渲染**：图表在 GitHub、VS Code 和文档站点中正确显示 * **辅助功能** ：用于 SVG 预览的可折叠“

”块 * **文件大小**：SVG < 1MB，Base64 字符串 < 1.5MB ## 技能限制 ### 不该做什么 * **请勿** 在未经明确许可的情况下在存档文件夹中创建图表 * **请勿** 在未检查版本历史记录的情况下修改现有图表文件 * **请勿** 嵌入大型二进制图像（仅使用 SVG） * **请勿** 使用甘特图、饼图或 git 图（超出范围 - 仅架构图） * **不要** 为简单列表或表格创建图表（使用 Markdown） * **不要** 跳过文档控制元数据 * **请勿** 使用通用文件名，如“diagram1.md”（使用描述性名称） ### 文件组织规则 * **始终** 在与父文档相同的目录中创建“diagrams/”子文件夹 * **始终** 使用父文档 ID 作为图表文件前缀 * **始终** 通过交叉引用保持可追溯性 * **始终**遵循模板结构以保持一致性 ## 错误处理 ### 错误：找不到`mmdc`命令 **原因**：未安装 Mermaid CLI **分辨率**： npm install -g @mermaid-js/mermaid-cli # 或 # 提供使用 Mermaid Live 的手动说明 (https://mermaid.live) ### 错误：无效的 Mermaid 语法 **原因**：图表代码中的语法错误 **分辨率**： * 在验证语法 * 检查是否缺少引号、括号或关键字 * 查看 Mermaid 文档的图表类型 ### 错误：SVG 文件太大 (> 1MB) **原因**：图表太复杂 **分辨率**： * 分割成多个图表 * 简化图表（删除多余元素） * 使用子图来组织复杂性 ### 错误：无法确定父文档 ID **原因**：文件名不遵循标准命名（例如，没有 ID 前缀） **分辨率**： * 提示用户手动指定父ID * 建议重命名父文件以遵循约定 ### 错误：`diagrams/` 文件夹创建失败 **原因**：权限问题或无效路径 **分辨率**： * 检查文件权限 * 验证父目录是否存在 * 使用绝对路径 ## 用法示例 ### 示例 1：为 BRD 创建新流程图 **用户请求**： >“创建显示 BRD-01 用户工作流程的流程图” **技能动作**： 1. 解析父级：`{project_root}/docs/BRD/BRD-01_project_requirements.md` 2.提取ID：`BRD-01` 3. 创建文件：`docs/BRD/diagrams/BRD-01-diag_user_workflow.md`（在 BRD 子文件夹中） 4. 生成包含用户旅程步骤的 Mermaid 流程图 5.使用`mmdc`转换为SVG 6. 在 BRD-01 中嵌入 Base64 SVG 7.添加参考链接 **结果**： * 在“docs/BRD/diagrams/”（特定于文档类型的子文件夹）中创建的图表文件 * SVG 预览在父文档中可见 * 双向交叉引用 ### 示例 2：迁移现有图表 **用户请求**： >“将状态机图从strategy_state_machine.md迁移到单独的文件” **技能动作**： 1. 扫描 `{project_root}/strategy/strategy_state_machine.md` 2.找到```美人鱼块（状态图） 3.提取图代码 4. 创建 `{project_root}/strategy/diagrams/SSM-001-diag_state_transitions.md` 5.生成SVG 6.用SVG+参考替换原始块 7. 验证迁移 **结果**： * 原版美人鱼移至单独文件 * SVG 预览嵌入在主文档中 * 主文档渲染速度更快 ### 示例 3：创建 ADR 的序列图 **用户请求**： >“创建显示 ADR-003 代理通信流程的序列图” **技能动作**： 1.父级：`docs/ADR/ADR-003_agent_communication.md` 2. 创建：`docs/ADR/diagrams/ADR-003-diag_agent_communication_sequence.md`（在 ADR 子文件夹中） 3. 生成序列图：系统编排器→选择服务→策略代理→风险服务 4. 添加计时泳道（A2A 协议模式） 5. 转换为 SVG 6.嵌入ADR-003 **结果**： * `docs/ADR/diagrams/` 中的序列图（特定于文档类型的子文件夹） * 消息流的 SLA 注释可见 <50ms * ADR 文档中的 SVG 预览 ## 输出格式 ### 生成的工件 1. **图表文件** (`{PARENT-ID}-diag_{description}.md`) * 位置：`{parent_folder}/diagrams/` * 格式：带有 Mermaid 代码块的 Markdown * 包括：文档控制、图表代码、描述、参考文献 2. **SVG 文件**（可选，如果使用基于文件的方法） * 位置：与图表文件相同，扩展名为“.svg” * 格式：可缩放矢量图形 * 用于Base64编码 3. **更新父文档** * 在相应部分添加参考链接 * SVG 预览嵌入到 `

` 块中 * 保留原始内容 ### 执行后的文件组织 **每种文档类型都有自己的图表子文件夹**：文档/ ├── BRD/ │ ├── BRD-01_project_requirements.md ← 使用 SVG + 链接更新 │ └── 图解/ │ ├── BRD-01-diag_user_workflow.md ← BRD 图 │ └── BRD-01-diag_business_rules.md ├── 珠三角/ │ ├── PRD-01_multi_agent_system.md ← 使用 SVG + 链接更新 │ └── 图解/ │ ├── PRD-01-diag_3_tier_hierarchy.md ← PRD 图 │ └── PRD-01-diag_cloud_architecture.md ├── 美国存托凭证/ │ ├── ADR-005_deployment_strategy.md ← 使用 SVG + 链接更新 │ └── 图解/ │ └── ADR-005-diag_deployment_flow.md ← ADR 图 ├── 系统/ │ ├── SYS-002_data_pipeline.md ← 使用 SVG + 链接更新 │ └── 图解/ │ └── SYS-002-diag_data_flow.md ← SYS图 └── IMPL/ ├── IMPL-010_phase_1_plan.md ← 使用 SVG + 链接更新 └── 图/ └── IMPL-010-diag_implementation.md ← IMPL 图 ## 与项目工作流程集成 ### 溯源链产品策略 ({project_root}/strategy/*.md) ↓ 要求（docs/reqs/*.md） ↓ 架构决策 (docs/adrs/*.md) ← 图表支持 ADR ↓ 系统规范 (docs/sys/*.md) ← 图表显示架构 ↓ BDD 场景 (docs/BDD/*.feature) ↓ 代码实现 **图表增强**：具有可视化架构表示的 ADR、SYS、PRD、BRD 文档 ### 与其他技能的关系 * **doc-flow** ：创建规范文档； Charts-flow 将图表添加到这些文档中 * **google-adk** ：定义代理框架；图表流可视化代理层次结构 * **project-mngt** ：创建实施计划；图表流显示依赖关系图 ## 参考文献 ### 内部文档 * [Claude 代码技能自述文件]() * [SDD框架指南]() ### 外部资源 * [美人鱼文档]() * [美人鱼现场编辑器]() * [Mermaid CLI 文档]() ### 相关模板 * [BRD 模板]() * [PRD 模板]() * [ADR 模板]() * [SYS模板]() * [IMPL 模板]() ** ** **技能版本**：1.0.0 **创建**：2025-01-04 **最后更新**：2025-01-04 **维护者**：开发团队

图表流程

包含技能