games-development-ai/.agents/skills/architecture-diagram-atlas.md

---
name: architecture-diagram-atlas
description: "当为 docs/architecture 某领域补图说、新增系统级图、或设计档变更后据防漂移门同步 SVG/图说时使用:SVG house style、图说文档结构、三范式纪律(单源/防漂移/状态双层)、按域并行编排配方与主会话复验脚本。"
---

# 架构图集生成配方(architecture diagram atlas)

把 `docs/architecture` 的每个领域画成"一套图 + 讲解"的图说,外加一份顶层总图叙(apex)。目标三条:① 新人看图入门;② 评审者**据图发现设计缝**;③ 图与设计档不漂移。2026-06-22 第一期(总图叙 + 7 域图说 ≈ 71 图位 / 35 SVG)实证,配方在此固化。计划稿 = `git show 8ea97234:docs/plans/2026-06-22-架构图集-目录与图清单-plan.md`;金样板 = `docs/architecture/07-运维图说.md` + 其 `assets/`。

## 何时用
- 给某个领域/子系统补图说,或新增系统级图。
- 设计档变更后,据防漂移门把对应图说与 SVG 同步更新。

## 产物形态
- **混合**:复杂/跨域图 = 手绘 **SVG** 大图(高保真、矢量、GitHub 直渲);简单/线性图 = **Mermaid** 内联。
- 每张 SVG 另在 **mini-desktop** 批量转 PNG 入仓(6c6g 禁 chrome、无转换器)。SVG 只在 6c6g 出。
- **最终产物 = 按领域拆分的编号文档,全放 `docs/architecture/` 顶层**:`00-系统总览图说.md`(总图 = 7 张系统级图 + 目录,链各域)+ `01-产品…07-运维图说.md`(每域一篇,各含该域全部图 + 讲解)。SVG 仍按域留各子目录 `assets/`(`运维/assets/`、`架构/assets/arch-`/`sbx-`、`产品/assets/` 等),顶层文档经**顶层相对路径**(`运维/assets/xx.svg`;00 的系统级图在 `assets/xx.svg`)引用、inline 渲染。
- **结构演进的教训(2026-06-22 创始人三次反馈收敛,务必照终态做)**:① 起初「导览式 apex(顶层)+ 各域图说(子目录)」——apex 跨子目录**链**各域、子目录文档间互引,在部分渲染环境**不显图**;② 改合并成一份顶层全量主档——**太大**(1721 行,创始人嫌大);③ **终态 = 按领域拆成多篇、都放顶层、文件名编号 01/02/03 排序**——既小而可读,又因「顶层文档 → 子目录 assets」是**单向下引**(渲染没问题,合并版已实证)而全图真渲染。**铁律:图集文档一律放顶层、引子目录 assets;切忌让子目录里的文档去跨引另一子目录的图。**各域 `README.md` 是既有设计档、不动。

## SVG house style(逐条照做,违一条图废)
- 头:`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1480 H" font-family="-apple-system,'PingFang SC','Microsoft YaHei',Segoe UI,sans-serif">`,H 按内容 700~960。
- 浅底 `#f8fafc`;主文字 `#0f172a`、次要 `#475569`;实线 `#334155`、虚线 `#64748b`(`stroke-dasharray="6 4"`)、远期紫 `#7c3aed`、红线 `#dc2626`;圆角矩形 `rx 7~12`。
- 标题 24px 粗「图 N · 名称」+ 副标灰 12px + 底部脚注「映射：源档 ｜ 状态：现/接/缓 ｜ 设计变动须同步本图」(**全角冒号「：」**)。
- 生产维度徽章小色块+白字:安全`#dc2626` / 可观测`#0ea5e9` / 可靠`#16a34a` / 成本`#16a34a` / 数据`#475569` / 伸缩`#7c3aed` / 质量`#15803d`,按图相关维度点几个。
- 复用/边界三线:实线=现成直接用/同步,虚线=自建/解耦/远期,双线或加粗框=跨域共享/强调边界;箭头用 `<marker>`。
- **SVG 文字里 `< > &` 必须转义**(`&lt; &gt; &amp;`);XML 注释禁出现连续两个连字符(`--`);所有元素在 viewBox 内不溢出。

## 图说文档结构(沿用金样板)
- **frontmatter**:date/topic/status + 「映射源档 + 各源档当前 commit hash」(`git -C <repo> log -1 --format=%h -- <源档>` 取)= **防漂移门**。
- `## 0 阅读约定与同步纪律`(映射哪些档 + 同步纪律 + 本域状态分布)。
- `## 1 全图通用图例`(徽章集 + 三线 + 状态码)。
- `## 2 图集`:每图 = 嵌图 + 一段**人读散文**(完整句子、讲清这图让人看出什么、现行/远期边界、设计缝;**不要电报体黑话**——创始人铁律)。
- `## 3 图清单与状态表`(# / 图名 / 家族 / 形式 / 状态 / 覆盖内容)。
- 总图叙(apex)额外:导览式——只内联系统级跨域新图,对各域写「讲什么故事 + 命门缝 + 链接」导航段,再加按角色下钻路径。

## 三范式纪律(本图集的硬约束)
- **(a) 单源**:形式标「引」的图**绝不复制** README 已有的 Mermaid,只在散文里链接「见该域 README §X」。同一张图绝不存两处(复制=自造漂移面)。领域已画的图,总图叙只链不重画。
- **(b) 防漂移**:frontmatter 记源档 commit hash;§3 状态表逐图复述状态;收口脚本比对 hash,对不上标「待复核」。
- **(c) 状态双层**:状态码 = 现(已建)/接(待接线)/建(待建)/缓(缓做)/F(future)/废(决策史)。整图非「现」时图顶加**状态约定条**说明整图状态 + 实心/虚线含义;元素级凡 接/建/缓/future/废 一律虚线框 + 文字小标,与「现行已建」实心块一眼区分。**绝不把 future(k3s 迁移/SAA·Dify 可插拔适配)、在飞(tier2)或已废(OpenGame/玩法填参模板/15KB)画成现行;而 Nacos/RocketMQ 已是生产 runtime、应画「现/接」，勿再当 future。**(Dify 按 AGENTS.md 口径=最低优先级远期,非已废)

## 编排配方(按域并行)
- **每域一个 opus agent**(`agentType: general-purpose`,可 Write),克隆金样板:读 计划稿+金样板 md+2 张金样板 SVG+本域源档 → 逐图产出(SVG/Mermaid/引用)→ 自检 → 汇编 md。结构化返回 `{docFile, svgFiles, figureCount, svgOk, statusDisciplineNote, singleSourceNote, selfCheck, flagsForReview}`。
- 多域 = `parallel()` 扇出(不同域不同文件夹、零碰撞,无需 worktree 隔离)。同域两份图说共享 `assets/` 时用文件名前缀区分(如 `arch-` / `sbx-`)。
- **汇编成 00-07 编号文档,全放顶层**(放最后,关键收尾):各域产出 → `0N-<域>图说.md`;系统级图 + 目录 → `00-系统总览图说.md`(用相对链接指 01-07)。规则:各域散文逐字保留、SVG 用顶层相对路径(`<域>/assets/xx.svg`,00 的系统级图用 `assets/xx.svg`)、「引」图 inline 其 README 的 Mermaid(带「(图源:…)」小注)。生成引擎子树只链接不并入。每篇 frontmatter 防漂移门记该域真实设计档 hash(非中间图说),各图具体映射在图脚注。(若中途产过 per-domain 子目录图说或合并大档当过渡,终态须收敛到这套顶层编号文档、删过渡件,避免双份漂移。)
- **分两期降风险**:先六域(自包含、可立全局轮廓),后生成引擎子树(最厚、且常被另一 session 在飞建——**第二期前必先跨 session 对齐边界、只链不双写**)。

## 复验脚本(主会话亲验,不轻信 agent 自检)
```python
import re,glob,xml.dom.minidom as M
for f in sorted(glob.glob("docs/architecture/**/assets/*.svg",recursive=True)):
    s=open(f,encoding="utf-8").read()
    try: M.parseString(s); wf="良构"
    except Exception: wf="XML错!"
    vb=re.search(r'viewBox="0 0 (\d+) (\d+)"',s); W,H=int(vb.group(1)),int(vb.group(2))
    mx=my=0
    for m in re.finditer(r'<rect[^>]*?\bx="([\d.]+)"[^>]*?\by="([\d.]+)"[^>]*?\bwidth="([\d.]+)"[^>]*?\bheight="([\d.]+)"',s):
        x,y,w,h=map(float,m.groups()); mx=max(mx,x+w); my=max(my,y+h)
    for m in re.finditer(r'<(?:text|line|tspan)[^>]*?\bx2?="([\d.]+)"[^>]*?\by2?="([\d.]+)"',s):
        mx=max(mx,float(m.group(1))); my=max(my,float(m.group(2)))
    over="溢出!" if (mx>W+2 or my>H+2) else "界内"
    foot="脚注" if "映射" in s else "缺脚注!"   # 注意脚注用全角「：」,别用半角冒号匹配
    amp="裸&!" if re.findall(r'&(?!amp;|lt;|gt;|#\d)',s) else "ok"
    print(f"{f.split('/')[-1]:30} {W}x{H} ({mx:.0f},{my:.0f}) {over} {wf} {foot} {amp}")
```
md 另核:§0-3 齐、frontmatter hash 与当前 git 一致、```mermaid 块数 = 新 Mer 图数(引图区零 mermaid)。再人工抽读 1–2 张最高风险图(如契约族、合规死锁)。
> **复验脚本盲区(必补一道主会话 sweep):** 上面的「脚注 ok」只验「映射」二字在不在,**查不出脚注里半角冒号 vs 全角「：」**——派出去的子代理逐图各验也会漏。主会话提交前另跑一道:对每张 `t2-*.svg` grep 含「映射」的脚注行有无 ASCII 冒号,有就批量改全角(只改脚注行、别动 `<style>` 里的 CSS 冒号)。tier2 细图扩展轮即靠这道 sweep 补逮 6 张漏网。

## 双评审揪出的六坑(画图前过 Codex+Opus 双评审,这些是真命中)
1. **漏整域**——v1 清单漏了运维域(声称 140 实列 132)。逐域核对覆盖矩阵。
2. **现行/远期错标**——现行 = 统一框架 AgentScope 上的三档(按 AI 参与深度分),引擎随游戏复杂度选 LittleJS / Phaser 变体、引擎非分档轴;**SAA 固定 16 节点线为旧路线的历史表示**(已降最低优先级,只留远期可插拔适配),画图时别把它当现行主线。整图按现行/远期分簇,逐图核状态标。
3. **缺状态列**——逐图必标状态,否则极易把 future/已废画成现行。
4. **契约/验收门画理想**——契约总览自陈「DB 镜像已漂移、CI 防漂移门缺位、Dify#6 废、第9契约五套编号相撞」;图必画**声明 vs 现实**,不画治理已到位。验收门拆「九门 harness(机制地板)」与「W-G1 开闸 6 门(发布门)」两层。
5. **「每域齐五种图」是凑数配额**——家族由内容定,别为凑类图硬画;会产 AI slop。
6. **复制 README Mermaid 进图说 = 自造漂移**——必须单源引用(只链不抄)。

## 可review设计意图
图不只好看,要让评审据图发现缝:每图标现行/远期边界、跨域接缝、待裁项;总图叙 §3 逐域点「命门缝」。第一期实证的高价值跨域图 = 失败/降级/补偿路径全景、端到端鉴权信任边界、契约镜像+防漂移现状。

## 细颗粒 detail-图说 扩展(子树放大层)

域图说之外,某个子系统要逐项放大(把总览一句话带过的「九门」「skills」「源项目契约七要素」铺成逐门 / 逐工具 / 逐要素的细图),按「族」拆 detail-图说,放在该子系统目录、单源引用总览。tier2 生成引擎子树即用此法建了 8 族 32 图,现在位仅 `tier2细节图说-G-spike-runbook.md` 一件,余已随整理归档(git 可查)(见记忆 `tier2-detail-diagrams`)。

- **编排 = draw → 对抗验证 → 族汇编 pipeline(Workflow)**:每图一个 opus 子代理,先读源档取证(绝不编)→ 画 SVG → 跑共享 `/tmp/verify_svg.py <checkKey>` 自检 → 对抗评审(内容对源 / house-style / 无 AI 味 / deepen 不 duplicate,小瑕疵就地修);一族图齐后一个 opus 汇编族图说 md(防漂移 hash + 人读散文,house-style/散文铁律/deepen 规则的正反例必须随 prompt 一起传下去)。2 轮共 66 子代理实证可复用、稳定产出过门。
- **deepen 不 duplicate**:detail 图是总览某图的逐项放大,不重画总览已有的图;承接时脚注写「(放大总览图 N)」单源引用。workflow 专设一道 `deepensNotDuplicates` 验,防换皮重画。
- **复验脚本放共享 `/tmp` 文件**,别内嵌进 JS workflow 脚本——python 正则的反斜杠会被 JS 模板字面量吞掉。
- **看图入口回链**:子树总览图说加一段「细节族图说(放大层)」指针,链各族 detail 文档,保持可发现。

> 相关:[`wave-close-checklist.md`](wave-close-checklist.md)(同步纪律入收口第 8 步)、[`staging-ops.md`](staging-ops.md)(PNG 转换在 mini-desktop)、[`saa-graph-orchestration.md`](saa-graph-orchestration.md)(生成引擎子树图的内容源)。
</content>