zizi c7e37a739b docs(skills): 蒸馏架构图集生成配方(§7 知识沉淀)——第一期实证

配方含 house style 规格/图说文档结构/三范式纪律(单源·防漂移·状态双层)/按域并行编排/
复验脚本/双评审揪出的六坑/分两期+跨session协调;供第二期(生成引擎子树)、在飞 session、
后续加域复用。.agents/README.md 索引同步。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-22 12:38:05 +00:00

7.3 KiB

Raw Blame History

架构图集生成配方(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 出。
每域一份 <域>图说.md + 同级 assets/;总图叙 = docs/architecture/系统全景图说.md + docs/architecture/assets/。

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-)。
总图叙 apex 单独产(导览要引用已建成的各域图说,放最后做)。
分两期降风险:先六域(自包含、可立全局轮廓),后生成引擎子树(最厚、且常被另一 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 双评审,这些是真命中)

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

可review设计意图

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

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

7.3 KiB Raw Blame History Unescape Escape