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

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

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

何时用

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

产物形态

• 混合:复杂/跨域图 = 手绘 SVG 大图(高保真、矢量、GitHub 直渲);简单/线性图 = Mermaid 内联。
• 每张 SVG 另在 mini-desktop 批量转 PNG 入仓(6c6g 禁 chrome、无转换器)。SVG 只在 6c6g 出。
• 最终产物 = 单一全量主档 docs/architecture/系统全图说.md(总图 + 目录 + 全部图说 inline 在一篇)。为什么不分多文件(2026-06-22 创始人反馈纠偏):多文件形态下,顶层/某文档跨子目录引用另一子目录里的 SVG,在部分渲染环境不显图;故合并成一份顶层文档。SVG 仍按域留各子目录 assets/(产出阶段如 运维/assets/、架构/assets/),主档经顶层相对路径(运维/assets/xx.svg、架构/assets/arch-xx.svg,apex 系统级图在 assets/xx.svg)引用,全部 inline 渲染。各域 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 文字里 < > & 必须转义(< > &);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(tier2/k8s/Nacos/RocketMQ)或已废(Dify/OpenGame/玩法填参模板/15KB)画成现行。

编排配方(按域并行)

• 每域一个 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-)。
• 合并成单一全量主档(放最后,关键收尾):各域产出 + 系统级图 → 合进 系统全图说.md。规则:逐字保留各域散文、SVG 改顶层相对路径、「引」图 inline 其 README 的 Mermaid(带「(图源:…)」小注)、顶部生成目录锚(GitHub-slug 算法,逐个核命中零断链)。生成引擎子树只链接不并入。各域中间产物(per-domain <域>图说.md)是临时件,合并后删除(避免与全量主档双份漂移),SVG 留子目录;主档防漂移门改记真实设计档 hash(非中间图说)。
• 分两期降风险:先六域(自包含、可立全局轮廓),后生成引擎子树(最厚、且常被另一 session 在飞建——第二期前必先跨 session 对齐边界、只链不双写)。

复验脚本(主会话亲验,不轻信 agent 自检)

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 张最高风险图(如契约族、合规死锁)。

双评审揪出的六坑(画图前过 Codex+Opus 双评审,这些是真命中)

1. 漏整域——v1 清单漏了运维域(声称 140 实列 132)。逐域核对覆盖矩阵。
2. 现行/远期错标——金样板(agentic 运行时)画的是远期 tier2 自治轨,非现行主线;现行 = SAA 固定 16 节点线。子树必拆现行/远期两簇。
3. 缺状态列——逐图必标状态,否则极易把 future/已废画成现行。
4. 契约/验收门画理想——契约总览自陈「DB 镜像已漂移、CI 防漂移门缺位、Dify#6 废、第9契约五套编号相撞」;图必画声明 vs 现实,不画治理已到位。验收门拆「九门 harness(机制地板)」与「W-G1 开闸 6 门(发布门)」两层。
5. 「每域齐五种图」是凑数配额——家族由内容定,别为凑类图硬画;会产 AI slop。
6. 复制 README Mermaid 进图说 = 自造漂移——必须单源引用(只链不抄)。

可review设计意图

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

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