| name | saas-arch-diagrams |
| description | 设计企业 SaaS 类产品的两类核心架构图：「产品架构图」（产品在更大生态中的定位 · 4 层视图）和「功能架构图」（4 层纵向 × 能力域横向 chip · 3 级嵌套）。当用户提到「画产品架构图」「功能架构图」「product architecture diagram」「functional architecture」「画一张架构图」「按 4 层结构梳理功能」「区分多端功能」时使用。蒸馏自 企业 SaaS 项目的迭代实战，覆盖 SaaS 多端产品的常见结构问题（端 / 服务混用、能力域平铺、版本视角混淆、空白区过多、合并模块违反逻辑等）。 |
SaaS 架构图设计
这个 Skill 解决什么
企业 SaaS 类产品在做产品评审 / 范围判定 / 迭代规划时，需要两类截然不同的架构图：
- 产品架构图（Product Architecture） —— 产品在更大生态中的定位、面向谁、提供什么能力域、与外部依赖的边界
- 功能架构图（Functional Architecture） —— 平台具体功能的完整清单，按层 + 能力域 + 子能力 3 级嵌套
这个 skill 提供两类图的结构模板、CSS 设计 token、内容组织原则、常见陷阱清单，让你避开 6 轮以上的反复返工。
触发场景
- 「画产品架构图」「画功能架构图」「按 4 层结构画下功能」
- 「我需要让别人看清楚我们做什么、面向谁」
- 「这个图能不能区分一下哪些功能是哪个端」
- 「按能力域分类一下」「按子能力做嵌套」
- 「product architecture diagram」「functional architecture for SaaS」
两类图的根本区别
| 维度 | 产品架构图 | 功能架构图 |
|---|
| 回答问题 | 我们做什么、面向谁、与下游的边界 | 平台具体有哪些功能模块 |
| 视角 | 自上而下看生态 | 自内而外看实现 |
| 主轴 | 用户 → 应用 → 能力 → 底座 | 端 → 服务 → 数据 → 底座 |
| 颗粒度 | 能力域级（A/B/C/D） | 模块级（每个功能一卡） |
| 适用场景 | 给老板 / 跨团队 / 外部讲产品定位 | 内部研发 / PM 做范围判定与迭代规划 |
| 是否分版本 | 不分 | 不分（全局功能视图） |
不可违反的原则
读图者最容易抓出来的 7 个"硬伤"，做之前先内化：
- 不要分版本 —— 架构图是全局视角，"v0.1 / 远期 / 未来" 这类标记一律不要出现。版本规划放 roadmap / PRD。
- 不要省略合并 ——
④-⑧ 高阶节点 合并为一卡是为了视觉省事，违反"内容逻辑"。8 个节点就要画 8 张卡。
- 端的定义要纯粹 —— "端"是用户使用的客户端，只能是：运营端 / 供应商端 / 客户端 / 管理端 / 第三方平台。绝不能包含「后端」「业务服务」「数据」这种技术语言。
- 服务和页面不能混 —— 评测任务列表（页面）和评测流水线 controller（服务）属于不同层次，硬放一起会让人看不清。
- 能力域不能平铺 —— 域内功能必须再分子能力，3-7 个并排卡片堆在一起没有层次。
- 不要为了对齐而留空白 —— grid 等宽分配 4 列时，某列卡片少就空一片。要按内容动态分配 col-span。
- 不要编造功能填版面 —— 图是事实陈述不是装饰：只画真实存在/已规划立项的能力，"显得完整""饱满好看"不构成加卡理由；版面不满用 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。
CSS 设计 token
完整模板见 templates/styles.css，核心 token：
.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); }
.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); }
.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); }
.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); }
.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; }
.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; }
.m-out { background: #f5f5f4 !important; border-style: dotted !important; opacity: .7; }
.m-out .ct { text-decoration: line-through; color: #78716c; }
标准实施流程
Step 1 · 先做产品架构图（1-2 轮）
- 写一句话定位：本产品是「X 平台的 Y 子系统」（如不是子系统则跳过）
- 列出 4-5 个能力域（A/B/C/D/E），每个域 1 句话能讲清楚
- 列出用户与场景（内部 / 外部，区分角色）
- 标识不在本平台范围但要协同的能力（→ 下游聚合平台、→ 外部 API 等）
- 用
templates/product-arch-template.html 起手
Step 2 · 再做功能架构图（3-5 轮）
- 第一轮：列功能清单 —— 把所有功能列出来，标 (端，能力域，子能力)
- 第二轮：按 4 层分类 —— 把功能放到 L1-L4 对应层
- 第三轮：嵌套到 3 级 —— L1 内每个端按能力域分子组，每域按子能力再分一级
- 第四轮：col-span 填满 —— 算每行 col 总和 = 12，调整子组宽度
- 第五轮：检查 7 个硬伤 —— 见前文「不可违反的原则」逐条对照
- 用
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、out_of_scope）ecosystem 上下游（仅产品架构图）
完整 schema + 下游消费契约 + 反模式见 references/skeleton-generation.md。
⚠️ skeleton.yaml 是自动派生 · 永远只读 —— 改 HTML 后重新生成，禁止手工编辑 yaml。
Step 4 · 评审 checklist（每次改完都过一遍）
参考 references/review-checklist.md（v2.0 已 DoD 分层 · 核心必勾 8 / 场景必勾 8 / 推荐 5）。核心必勾 8 条：
场景必勾 8 / 推荐 5 / 视觉约定示例 见 review-checklist.md 全文。
常见陷阱与对照案例
每条都附最初错误和修正方式，见 references/anti-patterns.md：
- "评测集体系 22 模块" vs "评测集数据 + 评测集管理工具 拆开" —— 数据资产和管理 UI 不是一个维度
- "报告产出 4 模块包含基线" —— 行业基线是数据资产，不是报告产出
- "层 6a 对象 + 层 6b 底座" —— 用 a/b 表示子层混乱，要么拆成独立层 7、要么不拆
- "评级算法 + 综合评分 + 行业基线 + 审批面板 全塞 ③ WHAT 段" —— 评级是 D 风险域 / 审批是 L1 端层 / 基线是 L3 数据层
- "运营端 + 评测工程师 + 供应商 + 后端 + 下游聚合 5 个端" —— 评测工程师是运营端内角色，后端不是端
- 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，不要等用户提醒。
触发评估时机
更新约束（防御性规则）
- ❌ 不要默默更新 skill——必须告诉用户「本轮新增 N 条 X」让用户有否决权
- ❌ 不要等到 10+ 张图后再一次性蒸馏——错过太多上下文，记不清当时为什么改
- ❌ 不要把项目特定的层数 / 域数当通用规则——只有跨 ≥2 个项目（如 项目 A + 项目 B）验证过的才进 references
- ✅ 更新时必须在 SKILL.md 末尾
## Changelog 加一行（日期 + 改动摘要 + 来源项目）
评估清单（画完一张架构图后 30 秒自检）
增长驱动（有没有新东西要加）：
简化驱动（有没有可以砍的 · v2.x 新增 · 防止 references 单调膨胀）：
任一项勾选 → 显式回头更新 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 | <project>/.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 中以避免后人走同样弯路。
