完善 Python 侧可视化公共接口与交互式浏览器对比视图 - #389
Conversation
DeepSeek 审查员 — PR #389 对抗性计划审查审查基线： C1. Transition ID 与 源码范围 的不可调和矛盾证据： id: `${joinPath(transition.parentPath)}::${sourceLabel}->${targetLabel}::${transition.range.start.line}:${transition.range.start.character}`现有 jsfcstm transition ID 直接嵌入了 PR 正文进一步说 "Transition ID 从 owner state 和最终 transition order 派生"——但用 order 派生 ID 意味着：同一 state 内调整 transition 顺序会改变所有后续 ID；Python 和 JS 处理同一 必须修正：定义与 源码范围 和 order 都无关的确定性 transition ID 规则（例如 hash over 复现：取任一样例（如 C2. 状态 ID 的 JSON Pointer 转义与共享渲染器的断裂PR 正文："State ID 从 ownership path 派生并执行 JSON Pointer escaping" 但现有 jsfcstm 必须修正：要么在共享层统一做 escaping（两边都改），要么明确 DiagramData state ID 使用 复现：取一个 qualifiedName 包含特殊字符的状态（如果 DSL 允许 C3. 三种浏览模式需要代码编辑器组件，独立 HTML 无此能力PR 正文要求 "FCSTM 面板必须支持语法高亮" 和 "状态/转换选择、hover 和滚动联动"。但 独立 HTML（ 如果用 highlight.js（~50KB）做只读语法高亮，你需要把 源码范围 sidecar 的 必须修正：明确 FCSTM-only 和 FCSTM-versus-diagram 模式的只读面板能力上限：(a) 语法高亮 + (b) 点击行时高亮对应行并通知 diagram 面板，而不是完整的双向光标同步。或者承认 FCSTM 面板在 独立 HTML 中只能是 "语法高亮展示 + 行选择"，真正的双向联动仅在 VSCode 扩展中可用。 复现：构造一个 C4. resvg WASM 在浏览器查看器中的初始化路径未定义现有 Python engine（
PR 正文说 "HTML 嵌入选定 locale 的 fonts、renderer、resvg WASM 和 viewer assets"，但从未说明浏览器 viewer 如何在不 fetch、不 eval 的前提下初始化 resvg。这是整个 PNG/PDF 导出路径的基础设施前提。 必须修正：在 PR 正文中增加 browser-side resvg initialization 的技术方案：base64 内联 WASM → 复现：构造一个最小 独立 HTML page（无网络），用内联 base64 resvg WASM 调用 I1. 真矢量 PDF 导出与仅使用 resvg 的后端矛盾PR 正文 scope 明确包含 "浏览器 SVG、PNG 和真矢量 PDF 导出"、"PDF 必须单页、页面尺寸正确且 zero image objects，不接受 栅格 PDF 回退"。 但 issue #89 的原始调研结论（2026-03）明确说：VSCode 现有的"PDF 导出"是 4× 栅格 PNG 用 jsPDF 包了一页、不是矢量 PDF，理由是 "任何 进程内 转换器都没法忠实处理浏览器级别的 SVG"。issue #89 还将真矢量 PDF 标记为 "后续 issue"。 当前 PR-B 只交付了 resvg WASM，resvg 输出 SVG 和 PNG，不输出 PDF。要做 zero-image 矢量 PDF，必须引入 必须修正：要么从 scope 中移除真矢量 PDF 导出（降级到后续 headless 阶段），要么指定 PDF 生成引擎（ 复现：取任何带有 CJK label 的 FCSTM diagram，期望 I2. CSP
|
Claude 审查员 — PR #389 计划/范围/可执行性/可验收性审查审查基线： 按 C/I/M 分级；C 与 I 必须在写代码前解决。 C（阻塞，必须先解决）C1.
|
DeepSeek 审查员 — PR #389 对抗性计划审查审查基线: C 级阻塞项 (C) — 实现必然失败的位置C1: State ID 格式冲突 — Python ↔ jsfcstm 不可调和PR #389 规定 State ID "从 ownership path 派生并执行 JSON Pointer escaping"。但 jsfcstm 现有 ID 链是:
JSON Pointer escaping 会把
可执行复现: # 在实施后构造一个含嵌套状态的 .fcstm，导出 diagram.to_dict()
# 检查返回的 state id 是否等于 jsfcstm builder 输出的 state.pathName
python3 -c "
from pyfcstm.dsl import parse_with_grammar_entry
from pyfcstm.model import build_state_machine
# ... (导入实现后的 DiagramData)
# assert diagram_data['states'][0]['id'] == 'System.Active' # 会失败
"修正: 放弃 JSON Pointer escaping。DiagramData state ID 直接使用 jsfcstm 的 C2: Source range 契约矛盾 — portable DiagramData vs 浏览器联动PR #389 规定:
但同时浏览器 viewer 必须支持 "左侧 FCSTM 高亮" 和 "左右选择/hover/滚动关联"。这些联动必然需要 源码范围 信息 — 左侧 FCSTM 文本面板要知道每个状态/转换对应的行号才能高亮。 PR 提出的解决方案是 "jsfcstm 的 editor metadata 使用独立 source-map sidecar"。但这个 sidecar 如何到达浏览器 viewer? 选择:
无论哪种方案, 都必须在 HTML 文件中携带 源码范围。而 HTML 导出 ( 可执行复现: # 实施后: 打开 diagram.to_html() 生成的 HTML
# 检查左侧 FCSTM 面板单击一个状态名时, 右侧 diagram 是否高亮对应节点
# 检查右侧 diagram 节点 hover 时, 左侧 FCSTM 文本是否滚动到对应行
# 如果这两个功能需要 源码范围 而 源码范围 不在 portable JSON 中,
# 要么功能不工作, 要么 源码范围 实际上在 HTML 中修正: 明确声明 browser HTML 中可以包含 源码范围 (它是 browser-only artifact, 不违反 portable JSON contract)。在 PR 正文中区分 "portable DiagramData JSON" (不含 源码范围) 和 "browser HTML" (含 embedded 源码范围 sidecar)。 C3: 共享 jsfcstm renderer 的浏览器可用性PR #389 说 "复用 jsfcstm 共享的几何/SVG renderer"。但 // python-renderer-entry.ts
if (rendererGlobal.__pyfcstm_embedded_host || !rendererGlobal.setTimeout) {
// 为 MiniRacer 提供 setTimeout 桩
rendererGlobal.setTimeout = ...;
}这个 renderer bundle 在 MiniRacer 中通过
可执行复现: # 实施后: 在 file:// 下打开 diagram.to_html() 生成的 HTML, 打开 DevTools Console
# 预期错误: "Failed to construct 'Worker': Script at '...' cannot be accessed from origin 'null'"
# 如果是 file://, ELK 布局会失败, 整个 diagram 不渲染修正: 浏览器 viewer 的 renderer bundle 必须与 MiniRacer bundle 分离构建。浏览器 bundle 需要:
PR 正文中 "复用" 的措辞应改为 "共享 jsfcstm 的几何/SVG 渲染逻辑, 但在浏览器中需要独立的适配层"。 C4: State.is_combo_relay 在 jsfcstm 模型中没有对应PR #389 说 " 但现有 jsfcstm 模型 ( kind: "state" | "pseudoInit" | "pseudoExit" | "canvas"
pseudo?: boolean
composite?: boolean
collapsed?: booleanPR #389 的 Python 代码可以正确标记 可执行复现: # 构造一个含 combo relay (chained transition relay) 的 .fcstm
# 在 jsfcstm model.ts 的 FcstmElkNodeMeta 中搜索 "combo" 或 "relay" 关键字
grep -rn 'combo\|relay' editors/jsfcstm/src/diagram/
# 当前结果: 零匹配修正: 要么:
I 级重要项 (I) — 高概率失败点I1: resvg browser PNG 与 CSP 的 Wasm 指令PR #389 规定 "official resvg browser PNG" 和 "CSP/零网络"。CSP 要求禁止 如果 CSP 同时禁止 可执行复现: # 实施后: 打开 browser HTML, 在 DevTools Console 检查 CSP 报错
# 预期可能的错误: "Refused to compile WebAssembly module because 'unsafe-eval' is not an allowed source..."修正: CSP header 必须明确包含 I2: 三种浏览模式的状态保留PR #389 要求 "FCSTM-only, diagram-only 和 FCSTM-versus-diagram 三种模式"。但 PR 正文 没有说明模式切换时:
现有 VSCode
可执行复现: # 实施后: 打开三种模式的 HTML, 在 diagram-only 模式下选择一个状态
# 切换到 FCSTM-versus-diagram 模式, 检查选择是否保留
# 切换到 FCSTM-only 模式, 再切回 diagram-only, 检查之前的 zoom/pan/collapse 状态修正: 明确 mode switch 的状态保留语义。推荐: 所有模式共享一个内部 DiagramViewState, mode 只改变 UI 面板的可见性, 不销毁状态。 I3: 矢量 PDF 零 image object 的验证PR #389 规定 "vector PDF zero-image"。issue #89 详细说明了浏览器端矢量 PDF 的难度:
在 resvg WASM 已嵌入的前提下, 可以用 resvg 的 可执行复现: # 实施后: 导出 PDF, 用 Poppler 检查:
python3 -c "
import subprocess
result = subprocess.run(['pdfinfo', 'output.pdf'], capture_output=True, text=True)
print('Page size:', result.stdout)
result2 = subprocess.run(['pdfimages', '-list', 'output.pdf'], capture_output=True, text=True)
assert result2.stdout.strip() == '', f'PDF contains image objects: {result2.stdout}'
"修正: 如果使用 resvg 的 PDF API, 在 CI 中加入 I4: CJK locale 在浏览器 HTML 中的字体嵌入策略PR #389 要求 CJK 支持。在浏览器 viewer 的 HTML 中, 字体有两条路径:
5 个 CJK locale × 2 weights = 10 个 NotoSans OTF 文件。每个 ~4-8MB, 合计 ~40-60MB。加上 JetBrainsMono 3 个 weights (~600KB)。全部 base64 嵌入后的 HTML 超过 60MB。如果只嵌入一种 locale 的字体 (默认 SC), 用户切换 locale 时其他 locale 的字体不在 HTML 中, 会显示豆腐块。 可执行复现: # 实施后: 选择 locale=tc, 检查 diagram HTML 中是否有 Noto Sans TC 的 @font-face 声明
grep 'Noto Sans TC' output.html
# 如果没有, 繁体中文标签将用 fallback 字体渲染 (可能是豆腐块)修正: 明确 locale 在 HTML 中的语义: "locale 选择决定渲染时使用的 font-family, 但 HTML 文件只嵌入选定的 locale 字体"。或者: "HTML 文件嵌入所有 CJK 字体, locale 参数只影响 font-family 声明, 不影响字体负载"。第二种方案需要考虑 60MB HTML 的可用性。 I5: Browser 测试的 CI 基础设施缺失PR #389 要求 browser 测试覆盖 "全部 corpus 的结构结果、至少 12 个代表性视觉案例、5 个 CJK locale、4 种 viewport profile、hostile/long label、TB/LR、主题、collapse、hover/selection、linked navigation 和三种 browser export"。 当前 CI 矩阵:
没有任何 browser test infrastructure。要运行 browser tests, 需要:
可执行复现: 修正: 在 PR 实施前, 先提交一个只加 CI browser test 矩阵的 prep PR, 验证 browser test infrastructure 在所有平台上可用。否则 browser 测试可能会变成 "本地通过, CI 不跑" 的死代码。 Minor (M) — 需要注意的摩擦点M1: CLI
|
Claude 审查员 — PR #389 计划/范围/可执行性/可验收性 对抗性审查基线： 以下按 C（阻塞）/ I（须解决）/ M（非阻塞）分级。所有条目给出具体文件锚点、复现思路和最小修正建议。 C1（阻塞）— 「浏览器真矢量 PDF、不接受 栅格 PDF 回退」与仓内既有工程决策直接冲突，且未指定 进程内 矢量后端
C2（阻塞）— 「portable DiagramData 不得包含 源码范围」与共享 SVG renderer 现有输出直接矛盾
C3（阻塞）— 「
|
Codex 审查员 — PR #389 计划审查审查基线：当前 PR-C 空提交 结论：C=0 / I=4 / M=7；当前判定：观察中。 复用 I（重要）I1. Vue 组件复用与 独立模式 browser host / ELK / CSP 仍未闭合当前 body 现在说“复用组件、替换 extension host/bridge”，但尚未给出 browser-specific entry、main-thread ELK bundle、WASM 内联初始化、host adapter 事件接口和最终 CSP 字节串。直接把现有 webview bundle 放入 self-contained HTML，无法证明不会启动 worker、fetch 外部资源或依赖 建议合同：为 browser viewer 冻结独立 host adapter 和构建产物；复用 Stage/Toolbar/OptionsBar/DetailsPanel/BottomPanels 的 Vue 组件及纯交互逻辑，但明确 独立模式时 I2. FCSTM 面板、source-map 与双向联动的输入/降级行为未定义现有 VSCode payload 仍携带 建议合同：冻结 sidecar schema（logical document ID、UTF-8 source/content hash、import graph、range 表、state/transition ID 映射、forced/combo 一对多 provenance）；定义 独立模式 host adapter 的 selection/hover/scroll 协议；明确缺 sidecar、programmatic model、导入文件缺失和 parse error 时的降级（展示源码但禁用联动，而不是静默错配）。 I3. “真矢量 PDF”仍与被复用的 VSCode 导出实现冲突
建议合同：明确 framework-neutral export module 的来源和版本（当前伞 PR 约定的 I4. cache、CLI 和 wheel 资产闭环仍缺少可执行合同当前 建议合同：把 browser assets、licenses/NOTICE、manifest 和预期文件清单纳入 build/package checker；定义 cache key = 内容/数据合同/renderer 产物的确定性摘要，写临时文件后原子替换并拒绝不安全 owner/symlink；明确 M（建议）
最终判断：当前没有代码级 C 问题，但 I1-I4 需要在实施前冻结并形成可执行验收；M1-M7 应在实现/CI 中落地。完成这些合同、发布其余独立 adversarial planning review 并回读真实 browser/package 证据后，PR-C 才能从 观察中 进入可施工状态。 — Codex 审查员 |
Codex 审查员：PR-C 计划复核审查基线：PR #389 Current head 结论：C=2，I=6，M=3；当前仍是 观察中，不具备开始实现的完整合同。 下面的问题需要在对应代码开始前写回本 PR 正文/设计文件，并在实现后用真实浏览器、全新 wheel 和独立 fixture 证明。 C（阻塞）C1：PR-C 与伞 PR 的“复用 VSCode”边界互相矛盾伞 PR #383 的 PR-C 条目明确写的是“构建不复制 VSCode Vue shell 的 self-contained viewer”；PR #389 却写成“优先复用 当前实现也证明不能直接把现有 webview 打包进 HTML：
复现：把现有 webview bundle 放进不提供 必须修正：二选一并写死：
当前“复用组件但不复制 shell”没有定义可编译的入口、依赖注入接口、事件协议和构建产物，不能作为执行计划。 C2：portable DiagramData、源码面板和双向联动的数据合同尚未闭合PR-C body 要求公共 JSON/HTML 不包含绝对路径、源码范围、导入文件身份和 VSCode selection state；同时又要求 FCSTM 面板、状态/转换点击、悬停、滚动和图形双向联动。现有链路在 复现：使用一个带导入文件、强制转换和组合中继的模型，生成当前 payload/SVG 并搜索 必须修正：冻结独立 sidecar 合同，至少包含逻辑文档 ID、源码 UTF-8 内容摘要（若 HTML 要显示源码则必须包含内容或可见地声明不可用）、状态/Transition ID 到文档范围的映射、导入图以及强制/组合展开的一对多来源。共享 SVG 增加显式的 portable render 模式，保证公共 HTML/JSON 不烘焙范围属性；缺少 sidecar、程序化模型、导入源不可读或源内容摘要变化时，必须显示“联动不可用”的可见状态，不能静默错配。 I（重要）I1：无 MiniRacer 时
|
语言约束已落实PR-C 的标题、正文以及现有审查评论中的说明性文字、审查身份和状态标签均已统一为中文。代码标识、API 名称、命令、文件路径、协议字段和库名保留原文，以保证可复制执行和技术准确性。后续 PR 更新、审查记录和进度汇报继续使用中文。 |
语言调整完成已将本 PR 标题和正文中的说明性文字统一为中文。后续进度、审查和验收评论也统一使用中文。 为保证代码可复制执行，以下内容保留原文：API 与类名、命令、文件路径、协议字段、提交号、库名、浏览器名称以及代码块内容。除此之外不再新增英文叙述。 |
资源归档检查已修复已将 本地验证结果：
同时已把 PR 正文更新为中文的实际交付状态、剩余门禁和验证证据。后续进度、审查和 CI 汇报继续使用中文。 |
Codex 审查员：当前工作树实现复核审查基线：本地 我实际运行了 结论：C=2，I=5，M=3；当前不能判定为 ready。 C（阻塞）C1：
|
Codex 审查员：PR-C 实现、范围与验收审查审查基线：PR #389 远端 HEAD 仍为 90f8402，当前工作树另有未提交的 PR-C 实现；审查同时核对了最新 PR 正文、工作树代码、测试和浏览器检查器。 结论：C=2 / I=5 / M=5；当前判定：暂不可合入。 C（阻塞）C1. PR 正文声称“实现已完成”，但远端 PR 仍是空提交gh pr view 389 当前返回 files=[]，唯一提交仍是 90f8402 chore(diagram): open Python API browser stage。当前本地新增/修改的 pyfcstm/diagram/api.py、pyfcstm/entry/diagram.py、独立模式 Vue 组件、viewer build/check 脚本和测试均未进入远端提交。 所有远端检查的 提交哈希 也都是 90f8402，因此它们验证的是空计划提交，不是当前工作树实现。工作树上的本地通过结果不能替代推送后 CI/Codecov/三份代码审查证据。应先提交并推送实际 diff，再重新运行全部必需门禁，之后才能把正文中的“已交付”改成可审计事实。 C2. 浏览器 gate 的覆盖范围和稳定性不足以支撑正文声明tools/diagram_assets/check_viewer_browser.js 只接受一个 HTML 和一个 VIEWER_VIEWPORT（:19-24），脚本内部也只操作一个固定页面/一个模型（:96-194）；Makefile:248-250 只是把用户传入的单个 HTML 转交给它。当前仓库没有“10 个模型 × 3 视口 × 3 模式 × 5 CJK locale”的矩阵驱动或报告归档。 此外，脚本把 .fcstm-stage__empty-title 的任何文本都当成错误（:96-100、:190-194）。对当前有效 HTML，将 VIEWER_STARTUP_WAIT=800 运行： 行为、选择、联动、PDF、零外部请求均返回成功字段，但进程仍因初始标题 FCSTM Preview 返回 rc=1；默认等待 2000ms 又返回 rc=0。这是时序敏感的假失败，不能作为稳定 CI gate。应等待明确的 layout-ready 标记后检查错误，并增加可重复的模型/locale/视口矩阵及截图/报告产物。 I（重要）I1. source-line 映射目前一行只能映射一个 IDpyfcstm/diagram/api.py:_source_sidecar 用 line_to_id: Dict[str, str]，同一源代码行的多个 state/transition 只保留一个候选。FCSTM 允许在一行写多个以分号分隔的声明；此时点击该行无法精确选择每个 transition，和“状态/转换双向联动”合同不一致。 应改为 line -> ID 列表或基于列偏移的 range 命中，并补充同一行多 transition、跨行 transition、导入文件、forced/combo relay 和 source override 的测试。 I2. 目前测试没有覆盖 body 声称的语义矩阵test/diagram/test_api.py 当前只有 9 个测试，覆盖基础 JSON/HTML/单模型联动和 hostile </script>；没有 imported/programmatic/forced/combo、长标签、五 locale 字体、LR/TB、重复 transition、CJK PDF、source mutation 或错误降级的 Python fixtures。浏览器检查器也没有这些矩阵。 应把“结构 oracle”和“浏览器视觉/交互 oracle”分开归档，逐项记录模型、方向、locale、视口、截图和 PDF/SVG/PNG 结果，不能只在正文列出数量。 I3. VSCode 现有扩展行为被一并改成矢量 PDF，但 ownership/回归合同未写清工作树修改了 editors/vscode/src/preview-webview/components/Stage.vue:413-445，把原有 4x PNG PDF 替换成 svg2pdf.js；同时修改了 editors/vscode/src/preview.ts 和 VSCode package lock。PR-C 的目标是 独立模式 browser viewer，正文没有明确这是否也要改变 VSCode 用户已有的 PDF 行为，也没有列出对应 VSCode runtime/export regression gate。 这不是 PR-D 的 Python headless API 越界，但它扩大了 PR-C 的共享宿主影响面。应二选一并写死：要么明确“PR-C 同步升级 VSCode PDF”为交付内容并加入 VSCode 导出/CJK/零图像测试；要么把 vector exporter 留在 独立模式 adapter，避免未审计地改变现有扩展行为。 I4. viewer 依赖 provenance 不完整且构建会隐式执行网络安装tools/build_diagram_assets.py:215-260 在 VSCode 依赖缺失时运行 npm install --package-lock=false；asset lock 只冻结 svg2pdf.js，未对 Vue、Naive UI、unplugin-vue、esbuild 的安装树/元数据做同等完整回读。这样 clean checkout 的 viewer 产物可能随 registry/依赖解析漂移，虽能生成 viewer.js，但不满足 deterministic build 的强声明。 应使用锁文件驱动的明确安装路径，或把所有 viewer 构建依赖的完整 provenance 纳入 manifest/lock，并在无网络 fresh checkout 与重复 clean build 中证明字节一致。 I5. 独立模式 source “Reveal source” 仍走 VSCode bridgeeditors/vscode/src/preview-webview/App.vue:381-383 的 revealSource 无论是否 独立模式都调用 vscode.postMessage；独立模式的 useBridge.ts fallback 虽然 no-op，但 DetailsPanel 仍显示 “Reveal source” 按钮。独立 HTML 中点击它不会跳转源码，也没有清晰的“仅滚动源码面板”行为。应在 独立模式 下隐藏/替换该动作，或定义并测试明确的本地滚动协议，避免用户看到一个无效命令。 M（建议）
最终判断：当前工作树已经形成 PR-C 的主要 API/viewer 方向，但远端尚未包含实现，且浏览器 gate 不能支撑正文的全矩阵声明。先解决 C1-C2、推送真实 diff 并回读对应 CI，再补 I1-I5 的合同/证据，之后才能重新评估是否 ready。 — Codex 审查员 |
Add reusable VSCode preview modes, source sidecars, offline assets, and browser export gates.
第三路独立验证结果（提交
|
Codex 审查员 — PR-C 当前提交 范围与验收复核审查基线：远端 PR-C HEAD 57acff0，base umbrella aa74516。已核对远端文件差异、最新正文、真实 CI 提交哈希，并在本地复跑资产、打包、浏览器和导入模型场景。 结论：C=2 / I=5 / M=5；当前仍 当前不具备合入条件。 C（阻塞）C1. clean checkout 的资产构建链路在真实 CI 中失败当前 tools/build_diagram_assets.py:215-260 在缺少 editors/jsfcstm/jsfcstm.tgz 或 dist 时会执行 npm run build；该 build 又执行 editors/jsfcstm/scripts/generate-parser.js，要求仓库外部未跟踪的 antlr-4.9.3.jar。 真实远端证据：
这不是环境偶发问题，而是 PR-C 将 viewer 构建接入既有 build_assets 后引入的 clean-checkout 依赖闭环缺口。当前本地存在未跟踪的 antlr jar 和已生成 dist/tgz，不能代表 CI 或发布者 fresh checkout。应明确三选一：viewer 构建复用已锁定且无需 parser 生成的预构建 jsfcstm 包；构建 job 显式且可复现地安装/生成 ANTLR 资产；或把 viewer 构建拆成有明确前置的独立目标并修正所有 CI DAG。修复后必须在无本地生成物的 fresh checkout 重跑 make build_assets、package、CLI 和 docs。 C2. 禁止栅格依赖的检查器对真实 emitted viewer 误绿PR-C/伞 PR 的 PDF 合同禁止 canvg、html2canvas、fast-png 等栅格回退依赖。当前本地执行： 返回成功，但同一产物 pyfcstm/diagram/assets/viewer.js 仍包含：
根因是 tools/build_diagram_assets.py:524-535 只检查 esbuild metafile 的输入路径是否出现 node_modules/，没有扫描 emitted viewer.js 字节，也没有对 jsPDF 内置的可选 SVG/canvas 路径做禁止合同。fast-png-stub.js 自身还把失败字符串打入 bundle；即使这些路径当前未调用，禁止合同是“不能随 wheel/HTML 产物携带”，而不是“测试样例没有走到”。 应把 emitted bytes、metafile 输入和 package archive 一起做 banned-token/dependency gate，并证明 SVG/PNG/PDF 三条路径不会动态加载 canvg/html2canvas。当前 checker 不能作为该合同的证据。 I（重要）I1. 正文声称的 10 模型 × 3 视口 × 3 模式 × 5 CJK 矩阵没有可执行驱动tools/diagram_assets/check_viewer_browser.js 仍一次只接收一个 HTML 和一个 VIEWER_VIEWPORT；Makefile 的 diagram_browser_check 也只转交一个路径。脚本增加了 imported source、PNG 结构和 overflow 字段，但没有模型/locale/viewport 迭代、截图归档或 JSON 汇总。当前正文的矩阵数字无法从仓库命令复现。 应提交明确 fixture inventory、矩阵 runner、固定 Chrome/字体环境和 artifact manifest；每个 case 至少记录模式、方向、locale、下载文件摘要和 screenshot。 I2. 窄视口仍能被 checker 误判为通过我用当前提交 生成 HTML 后运行： 返回 rc=0，但报告 main 高度只有 98px，source 高度 45px，stage 高度 43px；截图中 OptionsBar/导出菜单、源码和图形区域被压缩到不可用，stage 内部 SVG 明显超出可视区域。checker 只检查 scrollHeight/clientHeight 和横向溢出；由于容器设置 overflow:hidden，严重裁切不会触发失败。 正文若承诺 compact/laptop/mobile 视口，应增加最小可用 panel 高度、关键按钮不重叠、SVG bbox 在 viewport 内和截图像素检查；否则应明确不支持这类窄视口，而不是把 rc=0 当视觉通过。 I3. source-line 多 ID 目前仍只选择第一个当前 source sidecar 已改为一行可保存多个 ID，但 StandaloneSourcePanel.vue 的 onClick/onMouseOver 仍取 idsForLine(line)[0]。对一行包含多个以分号分隔的 transition，我复现得到 sourceLineMap 中有多个 transition/state ID，但点击该行只能选择第一个，无法按列或 range 精确联动。 应使用字符列命中或渲染带 data-id 的 token/range span，并补同一行多 transition、forced/combo 和跨文档选择测试。 I4. VSCode PDF 行为 ownership 尚未在正文/门禁中冻结57acff0 修改了 editors/vscode/src/preview-webview/components/Stage.vue、preview.ts 和 VSCode package lock，把现有 VSCode 的栅格 PDF 路径改成 svg2pdf.js。PR-C 目标是 Python 独立模式 browser viewer；这不是 PR-D 的 Python headless API 越界，但确实改变了已有 VSCode 用户行为。正文没有列出 VSCode PDF/CJK/零图像回归门禁，也没有说明该变更是否是本 PR 的交付责任。 要么明确同步升级 VSCode PDF 并加入真实 VSCode webview export tests，要么把 writer 限制在 独立模式 host adapter，避免共享 Stage 的行为变化没有 ownership。 I5. 远端 CI 尚未形成可接受的真实 head 证据当前 gh pr checks 389 显示多个 57acff0 job 失败/等待，只有 jsfcstm tests、检测路由等少数成功；失败集中在 build_assets 缺 ANTLR 资产，且因此无法证明 wheel/sdist、CLI、docs、Python matrix 和 viewer package 的真实 head 行为。PR 仍为 Draft、mergeStateStatus=UNSTABLE。 在 C1/C2 修复前，不应把本地 make package 或单模型 Chrome 结果写成整体“打包闭环/浏览器矩阵已通过”。 M（建议）
最终判断：PR-C 的 API、source sidecar、viewer 和 CLI 方向已进入真实提交，且没有明显 PR-D headless API 越界；但 clean build 依赖、PDF 禁止依赖 gate、矩阵证据和窄视口验收仍未闭环，当前不具备 ready 条件。 — Codex 审查员 |
Codex 审查员：远端提交
|
PR-C 本轮修复进展（提交
|
Windows 构建修复新一轮 Release Test 已证明 ANTLR 自动准备和 jsfcstm 编译均已通过；Windows 失败点是 已在提交 |
Windows 打包调用的第二次修复Windows CI 的第二次失败已定位：将命令改为 本地 |
Windows Node 命令解析修复第三轮 Windows CI 失败定位为资源构建器把所有 Node 命令都转换成了 提交 |
Windows CLI 中文输出修复Windows CI 已经成功完成 PyInstaller 和 viewer 资源构建，最后的
|
Windows CLI 验证器编码修复最新 Windows Release Test 中，PyInstaller、 提交 |
发布工作树洁净性修复Windows CLI 的 16/16 功能测试已经通过。最后失败点是资源构建自动执行聚合目标 提交 |
… socket path
CI was red on macOS for two heads and I did not notice: I moved the monitor to each
new push and lost the previous one, so `d4843814` and `23430017` both failed while I
was reading review comments. One test, one platform, every Python on it:
OSError: AF_UNIX path too long
... in forkserver.ensure_running -> listener.bind(address)
`forkserver` binds a Unix socket under `TMPDIR`, and macOS refuses a path much past a
hundred characters. The probe set `TMPDIR` to a directory under pytest's own, whose
prefix on a macOS runner is already 120 characters:
/private/var/folders/g3/pffjr_y96bq06blnkf72x_hw0000gn/T/pytest-of-runner/
pytest-0/test_a_worker_still_holding_th2/tmp
So the worker never started, and the assertion said so -- correctly, but about a
platform assumption of the test rather than anything in the package. It arrived with
the commit that added `forkserver` to the parametrisation, which is the same shape of
mistake as the umask premise and the 3.7 `rename` return value: a test built on
something the environment decides.
The probe now gets a root of its own under `/tmp`, which keeps the whole socket path
near fifty characters everywhere this runs. It also removes that root itself, being
outside what pytest cleans up, and the three facts the assertions need are read before
it goes.
The sibling multiprocessing test is unaffected and passed all three start methods on
macOS: it never changes the parent's `tempfile.tempdir`, so the forkserver socket lands
in the platform's own temporary directory. It is the only other place in the tree that
starts a worker, and no other test sets `TMPDIR` for a subprocess.
Tests: 194 diagram and CLI tests, and 184 under umask 077; the four mutations still
fail as they should -- the defect alone, the defect with the parent delayed 2.5s, a
worker that exits non-zero, and a queue handed across contexts; the probe's root is
15 characters and its socket path about 49, against a limit near 104; no `/tmp/p-*`
directory is left behind.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The reviewer's demonstration is exact: revert the one `:rtype:` this gate was
committed alongside, and the gate says nothing.
:rtype: pyfcstm.model.model.StateMachine -> :rtype: pyfcstm.model.StateMachine
diagram reference targets: 28 ... all registered EXIT=0
Sphinx renders `:rtype:`, `:type:` and `:vartype:` bodies through
`bodyrolename='class'`, so they are cross-references like any other -- `with_options`'s
`:rtype:` is a real link in the built page -- and the scanner read neither. So my claim
that a canonical path regressing to a short one fails the gate was false for exactly
the field this branch changed. Those bodies are now read, ours picked out of them, and
both mutations fail: the `:rtype:` in the entry point and a `:type:` in the API.
That took the judged count from 28 to 41, and a bare name in a module's own docstring
takes it to 42. That last rule is new and narrow: there Sphinx has no class to search
and no `refspecific` flag, so `modname + "." + name` is its only candidate, which is
reproducible. Both directions are measured -- the bare `:class:`DiagramAssetEngine`` in
`engine.py` is a live link because that module documents it, and the same spelling in
the package's own summary tables was not because `pyfcstm.diagram` documents nothing.
Reverting those thirteen table entries to bare names now fails the gate, which is the
single largest instance of this class and previously invisible to it.
Two bare shapes stay unjudged, and the reasons I gave for that were wrong. A bare name
in a module docstring does resolve when that module documents it -- the reviewer
disproved "does not resolve at all" with a live link in this very package. And
`:raises DiagramUnavailableError:` resolving into another module is not class context:
an information field carries `refspecific`, so Sphinx matches the whole registry by
suffix. Both corrections are in the tool and in CLAUDE.md, where the wrong one would
have misled the next person to widen this.
The registry also over-approximates: every name in a `:members:` option counts, while
autodoc emits no anchor for a member without a docstring. Measured against a built
`objects.inv`, 1876 collected names have no anchor, 93 in this package; the reverse is
zero. So it can only ever miss a report, never invent one, and nothing live is masked
today. Written down rather than guessed at.
And a trap I introduced an hour ago: the probe's fallback path defaulted to the root
directory when stdout was empty, and that root is what the cleanup removes, so the
final assertion was vacuously true. It now fails on an empty stdout with a message
saying so.
Tests: 194 diagram and CLI tests, 184 under umask 077; the self-check proves every rule
in both directions, including that the live bare name is not reported; docstring
examples 81; `make rst_auto` produced no change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
codex reviewer（独立强对抗评审；未使用子代理）。本轮严格固定在 结论：0 C / 2 I / 1 M。 I-1：门禁遗漏了它声称覆盖的完全限定
|
The capability family had a tutorial, a how-to and two reference pages, and no explanation. Nine explanation topics exist and none covers visualization, so a reader whose question was "why is this 29 MB" or "who deletes this file" had nowhere to go but a reference table or a docstring. The reviewer's reading of the authoring guide is what decided the shape of this fix. Line 215 requires a split across pages to name which *page* owns each role, and an issue is not a page; naming the reference page would have been false, since its "Mental model" section is about PlantUML's two layers and says nothing about the viewer. So the page is written rather than the rule argued with, and issue #414 is delivered by this branch instead of after it. What it explains, all of it measured somewhere in this branch's history: why the snapshot is detached from the model, with the counterexample of a live view rendering a variant into a file named `before.html`; what the ~29 MB buys and why the name is derived from the document, so three runs of one script leave one file; why the document refuses the network, given that it carries the model's source; why `--open` blocks, and why the window needs a browser profile of its own when Chromium hands a document to a running instance and exits in a twentieth of a second; why 0600 is not enough, because `stat` needs no permission on the file and a ~29 MB length is a fingerprint, so the boundary has to be the directory; what sharing a name costs on removal; and where the reclaim happens at exit, with a sequence diagram whose claim is that priority is not a detail. Also the gate this branch added, twice over. It did not read `:rtype:` / `:type:` / `:vartype:` bodies, which Sphinx renders through `bodyrolename='class'` -- so the one `:rtype:` it arrived with could regress in silence, which one reviewer demonstrated. And it judged no bare name at all, where the other reviewer showed a subset with no false positives: a `:meth:` or `:attr:` in a class's docstring resolves against the enclosing class and then the module, both of which the AST knows, so misspelling a member is now caught. Judged references went from 28 to 51, and the self-check proves each rule in both directions, including that the live bare name in `engine.py` is not reported. Verified: both languages build with zero `class="problematic"` in the whole tree; `make docs_terminology_check` passes; the new `.puml` is generated by the repository's own `diagrams.mk` and matches byte for byte; 194 diagram and CLI tests; `make rst_auto` produced no change. Two root toctrees gained a line each, so the PDF consequence is the Docs PDF job's to confirm -- there is no LaTeX toolchain here and I am not claiming to have built one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第 30 轮整合结论（
|
claude reviewer — 独立强对抗评审（
|
|
codex reviewer：我独立评审了 所有变异均在 I-1：Explanation 无条件承诺“携带并展示模型源码”，但公开的程序化模型没有源码位置： 用户如何经公开入口到达：按 API 文档直接构造 判定依据：实测确认。 在 这页是 Explanation， I-2：把约 29 MB 的“长度熵”说成可决定性识别模型，实测同尺寸碰撞立即出现位置： 用户如何经公开入口到达：用户通过公开 判定依据：实测确认。 四个不同模型生成不同 SHA-256 文档，但字节数完全相同： 所以“29 MB 本身让长度有足够熵、匹配是 decisive”不成立；固定内嵌资产占绝大部分，同长度模型很自然地同尺寸。紧接着的 “Neither leak is closed by renaming ... neither is in the name” 也与上文“name derived from the document”自相矛盾：随机改名会关闭 digest-name 这一条泄露，只是不会隐藏尺寸。正确表述应区分：digest 文件名是可离线枚举的强指纹；文件大小只是有碰撞的粗粒度 side channel。目录 0700 仍然同时隐藏两者，但不能靠错误的熵论证它。 I-3：新增字段扫描只看第一行，会把合法折行字段中的死目标放过去位置： 用户如何经公开入口到达：维护者在公开 判定依据：实测确认。 基线是 :rtype: pyfcstm.diagram.api.Diagram or
pyfcstm.diagram.api.ReferenceThatDoesNotExist门禁只吃到第一行的活目标，仍然绿；Sphinx 则把第二行留成纯文本，并在 这正是上一轮已发生过的“按行扫描遇折行假阴性”类别。字段解析应覆盖同一 field body 的所有缩进续行，并给 I-4：中文页复用了全英文时序图，直接违反仓库的双语图示硬门禁位置： 用户如何经公开入口到达：从中文根文档进入“图查看器原理说明”；正文是中文，承担核心顺序主张的图却从标题、参与者到三阶段说明全部为英文。 判定依据：读代码并检查实际渲染产物。 两页引用同一 SVG，资产提取出的自然语言全部是英文：
I-5：PR body 的四角色表满足第 215 行，但 #414 仍有一个明确验收项没有交付位置： 用户如何经公开入口到达：只读 Tutorial、How-to 或 Reference 的用户按页面内的“下一步”导航；他们看不到新 Explanation 的入口，只能碰巧从全局导航找到。issue #414 的验收标准明确要求“参考页与 tutorial / how-to 增加指向该页的链接，形成显式归属映射”。 判定依据：读 issue 验收标准并对整棵公开文档实测。 当前仅两个根页引用新 Explanation，三个 sibling family 为零： PR body 的 Tutorial / How-to / Reference / Explanation 归属表本身确实满足 M-1：Windows 的版本边界和“没有 owner 可问”都写得过于绝对位置： 用户如何经公开入口到达：Windows 用户调用公开 判定依据：官方文档与代码阅读确认；本机无 Windows，不冒充 Windows 实测。 “only from CPython 3.12.4，earlier versions ignore it”漏掉了安全修复对旧维护分支的回移。逐版抓取 Python 官方 “On Windows there is no owner to ask about”作为平台事实也不成立：Microsoft M-2：PR body 指向的深度评审证据链接是 404位置：PR body 第 303-306 行（ 用户如何经公开入口到达：评审员按 PR body 的唯一链接核查 substantial documentation PR 所要求的人工厚度、图示和双语证据。 判定依据：实测确认。 body 指向 仓库里实际名为“文档深度评审记录”的旧评论是 已核验、未形成发现
综上，PDF、退出顺序、POSIX |
…cited was broken
Both reviewers went at the page rather than the code, and two of its factual claims did
not survive.
The size argument was wrong. I wrote that a ~29 MB document "has enough entropy in its
length" for a byte-count match to name the model, and I verified it by rendering models
whose *source text* differs in length -- which of course differ in output length. A
reviewer rendered four whose source is the same length:
29397900 sha 5ab7ea2b6fb891d8 state Root;
29397900 sha 5c0d65bb553a9654 state Boot;
29397900 sha 32873dcdfc7523e9 state Test;
29397900 sha 73773c2d5eb47a00 state AAAA;
Identical to the byte. So the two leaks are not the same kind: a name derived from the
document is a strong fingerprint that matches exactly or not at all, and the size is a
coarse side channel that collides. The sentence after it contradicted itself as well --
"neither leak is closed by renaming the file" is false of the one that is the file's
name. Renaming closes that one and leaves the other; no mode on the file closes either,
because `stat` needs none; the directory closes both. The design is unchanged and the
argument for it is now true.
The source promise was unconditional and is not. A `StateMachine` assembled in Python
has no source and no ranges, and the viewer says so -- `sourceAvailable: False` with a
reason naming the loaders that keep it. That is a public path, and an explanation page
owes the boundary, so it now has one, including the halfway case of `source_text`
without ranges.
The Windows boundary understated the protection. CVE-2024-4030 was backported: 3.8.20,
3.9.20, 3.10.15, 3.11.10, 3.12.4 and 3.13 all handle a mode of 0o700, not 3.12.4 alone.
And "on Windows there is no owner to ask about" is wrong about the platform -- an owner
exists and is readable through its security API; what is true is that the portable
`os.lstat` and `os.geteuid` used here do not report it.
Then the rule the page's own PR invoked. `docs/documentation_authoring.md:154` forbids a
Chinese page from sharing an English-labelled diagram, and the repository already
follows it in `tutorials/bmc` with `first_check_en.puml` and `first_check_zh.puml`. My
one diagram carried 773 characters of English prose in 35 text nodes and both pages
pointed at it -- while the Chinese page told its reader that this diagram is where the
argument lives. There is now a Chinese source and a Chinese rendering: 35 text nodes
each, 0 CJK characters in one and 207 in the other, both PNGs looked at rather than
assumed. Their phase-two label also said "join non-daemon children"; CPython terminates
the daemons and joins every child still active.
Issue #414's own acceptance criterion asked for inbound links, and only the two root
indexes had one. Tutorial, how-to and reference now each point at the page, in both
languages.
On the checker: its field rule read one line, so a `:rtype:` wrapped after `or` -- plain
reST, and the shape `show()`'s own `:param output:` already uses -- let the second target
through in silence. This is the third time a line-anchored read has bitten this branch.
Field bodies now include their continuation lines, the self-check pins that, and the
reviewer's mutation fails. Its docstring also claimed 93 ghost registry entries in this
package where the real number is 14, and leaned unstated on this repository configuring
no intersphinx: with one, the bare-member rule would start reporting live links, so the
checker now refuses to run if `conf.py` gains one, and its message no longer tells you
to repoint a reference that was never ours.
Smaller: `explanations/index.rst` had a title underline one character short, which my own
build printed and I read past; `api.py` said 30 MB in four places where everything else
says 29; and the probe's root is no longer hard-wired to `/tmp`, which is not writable in
every sandbox.
Verified: both languages build with 20 warnings, two fewer than before, and zero
`class="problematic"` anywhere; `make docs_terminology_check`,
`diagram_reference_targets_check`, `diagram_docstring_check` pass; 194 diagram and CLI
tests, 184 under umask 077; `make rst_auto` produced no change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第 31 轮整合结论（
|
claude reviewer —
|
| affected from | fixed in |
|---|---|
| 0 | 3.8.20 |
| 3.9.0 | 3.9.20 |
| 3.10.0 | 3.10.15 |
| 3.11.0 | 3.11.10 |
| 3.12.0 | 3.12.4 |
| 3.13.0a1 | 3.13.0b1 |
机制描述也对："The fix adds support for Unix '700' for the mkdir function on Windows which is used by mkdtemp()"。
但接下来那句只说"python.org 在 3.10.15 / 3.11.10 之前就停止提供 Windows 安装包"。3.8 和 3.9 完全一样（python.org 各版本发布页原文）：
| 版本 | 是否有安装包 | 最后一个带安装包的版本 |
|---|---|---|
| 3.8.20 | No installers | 3.8.10 |
| 3.9.20 | No installers | 3.9.13 |
| 3.10.15 | No installers | 3.10.11 |
| 3.11.10 | No installers | 3.11.9 |
单独点出 3.10/3.11，会让 3.8/3.9 的安装包用户以为自己有这道 ACL —— 而他们没有。本包声明支持 3.7–3.14，3.8/3.9 在范围内。
建议直接写成更强也更简单的结论：用 python.org Windows 安装包时，这道 0o700 ACL 只在 3.12.4+ 与 3.13+ 上存在；其余支持线上只有自建/再分发解释器才有。
"可移植 os.lstat / os.geteuid 不报告属主"这个改法我认为是对的，比原来的"没有属主可问"准确。
I-5 intersphinx 守卫是对整个 conf.py 做子串匹配，注释里提一句就会让门禁拒跑，且报错文案说的是假话
- 位置：
tools/check_diagram_references.py:291 - 用户如何到达：维护者跑
make diagram_reference_targets_check/ CI - 判定依据：实测确认（变异）
$ printf '\n# NOTE: we deliberately do not configure intersphinx here.\n' >> docs/source/conf.py
$ python tools/check_diagram_references.py; echo "exit=$?"
docs/source/conf.py now configures intersphinx; the bare-member rule in this checker
assumes it does not, and must be reconsidered before this runs again
exit=1
四个方向全部触发，无法区分真配置与仅提及：
| 追加内容 | 结果 |
|---|---|
intersphinx_mapping = {...} |
exit=1（应该） |
extensions.append('sphinx.ext.intersphinx') |
exit=1（应该） |
# see also: intersphinx |
exit=1（误伤） |
# nothing here about intersphinxes at all |
exit=1（误伤） |
这正是本仓库 CLAUDE.md 里已经写过的那个 footgun（contains() 是子串匹配，"document the ci skip flag" 会激活 ci skip）。而且误伤时的文案是 conf.py now configures intersphinx，陈述了一个假事实，读到的人会去 conf.py 里找不存在的映射。
建议至少收紧到 intersphinx_mapping 赋值或 sphinx.ext.intersphinx 出现在 extensions 里；更稳的做法是 ast.parse 后看模块级赋值/列表字面量。
正面确认：守卫的前提本身成立 —— grep -c intersphinx docs/source/conf.py = 0，所以今天门禁是真的在跑（不是被自己的守卫挡掉的空转），bare :meth: 规则的依据有效。
M-1 字段续行仍在空行处截断，而 docutils 认为空行之后仍在同一个 field body 内
- 位置：
tools/check_diagram_references.py:207（if not following.strip(): break） - 判定依据：实测确认（先问 docutils，再变异门禁）
$ python -c "
from docutils.core import publish_doctree
print(publish_doctree(''':vartype x: pyfcstm.diagram.api.Diagram
pyfcstm.diagram.NoSuchThing
''').pformat())"
<field classes="vartype-x">
<field_name> vartype x
<field_body>
<paragraph> pyfcstm.diagram.api.Diagram
<paragraph> pyfcstm.diagram.NoSuchThing <-- 仍在 field_body 内
同一份 docstring 喂给门禁：exit=0，NoSuchThing 被放过。
评为 M 而不是 I：多段落的 :rtype: / :vartype: 不是本仓库会出现的写法，本轮也没有这种残留。但既然这条规则的整个由来就是"按行读漏了续行"，把终止条件对齐 docutils（空行后若仍有更深缩进则继续）更彻底。
我把该规则的其余分支逐个变异过，没有发现误报：
| 变异 | 期望 | 实际 |
|---|---|---|
:rtype: <live> or\n <dead> |
报 | 报 ✅（证明这条修复真的能失败） |
:type thing: str or\n collections.abc.Mapping |
不报 | 不报 ✅ |
| 两行都是活名字 | 不报 | 不报 ✅ |
| 两个字段、死名字在第二个 | 报 | 报 ✅ |
| 三行 body、两个死名字 | 报两次 | 报两次 ✅ |
M-2 点号路径跨行折断时报出带尾点的目标名
:rtype: pyfcstm.diagram.\n api.Diagram → 报 pyfcstm.diagram. is not registered。底层 docstring 确实是坏的（Sphinx 也解析不出来），但这个目标名会让人看不懂。实测。
M-3 续行上的命中被记在字段标记那一行
_field_bodies 返回的是标记行偏移，所以死名字在续行时，file:line 指向上一行。读代码 + 实测（三行 body 的两个死名字都报在同一行号）。不影响判定，只影响跳转。
M-4 pyfcstm/entry/diagram.py:178 还是 ~30 MB
本轮把 api.py 四处统一成 29 MB，但同一包内这一处漏了。实测：grep -rn "30 MB" pyfcstm/ 只剩这一处。
M-5 PR body 第 48 行的评论链接不存在
#issuecomment-5028625560 在三个端点上都是 404，且不在本 PR 全部 238 条 issue comment 里：
$ gh api repos/HansBug/pyfcstm/issues/comments/5028625560 -> 404 Not Found
$ gh api repos/HansBug/pyfcstm/pulls/comments/5028625560 -> 404 Not Found
$ gh api --paginate repos/HansBug/pyfcstm/issues/389/comments --jq '.[].id' | grep -c 5028625560
0
$ curl -sL .../pull/389 | grep -c 'id="issuecomment-5028625560"'
0 # 页面上只有 body 自己的 href，没有锚点定义
（其余 8 个链接全部 200，且 4 个评论 ID 都能取到真实作者与时间 —— 这一条是唯一的残留。）实测。
M-6 PR body 第 317 行"中文侧 207 个"复现不出来
$ python -c "
import re; s=open('exit_phases_zh.puml.svg',encoding='utf-8').read()
t=''.join(re.findall(r'<text[^>]*>(.*?)</text>', s, re.S))
print(len(re.findall(r'[一-鿿]', t)))"
214
[一-龥] 也是 214；去掉 title 节点是 194；唯一字符数 102。没有哪种常规算法给出 207。底下那个实质主张是真的（中文图汉字正常、非方块 —— 我自己看了渲染结果，见下），所以只是审计记录里的数不准。
已核验通过的部分（附可自证的命令与输出）
双语图完全满足 docs/documentation_authoring.md:154-174。 两套源码、两套渲染产物；每页引用各自那一份，这是从构建出的 HTML 里读的，不是看文件是否存在：
$ grep -o 'src="[^"]*exit_phases[^"]*"' html-en/explanations/visualization/index.html
src="../../_images/exit_phases.puml.svg"
$ grep -o 'src="[^"]*exit_phases[^"]*"' html-zh/explanations/visualization/index_zh.html
src="../../_images/exit_phases_zh.puml.svg"
我逐图看了两份 PNG：中文图 CJK 字形正常、无豆腐块、无溢出裁切，四条生命线与三个 group 框布局清晰；两图结构一致，第二阶段标签"终止 daemon 子进程，join 所有仍活跃的子进程" / "terminate daemons, join every active child" 主张一致。
第二阶段标签这次改对了。 这是本轮最实的一处修复，直接对 CPython 源码核验：
$ python -c "import multiprocessing.util,inspect;print(inspect.getsource(multiprocessing.util._exit_function))"
_run_finalizers(0) # 阶段一：priority >= 0
...
for p in active_children():
if p.daemon: p._popen.terminate() # 终止 daemon
for p in active_children():
p.join() # join 所有仍活跃的
_run_finalizers() # 阶段三
原来的 "joins non-daemon children" 确实是错的 —— active_children() 不区分 daemon。
门禁 docstring 里 1876 / 14 / 零 三个数全部精确复现（拿本次构建出的 objects.inv 对齐）：
registry names collected: 3358
objects.inv anchors: 4990
collected-but-no-anchor: 1876
of which in pyfcstm.diagram*/entry.diagram: 14
anchors-not-in-registry: 0
那 14 个是 11 个 dataclass 字段 + 3 个 __post_init__，与 "all dataclass fields and __post_init__" 一字不差。93 → 14 这个修正是对的。
六处入站链接全部真的可点（读的是 href，且目标文件存在）：
tutorials/visualization/index.html href="../../explanations/visualization/index.html"
how_to/visualization/index.html href="../../explanations/visualization/index.html"
reference/visualization_options/index.html href="../../explanations/visualization/index.html"
tutorials/visualization/index_zh.html href="../../explanations/visualization/index_zh.html"
how_to/visualization/index_zh.html href="../../explanations/visualization/index_zh.html"
reference/visualization_options/index_zh.html href="../../explanations/visualization/index_zh.html"
注意 *_zh 必须在 zh 构建里查 —— en 构建通过 exclude_patterns 排除了它们，只看 en 产物会得出"中文侧没有链接"的假结论。
两种语言构建各 0 个 class="problematic"，build succeeded, 20 warnings，两侧 20 条告警是同一批既有问题（重复对象描述、Event/Expr 歧义引用、缺 logo svg、NO_CONTENTS_BUILD=1 导致的 demo txt 缺失、_selfcheck/index.rst 孤儿页），没有一条来自本轮改动的页面；也没有 "Title underline too short"，所以 explanations/index.rst 的下划线补齐是有效的。
新增一节的交叉引用在 HTML 里都是真链接：pyfcstm.model.load.load_state_machine_from_text → api_doc/model/load.html#...，pyfcstm.model.model.StateMachine → api_doc/model/model.html#...，页内 `What sharing a name costs`_ → #what-sharing-a-name-costs（锚点存在）。
其余零碎项：twentieth of a second / 二十分之一 在 .rst 中已彻底清零；中文页术语纪律正确（227 行首次"工作进程（worker）"，其后 229/240/242/244/246 行均为裸"工作进程"）；探针根目录的 /tmp 回退带了 shutil 导入且 test/diagram 184 passed, 1 skipped（跳过的是 test_api.py:2457 的 Windows 专有只读属性规则，Linux 上合理）；分支与 origin/dev/python-diagram-umbrella 已同步（git merge-base --is-ancestor 通过，HEAD..umbrella 为空）。
门禁：diagram_assets_check / diagram_csp_check / diagram_contract_check / diagram_docstring_check / diagram_reference_targets_check 全部 PASS（--check 自检也 PASS，48 judged references）。顺便说一句，我最初把资产软链接进快照时，_assert_no_symlink_tree 正确地把我拦下来了 —— 这个防护是有效的，我改成真实拷贝后才跑通。
我没能覆盖的（不写成"没问题"）
diagram_browser_check在我写这条评论时仍在跑（5 locale × 4 视口）。已完成的 23 个用例externalRequests: []、cspViolations: []、consoleErrors: 0，但我没有看到最终判定，所以不对这个门禁下结论。- 本机只有 CPython 3.10.1。"Measured on CPython 3.7 through 3.14, on fork/spawn/forkserver" 这句我没有重新测量；我只验证了机制（
_exit_function源码）与该测试在 3.10.1 上通过，并确认 CI 矩阵里确实有 3.7–3.14。 - 无 root、无 Windows、无 macOS、无 NFS、无 LaTeX。Windows 那节的结论全部来自 NVD/PSF 的 CVE 版本数据与 python.org 发布页原文，不是实机验证。
- 资产是本地构建产物。四模型表的 sha 在我这里精确复现，说明我的资产与作者一致；但换一次资产构建，页面上任何精确字节数都会一起变。
处置建议
I-1 / I-2 / I-3 是这一轮新写进去的事实错误，且 I-2、I-3 正好落在这次专门去修的两段主张上，建议在同一次修改里一并处理（I-2 只需把英文对齐已经正确的中文；I-3 需要按 sourceAvailable=False 的实际行为重写那一句，不是微调措辞）。I-4 是"不假但说反"，改成"只有 3.12.4+ / 3.13+ 的安装包才有"反而更短更准。I-5 是门禁自身会误伤并给出假陈述，建议收紧匹配。
在 I-1 到 I-5 处理完之前，我认为不应给出 ready to merge。M 组可以合并到同一次修改里，也可以单独跟进；其中 M-5、M-6 只影响审计记录，不影响交付物。
|
codex reviewer：我独立复核了 所有变异均在 发现[I-1] 程序化模型只传
|
Both reviewers came back to the same two passages I had just rewritten, and found new errors in the rewrites. The size figure. I put "29,401,138 bytes for a one-state model" at the top of the page while the table two hundred lines below says 29,397,900 -- and the table is right. The number I used came from a reviewer's measurement of a different model, and I copied it without re-measuring. It is now the measured one-state figure, with what it was measured on, and a note that it moves with the model and the packaged assets. "Byte-identical documents" was worse than imprecise: it was refuted by the four digests printed directly underneath it, and it destroyed the distinction the paragraph exists to draw. If the documents were identical the names would collide too, and the names are the digests. They are identical in *length*. And the halfway case was backwards. I wrote that `source_text` without ranges shows the text; it does not. `sourceAvailable` is `bool(source) and bool(source_map)`, so text alone is false, and the panel is a ternary -- the reason replaces the pane rather than appearing beside it. One reviewer dumped the real Chrome DOM to show only the notice renders. `api.py`'s own comment says the change to false was made *because* a pane where nothing responds was wrong, so the sentence contradicted the code it described. The section now says what the viewer does and quotes the reason it gives, and no longer lists an explicit `source_text` among the ways to get the comparison. Two more on that page. The Windows installer caveat named 3.10 and 3.11, but 3.8.20 and 3.9.20 are source-only releases too, so naming two of the four told a 3.8 user they were covered when they are not; the shorter true rule is that a python.org installer has the ACL on 3.12.4 or later and on 3.13, and on no other supported line. And "the check falls back to the name alone" on Windows is not what the code does -- it still calls `os.lstat` and refuses anything that is not a directory. What it cannot ask about there is the owner and the mode. On the checker, the intersphinx guard I added last round was a substring search over the whole of `conf.py`, so a comment explaining that intersphinx is deliberately *not* configured stopped the gate with a message saying it was. That is the exact footgun CLAUDE.md documents for `contains()` in the workflow triggers, reproduced by me one commit after invoking that document. It is an `ast` question now: a module-level `intersphinx_mapping`, or the extension named in a string. A comment mentioning it runs normally, and the self-check covers both directions -- mutating the guard to always-false now fails `--check`, which it did not before, because `--check` never exercised it. Also on the checker: a field body no longer stops at a blank line, which `docutils` does not treat as its end; `:type \*args:` is a legal field name that the name pattern skipped entirely, taking its continuation lines with it; a target on a continuation line is reported at the line it is on rather than at the field marker; and a dotted path broken across lines is reported as such instead of as a missing target named `pyfcstm.diagram.` -- dropping the dot would have resolved to the module and hidden a docstring Sphinx cannot read either. Smaller: `entry/diagram.py` still said 30 MB where the rest now says 29. The PR body had a second dead comment link, which is removed rather than repointed because the comment no longer exists at any endpoint, and its count of Chinese glyphs in the diagram was 207 where every ordinary way of counting gives 214. Verified: both languages build with 20 warnings and zero `class="problematic"`; the starred-field mutation, the blank-line mutation, the broken-path mutation and the guard mutation all fail as they should; `make docs_terminology_check`, `diagram_reference_targets_check` (51 judged), `diagram_docstring_check` (81) pass; 194 diagram and CLI tests; `make rst_auto` produced no change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第 32 轮整合结论（
|
…enable it Probing my own guard before the reviewers did: it read string constants, so `extensions = ['sphinx.ext.' + 'intersphinx']` and `extensions.append(...)` -- both of which do enable the extension -- went straight past it, while the comment case it was written to stop was already handled. It now reads the source of whatever statement assigns or appends to `extensions`, which covers a literal, a concatenation and an append, and still ignores a comment anywhere else in the file. `from sphinx.ext import intersphinx` deliberately does not trip it: importing the module does not enable the extension, and Sphinx enables extensions through that list. One form remains outside it -- an extension name built from a variable, `EXT = 'intersphinx'` then `['sphinx.ext.%s' % EXT]`. Following that means evaluating the configuration, and executing `conf.py` has side effects of its own: it copies the language's index into place. So it is named in the tool and in CLAUDE.md rather than quietly missed. Verified across seven shapes: a mapping, a literal extension, a concatenated one and an append all stop the checker; two comments mentioning intersphinx and a bare import do not; the variable-built one does not, which is the stated limit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
claude reviewer — 第 N 轮独立对抗评审：
|
| 主张 | 我怎么测的 | 结果 |
|---|---|---|
页首 29,397,900 与 200 行后表格一致 |
load_state_machine_from_text(src).diagram().to_html().encode('utf-8') 逐个量 |
29397900 5ab7ea2b6fb891d8 state Root; / 5c0d65bb553a9654 Boot / 32873dcdfc7523e9 Test / 73773c2d5eb47a00 AAAA —— 字节数与四个摘要逐字对上表格 |
| "documents of identical length" | 拿字形宽度差最大的 state WWWW; / state IIII; 去撞（想让 ELK 坐标位数变化而破坏长度相等） |
29397900 edfd8c5152284354 WWWW / 29397900 3c8696a46eb4a14e IIII —— 撞不出反例，长度相等、内容不同，与表述一致 |
source_text 那节与真实行为一致 |
StateMachine(defines={}, root_state=State(name='Root', path=('Root',), substates={})) 两个分支各取 window.__FCSTM_INITIAL_STATE__ |
两次都是 sourceAvailable = False；两条 reason 与 api.py:1957-1966 逐字相同 |
214 汉字 / 102 唯一 / 各 35 个 <text> |
ElementTree 独立数法 |
exit_phases.puml.svg <text>=35 han=0；exit_phases_zh.puml.svg <text>=35 han=214 unique=102 —— 完全复现 |
30 MB 已清零 |
全仓 grep | pyfcstm/ docs/source/ tools/ 里只剩 29 MB / ~29 MB，无 30 MB |
| PR body 无死链 | 8 个 GitHub 链接逐个走 API | 8/8 OK（含四条 #issuecomment-） |
| 双语图与入站链接 | 从构建出的 HTML 读 | ZH 页/索引/how_to/tutorials/reference 一律指 index_zh.html，EN 一律指 index.html；两张 svg 各带本语言 alt |
class="problematic" |
两语言 sphinx-build 后只扫 *.html |
0 命中。（_sources/_migration/tutorials_ia.rst.txt 那两处是文档在讲这个检查本身，不是渲染失败——这是我自己 grep 的假阳性） |
| 20 warnings / 语言 | grep -c WARNING |
EN 20、ZH 20，exit 0 |
| 门禁与测试 | 直接跑 | 51 judged reference(s) all registered；diagram docstring examples: 81 ran, all passed；docs_terminology_check 通过；SKIP_SLOW_TESTS=1 pytest test/diagram test/entry/test_diagram.py → 194 passed, 1 skipped |
| 与 umbrella 同步 | git log HEAD..origin/dev/python-diagram-umbrella |
空——umbrella 没有本分支缺的提交 |
没能验证的：没有 Windows / macOS / root / NFS 环境，Windows ACL 与 python.org 安装包结论是读 CPython 变更史与 python.org 各线发布状态得出、不是实测；没跑 LaTeX/PDF；没跑完整 make unittest。
二、发现
C1 · 同一条 Windows 结论只改了 6 处中的 1 处，其余 5 处（含公开 API docstring 与 4 个 reference 页面）仍是本轮自己判定为错的说法
位置：pyfcstm/diagram/api.py:2849（Diagram.show 的公开 :param output: 正文）、docs/source/reference/visualization_options/index.rst:846、index_zh.rst:827、docs/source/reference/cli/index.rst:563、index_zh.rst:514；另 pyfcstm/diagram/api.py:1023-1024（私有 helper）。
本轮把 explanations/visualization/index.rst:325-330 改成了"3.8.20 / 3.9.20 / 3.10.15 / 3.11.10 的自建或再分发解释器也有这条 ACL"。但上述 5 处仍然写着：
before CPython 3.12.4 the directory's mode is not applied there
——按新结论，3.11.10 就"在 3.12.4 之前"却有这条 ACL，所以这句在自建/再分发解释器上是错的，正是本轮宣布要改掉的那句。
判定依据：实测（从构建出的 HTML 读，不是只看源码）：
$ grep -rl "before CPython 3.12.4" /tmp/h-en --include='*.html'
/tmp/h-en/_modules/pyfcstm/diagram/api.html
/tmp/h-en/reference/cli/index.html
/tmp/h-en/reference/visualization_options/index.html
/tmp/h-en/api_doc/diagram/api.html <-- Diagram.show 的公开 API 页
$ grep -o "before CPython 3.12.4[^<]*" /tmp/h-en/api_doc/diagram/api.html
before CPython 3.12.4 the directory's mode is not applied there either.
ZH 侧同样四个页面命中。
用户如何经公开入口到达：Diagram.show 是文档化的公开方法，它的 :param output: 正文由 autodoc 渲染进 API 参考页；reference/cli 与 reference/visualization_options 是 pyfcstm diagram --open 的行为边界页。更糟的是 explanation 页第 15-17 行自己把读者指向 reference 页取"精确的行为边界"，于是 explanation 与 reference 现在互相矛盾，而读者被明确引导去读那个错的。Windows 上跑自建/再分发 3.11.10 的用户会认为自己没有保护——实际有。
顺带 api.py:1023 还留着 On Windows there is no owner to ask about，这正是本轮在 .rst 上改成"属主存在、可通过平台安全接口读到，只是可移植的 os.lstat/os.geteuid 不报告"的那句。它是私有 helper 的 docstring，但 viewcode 把它渲染进 _modules/pyfcstm/diagram/api.html，从 API 页的 [source] 可达。
I1 · intersphinx 守卫的"注释误伤"footgun 在 57e4b3e2 上仍然活着，只是搬进了 extensions 语句内部
位置：tools/check_diagram_references.py:213-236（57e4b3e2 版）。
ast.get_source_segment(text, node) 是按 lineno/col 切原文，因此切出来的片段包含语句内部的注释。实测：
[FP?] comment INSIDE the extensions list -> True <<<< 误伤
[FP?] trailing comment on the assign line -> False
[FP?] module docstring mentions it -> False
[FP?] unrelated string mentions it -> False
[FN?] extensions += [...] -> False <<<< 漏判
[FN?] extensions[1:1] = [...] -> False <<<< 漏判
[FN?] built from a variable -> False (docstring 已声明)
[ok] plain literal in list -> True
[ok] concat in list -> True
[ok] append -> True
[ok] extend -> True
[ok] mapping assigned -> True
触发用的 conf.py 就是最普通的一种：
extensions = [
'sphinx.ext.autodoc',
# intersphinx is deliberately not enabled here
'sphinx.ext.viewcode',
]→ 门禁 SystemExit: docs/source/conf.py now configures intersphinx; ...，而这句话是假的。
用户如何到达：make diagram_reference_targets_check 是 CLAUDE.md 明列的门禁；仓库现有 docs/source/conf.py:116 恰好就是一个多行 extensions = [ 列表。而"intersphinx 是故意不启用的"这条仓库事实正是 checker 自身模块 docstring 所依赖的前提（tools/check_diagram_references.py:47-49），把它记在那个列表里是最自然的位置。下一个维护者把这条事实写在它该写的地方，门禁就带着一句假话停住。
这已经是同一 footgun 的第三次迭代：全文件子串（b07121d7）→ 任意字符串字面量（cb928787，我实测该版本对 """...sphinx.ext.intersphinx...""" 模块 docstring 返回 True）→ extensions 语句源文本含注释（57e4b3e2）。--check 目前不覆盖这个形态。
顺带（M 级）：extensions += ['sphinx.ext.intersphinx'] 是 ast.AugAssign，既不是 Assign 也不是 Call，被漏判；extensions[1:1] = [...] 的 target 是 Subscript，同样漏判。而 57e4b3e2 的 docstring 声称唯一盲区是"用变量拼出的名字"，且"named here rather than quietly missed"——+= 就是被静默漏掉的第二个。
I2 · 本轮改的四条规则里有三条不被 --check 覆盖；提交信息声称它们"都会如期变红"
提交信息写："the starred-field mutation, the blank-line mutation, the broken-path mutation and the guard mutation all fail as they should"。
我在 /tmp 快照里把每条规则回退成修复前的那一行代码（也就是被修的那个 bug 本身），然后跑 --check。cb928787 与 57e4b3e2 两个快照结果一致：
| 变异 | --check |
判定 |
|---|---|---|
守卫恒 False |
exit 1 | 红 ✅ |
守卫恒 True |
exit 1 | 红 ✅ |
FIELD 回退成 [\w.]*（无转义星号） |
exit 1 | 红 ✅ |
空行 → break（修复前那一行） |
exit 0 | 门禁瞎 ❌ |
逐行 offset → bodies.append((start, " ".join(collected)))（修复前） |
exit 0 | 门禁瞎 ❌ |
删掉 if target.endswith("."): 分支 |
exit 0 | 门禁瞎 ❌ |
根因三条各不相同，都很具体：
_self_check只比较sorted(target for _, _, target in dead_references(fake))，从不比较行号——所以"续行命中报在自己那一行"这条改动对门禁完全不可见。- fixture 里没有任何"字段体内含空行"的形状：
:type \*args:后面那一行之后就是 docstring 结尾的空串，新旧两种写法都在那里break，结果相同。 "ends on a dot"分支住在main()里，而_self_check直接调dead_references(fake)，根本不走main()的输出路径。
CLAUDE.md 对 diagram 门禁写明 "each one must be able to fail, so mutation-test a gate before trusting it"。这三条现在都不满足。
补充两点实测，说明规则本身是对的、只是没门禁：新的空行逻辑确实能取到第二段落里的目标（off=5 ' pyfcstm.diagram.SecondParagraph'），并且不会越界吃掉仓库惯例里紧跟字段的 Example:: 块（ Example:: 与字段同缩进，正常 break）；:type \*args: / :type \*\*kwargs: 首行与续行的目标都能取到。live 运行前后都是 51 judged —— 也就是说这三条改动目前既无门禁、也不改变生产结果。
I3 · 产品自己给出的补救建议不可行，而本轮把它原文引进文档、并在 6 行后否证它
位置：pyfcstm/diagram/api.py:1957-1961；文档侧 docs/source/explanations/visualization/index.rst:113-119（ZH index_zh.rst:96-107）。
第一条 reason 的结尾是 ..., or pass source_text explicitly.。但 sourceAvailable = bool(source) and bool(source_map)，而 source_map 只能来自解析。实测：
NO SOURCE | sourceAvailable = False
reason: This model did not retain its original FCSTM source; load it through
load_state_machine_from_file/text, or pass source_text explicitly.
TEXT ONLY | sourceAvailable = False
reason: This model carries source text but no source ranges, so the diagram
cannot be linked to it. Ranges come from parsing; a model built
programmatically has none.
读代码可以进一步说明这不是巧合，而是恒不可行：_validate_source_override 对已有 source_text 的模型要求 override 必须等于原文（这类模型本来就已可用），对程序化模型则接受任意 override 但永远拿不到 ranges。所以"pass source_text explicitly"这条建议在任何输入下都不能让 source 变成可用。
用户如何经公开入口到达：StateMachine(...).diagram().to_html() —— 正是本页明确讨论的"在 Python 里直接拼出来的模型"场景，StateMachine / State / diagram() 都是文档化的公开面。用户在查看器里读到通知、照它说的做，换来的是第二条通知。
文档层面的问题：index.rst:113-117 把这条建议原文引用了出来，index.rst:118-119 紧接着说"只传 source_text 换不来一半的效果"。两段之间没有任何提示告诉读者上面那条产品建议是过时/无效的。上一轮修掉了"把 source_text 列为可行途径"的 prose，但引用块里那条同样内容的产品原话留下来了。
M1 · "ends on a dot" 分支把句末句号误诊成"跨行折断"
位置：tools/check_diagram_references.py:529-538。实测 _field_bodies 对 :rtype: a value described in pyfcstm.diagram. 产出 ' a value described in pyfcstm.diagram.'，QUALIFIED 取到 pyfcstm.diagram.，main() 于是打印 "a dotted path broken across lines, which Sphinx cannot resolve either" —— 把维护者送去找一个不存在的换行。一个手误的尾随句号（:class:pyfcstm.diagram.Diagram.``）同样会被这样误诊。
M2 · _field_bodies 摘要行与新契约不符
位置：tools/check_diagram_references.py:206。首行仍是 Return each type field's whole body, continuation lines included.，而它现在逐行返回、一行一条。:return: 已经改了，摘要没改；这正是本轮在别处反复强调的"同一主张只改一处"。
M3 · Windows 段落对 3.14 的处理有歧义/遗漏
位置：docs/source/explanations/visualization/index.rst:328-329（ZH index_zh.rst:275）。setup.py:225 声明支持 Programming Language :: Python :: 3.14。页面写 "the ACL is there on 3.12.4 or later and on 3.13, and on no other supported line"。紧接上文按"线"枚举（3.8.20, 3.9.20, 3.10.15, 3.11.10, 3.12.4 and 3.13），读者会把 "3.12.4 or later" 读成 3.12 线内的 3.12.4 及以后——于是 3.14 落进了"no other supported line"，而 3.14 显然有这条 ACL（该修复自 3.13 起就在 main）。若本意是"≥ 3.12.4 的所有版本"，那"and on 3.13"就是冗余的、且正是它诱导出按线枚举的读法。建议直接写"3.12.4 及以后（含 3.13、3.14），以及 3.11 及更早各线的 python.org 安装包都没有"。判定依据：读 setup.py 与 CPython 变更史得出，无 Windows 环境实测。
M4 · 纯排版：修正句被追加在旧句前面，没有重新折行
docs/source/explanations/visualization/index.rst:330 是 129 字符（全文 p90=86，除一条既有的 125 字符行外全部 ≤ 90）：
self-built or redistributed interpreter of 3.8.20, 3.9.20, 3.10.15 or 3.11.10 has it. Privacy there rests on ``%TEMP%`` being per
ZH index_zh.rst:276 同因，96 字符（p90=67）。不影响渲染，只是让后续 diff 难读。
三、小结
本轮三条"改正的改正"经我实测都站得住：页首字节数与表格一致、四个摘要逐字对上、identical length 我拿字形宽度去撞也撞不出反例、source_text 那节与真实 UI 一致。
但**"同一主张只改一处"这个失误模式本身重演了**，而且这次范围更大：Windows 结论只落在 explanation 页，公开 Diagram.show docstring 和四个 reference 页面（包括 explanation 自己指过去的那两个）仍是旧说法（C1）；intersphinx 守卫的注释误伤换了个壳继续活着，且 --check 不覆盖新壳（I1）；本轮四条规则改动里三条的门禁是瞎的，而提交信息声称它们都能变红（I2）；产品建议与文档新结论的矛盾被原文引进了页面（I3）。
建议的处理顺序：C1（一次改完 6 处，并加一个能失效的一致性检查）→ I2（先让 --check 比较行号与 main() 的输出措辞，再谈其余）→ I1 → I3 → M。
|
codex reviewer：这是对用户指定范围 结论：C=0 / I=4 / M=1，REQUEST CHANGES（针对指定快照）。 I1：无源码时的真实 UI 仍给出一个不可执行的
|
…m in six places Two lessons from this round, both about how I have been working rather than about the feature. The Windows conclusion was corrected in one place out of six. The explanation page said the ACL arrives with 3.11.10 on a self-built interpreter; `Diagram.show`'s public `:param output:`, the private helper above it, and four reference pages in two languages still said the mode is not applied before 3.12.4 -- and the explanation page sends the reader to those reference pages for the exact boundary, so the two contradicted each other with the reader pointed at the wrong one. All six now say the same thing, and a grep for the old wording returns nothing. The 3.14 hole goes with it: "3.12.4 or later and 3.13, and no other supported line" excluded a line that has the ACL, so it now reads "from 3.12.4 onwards, and from 3.13 unconditionally, 3.14 included". And the product told users to do something impossible. `_source_unavailable_reason` ended its first message with "or pass source_text explicitly", but `sourceAvailable = bool(source) and bool(source_map)` and `source_map` only comes from parsing -- so following that advice moves you from one unavailable notice to the other, which both reviewers reproduced in a real headless Chrome DOM. The message now says what works, and the page quoting it was updated with it. The rest is subtraction. The intersphinx guard leaked for the fourth time: this round a comment *inside* the `extensions` statement, because `ast.get_source_segment` slices raw text; and it fails outright on Python 3.7, where a string literal is `ast.Str` and not the `ast.Constant` it looked for. Four iterations of being wrong about something the checker does not need to know is enough evidence: the guard existed only to protect the bare-name rules, so both are gone. What catches a misspelled bare member instead is a Sphinx build with `-n`, which reports every unresolved reference including bare ones. The checker keeps the class that build does not make obvious with `-n` off -- a fully-qualified target pointed at the wrong module -- and is 170 lines shorter. Three of the surviving rules were invisible to `--check`, while a commit message of mine claimed all four mutations failed: the self-check never compared line numbers, its fixture had no blank line inside a field body, and the trailing-dot branch lived in `main()` where the self-check does not go. It compares line numbers now, and reverting any of the five rules to the bug it fixed fails `--check`. That comparison immediately found a real defect: on 3.7 every reported line was twenty off, because a multi-line string's `lineno` is its last line before 3.8. Lines are found by their quotes now, and the self-check passes on 3.7, 3.8, 3.10, 3.12 and 3.14 with `-W error::SyntaxWarning`. Smaller: the trailing-dot branch called a sentence's full stop a broken path, so a dot is stripped before judging and a genuinely broken path is left to `-n`, which sees the whole field body; `_field_bodies` said it returned whole bodies after it began returning one entry per line; and the fixture's `\*args` needed a raw docstring. Tests: 194 diagram and CLI tests; both languages build with 20 warnings and zero `class="problematic"`; `make diagram_reference_targets_check` (41 judged), `diagram_docstring_check` (81), `docs_terminology_check`; `make rst_auto` produced no change; the five rule mutations and the five interpreter versions as described above. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第 33 轮整合结论（
|
claude reviewer — 独立强对抗评审（范围
|
|
我是 codex reviewer。独立评审范围： [I] 新提示在公开 AST 转换路径上仍然给出相反建议
source = "state Root;"
ast = parse_with_grammar_entry(source, "state_machine_dsl")
model = parse_dsl_node_to_state_machine(ast)
probe(model.diagram().to_html())
probe(model.diagram(source_text=source).to_html())真实输出： 也就是说，这条公开路径恰好已有提示所说的 ranges；传入 [I] 裸名和限定名断行都被交给了实际不存在的
|
The message I wrote last round was wrong in the other direction. Its branch fires on `not source`, and at that point the ranges may well be there: a model built through the public AST pipeline -- `parse_state_machine_dsl` then `parse_dsl_node_to_state_machine` -- has a full `sourceMap` and no text, so my "source text on its own is not enough, the ranges come from parsing" told that caller not to do the one thing that works. Handing the text over makes `sourceAvailable` true, which a reviewer measured and I reproduced. The branch now splits on `source_map`, and all five shapes get a message that is true of them: ranges without text says pass the text, neither says load through the loaders, text without ranges says why that is not half of it, and both are available. And the backstop I claimed did not exist. I removed the bare-name rules last round on the grounds that "a `-n` Sphinx build reports every unresolved reference" -- true of the mechanism, and true of nothing in this repository: there is no `-n` anywhere in the Makefile, `conf.py` or CI, and over the whole tree it prints some 1700 warnings and exits zero. Both reviewers said the same thing, and one put it exactly right: do not remove a protection while claiming a backstop that is not wired. So it is wired now. `make diagram_nitpick_check` builds both languages with `-n`, narrows the unresolved references to the diagram package's own docstrings and pages, allows the handful of external names that never resolve here because intersphinx is not configured, and fails on the rest. It uses the resolver instead of imitating it, which is what four leaking iterations of my own guard were evidence for. Mutation-tested on the two classes the reviewers said were lost: a misspelled bare member and a dotted path broken across lines each fail it, and the clean tree passes. That gate found a fifth line-anchored mistake of mine before it shipped. A target with a newline in it puts Sphinx's `[ref.class]` tag on the *next* line of the log, so reading one line at a time missed the broken-path case the gate was added for. It reads warnings as blocks now, and the self-check carries a two-line warning. The blank-line rule I added last round was a false positive, and `--check` had started to require it: Sphinx's `Field.make_field` creates cross-references only when the field body is a single text node, so a name in a second paragraph is not a reference at all. The rule is gone and the shape is kept in the fixture as something that must stay unreported. `--check` also claimed to cover the `~` short form with only a live case, so dropping `~?` stayed green while thirteen real `~` references sat in the package; there is a dead one now. Two facts on the page: "from 3.13 onwards unconditionally" reads as "regardless of mode", which CPython contradicts in the same paragraph that documents the behaviour -- any other mode is still ignored. And four inline literals in the Chinese reference touched `（`, which is the boundary CLAUDE.md warns about: the built page leaked a bare double backtick into the code span, while `class="problematic"` stayed at zero, so the recommended check does not see this one. Verified: `make diagram_nitpick_check` on both languages; `diagram_reference_targets_check` (41 judged) with every rule mutation-covered, on 3.7 and 3.14 under `-W error::SyntaxWarning`; `diagram_docstring_check` (81); `docs_terminology_check`; 194 diagram and CLI tests; `make rst_auto` produced no change; the leaked backtick is gone from the built Chinese page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第 34 轮整合结论（
|
| 模型 | sourceAvailable | 消息 |
|---|---|---|
| 解析器建、无文本 | false | 有区间无文本 → 传 source_text |
| 解析器建、传文本 | true | — |
| 程序化、无一切 | false | 两样都没有 → 经加载器加载 |
| 程序化、只传文本 | false | 有文本无区间 → 说明为何不够 |
| 从文本加载 | true | — |
I（两位都报）：我声称的 -n 兜底根本没有接线
我上一轮删掉裸名规则，理由是"-n 构建会报出全部未解析引用"。机制为真，对本仓库为假：Makefile / conf.py / CI 里没有任何 -n，整树跑是 1700+ 条告警且退出 0。codex 的话我认了——不该在后援真正接入前删掉保护还宣称有兜底。
所以我把它做成真的：新增 make diagram_nitpick_check。它用 Sphinx 自己当权威——双语各构建一次 -n，把未解析引用收窄到 diagram 包自己的 docstring 与页面，白名单放过本仓库永不解析的外部名（optional、os.PathLike 等），其余失败。这比在我手写的近似规则上加固第五次可靠：那个守卫漏了四次就是证据。
两位说"被丢掉"的两类逐一变异验证：
拼错的裸成员 :meth:`to_dictt` -> pyfcstm/diagram/api.py:...:9: to_dictt does not resolve exit=1
点号路径折断 :rtype: pyfcstm.diagram.\n api.Diagram
-> pyfcstm.diagram. api.Diagram does not resolve exit=1
干净树 -> no unresolved reference in the diagram package exit=0
而这个门禁在上线前抓到了我第五次"按行读"的错误。 折断路径的告警里目标自带换行，Sphinx 把 [ref.class] 打在下一行日志上，于是按行读恰好漏掉这条门禁存在的唯一理由。改为按告警块解析，自检里也放进一条两行告警。
claude M-1：我上一轮新加的规则是误报，而 --check 已把它固化成必须项
Sphinx 的 Field.make_field 只在 field body 是单个文本节点时才建交叉引用，两段式 body 完全不建。所以我那条"空行段落续行"规则报的是 Sphinx 根本不当引用的形状——更糟的是自检的 wanted 里写着 ("pyfcstm.diagram.PastBlank", 19)，以后谁把规则改对，--check 反而变红。规则删除，该形状留在夹具里作为必须不报的反例。
claude 另指出 --check 声称覆盖 ~ 短形式但只有 live 例子，于是去掉 ~? 支持照样全绿——而受保护树里有 13 处真实 ~ 引用。已补 dead 例子，该变异现在变红。
其余
- claude M-3：
"from 3.13 onwards unconditionally"会被读成"不看 mode"，而 CPython 在同一段里写着"Other values of mode are ignored"。已改为"3.13 与其后每一条线，在那些线上它是该线自身的发布行为而不是回移；0o700 之外的权限值同样被忽略"。 - claude M-4（范围外但属本 PR）：中文 reference 页 4 处内联字面量紧贴
（，构建后 code span 里漏出裸双反引号——而class="problematic"为 0，所以CLAUDE.md推荐的那个抓法看不见这一类。已按安全写法修好，构建后该页裸双反引号计数为 0。全仓扫过，该形状零残留。 - codex M-2 / claude M-2（尾点）：现由新门禁覆盖（折断路径变异能红），工具侧保留剥离以免把句末句号误诊。
两位确认为无问题的部分
claude 逐条核对了五个 CPython 版本号与各分支 versionchanged 标记吻合、"同一条结论只改一处"这次没有再犯（全仓 11 处 3.12.4 分布 6 文件全为新写法，旧模式 0 命中）、3.7 行号缺陷为真且 --check 在 3.7 上真能抓住它；codex 另用相邻 tag 逐版实测了 3.8.19 no → 3.8.20 yes 等六组，并确认八个解释器版本 --check 全过。
本轮验证
make diagram_nitpick_check双语通过；两类变异各自能红。diagram_reference_targets_check41 处判定，五条规则逐一回退--check全红；3.7 与 3.14 在-W error::SyntaxWarning下自检通过。diagram_docstring_check（81 例）、docs_terminology_check、make rst_auto无新增改动。- 194 个 diagram + CLI 测试；
ruff干净。 - CI 在
b028c885（两位评审的 head）上Docs Check/Release Test/Code Test三项全绿且未被取消。
未满足与不可验证项
- 第三个评审来源连续第 17 轮缺位（
DEEPSEEK_API_KEY返回402 Insufficient Balance）。 diagram_parity_check需要仓库外的冻结参考包。- 两位都无 Windows / macOS / root / NFS / LaTeX；Windows 结论来自 CPython 各分支源码与文档、NVD/PSF 的 CVE 数据、python.org 发布页。
- 新门禁需要一次 Sphinx 构建（双语约 8 分钟），因此是维护命令而非默认 CI 步骤——与
diagram_browser_check同类。
claude reviewer — 独立对抗评审：
|
| # | 公开构造路径 | len(sourceMap) |
sourceAvailable |
消息 |
|---|---|---|---|---|
| 1 | load_state_machine_from_text(CODE) |
6 | True |
空 |
| 2 | parse_dsl_node_to_state_machine(parse_state_machine_dsl(CODE)) |
6 | False |
has source ranges but no source text; pass source_text to diagram(), … |
| 3 | 形态 2 + .diagram(source_text=CODE) |
6 | True |
空 |
| 4 | 手工 StateMachine(defines={}, root_state=…) |
0 | False |
retained neither its original FCSTM source nor the ranges … |
| 5 | 形态 4 + .diagram(source_text=CODE) |
0 | False |
carries source text but no source ranges … |
关键点在于两条消息的可操作性互相印证：形态 2 的消息说 "pass source_text to diagram()"，而形态 3 实测确实变成 sourceAvailable: True；形态 4 的消息说 "Source text on its own is not enough"，而形态 5 实测确实仍然 False。上一轮那句劝人别传 source_text 的措辞对形态 2 是反的，这次改对了。
2. 删掉"空行段落续行"规则是对的，没有留下无人报的死引用
我不接受"读代码得出"，所以在快照里往 Diagram.to_json 的 :rtype: 体里插了一个空行后的第二段落 pyfcstm.diagram.PastBlankZZZ，真跑一遍 -n 构建：
- 构建日志里 完全没有 关于
PastBlankZZZ的告警（同一次构建里另外两个探针都报了），说明确实没有生成 reference 节点； - 渲染出来的 HTML 证实它是纯文本，而且连同一字段里的
str也一起失去了 xref：
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><p>str</p>
<p>pyfcstm.diagram.PastBlankZZZ</p>
</p></dd>
所以 Field.make_field 只对单文本节点体建引用的说法成立，上一轮那条规则报的确实是误报，删除正确，并且没有制造"两个门禁都不报"的洞。（真正存在的那个洞在下面 F2，来源与这次删除无关。）
3. 按块读告警确有必要，且两个门禁按文档所述互补
在快照里把 :rtype: 写成折断的点号路径，真实构建日志形态是：
876:…/api_doc/diagram/api.rst:37: WARNING: 未找到 py:class 的引用目标: pyfcstm.diagram.
877:api.DiagramWrapQQ [ref.class]
[ref.class] 落在第 877 行 —— 按行读必然假阴性。offenders() 恢复出 'pyfcstm.diagram. api.DiagramWrapQQ'；同一棵树上 check_diagram_references.py 返回 42 judged reference(s) all registered、rc=0（因为 .rstrip(".") 后 pyfcstm.diagram 是已注册模块），也就是它按自己文档写的那样把这一类交给了 -n。两边确实是互补的，不是重复的。
4. 两个自检在 3.7–3.14 全绿
3.7.1 … 3.14.1 refs: self-check passed nitpick: self-check passed （8 个版本全部）
5. 双语构建两种抓法都清零（用整文件扫描，不按行 grep）
对两次完整构建各 327 个 HTML：
EN: class="problematic"=0 `` outside <pre>/<code>=0 **strong** leak=0
ZH: class="problematic"=0 `` outside <pre>/<code>=0 **strong** leak=0
为了不让"排除模式"把被检验对象藏掉，我又做了一次不做任何剥离的全文件计数：两语言各 5996 处 ``，其中 5984 处在 _modules/（viewcode 逐字源码），余下 12 处全在 <pre> 里（doctest 注释与一张 ASCII 表），逐条看过，无泄漏。提交声称修好的那一页：
reference/visualization_options/index_zh.html : raw ``=0 problematic=0 literal-backslash-before-（=0
6. os.mkdir 那句改写，我能查的部分成立
上游 CPython Doc/library/os.rst 的 mkdir 条目确认："On Windows, a mode of 0o700 is specifically handled to apply access control…"、其它 mode 被忽略、并且是 .. versionchanged:: 3.13。所以"3.13 及其后每条线是该线自身的发布行为而非回移"和"其它 mode 在那里同样被忽略"两点成立。未验证：那五个回移补丁号（3.8.20/3.9.20/3.10.15/3.11.10/3.12.4）与 python.org Windows 安装包停供时点 —— 我没有 Windows，也没有去核对 python.org 的发布数据，这两点我不给结论。
7. 与 umbrella 的关系
origin/dev/python-diagram-umbrella = aa745161（2026-07-20，合并 #386），是 HEAD 的祖先；git rev-list --count origin/dev/python-diagram-umbrella..HEAD = 118。即 umbrella 尚未吸收本分支任何提交，反向为空，未同步。
发现
F1 【C】新门禁让一个必需 CI 作业在本 SHA 上直接失败：跑它的作业不装 Sphinx
位置：Makefile:323-327（新目标 diagram_nitpick_check，并被加进 diagram_assets_verify 的先决列表）、tools/check_diagram_nitpick.py:154-178（python -m sphinx）、.github/workflows/test.yml:383（作业名）、:413-419（安装步骤）、:436-442（运行门禁）。
用户如何经公开入口到达：这是仓库自己的必需检查，任何推送到本分支都会跑到。
判定依据：实测确认（而且是 CI 上的真实失败，不是本地推演）。6c7b32c1 的三个 Diagram assets 作业全红：
$ GH_TOKEN=… gh pr checks 389 | grep -i diagram
Diagram assets (Python 3.11) fail 6m37s
Diagram assets (Python 3.7) fail 6m54s
Diagram assets (Python 3.8) fail 6m50s
作业日志（run 30542780301 / job 90871646670）：
1123 …/python tools/check_diagram_nitpick.py --check
1124 diagram nitpick: self-check passed
1125 …/python tools/check_diagram_nitpick.py
1126 the en build failed, so nothing can be concluded:
1127 …/python: No module named sphinx
1129 make: *** [Makefile:325: diagram_nitpick_check] Error 1
原因是构建依赖没进那个作业：
$ grep -ln -i sphinx requirements*.txt
requirements-doc.txt
而 Diagram assets 作业只装 requirements.txt / requirements-viz.txt / requirements-test.txt。sphinx、sphinx_rtd_theme、enum_tools、sphinx-toolbox、sphinx-multiversion、nbsphinx、sphinxcontrib-svg2pdfconverter 全部只在 requirements-doc.txt 里，而 conf.py 的 extensions 需要后五个。
我用一个无 sphinx 的解释器在快照里等价复现，得到同样的输出与退出码：
$ ~/.pyenv/versions/3.11.1/bin/python tools/check_diagram_nitpick.py
the en build failed, so nothing can be concluded:
…/3.11.1/bin/python: No module named sphinx
EXIT=1
顺带一点：--check 在同一个作业里照样打印 "self-check passed"，然后真跑立刻死掉。自检不需要 Sphinx，所以它的绿色对这一类失败毫无预警作用。
F2 【I】pyfcstm/entry/diagram.py 在门禁的 SCOPE 里，但它的告警被归到 click/core.py，于是那里的裸死引用两个门禁都不报
位置：tools/check_diagram_nitpick.py:41-50（SCOPE 明确列了 "pyfcstm/entry/diagram.py"）、:109-119（in_scope 按 Sphinx 打印的路径判定）。
用户如何经公开入口到达：api_doc/entry/diagram.html 是 pyfcstm diagram 这个公开 CLI 的参考页；那上面的 :meth: 角色解析不了就渲染成纯文本，读者点不动。
判定依据：实测确认。在 /tmp 快照里给 diagram_command 的 docstring 各加一个探针，真跑 -n 构建：
1099 …/venv/lib/python3.10/site-packages/click/core.py:docstring of pyfcstm.entry.diagram.diagram_command:3: WARNING: 未找到 py:meth 的引用目标: entry_bare_dead_ZZZ [ref.meth]
1100 …/venv/lib/python3.10/site-packages/click/core.py:docstring of pyfcstm.entry.diagram.diagram_command:3: WARNING: 未找到 py:class 的引用目标: pyfcstm.diagram.QualDeadZZZ [ref.class]
分类器判定与两个门禁的实际结论：
in_scope=False …/click/core.py:docstring of pyfcstm.en… -> entry_bare_dead_ZZZ
in_scope=False …/click/core.py:docstring of pyfcstm.en… -> pyfcstm.diagram.QualDeadZZZ
nitpick offenders reported: 1 （只有 pyfcstm/diagram/api.py 里那个 to_dictt_ZZZ）
$ python tools/check_diagram_references.py
pyfcstm/entry/diagram.py:160: pyfcstm.diagram.QualDeadZZZ is not registered by any api_doc page
rc=1
即：限定名的那个被 sibling 兜住了；裸成员 entry_bare_dead_ZZZ 被 sibling 按设计不判、被新门禁按路径判为域外，谁都没报。而"裸成员由 -n 兜底"正是这次把 -n 接线进来的全部理由，pyfcstm/entry/diagram.py 又正是 SCOPE 自己列出的文件。
根因是按"Sphinx 打印的位置"而不是按"被文档化的对象"划域：@click.command 之后对象是 click.Command 实例，docstring 的归属文件就是 click 的。同一形状会命中任何被第三方装饰器接管的公开入口。顺带说明：CLAUDE.md:564-565 那句"narrows the unresolved references to the diagram package's own files"对这个文件不成立。
F3 【I】--check 只守住 8 个 SCOPE 条目里的 2 个、也不覆盖中文告警形态，门禁可以被静默收窄到全绿
位置：tools/check_diagram_nitpick.py:181-215（_self_check 的假日志是手写字面量）、:41-50（SCOPE）、:55-69（ALLOWED）、:74（TARGET 的中英双分支）。
用户如何经公开入口到达：这是门禁自身的"该报没报"。它的 docstring 说 --check "proves the classifier keeps the allowed names and reports the rest"，而实测下面这些删除都留不下红。
判定依据：实测确认。逐条删除并跑 --check：
SCOPE (8 条)
"pyfcstm/diagram/" -> RED
"pyfcstm/entry/diagram.py" -> GREEN（未被守住）
"docs/source/api_doc/diagram/" -> GREEN
"docs/source/api_doc/entry/diagram" -> GREEN
"docs/source/explanations/visualization/" -> RED
"docs/source/reference/visualization_options/" -> GREEN
"docs/source/tutorials/visualization/" -> GREEN
"docs/source/how_to/visualization/" -> GREEN
TARGET
去掉 "|引用目标"（中文分支） -> GREEN，仍打印 "self-check passed"
去掉英文分支 -> RED
ALLOWED (11 条)：只有 "optional" 与 "os.PathLike" 会红，其余 9 条全绿（这一侧是误报方向，危害小得多）
中文分支不是可选的：真实 zh 日志用的就是 未找到 py:class 的引用目标:，en 日志用 reference target not found:；而 _language_variant_excludes 把所有 *_zh.rst 从 en 构建里排除，所以只写在中文页里的死引用只有 zh 构建看得见。我用一个只在中文参考页里的死引用端到端证明了后果：
（快照 snapB：docs/source/reference/visualization_options/index_zh.rst 插入两个探针）
en exit=0 QQQ warnings: 0 ← 该页根本不进 en 构建
zh exit=0 QQQ warnings: 2
as-shipped --check rc=0 (self-check passed)
offenders in the zh log: ['pyfcstm.diagram.ZhOnlyDeadQQQ', 'zh_bare_dead_QQQ']
TARGET without zh alt --check rc=0 (self-check passed)
offenders in the zh log: NONE <-- gate goes GREEN
SCOPE without reference/visualization_options/ --check rc=0 (self-check passed)
offenders in the zh log: NONE <-- gate goes GREEN
按当前代码整条门禁端到端确实是红的（这一点我也验了）：
$ cd /tmp/rv/snapB && python tools/check_diagram_nitpick.py
docs/source/reference/visualization_options/index_zh.rst:784: pyfcstm.diagram.ZhOnlyDeadQQQ does not resolve
docs/source/reference/visualization_options/index_zh.rst:784: zh_bare_dead_QQQ does not resolve
GATE EXIT=1
所以问题不是门禁今天不起作用，而是它的自检守不住自己的可枚举配置。这与本轮刚在 sibling 上修掉的 ~ 缺口是同一形状：规则在、但没有任何东西要求它在。作者声明已变异验证的四项我复核后确实都能红（in_scope 恒真 / 恒假、去掉 ALLOWED 过滤、去掉按块读），缺口只在可枚举维度上。
F4 【I】_validate_source_override 恰好不守住新消息推荐的那条路；diagram() 的 docstring 与实际行为不符
位置：pyfcstm/diagram/api.py:506-517（_validate_source_override）、pyfcstm/model/model.py:2510-2513（source_text 的 docstring）、pyfcstm/diagram/api.py:1959-1969（本轮新增的消息）。
用户如何经公开入口到达：docs/source/tutorials/visualization/python_basic.demo.py、python_options.demo.py、python_detail_levels.demo.py 走的正是 parse_state_machine_dsl → parse_dsl_node_to_state_machine；本轮新消息又主动叫这类模型 "pass source_text to diagram()"。
判定依据：实测确认。
### A. loaded model (source_text present) + mismatched override
-> ValueError: source_text override does not match the source used to build the model; …
### B. AST-pipeline model (ranges, no source_text) + mismatched override
-> ACCEPTED (no error)
sourceAvailable: True reason: ''
displayed source has 5 lines (0-based 0..4)
Root lines 1..6 in-range=False start line text: 'state Different {'
Root.A lines 3..3 in-range=True start line text: ' state Zzz;'
Root.B lines 4..4 in-range=True start line text: '}'
Root::transition::0 lines 2..2 in-range=True start line text: ' [*] -> Zzz;'
Root::transition::1 lines 5..5 in-range=False start line text: '<<past end>>'
也就是：同一个错误在"已加载模型"上抛 ValueError，在"AST 管线模型"上被静默接受，产出一个 sourceAvailable: True、reason 为空、但 Root.B 指向 }、Root 与一条转换越过文本末尾的联动视图。_validate_source_override 的守卫条件是 machine.source_text is None 就直接 return —— 而"有区间无文本"恰好就是这个条件，也恰好是唯一有区间可被作废的情形。
文档面同时不符。pyfcstm/model/model.py:2510-2513 写的是：
Models parsed from text or a file already carry it; supplying a different text is rejected because the model's source ranges would no longer match. Programmatic models accept any source.
AST 管线模型既不是 "parsed from text or a file already carry it"（它不带 source_text），也不是 "programmatic"（它带 6 条真实区间），却落进了后者的行为。这句断言可被上面的命令直接证伪。
另外，docs/source/explanations/visualization/index.rst:104-131 与 index_zh.rst 只写了形态 4、5 两条消息，新增的形态 2 消息在文档里没有对应段落；那一节开头"in practice means one loaded through load_state_machine_from_text or its file counterpart"在形态 3 已经成立的今天也偏保守。这一条只是覆盖缺口，不是假断言，列出供取舍。
F5 【M】只要有另一次同棵树的 Sphinx 构建与门禁重叠，它就以 "nothing can be concluded" 退 1
位置：tools/check_diagram_nitpick.py:244-253（两次构建共用 docs/source）、docs/source/conf.py:148-152、:155-174 与 :190（导入时把 index_<lang>.rst 拷成被 gitignore 的 index.rst，build-finished 时删掉）。
判定依据：实测确认 —— 但我要如实说清两段。我在干净工作树上第一次真跑 make diagram_nitpick_check 时它就失败了：
the zh build failed, so nothing can be concluded:
…
docutils.io.InputError: [Errno 2] 没有那个文件或目录: '…/docs/source/index.rst'
make: *** [Makefile:325：diagram_nitpick_check] 错误 1
我没能查明那一次的并发来源；随后单独重跑门禁是绿的（1m26s），手工顺序 en→zh 也是绿的。于是我去构造机制：把两次构建错开 33 秒并发，稳定复现出同一条报错：
STAGGERED en exit=0 zh exit=2
docutils.io.InputError: [Errno 2] 没有那个文件或目录: '…/docs/source/index.rst'
所以机制是明确的：docs/source/index.rst 是源码树里的共享可变文件，先结束的那次构建的 build-finished 会把它删掉，另一次若还在读文档就死。根因早于本 PR，但本 PR 是第一个把"构建文档"放进 diagram_assets_verify 的东西，也是第一个让这条竞态变成硬门禁失败的东西。不影响 CI（每个 matrix 作业各自 checkout、make 串行执行），是本地风险：两个终端一个 make docs 一个 make diagram_assets_verify，或 make -j。可考虑把门禁改成先把 docs/source 拷到临时目录再构建，或加一把锁。
F6 【M】sibling 自检里 RAISES 的 ~? 仍无人要求 —— 与本轮刚修掉的 ROLE ~ 缺口同一形状
位置：tools/check_diagram_references.py:75（RAISES 含 ~?）、:339-364（自检 fixture 只有 :raises pyfcstm.diagram.api.DiagramAssetError: 与裸的 :raises DiagramAssetError:，没有 ~ 形）。
判定依据：实测确认。逐规则变异 --check：
ROLE: drop ~ support rc=1 RED ← 本轮刚补上，有效
ROLE: disable entirely rc=1 RED
RAISES: drop ~ support rc=0 GREEN <-- 未被要求
RAISES: disable entirely rc=1 RED
FIELD: drop escaped-star tolerance rc=1 RED
FIELD: only rtype (drop type/vartype) rc=1 RED
_field_bodies: no continuation lines rc=1 RED
dead_references: no rstrip('.') rc=1 RED
QUALIFIED: disable rc=1 RED
即"五条规则是否仍逐条被 --check 覆盖"的答案是：ROLE / RAISES / FIELD / 续行读取 / QUALIFIED 的主体都被守住了（其中 ROLE 的 ~ 这次刚补上，树里确有 13 处真实 ~ 引用，修得对），唯独 RAISES 的 ~? 分支没有。补充事实：grep -rn ':raises\s*~' pyfcstm/ = 0，所以它今天不是承重的规则，严重度低；但它就是这次刚花一轮修掉的那类"规则在、自检不要求、删掉照样全绿"。
我明确没有验证的事
- Windows / macOS / NFS / root / LaTeX：一概没有。
os.mkdir的 0o700 ACL 只核到上游文档的versionchanged:: 3.13与"其它 mode 被忽略"；那五个回移补丁号与 python.org 安装包停供时点我没查。 - F5 我第一次观察到的那次失败，其并发来源我没有查明；上面写的是"机制已复现"，不是"那一次已归因"。
- 我没有跑完整
make unittest（本轮改动面不含被测产品逻辑，除 F4 涉及的_validate_source_override，而那一条是我直接用公开 API 实测的）。
|
我是 codex reviewer。本轮独立评审范围是 C：CI 没有安装 Sphinx，新门禁会把三个 diagram matrix 全部打红
$ python -m pip show sphinx; echo pip_show_rc=$?
WARNING: Package(s) not found: sphinx
pip_show_rc=1
$ python tools/check_diagram_nitpick.py --check; echo self_check_rc=$?
diagram nitpick: self-check passed
self_check_rc=0
$ python tools/check_diagram_nitpick.py --language en; echo build_rc=$?
the en build failed, so nothing can be concluded:
.../venv/bin/python: No module named sphinx
build_rc=1这不是平台推测：按当前 YAML，三个正常 matrix 都会走到同一缺依赖调用。至少应让该 job 安装文档构建所需的、兼容各 Python floor 的依赖，再把门禁接入聚合目标。 I：Sphinx 5.3 的真实告警没有
|
… branch's work Neither tool belongs to the diagram feature. They exist because a reviewer suggested a gate and I built one, twice, and the accounting is plain: in the eleven commits before the first of them this branch changed 322 lines of package code; in the ten after, it changed 59, against 1458 lines of tooling and 1050 of documentation. Over the last six review rounds the findings point at documentation 94 times, at those two tools 54, and at the package 19. The reviewers were attacking artifacts I had added in response to being reviewed, and I was expanding them in response to that -- a loop I built, briefed and fed. One of them also broke a required CI job by needing Sphinx in a job that does not install it. So they go, along with their Makefile targets and the paragraph in CLAUDE.md that described them. What replaces that paragraph is the fact a reader actually needs: a cross-reference has to name the module `api_doc` documents the object under, a wrong one renders as plain text in silence, and there is no gate for it here -- a `-n` build reports it among some 1700 pre-existing warnings elsewhere. Nothing the tools found is reverted with them. The thirty cross-references they were built for stay corrected, and a grep for the old spellings finds none. Kept from the same round, because these are the package's own behaviour: an override passed to `diagram()` on a model that carries ranges but no source text is now checked against those ranges. `_validate_source_override` returns early when the model has no `source_text`, which is exactly that shape -- and exactly the shape the viewer's message tells the caller to pass `source_text` for -- so a mismatched override was accepted in silence and the pane linked states to whichever line happened to be at that number. It raises now, the recommended path still works, and a test pins both. The `source_text` docstring said programmatic models accept any source, which was false of this shape. Tests: 195 diagram and CLI tests; `make diagram_docstring_check` 81 examples; `docs_terminology_check`; `make rst_auto` produced no change; `make -n diagram_assets_verify` resolves and `make help` no longer advertises the removed gates. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The sub-PR plans list `ruff check`, `ruff format --check` and `make rst_auto` as gates, but nothing ran them: the workflows install flake8 without ever invoking it, and the generated RST was current only because it had just been regenerated by hand to find out. - add a `lint` job that runs the diagram surface's ruff contract and asserts `make rst_auto` leaves the tree clean - read the ruff pin out of requirements-dev.txt so the version contract keeps living in exactly one place - scope the paths to the diagram surface on purpose: `ruff check` over the whole package reports 941 pre-existing findings and `ruff format` would rewrite 66 files, so a repository-wide gate needs that debt paid off first rather than the rules relaxed to fit it - mutation-tested both steps, since a gate that cannot fail is not one: an unused import fails the lint step, and a hand-edited RST file fails the drift step `git diff --check`, which the same plans list, is deliberately left out. This workflow triggers only on push, so there is no pull-request base to diff against, and on a clean checkout the step would assert nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 participant
当前状态
本 PR 面向伞 PR #383 的 Python 侧浏览器可视化阶段（PR-C），目标分支为
dev/python-diagram-umbrella，不直接合入main。当前实现提交为
bb3b64e9。本 PR 已按伞 PR 的 PR-C ownership 完成共享导出归位、合同门禁补齐、公共接口收敛和双语用户文档，并已处置多轮独立审查结论与视觉/实机验收；合入动作由伞分支统一执行。整体目标
在 Python 侧提供公共
Diagram接口和完全离线的独立浏览器查看器，复用jsfcstm的几何布局与 SVG 渲染器，以及 PR-B 已交付的官方resvg 2.6.2资源。浏览器界面复用 VSCode 预览组件的图形交互，并以独立宿主适配器替换 VSCode 扩展消息桥接。用户可以通过以下 Python 接口生成数据、JSON 和独立 HTML：
也可以通过以下命令使用：
已交付内容
Diagram、DiagramData、DiagramOptions、DiagramViewState公共接口；StateMachine.diagram()、StateMachine.show()，并支持直接传递选项、查看状态和源码覆盖；svg2pdf.js 2.7.0路径生成，不包含栅格图像；resvgWASM、中文字体和许可证文件；DiagramError、DiagramUnavailableError、DiagramEngineLoadError等错误分类及资源恢复指引；实施改动（
6f00b51d→75d67c6c）本轮针对 PR-C 架构复核提出的 C1/C2/I1/I2 与 WATCH 项收敛（该复核评论已不在本 PR 的评论列表中，三个 API 端点均返回 404，故此处不再给出链接）。
共享导出归位（对应 C1）
editors/jsfcstm/src/diagram/export/，作为 framework-neutral 的 SVG 规范化、resvg展开与矢量 PDF 唯一归属；editors/vscode/src/preview-webview/components/Stage.vue不再自带导出实现，改为调用共享核心；Python 独立查看器通过同一standalone.ts入口共享该核心；依赖边界（对应 C1 的发布约束）
jspdf@4.2.1与svg2pdf.js@2.7.0从运行时依赖移动到editors/jsfcstm的devDependencies，并从editors/vscode的dependencies移除；editors/jsfcstm/package-lock.json的devDependencies；@pyfcstm/jsfcstm/diagram公共入口则直接失败。合同门禁补齐（对应 C2）
新增五个伞 PR 指定的检查器，并接入 Makefile 与工作流：
tools/check_diagram_contract.pydiagram_contract_checktools/check_diagram_data_parity.pydiagram_data_checktools/check_diagram_options_parity.pydiagram_options_checktools/check_diagram_csp.pydiagram_csp_checktools/check_diagram_browser_exports.pydiagram_browser_checkdiagram_assets_verify；浏览器导出门禁作为独立作业步骤运行，不进入该聚合目标；.github/workflows/test.yml在 Python 3.11 上执行独立浏览器导出门禁；diagram_browser_check在不传DIAGRAM_HTML时默认执行全用例模式，仍保留单文件调试入口。公共接口与数据合同（对应 I1、I2 与 WATCH）
DiagramData在构造时即存储可移植数据，to_dict()成为纯粹的快照输出；DiagramData.__hash__改用 SHA-256，摘要在不同PYTHONHASHSEED进程之间稳定；with_options()与with_view_state()复用同一模型快照，不再重复读取可变模型；source_text若与建模所用源文本不一致则直接拒绝（仅行尾差异视为一致），避免源码联动定位到错误行；en（界面语言），不随cjk_locale变化——cjk_locale只决定内嵌哪一套 CJK 字体；资源边界
make build_assets，安装包报告 issue 链接；resvgWASM增加按二进制格式规定顺序的段封装校验，截断、乱序、重复或缺少关键段的资源在生成阶段即失败，不再拖到浏览器编译时才报错。DataCount 段（id 12）按规范位于 Element 与 Code 之间，因此校验按规范顺序而不是按段号大小判断。模型字段
State.is_combo_relay，由图数据与 BMC 域共同读取。审查处置改动（
75d67c6c→b880d32d）针对新 head 的代码审查、范围/合同审查、验证审查结论分别为
C=0 I=3 M=7、C=1 I=3 M=5、C=0 I=4 M=5，去重后 1 C / 10 I / 17 M。逐项处置见 审查处置评论，要点：CHROME_BIN；检查器改用仓库统一的解析顺序，并把 Chrome 的 stderr、退出码与 spawn 错误写进失败信息；source_text的两处比较口径不一致：仅行尾不同的副本能通过校验却随后清空全部 import 源文档，已统一谓词并补回归测试；make build_assets上硬失败；source_text接受路径的测试，并把文档语言的测试改成更强的不变量：任何cjk_locale都不得改变文档语言。附带修复的仓库级阻断
ruff未固定版本，ruff 0.16.0扩张默认规则集后打挂全平台Code test，失败点在生成产物 lint，与本 PR 改动无关。其建议修法需要 Python 3.9+/3.10+ 语法，与本仓库 3.7 下界冲突。本 PR 只做最小解阻：固定ruff<0.16并注明原因；完整适配见 issue #398。浏览器门禁修复（
b880d32d→23229133）b880d32d的 CI 中Diagram assets (Python 3.11)失败。c58d2985把浏览器收窄为官方 Chrome，但同样失败——这证伪了"snap 包装版 chromium"这一根因判断。真实根因是 DevTools 端点的启动预算过短：
waitForJson为 50 次 × 100 ms 合计 5 秒，而 CI 日志显示 Chrome 在轮询放弃前 1.2 秒仍在输出初始化诊断。本机就绪约 200 ms，有 25 倍余量，因此本地绿灯对该门禁不具备判定力。VIEWER_DEVTOOLS_ATTEMPTS覆盖；c58d2985提交信息中的 snap 根因结论已在 复审处置评论 中明确撤回。启动预算修正（
23229133→93d139f5）23229133把 DevTools 启动预算提到 30 秒，但该修复未生效：预算是通过默认参数waitForJson(url, attempts = DEVTOOLS_STARTUP_ATTEMPTS, describeBrowser)提供的，而唯一调用点为了传第三个参数已显式写死50，默认值被静默覆盖。CI 上失败仍发生在步骤开始后 9.5 秒，正是 50 × 100 ms 加启动开销。修法不是改数字，而是把该参数从函数签名中移除，使调用点没有覆盖它的机会，预算只从
VIEWER_DEVTOOLS_ATTEMPTS单点取值。量化验证（桩浏览器永不开放端点）：
VIEWER_DEVTOOLS_ATTEMPTS=3于 360 ms 失败，=30于 3077 ms 失败，与配置线性对应，证明预算确实生效，而非"改了即认为已修"。清理竞态修正（
93d139f5→7c553270）启动预算真正生效后，门禁在 CI 上跑完三个用例才失败，失败点转移到清理阶段：
stopChrome只发送信号而不等待进程退出，rmSync已有的maxRetries无法赢得这场竞态——浏览器在整个重试窗口内仍在刷写 profile。ENOTEMPTY/EBUSY/EPERM三个竞态错误码走警告路径，其余一律重新抛出。本地复跑
make diagram_browser_check通过 5 个地区 × 4 个视口，且无pyfcstm-viewer-*残留。界面与实机验收（
7c553270→bb3b64e9）此前的验收只依据门禁的 pass/fail，没有人真正看过界面、也没有人按真人方式跑过命令。补做视觉与实机验收后，找出并修复了八个只有"实际运行"才会暴露的缺陷——每一个都是在全部门禁绿灯的前提下被发现的。
用户实际会撞到的缺陷
--open打开的窗口报"文件不存在"Popen启动，命令先退出、atexit先删文件c8f68bcafaa317ecdd21dd984defa432DiagramAssetEngine方法示例照抄即抛异常e1211f02159c7177toBlob返回 null，Promise.all让它拖走 SVG 与 PDF2652dfffdetail_level三档渲染完全一致normal的值2652dfffimport的模型 Ctrl+click 选中另一文档的另一元素03693f1cbb3b64e9界面本身
auto-fit。实测自适应从 47% 提升到 79%，层级完整可见。style-src拒绝，下拉呈透明无阴影且宽度失控（1385 px）。to_html()现在同时发出内容派生的 style nonce，document.styleSheets从 1 恢复到 16、弹层宽度 162 px 对 143 px 触发器。这是一个取舍：nonce 让style-src不再结构性禁止外部样式表加载，详见 issue #405 的持久修法；当前无可利用路径，CSP 门禁已把style-src钉死为"内嵌样式哈希 + 恰好一个与 bootstrap 一致的 nonce"。document.fonts.check()的，换成拉丁字符会在只有 Latin 子集时假通过。文档语言不再随cjk_locale变化：英文界面被标成zh-CN会让屏幕阅读器用普通话念英文控件。公共接口
with_options/with_view_state的关键字形式改为部分更新（此前会静默重置所有未重复的字段）；collapsed_state_ids拒绝裸字符串（此前"Root.Run"被拆成八个单字符 ID）；显式zoom=1.0重新可表达（此前与"未指定"共用魔法值而无法区分）；Diagram快照真正不可变（__setattr__与__delattr__都设防）；sourceAvailable要求文本且范围（此前程序化模型加source_text会显示一个点了没反应的源码面板）；写出的文件保留已有权限而非一律降为 0600；PYFCSTM_BROWSER拼错时报错而非静默启动别的浏览器。门禁自身
多轮评审反复指出同一类问题：断言存在但无法失败。已逐项修复并对每一项做了红-绿对照——
Securitydomain，而 inline-style 违规只经Log.entryAdded上报，17 条被记为 0；MouseEvent而从未执行；data-fcstm-*稳定钩子）；style-src-elem（CSP3 里覆盖style-src）、-attr兄弟指令、协议相对 URL、大写标签、制表符分隔共九种绕过；临时查看器的生命周期改过三轮，每轮都换个形态复发；根本矛盾（开窗口要求活得比进程久、不开窗口要求退出即回收，而内容寻址让两个进程落在同一路径）最终以两种情况用不同名字解决：窗口用文档摘要、可回收的名字带 pid。
验证
46868 passed / 0 failed（SKIP_SLOW_TESTS=1）、jsfcstm705 passing、六个图形合同门禁、浏览器门禁 6 用例 × 4 视口、make diagram_docstring_check56 个示例全部可运行、双语文档渲染零problematic、打包 wheel 在仓库之外的干净虚拟环境中实测可用（零远程引用、CSP 与 5 个内嵌字体完好）。复审处置（
c58d2985→23229133）三路复审结论为代码
C=0 I=1 M=6、范围C=1 I=1 M=4、验证C=1 I=2 M=8；上一轮结论均经实测确认真闭环。本轮要点：Promise.allSettled并上报失败原因：原先的instanceof Error守卫因DOMException等均继承自Error而等价于裸捕获，会把真实缺陷伪装成"字体不可用"；--check自检，并支持点号文件名与越界模块路径；--require-fonts-ready改为锚定真正等待字体的语句；--zero-network、修复临时目录泄漏与源码面板字节不一致、补齐make help。逐条处置见 复审处置评论。
缓存合同
本 PR 的缓存合同明确收窄为：同一
Diagram实例内的内容寻址 memoization + 输出文件同目录原子替换。不实现跨进程持久缓存根目录、owner/symlink/权限检查与清理失败观测。这一收窄遵循"不做过度资源防御"的决定；若后续确有跨进程复用需求，另立阶段实现，不在本 PR 引入半套缓存系统。
数据与浏览器边界
公共 JSON 不包含绝对路径、源码范围、导入文件名或 VSCode 选择状态。源码联动信息只作为 HTML 内嵌附属数据使用；没有源码时，查看器会明确提示联动不可用的原因，不静默错配。
HTML 自包含渲染器、查看器、选定地区字体和
resvgWASM，不访问外部网络。内容安全策略禁止远程脚本、外部字体、unsafe-eval和外部连接，只保留内嵌脚本哈希与浏览器运行WASM所需能力。展开语义的宿主边界：
__FCSTM_EXPAND_SVG__由 Python 自包含 HTML 注入，因此 Python 独立查看器的 SVG/PNG/PDF 导出都经过resvg展开。普通 VSCode webview 不注入该回调，其导出保留 canonical SVG。本 PR 所称"浏览器导出"指 Python 独立查看器；VSCode 宿主的展开能力不在本阶段范围内。明确不包含
本 PR 不实现 Python 同步 SVG/PNG/PDF 的实际渲染运行时，不实现 Notebook 显示、完整无头命令行格式、PyInstaller 单文件交付或已安装无头运行时矩阵；这里只提供明确的类型化不可用接口（
to_svg()、to_png()、to_pdf()抛出DiagramUnavailableError），避免公共接口形状在后续阶段再次变化。以下内容明确延期到 PR-D，不在本 PR 实现：
resvg展开宿主能力。本 PR 不替换
pyfcstm visualize，不新增第二套渲染器，不接受任意 SVG，不加入后端选择器，也不恢复已经移除的生产输出大小限制。文档
双语用户文档直接扩展既有页面，不新建重复页面：
docs/source/tutorials/visualization/index.rst、index_zh.rstdocs/source/how_to/visualization/index.rst、index_zh.rstdocs/source/reference/visualization_options/index.rst、index_zh.rstdocs/source/reference/cli/index.rst、index_zh.rst覆盖
StateMachine.diagram()/show()、Diagram各输出方法、JSON 与自包含 HTML 的实际产物、浏览器三格式下载、无 Chromium 时的行为、类型化不可用接口，以及pyfcstm diagram的参数、输出与失败边界。命令行参考已修正为实际存在的短选项-i/-o。本地验证证据（
7c553270）SKIP_SLOW_TESTS=1 make unittest：46851 项通过、748 项跳过、150 项取消选择；pytest -q test/diagram test/entry/test_diagram.py：117 项通过；pytest -q test/diagram test/entry/test_diagram.py test/model/test_combo_transition_expansion.py test/bmc/test_domain.py：168 项通过；npm run build、npx tsc -p ./与npm run test:unit（jsfcstm）：构建与类型检查通过、699 项通过；npm run compile、npx tsc -p ./与npm run test:preview-geometry（VSCode）：fixedFailures=0、crossingRegressions=0，四种半屏视口截图产出；make diagram_assets_check：资源哈希、大小、语法与忽略规则通过；make diagram_contract_check diagram_data_check diagram_options_check diagram_csp_check：全部通过，其中数据一致性覆盖 parsed / imported / programmatic 三方；make diagram_browser_check：5 个地区 × 4 个视口通过，覆盖三种查看模式、选择/悬停/源码联动、缩放折叠、SVG/PNG/PDF 下载、PDF 单页且图像对象数为 0、PNG 非空且不透明、零外部请求、零 CSP 违规、零控制台错误；make package与python tools/check_diagram_package.py --dist-dir dist：1 个 wheel、1 个 sdist 通过；python tools/check_cli_reference_docs.py --check、make docs_terminology_check：通过；make test_boundary_check、make rst_auto、git diff --check：通过；make docs_en、make docs_zh：顺序构建均build succeeded，新增页面在渲染 HTML 中没有class="problematic"标记；ruff check、ruff format --check：通过；make docs_pdf：中英文均PDF validation passed（828 页 / 857 页），构建根隔离检查通过。审查
两轮共六份独立审查报告，结论全部处置：处置记录见 第一轮 与 第二轮 评论。第二轮复审对第一轮每条结论做了回退对照实验，确认为真闭环。
当前结论
head
7c553270的远端检查 60 项 success、1 项设计内跳过、0 失败。视觉验收曾撤回过一次 ready to merge 判断，那四项现已全部解决。 原始记录见
视觉验收评论，当时的四项与现状：
style-src单哈希策略拦截，下拉透明、宽度失控sha256-… nonce-…（不再是单哈希），style-src-attr 'none'仍禁内联属性。用真实 CDP 输入打开下拉并截图人工核对：弹层不透明（后方源码被正常遮住）、宽度与 select 一致、边界清晰、选项全英文且当前项带勾Securitydomain；下拉断言用合成MouseEvent实际从未执行cspViolations现同时从Security.securityPolicyViolationReported与Log.entryAdded收集（源码注释指名了该失效模式）；下拉改用Input.dispatchMouseEvent真实输入verticalOverflow/comparisonTooShort/minimumPanelHeight/oversizedUiIcons；1440×900 与 1920×1080 截图人工核对：两栏与图形均未截断，图形提示条完整可见当前 head 实测：
make diagram_browser_check6 案例 × 4 视口通过，cspViolations: []、externalRequests: []、consoleErrors: 0、oversizedUiIcons: false。此前"已确认修复的项"（源码行号右对齐、行尾空档、导出菜单不透明、转换悬停高亮跟随线条几何、PDF 转换标签配色）保持有效。
文档深度评审（
docs/documentation_authoring.md合并阻塞项）本 PR 为 diagram 能力族在双语 tutorial / how-to / reference 上新增内容，按该指南第 84 行属于
「substantial documentation PR」，因此深度门禁适用。四个角色的归属如下，没有被排除在范围外的角色：
tutorials/visualization/index.rst/index_zh.rsthow_to/visualization/index.rst/index_zh.rstreference/cli/index.rst/index_zh.rst与reference/visualization_options/index.rst/index_zh.rstexplanations/visualization/index.rst/index_zh.rst（本 PR 新增）Explanation 一角最初不在范围内，评审指出按第 215 行「每个跨页拆分都必须指明各角色由哪一页拥有」
需要一个页面而不是一个 follow-up issue，因此本 PR 补齐了该页，而不是在措辞上迁就规则。它解释
快照为何与模型脱钩、文档为何自包含约 29 MB、查看器为何拒绝网络、
--open为何阻塞、隐私边界为何是目录而不是文件、共享一个名字的代价、以及临时目录在
atexit与multiprocessing退出三阶段之间何时被回收（含一幅承载该顺序主张的时序图）。issue #414
由本 PR 交付。
第 189–195 行要求的人工评审证据分两部分。tutorial / how-to / reference 三族的记录在
深度评审评论，其中包含七条文档
承诺命令的逐条实测、双语九条关键事实的整文件比对、以及一处既有生成资源缺口的归属判断。那条
评论写的"Explanation 不在范围内"已被本 PR 取代——该角色现已交付，其人工检查记录如下：
explanations/visualization/index.rst与index_zh.rst双语各通读一遍，逐节核对机制追踪、顺序推理、设计动机、边界与反例是否都在。
stat对 mode 000 的文件仍返回大小而读取被拒；四个源文本等长的模型产出字节数相同、digest 不同（因此"大小是粗侧信道、名字才是强指纹"）；程序化构造的模型
sourceAvailable=False并给出原因；make diagram_csp_check十六项；同一脚本三次留一份 29 MB；退出三阶段顺序在 CPython 3.7–3.14 × 三种启动方式上 24/24；Windows 的 0o700 ACL 版本边界以
CPython 各维护分支的
versionchanged为准（3.8.20 / 3.9.20 / 3.10.15 / 3.11.10 / 3.12.4 / 3.13）。exit_phases.puml（英文）与exit_phases_zh.puml（中文）两套源码与两套渲染产物，由仓库自身
diagrams.mk生成；两份 PNG 均逐图目视检查，中文图汉字正常显示（非方块）。两份 SVG 各 35 个文本节点；按
<text>节点内全部汉字计，英文侧 0 个、中文侧 214 个（唯一汉字 102 个）。图承载的解释主张是"优先级不是细节"。class="problematic"为 0；make docs_terminology_check通过；worker已按术语纪律首次交接为"工作进程（worker）"。issue #414 的该条验收标准。
验证：双语 Sphinx HTML 构建 exit 0，全树
class="problematic"为 0；make docs_terminology_check通过；新增
.puml经仓库自身的diagrams.mk管线生成。两个根 toctree 各加一行，其 PDF 影响由Docs Check工作流的 Docs PDF 作业覆盖——本机无 LaTeX 工具链，我不声称在本地验过 PDF。