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/ 顶层: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 文字里 < > & 必须转义(< > &);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-)。
• 汇编成 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 自检)

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-detail-diagrams 与 docs/architecture/架构/生成引擎/tier2细节图说-*.md)。

• 编排 = 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(同步纪律入收口第 8 步)、staging-ops.md(PNG 转换在 mini-desktop)、saa-graph-orchestration.md(生成引擎子树图的内容源)。