Saas Arch Diagrams

SaaS 架构图设计

这个 Skill 解决什么

企业 SaaS 类产品在做产品评审 / 范围判定 / 迭代规划时，需要两类截然不同的架构图：

1. 产品架构图（Product Architecture） —— 产品在更大生态中的定位、面向谁、提供什么能力域、与外部依赖的边界
2. 功能架构图（Functional Architecture） —— 平台具体功能的完整清单，按层 + 能力域 + 子能力 3 级嵌套

这个 skill 提供两类图的结构模板、CSS 设计 token、内容组织原则、常见陷阱清单，让你避开 6 轮以上的反复返工。

触发场景

• 「画产品架构图」「画功能架构图」「按 4 层结构画下功能」
• 「我需要让别人看清楚我们做什么、面向谁」
• 「这个图能不能区分一下哪些功能是哪个端」
• 「按能力域分类一下」「按子能力做嵌套」
• 「product architecture diagram」「functional architecture for SaaS」

两类图的根本区别

| 维度 | 产品架构图 | 功能架构图 | |---|---|---| | 回答问题 | 我们做什么、面向谁、与下游的边界 | 平台具体有哪些功能模块 | | 视角 | 自上而下看生态 | 自内而外看实现 | | 主轴 | 用户 → 应用 → 能力 → 底座 | 端 → 服务 → 数据 → 底座 | | 颗粒度 | 能力域级（A/B/C/D） | 模块级（每个功能一卡） | | 适用场景 | 给老板 / 跨团队 / 外部讲产品定位 | 内部研发 / PM 做范围判定与迭代规划 | | 是否分版本 | 不分 | 不分（全局功能视图） |

不可违反的原则

读图者最容易抓出来的 7 个"硬伤"，做之前先内化：

1. 不要分版本 —— 架构图是全局视角，"v0.1 / 远期 / 未来" 这类标记一律不要出现。版本规划放 roadmap / PRD。
2. 不要省略合并 —— ④-⑧ 高阶节点 合并为一卡是为了视觉省事，违反"内容逻辑"。8 个节点就要画 8 张卡。
3. 端的定义要纯粹 —— "端"是用户使用的客户端，只能是：运营端 / 供应商端 / 客户端 / 管理端 / 第三方平台。绝不能包含「后端」「业务服务」「数据」这种技术语言。
4. 服务和页面不能混 —— 评测任务列表（页面）和评测流水线 controller（服务）属于不同层次，硬放一起会让人看不清。
5. 能力域不能平铺 —— 域内功能必须再分子能力，3-7 个并排卡片堆在一起没有层次。
6. 不要为了对齐而留空白 —— grid 等宽分配 4 列时，某列卡片少就空一片。要按内容动态分配 col-span。
7. 不要编造功能填版面 —— 图是事实陈述不是装饰：只画真实存在/已规划立项的能力，"显得完整""饱满好看"不构成加卡理由；版面不满用 col-span cookbook 重排列宽解决，不靠虚构内容解决。

产品架构图：4 层视图

结构

═══ L1 用户与场景 ═══  谁在用 / 在什么场景下用
═══ L2 应用层端 ═══     端的 UI 入口
═══ L3 能力域 ═══       4-5 个 capability domain（A/B/C/D/E）
═══ L4 平台底座 ═══     执行 / 观测 / 通信 / 数据治理 等共用基础
                       ⇩
═══ 外部依赖 / 下游 ═══  下游消费方（如本平台是 下游聚合子系统则下游是 API 网关）

横切关注点（纵向条带，跨所有层）：治理与合规 · 安全 · 可观测

关键判断题

写第一张产品架构图前先回答清楚：

• 我们的产品是更大生态里的子系统吗？是 → 顶部 Hero 写"作为 X 的 Y 子系统"，底部画外部依赖箭头
• 谁是直接用户？分内部端（admin 多角色）和外部端（vendor / customer / partner）
• 有没有不在本平台范围但要协同的能力？标 m-out（dotted 置灰 + line-through），不画进能力域内
• 是否有横切关注点？治理 / 安全 / 计量 等跨所有能力域，用纵向 sidebar 条带

功能架构图：4 层纵向 × 能力域横向

顶层结构

L1 端层 · User Endpoints          ← 用户界面
  ├── 端 A（如 运营端）
  │   ├── 能力域 1 子组
  │   │   ├── 子能力 1.1 → 卡片
  │   │   └── 子能力 1.2 → 卡片
  │   └── 能力域 2 子组
  │       └── ...
  ├── 端 B（如 供应商端）
  └── 端 C（如 第三方平台 · 置灰）

L2 业务服务层 · Business Services  ← 页面背后的能力
  ├── 能力域 A 服务
  │   ├── A1 子能力 → 服务卡片
  │   └── A2 子能力 → 服务卡片
  ├── 能力域 B 服务
  └── ...

L3 数据资产层 · Data Assets       ← 跨服务共用的数据
  ├── 主体数据（vendor / model / endpoint 表）
  ├── 业务数据（评测集 / 基线 / 账单）
  └── 监控 + 审计

L4 平台底座 · Platform Foundation ← 跨域基础设施
  ├── 执行引擎
  ├── 观测计量
  ├── 通信触达
  └── 数据治理

3 级嵌套规则

每张图都是这 3 级，缺一不可：

| 级别 | 用途 | 视觉容器 | |---|---|---| | L1 顶层 = 层（端 / 服务 / 数据 / 底座） | 大背景渐变 + 边框 | .lyr-N | | L2 中层 = 能力域（A / B / C / D） | 浅色背景 + 实线边框 | .subgroup-box | | L3 子层 = 子能力（A1 / A2 / B1 ...） | 虚线轻量框 / chip 头 | .sub2-box 或 .sub3-block | | 卡片 = 单个功能模块 | 白底 + 左 3px 域色 accent + 软阴影 | .module-card |

Col-span 填满规则（紧凑布局核心算法）

12 列网格内，每个子组（sub2 或 sub3）按卡片数动态分配 col-span，加起来必须 = 12，不能留空白。

1 卡片  → col-span-2 / 3 / 4 / 6 / 12（根据该行总卡数算）
2 卡片  → col-span-4 inner-2 / col-span-6 inner-2 / col-span-12 inner-2
3 卡片  → col-span-3 inner-1 / col-span-6 inner-3 / col-span-12 inner-3
4 卡片  → col-span-4 inner-2 / col-span-8 inner-4 / col-span-12 inner-4
8 卡片  → col-span-12 inner-4（占整行 · 2 行高）
N 卡片（N>8） → col-span-12 inner-4 多行

强制规则：每行 col-span 加起来必须 = 12，不能少。某行卡片差太多导致行高不齐时，宁可让小子组单独成行（col-span-12 inner-N）也不要让一行内 col 高度差超过 2 倍。

具体配置见 [references/col-span-cookbook.md](references/col-span-cookbook.md)。

CSS 设计 token

完整模板见 [templates/styles.css](templates/styles.css)，核心 token：

/* 4 层背景色（淡色 + 同色边框） */
.lyr-1 { background: linear-gradient(180deg, rgba(99,102,241,.08) 0%, rgba(99,102,241,.02) 100%); border: 1px solid rgba(99,102,241,.18); }  /* L1 indigo - 端层 */
.lyr-2 { background: linear-gradient(180deg, rgba(245,158,11,.07) 0%, rgba(245,158,11,.02) 100%); border: 1px solid rgba(245,158,11,.18); }  /* L2 amber - 服务层 */
.lyr-3 { background: linear-gradient(180deg, rgba(139,92,246,.07) 0%, rgba(139,92,246,.02) 100%); border: 1px solid rgba(139,92,246,.18); }  /* L3 violet - 数据层 */
.lyr-4 { background: linear-gradient(180deg, rgba(100,116,139,.08) 0%, rgba(100,116,139,.02) 100%); border: 1px solid rgba(100,116,139,.18); }  /* L4 slate - 底座 */

/* 能力域 chip（5 种 + X 共用） */
.dc-A { background: #f5e6ff; color: #6b21a8; }  /* 紫 */
.dc-B { background: #fef3c7; color: #92400e; }  /* 琥珀 */
.dc-C { background: #dbeafe; color: #075985; }  /* 蓝 */
.dc-D { background: #ffe4e6; color: #9f1239; }  /* 玫红 */
.dc-X { background: #f1f5f9; color: #475569; }  /* 灰 - 平台共用 */

/* 卡片 + 左 accent */
.module-card { background: #fff; border: 1px solid rgba(15,23,42,.06); border-left: 3px solid #cbd5e1; border-radius: 5px; padding: 6px 9px; box-shadow: 0 1px 2px rgba(15,23,42,.04); }
.dom-A { border-left-color: #a855f7 !important; }
.dom-B { border-left-color: #f59e0b !important; }
.dom-C { border-left-color: #0ea5e9 !important; }
.dom-D { border-left-color: #f43f5e !important; }

/* 不在本平台范围（dotted 置灰） */
.m-out { background: #f5f5f4 !important; border-style: dotted !important; opacity: .7; }
.m-out .ct { text-decoration: line-through; color: #78716c; }

标准实施流程

Step 1 · 先做产品架构图（1-2 轮）

1. 写一句话定位：本产品是「X 平台的 Y 子系统」（如不是子系统则跳过）
2. 列出 4-5 个能力域（A/B/C/D/E），每个域 1 句话能讲清楚
3. 列出用户与场景（内部 / 外部，区分角色）
4. 标识不在本平台范围但要协同的能力（→ 下游聚合平台、→ 外部 API 等）
5. 用 [templates/product-arch-template.html](templates/product-arch-template.html) 起手

Step 2 · 再做功能架构图（3-5 轮）

1. 第一轮：列功能清单 —— 把所有功能列出来，标 (端，能力域，子能力)
2. 第二轮：按 4 层分类 —— 把功能放到 L1-L4 对应层
3. 第三轮：嵌套到 3 级 —— L1 内每个端按能力域分子组，每域按子能力再分一级
4. 第四轮：col-span 填满 —— 算每行 col 总和 = 12，调整子组宽度
5. 第五轮：检查 7 个硬伤 —— 见前文「不可违反的原则」逐条对照
6. 用 [templates/functional-arch-template.html](templates/functional-arch-template.html) 起手

Step 3 · 生成机器可读骨架（arch-skeleton.yaml · v2.0 新增）

每张架构图 HTML 落盘后额外派生 arch-skeleton.yaml，与 HTML 同目录同名（如 功能架构图.html → 功能架构图.skeleton.yaml）。

为什么需要骨架：HTML 是给人看的视觉资产，但下游 AI agent（pm-wiki-maintainer ingest / prd-writer Stage 1 引用 / 自动 lint）需要 4 维元数据（层 / 能力域 / 子能力 / 端），从 HTML grep 出来满是 CSS class 噪音 + 上下文割裂。

4 字段最小集：

• layers[] 4 层定义
• endpoints[] 端清单（含 user_roles）
• capability_domains[].sub_capabilities[] 能力域 + 子能力（含 pages、outofscope）
• ecosystem 上下游（仅产品架构图）

完整 schema + 下游消费契约 + 反模式见 [references/skeleton-generation.md](references/skeleton-generation.md)。

> ⚠️ skeleton.yaml 是自动派生 · 永远只读 —— 改 HTML 后重新生成，禁止手工编辑 yaml。

Step 4 · 评审 checklist（每次改完都过一遍）

参考 [references/review-checklist.md](references/review-checklist.md)（v2.0 已 DoD 分层 · 核心必勾 8 / 场景必勾 8 / 推荐 5）。核心必勾 8 条：

• [ ] 不分版本：没有"远期 / v0.x / 未来"等字样
• [ ] 不省略合并：所有功能模块独立成卡，没有"X-Y 节点"
• [ ] 端纯粹：只有客户端，严禁"后端 / 业务服务 / 数据层"
• [ ] 页面 vs 服务分层：UI 入口属 L1，业务能力属 L2
• [ ] col-span = 12：每行子组加起来 = 12，不留右侧空白
• [ ] 描述用业务语言：避免「中间件 / 微服务 / 后端 / API 网关」
• [ ] 卡片标题用户能理解：「评测任务列表」而非 eval_run_list
• [ ] 层名固定用词：「端层 / 业务服务层 / 数据资产层 / 平台底座」

> 场景必勾 8 / 推荐 5 / 视觉约定示例 见 review-checklist.md 全文。

常见陷阱与对照案例

每条都附最初错误和修正方式，见 [references/anti-patterns.md](references/anti-patterns.md)：

1. "评测集体系 22 模块" vs "评测集数据 + 评测集管理工具 拆开" —— 数据资产和管理 UI 不是一个维度
2. "报告产出 4 模块包含基线" —— 行业基线是数据资产，不是报告产出
3. "层 6a 对象 + 层 6b 底座" —— 用 a/b 表示子层混乱，要么拆成独立层 7、要么不拆
4. "评级算法 + 综合评分 + 行业基线 + 审批面板 全塞 ③ WHAT 段" —— 评级是 D 风险域 / 审批是 L1 端层 / 基线是 L3 数据层
5. "运营端 + 评测工程师 + 供应商 + 后端 + 下游聚合 5 个端" —— 评测工程师是运营端内角色，后端不是端
6. C4 路由 col-span-3 留 col-9 空白 —— 应该 col-span-12 inner-2，或并入其他子组同行

推荐工具栈

• Tailwind CSS CDN（快速 prototyping）
• 自定义 CSS variable token（域色 / 层色 / 状态色）
• Python 脚本生成 HTML（卡片多、布局规整，手写易错）
• Firebase Hosting / GitHub Pages（直接 deploy）

Self-Evolving Protocol（每张架构图画完主动评估）

本 skill 是 living document——架构图的反模式来自真实返工，不主动回流就会丢失。每次画完一张架构图（产品架构 / 功能架构），主动评估是否更新本 skill，不要等用户提醒。

触发评估时机

| 完成动作 | 评估问题 | 归档路径 | |---|---|---| | 画完一张架构图（产品 / 功能） | 这轮有没有新的卡片排布模式（col-span 组合）？ | [references/col-span-cookbook.md](references/col-span-cookbook.md) | | 用户给出明确否定（"不要 X" / "去掉 Y"） | 这条否定是不是普适规则？要不要进反模式？ | [references/anti-patterns.md](references/anti-patterns.md) + SKILL.md「常见陷阱」段 | | 评审 checklist 漏检（事后才发现问题） | 是不是 21 条四层 checklist 该新增一条？ | [references/review-checklist.md](references/review-checklist.md) | | 遇到现有 4 层架构不够用（如 L0 / L5） | 是项目特例还是通用扩展？ | SKILL.md 主文档「层定义」段（仅当跨 ≥2 项目验证过） | | 发现新的能力域 chip 命名冲突 | 是不是 A-E 域不够分？ | SKILL.md 主文档「能力域 chip」段 |

更新约束（防御性规则）

• ❌ 不要默默更新 skill——必须告诉用户「本轮新增 N 条 X」让用户有否决权
• ❌ 不要等到 10+ 张图后再一次性蒸馏——错过太多上下文，记不清当时为什么改
• ❌ 不要把项目特定的层数 / 域数当通用规则——只有跨 ≥2 个项目（如 项目 A + 项目 B）验证过的才进 references
• ✅ 更新时必须在 SKILL.md 末尾 ## Changelog 加一行（日期 + 改动摘要 + 来源项目）

评估清单（画完一张架构图后 30 秒自检）

增长驱动（有没有新东西要加）：

• [ ] 用户在评审过程中说过"不要 X"吗？X 是不是普适反模式？
• [ ] 有没有新 col-span 组合（如 col-span-5 + col-span-7）？要不要进 cookbook？
• [ ] 21 条 review-checklist（四层）有没有漏掉本次踩坑的项？
• [ ] 这张图涉及的端 / 服务 / 数据资产，有没有现有 4 层覆盖不到的？
• [ ] 配色 / 状态色 / dotted 用法有没有新约定？

简化驱动（有没有可以砍的 · v2.x 新增 · 防止 references 单调膨胀）：

• [ ] 哪些反模式 / col-span cookbook 条目 ≥ 3 个月没被引用？标 deprecated 候选
• [ ] 21 条 review-checklist 哪条本次画图根本没用上？是否应降级到「场景必勾」或「推荐」？
• [ ] Changelog 最近 N 条是不是全是「新增」？这次能不能落一条「合并 / 删除 / 降级」？
• [ ] 有没有反模式实际是「项目特化」误归通用？加 scope: 项目特化 元字段或迁出
• [ ] 5 色 A/B/C/D/X 能力域写死是不是对其他项目过度约束？

任一项勾选 → 显式回头更新 skill + 告知用户。简化驱动至少与增长驱动同等优先。

画完架构图后：建议 ingest 到项目 wiki

如果当前项目装了 pm-wiki-maintainer 且存在 docs/wiki/，画完架构图后额外做一项：

- [ ] 本轮架构图引入了几个新能力域？
- [ ] 有没有模块边界变更（拆分 / 合并 / 移交下游）？
- [ ] 有没有新增的下游平台 / 外部依赖？
- [ ] 4 层结构是否发生变化（角色层 / 产品层 / 能力层 / 底座层）？

任一项 ≥ 1，主动提示用户： > 「本轮架构图引入 X 能力域 / Y 边界变化 / Z 新下游，建议执行 ingest 架构图到 wiki，这样下次写 PRD 时能自动加载架构上下文。是否现在 ingest？」

用户同意后 → 调用 pm-wiki-maintainer 的 ingest 流程，按该 skill 的 ingest 工作流文档（其 references 目录下的 ingest-workflow，以实际安装目录为准）「从架构图 ingest」映射表执行；该 skill 未安装则跳过本节，不要按相对路径猜测文件位置。

来源

蒸馏自企业 SaaS 项目（某 LLM 服务聚合平台）的 6 轮迭代实战：

• 第 1 轮：单层平铺 → 用户反馈"配色全是灰色，没有层次"
• 第 2 轮：加 v0.1 角标 → 用户反馈"全局视图不分版本"
• 第 3 轮：合并 ④-⑧ → 用户反馈"省略的功能定义"
• 第 4 轮：层 6a/6b → 用户反馈"a/b 区分混乱"
• 第 5 轮：用"后端"作为端 → 用户反馈"端和使用对象混用"
• 第 6 轮：col 等宽留空白 → 用户反馈"大量空白，紧凑并有层次"

🌐 跨平台支持（codex / cursor / antigravity / gemini / copilot）

本 skill 的核心知识（4 层架构、col-span-cookbook、anti-patterns、review-checklist）跨平台通用。Self-Evolving Protocol 的执行能力因宿主而异：

| 平台 | 安装路径 | Self-Evolving 触发方式 | |---|---|---| | Claude Code / Desktop | ~/.claude/skills/saas-arch-diagrams/ | 🟢 全自动（AI 主动执行） | | Cursor | /.cursor-plugin/skills-songshishuang/saas-arch-diagrams/ | 🟡 半自动（用户提示自检） | | Codex CLI / App | ~/.codex/plugins/songshishuang-skills/skills/saas-arch-diagrams/ | 🟡 半自动 | | Gemini CLI / Antigravity | gemini extensions install github.com/songshishuang/Skills | 🟡 半自动 | | GitHub Copilot CLI | gh copilot marketplace add songshishuang/Skills | 🟡 半自动 | | ChatGPT Web / 本地小模型 | 复制 SKILL.md 到 instructions | 🔴 仅建议 |

半自动平台的触发咒语（画完架构图后手动发给 AI）：

请按本 skill 的 Self-Evolving Protocol 自检本轮架构图，
评估有没有新 col-span 组合 / 新反模式 / 新 checklist 项要进 references/。

一键安装脚本与详细说明见仓库根 INSTALL-MULTI-PLATFORM.md。

Changelog

• 2026-06-01 · v2.0 — 脱敏 + 边界拆分 + Self-Evolving 反向简化 + DoD 分层 + arch-skeleton.yaml 切片
• 通用化命名：把项目特定的业务领域词换成中性术语（如"下游聚合平台" / "LLM 服务聚合平台"），确保跨项目复用
• 接收 saas-prototype-design 迁出的反模式：原 prototype 反模式 3 / 11-16 共 7 条本质是架构图反模式，已在本 skill 反模式表 1-10 中覆盖
• Self-Evolving 加反向简化问题：30 秒自检清单分「增长驱动」+「简化驱动」两段，防止 references 单调膨胀（参考 prd-writer v2.3）
• review-checklist DoD 分层：21 条全"必勾"重排为「核心必勾 8 / 场景必勾 8 / 推荐 5 / 项目特化示例」4 层；项目特化的 5 色 A-X 能力域映射从"必填"降为"示例"
• 新增 arch-skeleton.yaml 机器可读切片：每张架构图 HTML 同步派生 yaml（4 字段：层 / 能力域 / 子能力 / 端），下游 pm-wiki-maintainer ingest 和 prd-writer Stage 1 引用直读 yaml 不读 HTML，省 95% token；规范见新增 references/skeleton-generation.md
• 2026-05-20 Self-Evolving Protocol 增加「画完架构图后：建议 ingest 到项目 wiki」环节，触发对 pm-wiki-maintainer 的协作（按新能力域 / 模块边界 / 下游平台 / 4 层结构 4 维度评估）（自迭代回流）
• 2026-05-14 初始版本（蒸馏自 企业 SaaS 项目 6 轮迭代，含 anti-patterns / col-span-cookbook / review-checklist）
• 2026-05-15 新增 Self-Evolving Protocol（触发评估时机表 + 防御性约束 + 30 秒自检清单）
• 2026-05-15 新增跨平台支持段（codex / cursor / antigravity / gemini / copilot 路径与 Self-Evolving 触发方式）

每条都对应一个原则，固化在本 skill 中以避免后人走同样弯路。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: songshishuang
• Source: songshishuang/Skills
• License: MIT
• Homepage: https://github.com/songshishuang/Skills

Install and usage instructions live in the source repository linked above.