taiyi-diagram-arch

name	taiyi-diagram-arch
description	TaiyiForge 辅助 — 系统/产品架构图（Mermaid · SVG 海报 · 嵌入 DESIGN.md）。OpenCode / Claude / Codex / Cursor 通用。

taiyi-diagram-arch

目的

把 DESIGN.md 里的文字架构落成可读、可版本管理、可导出高清的架构图——组件边界、数据流、部署视图、产品级全景图（Flow-X 风格海报）。

何时使用

时机	说明
taiyi-design 写 Architecture 节	默认推荐（与 ASCII/mermaid 并列）
新模块 / 跨服务边界	必做 C4 或组件图
仓库级文档	docs/*-architecture.svg + PNG
taiyi-evolve 发现架构漂移	同步更新架构图

可跳过：纯文案/配置改动、无新组件且无边界变化。

输入

• 优先真源：diagrams/c4/containers.md 或 docs/c4/containers.md（由 /taiyi:diagram-c4 产出）
• REQUIREMENT.md、DESIGN.md（Decision + Architecture 草稿）
• CONTEXT.md（既有模块与路径）
• （可选）adr/、docs/ARCHITECTURE.md

流水线第 2 步：加载本 Skill 时同步 C4 真源，勿重新划分模块。总编排：/taiyi:diagram-pipeline。

输出（择一或组合）

产物	路径	适用
变更内架构说明	.taiyi/changes/<slug>/diagrams/architecture.md	九阶段工件（mark-aux 检测）
嵌入 DESIGN	DESIGN.md § Architecture 内 mermaid 代码块	轻量变更
矢量海报	diagrams/architecture.svg + architecture.png	产品/对外文档
仓库级	docs/<name>-architecture.svg	本仓库参考：docs/taiyiforge-architecture.svg

mark-aux：独立文件路径时执行 scripts/taiyi-forge.sh mark-aux <slug> taiyi-diagram-arch。

图类型选型

问题	推荐图型	工具
模块谁依赖谁	graph TB / graph LR	Mermaid
请求怎么走	sequenceDiagram	Mermaid
部署/运行时	graph + subgraph 环境	Mermaid
产品全景（六大标准+九阶段+门禁）	分栏海报 SVG	Python 脚本或手调 SVG
C4 容器级	Mermaid C4（若渲染器支持）或结构化 graph	Mermaid

执行步骤

0. 若存在 diagrams/c4/containers.md：以其为节点/边界真源；顶部加 > C4 真源：diagrams/c4/containers.md
1. 读 DESIGN Decision：只画「已选定方案」，不把未选 Option 画进主图
2. 列节点清单：组件名 = 仓库内真实路径/包名（如 src/core/workflow-engine.ts）
3. 选视图：默认 1 张组件图 + 1 张关键序列图（有外部 API 时）
4. 写 Mermaid（变更内首选）：

# Architecture Diagram

## Component view

\`\`\`mermaid
graph LR
  CLI[taiyi CLI] --> Engine[workflow-engine]
  Engine --> Manifest[workflow-manifest.yaml]
  Engine --> Skills[skills/taiyi-*]
\`\`\`

## Notes

- 与 DESIGN.md §Decision 一致
- 更新日期：ISO8601

5. （可选）导出 PNG：node scripts/render-mermaid.mjs .taiyi/changes/<slug>/diagrams/architecture.md
6. （产品海报） 宽屏分栏布局参考 docs/taiyiforge-architecture.svg；可 fork scripts/generate-architecture-svg.py 改文案后重跑
7. 回链 DESIGN.md：Architecture 节写 详见 diagrams/architecture.md 或内嵌同一段 mermaid
8. mark-aux（若写了独立 diagrams 文件）

视觉规范（对齐 Flow-X / TaiyiForge 海报）

• 画布：宽屏 16:9 或 3:2（如 2800×1880 SVG viewBox）
• 背景：深色 #060b16，面板 #0d1528，文字 #eef2ff
• 结构：顶栏标准 → 左 ARTIFACT → 中 CORE + 九阶段 → 右门禁 → 底 Skill 全景 → 页脚价值
• 导出清晰度：SVG 真源 + PNG ≥5×（本仓库：python3 scripts/generate-architecture-svg.py → 16800×11280）

质量自检

• 每个框可映射到 REQUIREMENT AC 或 DESIGN 组件表
• 箭头方向与数据/控制流一致（无「悬空节点」）
• 图例或 Notes 说明缩写与边界（Trust boundary、DB、外部 SaaS）
• Mermaid 在 GitHub / Cursor 预览可渲染（避免实验语法）
• 若与旧图冲突，在 Notes 标 supersedes 路径

与主流程

taiyi-requirement → taiyi-design
                         ↓
              taiyi-diagram-arch（推荐）
              taiyi-diagram-flow（流程细节）
                         ↓
                    DESIGN.md + diagrams/

禁止

• 无 DESIGN 决策就画「最终架构」
• 架构图代替 ADR（边界决策仍走 taiyi-architect）
• 仅截图无源文件（须保留 .md / .svg 可 diff 真源）