dsh-ppt-studio 1.1.5 → 1.2.0

package/docs/09-/344/273/243/347/240/201/345/234/260/345/233/276/344/270/216/346/250/241/345/235/227/350/201/214/350/264/243.md

@@ -0,0 +1,148 @@
+# 09 · 代码地图与模块职责
+
+> 目的：回答三个问题——**这个文件负责什么**、**改它会波及什么**、**改完该跑哪些测试**。
+> 状态：随代码增删，**每次往 `src/` 加/删/挪模块时同步更新本文件**。
+> 生成方式：`src/` 每个文件的首条模块注释 + 导出清单（本文件的表格由脚本与人工共同维护，避免与代码脱节）。
+
+---
+
+## 1. 顶层目录
+
+| 路径 | 作用 |
+|---|---|
+| `src/` | 插件源码（**纯 ESM JS**，无构建步骤；`node scripts/build.mjs` 只是复制到 `lib/`） |
+| `lib/` | **已提交**的构建产物（与 `src/` 逐字节一致，`npm run check:lib` 守卫） |
+| `scripts/` | 自检与验证脚本（smoke / e2e / verify-* / 影响面映射 / 发版同步） |
+| `docs/` | 开发文档（00 设计源 · 01 需求 · 02 技术 · 03 日志 · 04 路线 · 05 迭代流程 · 06 评审测试 · 07 立项 · 08 阶段A设计 · 09 本文件 · 10 宿主耦合 · 11 术语表） |
+| `skills/` | 4 本内置技能（提问式手册 manual / 制作 craft / 数据 data / 文案 copy），正文各 ≤8000 字 |
+| `agent-presets/` | 预设声明资产（`ppt` 预设的 `agent.cordis.yml`） |
+| `examples/` | 样例工程与 smoke 临时工作区（`.tmp-*` 为忽略目录） |
+| `cordis.patch.yml` | profile bundle patch（声明本插件在 profile 中的挂载行） |
+
+---
+
+## 2. 入口 / 装配层（**改这里要重点回归"隔离"**）
+
+| 文件 | 职责 | 关键导出 |
+|---|---|---|
+| `src/index.js` | 插件入口：两层装配（profile/preset）、作用域防重、挂载自证信号、能力面注册与失败回落 | `name, inject, apply, statusToolFor` |
+| `src/preset-delivery.js` | 预设交付（DSH 0.1.7+）：自定位 `file://` 行声明预设、健康度与隔离判定 | `PRESET_ID, selfPresetRow, presetDeclaration, declareAgentPreset, notePresetStatus` |
+| `src/commands.js` | `/ppt` 斜杠命令面（命令写入会话/项目状态） | `registerCommands` |
+| `src/state.js` | 状态：会话级（路由/档位）+ 项目级（`state.json`） | `sessionDir, loadSession, saveSession, loadProject` |
+| `src/home.js` | **DSH 用户目录解析的唯一实现**（`DSH_HOME` 口径） | `dshHome, pptStudioDir` |
+| `src/router.js` | 语义检测（是否 PPT 意图）+ **工作流提示词注入**（`workflowSection`，受基线超集断言保护） | `isPptIntent, detectTaskType, workflowSection, modeBrief` |
+| `src/skill.js` | 内置技能包通道（4 本手册的解析与暴露） | `SKILLS_DIR, listBundledSkills, parseManual` |
+
+> **改 `index.js` / `preset-delivery.js` / `router.js` 后必须跑**：`npm run test:scope`（真宿主隔离矩阵 22 条）+ `npm test`（含提示词超集与 quick 逐字节断言）。
+
+---
+
+## 3. 模型工具面
+
+| 文件 | 职责 | 关键导出 |
+|---|---|---|
+| `src/tools.js` | **22 个 `ppt_*` 工具**的注册、描述与输出文案（导出报告/门禁行/兜底说明都在这里） | `defineTool(s), resolveEngine, parsePagesArg` |
+| `src/scaffold.js` | 新手引导：`ppt_schema` 语法速查 + 一键样例工程 | `SCHEMA_REF, scaffoldProject` |
+| `src/capabilities.js` | 部署能力探测（捆绑 Python/Node、LibreOffice kit、官方 office 资产、primary-runtime 候选） | `detectCapabilities, findBundledPython, findAnyPython, resourcesFrom, primaryRuntimeRoots` |
+| `src/office-qa.js` | 官方 QA 通道：`check_office.py` 结构自证 + LibreOffice kit 渲染降级 | `runOfficeStructureCheck, runLibreOfficeRender, officeQaStatus` |
+
+> **改 `tools.js` 后必须跑**：`npm test`（大量断言直接匹配工具输出文案）+ `npm run audit:facts`（手册与工具描述的事实一致性）。
+
+---
+
+## 4. PPTD 中间层与引擎
+
+| 文件 | 职责 | 关键导出 |
+|---|---|---|
+| `src/pptd/schema.js` | **DSL 校验 + 归一化**（`SHAPE_KINDS` 白名单、`PATH_CMDS`、图表/表格/文本字段、`chartOptions()` 默认值唯一真相） | `SHAPE_KINDS, PATH_CMDS, validatePage, resolveDeck` |
+| `src/pptd/layout.js` | 布局数学：文本度量估算 + 元素归一化（渲染/导出/校验共用） | `measureText, textMetricsOf, TABLE_CELL_PT` |
+| `src/pptd/render-html.js` | 预览渲染器 + `layout.json`（渲染器同源快照） | `renderDeck` |
+| `src/pptd/export-pptx.js` | **导出主引擎**：手写最小 OOXML（含 parity 自证、内容级回读、原生图表接线） | `exportPptx, connectorEndsFromXml` |
+| `src/pptd/nativeChart.js` | 原生可编辑图表部件（`chartN.xml` + `_rels` + 内嵌 xlsx + 包级自证） | `nativeChartXml, embeddedWorkbook, auditNativeCharts` |
+| `src/pptd/svgCharts.js` | 图表模型与 SVG（预览与导出**同一**模型） | `chartData, resolveChart, chartSvg` |
+| `src/pptd/import-pptx.js` | PPTX → PPTD 导入（内容保真 + 参考层 + 组合拍平） | `importPptx` |
+| `src/pptd/loss-audit.js` | 导入损失审计（7 类不可保真特性 + 页码/元素级证据） | `auditLoss, lossAuditLine` |
+| `src/pptxPy.js` | python-pptx **兜底引擎**（捆绑 Python 优先） | `genPythonScript, findPython, runPythonExport` |
+| `src/zips.js` | 极简 ZIP 读写（store/deflate，基于内置 zlib） | `zipWrite, zipRead, decodeXml` |
+| `src/xmljs.js` | 极简 XML 解析（去命名空间标签树） | `parseXml, children, allText` |
+
+> **改 `export-pptx.js` / `schema.js` 后必须跑**：`npm run test:e2e`（端到端产物）+ `node scripts/verify-native-charts.mjs`（图表部件与数据一致性）+ smoke 里的 parity/内容自证分节。
+
+## 5. 校验 / 审阅
+
+| 文件 | 职责 | 关键导出 |
+|---|---|---|
+| `src/verify.js` | **门禁引擎**：重叠（按 role 分级）、出界分级、文本/表格溢出、对比度、美学建议 | `analyzePage, verifyDeck, aestheticSuggestions, themeConformance` |
+| `src/measurement.js` | M2 文本实测档：真渲染回读精确测量 | `measureLayout, extractMeasured` |
+| `src/crosscheck.js` | 内容审阅材料包（跨页正文/表格/图表数据 + 素材清单 + 审阅协议） | `crosscheckDeck, crosscheckReport` |
+| `src/autodeclare.js` | 一键声明（把警告级未声明重叠写入 `expectedOverlaps`） | `applyAutoDeclare` |
+| `src/imgmeta.js` | 图片元数据（读文件头取宽高/格式） | `imageInfo` |
+| `src/msrender.js` | Office 真渲染通道（PowerPoint COM → PNG） | `findPowerPoint, renderPptxToPng` |
+
+## 6. 交付 / 手术 / 模板
+
+| 文件 | 职责 | 关键导出 |
+|---|---|---|
+| `src/splice.js` | 保真交付：在原件上只换一页、其余页**逐字节不动** | `spliceIntoSource, sliceSource, zipDigests` |
+| `src/surgical.js` | 手术模式：以模板 .pptx 为底版做结构精确贴合 | `patchSlideXml, surgicalMap, slideOrderOf` |
+| `src/templates.js` | 模板库（内置 + 用户） | `listTemplates, templateDirOf` |
+| `src/preview-server.js` | 预览服务与路由注册（会话内看 PPT） | `buildPreview, registerPreviewRoute` |
+
+---
+
+## 7. 改动 → 该跑什么（速查）
+
+| 你改了 | 最小验证 | 批次边界/发版 |
+|---|---|---|
+| `docs/**`、`README`、`skills/**` | `npm run test:fast`（≈4–9s，跳过 smoke） | `npm test` |
+| `src/verify.js`、`src/autodeclare.js` | `npm test`（门禁断言集中在 smoke） | + `test:e2e` |
+| `src/pptd/export-pptx.js`、`schema.js` | `npm test` + `test:e2e` | + `verify-native-charts` |
+| `src/index.js`、`preset-delivery.js` | `npm run test:scope` + `npm test` | + `npm run fresh` |
+| `src/tools.js` | `npm test` + `npm run audit:facts` | + `test:release` |
+| `src/pptd/import-pptx.js`、`loss-audit.js` | `node scripts/verify-loss-audit.mjs` + `npm test` | + `test:e2e` |
+| `cordis.patch.yml`、`agent-presets/**` | `npm run test:preset` | + `npm test` |
+| 任意 `src/**` | `node scripts/build.mjs` + `npm run check:lib`（**必须**） | — |
+
+## 8. 新增模块的落位约定
+
+- 引擎/DSL 相关 → `src/pptd/`（纯函数优先，便于单测）
+- 门禁与审阅相关 → `src/verify.js` 或新增 `src/verify-*.js`
+- 工具面 = `src/tools.js` 注册 + 描述；**不要**把业务逻辑塞进 `tools.js`（它只做校验、调度与文案）
+- 能力探测/外部工具接入 → `src/capabilities.js` / `src/office-qa.js`
+- 每个新模块必须在 §4 或 §5 的表里出现一行（否则视为"没有地图的模块"）
+
+---
+
+## 9. 白名单纪律：新增 DSL 字段必须改**三处**（阶段 A 踩了三次的坑）
+
+归一化与快照都是**白名单式构造**（只挑自己认识的键），所以新字段不加进去就会**静默消失**——表现为"功能看着做了、跑起来全 0"。阶段 A 的 `contains/attach/badgeOf/roleReason/dash/arrow:'both'` 先后在这三处被吞：
+
+| # | 位置 | 后果 | 本次修法 |
+|---|---|---|---|
+| ① | `src/pptd/layout.js` `normalizePage` | 新字段不进归一化元素 ⇒ 预览/导出/校验全看不到；`arrow: !!el.arrow` 还会把 `'both'` **压成 `true`**（两端箭头失效） | 逐字段透传；`arrow` 原样透传 |
+| ② | `src/pptd/render-html.js` `snap()` | 字段不进 `layout.json` ⇒ **`ppt_verify`（吃 layout.json）里结构关系全为 0**，而性能数字照样好看 | 逐字段透传（含 `attachNotes`） |
+| ③ | `src/pptd/import-pptx.js`（导入侧写 DSL） | 参考稿里的组合/容器信息在导入产物里丢失（阶段 D 才完整做） | 阶段 D 处理；现在导入只写基础字段 |
+
+**纪律**：新增任何 DSL 字段时，同时改这三处 + 在 `scripts/smoke.mjs` §58 的"三处白名单透传"断言里加一行 + 在 `SCHEMA_REF`（`ppt_schema`，模型唯一的权威通道）里写一句。
+**守卫**：`smoke §58`（透传断言）、`scripts/bench-diagram-scale.mjs`（"结构关系被真的用到"断言——它正是抓到 ② 的那条）。
+
+---
+
+## 10. 阶段 A–D 新增模块速查（2026-09-28）
+
+| 模块 | 职责 | 关键导出 | 自证 |
+|---|---|---|---|
+| `src/pptd/relations.js` | 结构关系推导 + **几何反验证** + `attach` 解析；豁免不落盘 | `deriveRelations` / `checkDiagram` / `resolveAttach` / `usesStructure` / `onSide` / `rectOf` / `ATTACH_SIDES` | `scripts/verify-diagram-relations.mjs`（70/0） |
+| `src/pptd/style-profile.js` | 参考稿**观测 → 令牌 → theme**（阶段 D-①） | `observeFromDeck` / `observeFromLayout` / `extractStyleProfile` / `profileToTheme` | 同上第 6 节 |
+| `src/pptd/blocks.js` | 组合作为**可复用块**（copy 语义 + 引用重映射，阶段 D-②） | `materializeBlock` | 同上第 7 节 |
+
+
+### 10.1 泛用性补充（2026-09-29）
+
+| 模块/脚本 | 职责 |
+|---|---|
+| `src/pptd/line-rules.js` | **手写路径**的折线规则检查（`arrow-end-short-run` / `line-diagonal-segment`），`verify.js` 在**非门控**位置调用 ⇒ 所有页面（含自由发挥的手写图）都有机械反馈；`role: decoration` 可声明"刻意斜"豁免 |
+| `scripts/verify-handwritten.mjs` | `npm run verify:handwritten`：证明**手写路径是一等路径**——合法手写复杂图 0 错误 + 规则不误报 + 正反例 + 导出 parity（7/0） |
+
+
+

package/docs/10-/345/256/277/344/270/273/350/200/246/345/220/210/347/202/271/346/270/205/345/215/225.md

@@ -0,0 +1,49 @@
+# 10 · 宿主耦合点清单
+
+> 目的：我们把"命"押在宿主（DSH）的哪些具体行为上。**升级 DSH 时逐条核对本表**（配合 docs/05「宿主升级纪律」）。
+> 图例：**强**＝破了直接失效（有守卫）｜**中**＝破了会静默降级（需人工看）｜**弱**＝只是观察项。
+> 证据里的宿主行号对应 **DSH 0.1.7-rc.2**（npm 全局安装 + 桌面端 asar 两处内容一致）；换版本后行号可能漂移，**以行为特征为准**。
+
+---
+
+## 1. 装配与预设（最要紧的一组）
+
+| # | 耦合点 | 我们依赖的具体行为 | 我们的位置 | 宿主证据 | 破了会怎样 | 升级核对方式 |
+|---|---|---|---|---|---|---|
+| H1 | **预设注册表 API** | `ctx.agentPresets.register({id, name, plugins:[…]})` 声明式预设 | `src/preset-delivery.js` | `dsh-agent-preset-registry` | **强**：预设不出现；我们自动回落 profile 全局能力面（有自证） | `node scripts/verify-preset-scope.mjs`（22 条真宿主矩阵） |
+| H2 | **预设行的 baseUrl 语义** | 预设行按**注册表 ctx 的 baseUrl** 解析；名字不以 `.` 开头时 Loader **原样 `import(name)`** ⇒ 只有**绝对 `file://`** 能挂上 | `src/preset-delivery.js`（`selfPresetRow()`） | `dsh-agent-preset-registry/lib/index.js:534`；`cordis-plugin-loader/lib/index.js:219-226` | **强**：相对名/裸包名全部挂不上（历史踩过） | 真宿主启动看 `apply … tier=preset` 日志 |
+| H3 | **broken 判定与前端过滤** | 预设 `audit` 失败 ⇒ `record.broken`；前端新建会话时**过滤掉 broken 预设** | 同上 | `dsh-agent-preset-registry`（broken 写入与 `list()`）；`dsh-client-ui-agent-preset`（过滤） | **强**：预设从选择器里消失（负面对照已复现） | 故意写错路径，确认报"BROKEN + 行 id/URL" |
+| H4 | **tools 作用域链** | `register()` 落在**调用方 scope 的层**；读按 scope 链合并 | `src/tools.js`、`src/index.js` | `dsh-tools/lib/index.js:2878-2887`、`2959-2985` | **强**：能力泄漏到其它预设（隔离卖点没了） | `npm run test:scope`（标准预设 `ppt_*` 必须为 0） |
+| H5 | **skills 作用域** | 技能注册同样按 scope 分层 | `src/skill.js` | `dsh-skill/lib/index.js:193-215` | **强**：技能跨预设泄漏 | 同上（矩阵含技能一列） |
+| H6 | **`inject` 回调触发条件** | 部署**没有** `agentPresets` 服务时，声明失败路径的 `inject` 回调**根本不触发** | `src/index.js`（3s 兜底超时） | 行为特征：无回调 | **中**：不装预设的能力面永远等不到（已修：超时后回落） | 在无 agentPresets 的组合里启动，看是否回落 |
+| H7 | **DSH 版本门** | 0.1.7 起"预设=向注册表声明"（旧版扫磁盘目录） | `package.json` `dsh.engines.dsh` | 上游变更说明 | **中**：旧宿主上"装了也看不到预设" | 装机前读 `dsh.engines` 报错信息 |
+
+## 2. 运行期服务与传输
+
+| # | 耦合点 | 我们依赖的具体行为 | 我们的位置 | 宿主证据 | 破了会怎样 | 升级核对方式 |
+|---|---|---|---|---|---|---|
+| H8 | **`webServer.register` 同步契约** | 返回**非 Promise**（`1.1.1` 事故：`.then is not a function`） | `src/preview-server.js` | `dsh-web-app` 的 webServer 服务 | **强**：桌面端插件激活失败 | 真宿主启动无 `did not activate` |
+| H9 | **工具呈现模式（PTC/both）** | `presentAs(mode)` 公开；但 `modeFor` 是 **private**（我们**读不到**当前模式，只能间接推断）；`both` 下原生 schema 仍全在、`run_code` 只是**追加**；纯 `ptc` 下直接调其它工具会 `UNKNOWN_TOOL`；子调用 id 形如 `<parent>:ptc:<n>` | 未来若做 PTC 才用 | `dsh-tools/lib/types/index.d.ts:587`（private）、`:609`（presentAs）；`lib/index.js:3100`（UNKNOWN_TOOL 判据）、`:1298`（子调用 id） | **弱/观察项**：我们暂不启用 PTC（docs/07 决策） | 若将来启用：重读 `dsh-tools` 的 mode 相关实现与 id 命名 |
+| H10 | **子代理 / 团队服务** | `subagent` / `list_agents` / 任务看板等由宿主组合提供 | 未见直接调用（我们只按需手动用） | `dsh-tool-subagent*` | **弱** | — |
+
+## 3. 目录、运行时与外部工具
+
+| # | 耦合点 | 我们依赖的具体行为 | 我们的位置 | 证据 | 破了会怎样 | 升级核对方式 |
+|---|---|---|---|---|---|---|
+| H11 | **`DSH_HOME` 与 profile 布局** | 用户数据在 `<DSH_HOME>/profiles/<name>/{package.json,node_modules}`；`dsh.profile.bundles` 决定自动入栈 | `src/home.js`、`cordis.patch.yml` | 实测（安装自证脚本） | **强**：找不到自己的状态目录 | `npm run test:bundle` |
+| H12 | **`resources` 布局与 asar 锚点** | `<install>/resources/{app.asar, app.asar.unpacked, runtime/office-skills}`；插件可能跑在深层子进程 node 中 ⇒ 需**逐级上溯** | `src/capabilities.js`（`resourcesFrom`） | 桌面端实测 | **中**：探不到官方资产 ⇒ 静默少掉第三方自证 | 桌面端跑 `ppt_state` 看 `capabilities` |
+| H13 | **primary-runtime 安装副本** | `<DSH_HOME>/dsh-runtimes/dsh-primary-runtime/**`（含 Python 与 Node） | `src/capabilities.js`（`primaryRuntimeRoots`） | 桌面端实测 | **中**：兜底引擎退回 PATH python（可能没有 python-pptx） | 同上 |
+| H14 | **LibreOffice kit CLI 契约** | 子命令 `capabilities/convert/recalculate/render`；**输出目录必须不存在**（预建会 `EEXIST`）；`manifest.json` 提供 `images[].page`（原页号）与 `missingFonts` | `src/office-qa.js` | 桌面端实测（本轮踩过 EEXIST） | **中**：无 Office 时的真渲染降级失效 | 跑 `runLibreOfficeRender` 并检查 manifest |
+| H15 | **官方 `check_office.py` 契约** | 位置 `<assets>/scripts/check_office.py`；`INPUT [--contains T] [--count N]`；stdout JSON `{format, verdict, checks, summary}`；退出码 0/1/2 | `src/office-qa.js` | 桌面端实测（verdict=pass） | **中**：第三方结构自证消失（会如实打印"未执行"） | 同上 |
+| H16 | **捆绑 Python / Node 路径** | `<runtime>/dependencies/python/python.exe`、`…/node/node.exe` | `src/capabilities.js`、`src/pptxPy.js` | 桌面端实测 | **中**：兜底引擎与 kit 调用退化 | 看 `findPython()` 的 `source=bundled:*` |
+| H17 | **技能目录约定** | `<plugin>/skills/<name>/SKILL.md`（front-matter + 正文；≤8000 字由我们自守） | `src/skill.js` | 宿主技能加载行为 | **强**：技能加载失败 | `npm test`（技能分节 + 字数断言） |
+| H18 | **profile 管理权归属** | **`desktop` profile 由 Electron 应用独占**，CLI 明确拒绝 `--profile desktop` | 文档与流程 | CLI 实测报错 | **中**：桌面端只能走应用内插件管理或手动 pnpm | 见 docs/05「发布-同步纪律」 |
+
+## 4. 外部依赖（非宿主，但同样会咬人）
+
+| # | 依赖 | 行为 | 位置 | 破了会怎样 |
+|---|---|---|---|---|
+| E1 | **npm Trusted Publishing（OIDC）** | release 事件触发 → 下载 Release 资产 → OIDC `npm publish` → 发后自证 integrity；**无长期 token** | `.github/workflows/publish.yml` | 发布链路断（有手工补发入口） |
+| E2 | **pnpm `minimumReleaseAge`（默认约 12h）** | 按名安装/更新会被窗口挡住；卸载时也可能因 lockfile 校验被拒 | 流程 | 安装/卸载都要绕：`--config.minimumReleaseAge=0`（卸载）或本地 tgz |
+| E3 | **PowerPoint COM** | 真渲染通道依赖本机 Office | `src/msrender.js` | 降级到 LibreOffice kit（引擎不同，报告会标注） |
+| E4 | **Node 内置模块** | 只用 `node:*`（无运行时依赖是纪律） | 全仓 | 新增依赖属"破坏纪律"，需用户批准 |

package/docs/11-/346/234/257/350/257/255/350/241/250.md

@@ -0,0 +1,42 @@
+# 11 · 术语表
+
+> 目的：跨文档/跨会话统一用词。**新增术语先加到这里再使用**（尤其图子系统开工后）。
+> 用法：文档里第一次出现某术语时，可回指本表条目号。
+
+| # | 术语 | 含义 |
+|---|---|---|
+| 1 | **PPTD** | 本插件自研的中间层（`deck.yaml` + `pages/*.yaml` + 主题），介于"模型写的结构"与"OOXML 产物"之间 |
+| 2 | **DSL** | 上述中间层的写法规则（由 `src/pptd/schema.js` 校验） |
+| 3 | **元素（element）** | DSL 里的最小绘制单元：`text / shape / line / image / table / chart` |
+| 4 | **页面（page）** | 一页幻灯片；含 `elements`、可选 `groups`、声明字段与讲稿 |
+| 5 | **引擎 A / pptd 引擎** | 我们手写 OOXML 的导出主引擎（`src/pptd/export-pptx.js`） |
+| 6 | **引擎 B / 兜底引擎** | python-pptx 兜底（`src/pptxPy.js`），主引擎硬失败时自动降级并标注 |
+| 7 | **IR（中间表示）** | 图子系统的**结构描述层**（阶段 B 引入）：声明"有什么节点/关系/层次"，几何由布局引擎算 |
+| 8 | **结构关系** | 图子系统里的类型化关系：`contains`（包含）/ `attach`（附着）/ `badgeOf`（徽章归属）/ `groups`（组合） |
+| 9 | **组合（group）** | 用户工作方式中的"把若干元素当一个整体"；既用于剪枝/审阅，也用于导出真 `grpSp`（阶段 A 第二步） |
+| 10 | **块（block）** | 可复用的组合（局部坐标 + 参数）；复用默认 **copy 语义**，不做隐式联动 |
+| 11 | **声明（declaration）** | 设计期显式写下的意图：`expectedOverlaps`（有意重叠）/ `expectedOutOfSafeArea`（有意出安全区）/ `role` 覆盖（附 `roleReason`）/ 结构关系 |
+| 12 | **豁免（exempt）** | 因**有效声明或结构关系**而不报冲突的对；**推导出的豁免不落盘**（每次现算） |
+| 13 | **剪枝 ≠ 豁免** | 包围盒只能用来**排除候选**；剩下的必须落到元素级真实判断，否则是假阴性 |
+| 14 | **几何反验证** | 对每条声明按几何实测核对（"声称包含"就实测真包含）；不成立 ⇒ 声明作废并按冲突报 |
+| 15 | **门禁（gate）** | `ppt_verify` 的结论；ERROR 必须清零才能交付 |
+| 16 | **冲突分级** | `content-collision`（内容互压，**永不可声明**）｜warning 级"设计预期外重叠"（可声明）｜超页面（**永不可声明**）｜超安全区（声明制） |
+| 17 | **role** | 层叠角色：`background / content / decoration`；`decoration` 完全豁免重叠报告 |
+| 18 | **autoDeclare** | 把警告级未声明重叠批量写入 `expectedOverlaps` 的一键操作 |
+| 19 | **parity** | 导出后自证：期望 vs 产物（表/图/线/媒体/文本内容/图表部件/组/关系…），全部进 `parity.ok` |
+| 20 | **内容级回读** | 从产物 OOXML 反推"该写的字/该画的图形在不在"，而不是读中间层 |
+| 21 | **参考层** | `ppt_import` 保留的原始 pptx + 真渲染预览 + 色板，供"先看后做" |
+| 22 | **样式档案** | 从 `$theme` 或参考稿提取的样式令牌（配色/圆角/线宽/字号阶梯/间距基数），图的风格来源 |
+| 23 | **手术（surgery）** | 三类保真交付：`ppt_patch`（XML 级换文字）/ `ppt_splice`（只换一页，其余页逐字节不动）/ `ppt_slice`（单页独立版） |
+| 24 | **loss-audit** | 导入时的"重建有损"审计：动画/阴影/超链接/切换/SmartArt/不可嵌入媒体/主题渐变 |
+| 25 | **crosscheck** | 内容审阅材料包（跨页正文/表格/图表数据 + 素材清单 + 审阅协议），供模型判定四分类 |
+| 26 | **P1 铁律** | 真渲染抽检铁律：含 table/chart/image/custGeom 的页必须真渲染 + 读图审阅 |
+| 27 | **自证** | 由产物/真渲染反推结论的机器化证明（parity、内容级回读、官方 `check_office.py`、`git bundle verify` 式校验） |
+| 28 | **隔离（isolation）** | 能力面只在「PPT 工作室」预设作用域注册；`scope: preset` 默认，`scope: profile` 为旧全局行为 |
+| 29 | **装配档（tier）** | `profile`（插件随 profile 挂载）｜`preset`（随预设作用域挂载）；`assembly.tier` 可查 |
+| 30 | **快测 / 全量 / 发版档** | `test:fast`（改动即跑）｜`npm test`（批次边界）｜`test:release`（发版，并行全档） |
+| 31 | **硬门槛** | 阶段 A 起生效的四条量化门：确定性（两次导出逐字节一致）｜性能基线｜判据严格性与图进 parity｜常驻 token 增幅 ≤5% |
+| 32 | **回归门** | 无图页产物逐字节不变、提示词只增行、既有断言全绿、隔离矩阵不变；任一破 ⇒ 回滚该阶段 |
+| 35 | **北极星场景** | "给一份已有复杂图的 ppt，再加一页同风格复杂图"：import（参考+样式）→ IR → 布局 → splice |
+| 36 | **审阅锚点** | 判断可信度的外部依据：可机械反查 → 门禁｜可证据核验 → 抽样复核｜纯审美 → 用户 |
+| 37 | **缝合页** | IR 生成的块与手写元素混排、但未共享同一套约定 ⇒ "每件都不差、合起来不像一套" |

package/docs/12-/345/244/215/346/235/202/345/233/276/351/200/232/350/267/257/347/232/204/351/200/211/346/213/251/344/270/216/351/252/214/346/224/266.md

@@ -0,0 +1,65 @@
+# 复杂图通路的选择与验收
+
+> 本文记录**为什么本插件采用「手写显式 elements + 门禁」这条通路**、它的等价性证据，以及回归基线机制。
+> 早期设计记录中的方法论资产（真问题清单 / 止损判据 / 机械量化）摘录于文末。
+
+## 1. 选择的通路
+
+- 页面只用**显式 `elements`**：`shape`/`text`/`line`/`image`/`table`/`chart` + `bounds`/`points`/`kind`/`contains`/`attach`/`role`/`roleReason`；
+- 引擎提供**机制**而不是模板：折线正交化、箭头前直段 ≥18px、`attach` 锚真实边缘（含斜边）、结构关系反验证、全部门禁检查；
+- **不引入编译器**：没有"结构输入 → 自动布局"的一层。几何由作者显式给出，引擎只做后处理与校验。
+
+## 2. 为什么不做编译器
+
+- 编译器只能覆盖**枚举过的图形**；枚举之外要么降级、要么半成品 ⇒ 泛用性有硬上限；
+- 一套编译器要自带审美与布局策略，改画法就得改代码 ⇒ 维护面扩大；
+- 显式元素的表达力是**上界**：任何能被编译器产出的图，都能被显式元素写出来（反之不成立）；
+- 代价（如实）：没有编译器 ⇒ 每页的坐标由作者给出，单页成本更高、批量大 deck 更慢。
+
+## 3. 等价性证据（同内容严格对照）
+
+| 判定 | 页数 | 说明 |
+|---|---|---|
+| 更好 | 10 | 02 03 04 05 07 09 10 11 12 13 |
+| 持平 | 1 | 06 |
+| 风格取向不同 | 2 | 01（是否加分组容器）、08（环用卡片还是真圆+编号点）—— **风格选择，不视为缺陷** |
+| 变差 | **0** | —— |
+
+门禁：13 页 **0 错**；机制（正交化/≥18px/attach/结构声明/检查）与既有实现**共用同一份代码**。
+
+## 4. 回归基线机制
+
+- `scripts/fixtures/handdrawn-baseline.json`：每页「元素 id+类型+圆整 bounds/points」规范化 JSON 的 sha256 + 每页错警计数 + 13 张 PNG sha；
+- `npm run verify:handdrawn`：与基线比对（硬不变量 = layout 摘要；PNG sha 为次要不变量，差异只警告）；
+- 几何若**确需变更**：`verify-handdrawn.mjs --capture --reason "原因"` ⇒ 保留 `history` 数组留痕（不许静默改基线）；
+- 另三条手画护栏并入 `npm test`：`verify:redprobe`（6 条）/ `verify:linetext`（3 条）/ `verify:optionprobe`（2 条）。
+
+## 5. 摘录：早期设计记录中的方法论资产
+
+## 6. 结构关系自动产出（阶段 A 的地基在这里被"用起来"）
+
+| 关系 | 谁产出 | 说明 |
+|---|---|---|
+| `groups[]` | IR 的 `groups` | id 加前缀；成员 = 节点 id（含嵌套时按 IR 层次） |
+| `element.contains[]` | 每个 `groups` 条目产出一个**容器 shape**，声明包含其成员 | 容器是几何真实的（包住成员，pad ≥ 6），因此几何反验证必然通过 |
+| `element.attach{from,to}` | 每条 `edges` 产出一条 line，两端锚到节点边 | 方向决定 `side`（LR：右→左；TB：下→上）；因此**箭头必然落边**（阶段 A 的 `arrow-not-on-edge` 永不触发） |
+| `expectedOverlaps` | 仅当引擎确实产出有意重叠时（本阶段：无） | 引擎不靠声明掩盖自身几何问题 |
+
+**这条是阶段 B 的核心收益**：结构关系不再是"用户手写 + 引擎事后验证"，而是"引擎产出 + 用户可改"。
+
+## 8. 硬门槛与回归门（沿用阶段 A 的四条 + 阶段 B 专属）
+
+1. **确定性**：同一 deck 两次导出除 `core.xml` 时间戳外逐部件一致（含 IR 展开的 id 编号）；
+2. **性能**：150 元素基线不退化（`scripts/bench-diagram-scale.mjs`）；新增"含 IR 的 150 节点页"基线（阶段 C 用）；
+3. **判据严格性**：IR 校验与布局不变量的负面对照必须报红（自证脚本）；
+4. **prompt 增幅 ≤5%**：`npm run probe:prompt:check`（阶段 B 若新增工具/参数必须复测）；
+5. **无图页产物逐字节不变**：无 `diagram` 的页沿用阶段 A 的门控（`usesStructure`）与基线 tag 对照；
+6. **预览↔成品同源**：由 §5 的结构保证（零改动）——自证脚本断言"预览 layout.json 的元素 == 导出消费的元素"。
+
+## 4. C1 过程中被机械判据抓出的真问题（值得后续复用）
+
+1. **组容器与"组内折线"相交**：树的肘形连线 AABB 有高度 ⇒ 与容器判为意外重叠。修法：分组容器把**两端都在组内**的连线也纳入 `contains`（轴对齐直线 AABB 高度为 0，本来不受影响）。
+2. **矩阵标题跑到安全区外**：标题原本放在 `box.y - 24`；改为**占画布内一条**（`titleH`）并把网格下移。
+3. **断言侧**：IR 产出的 `line` **没有 `bounds`**（由 points 推导，schema 允许）⇒ 断言里必须自己按 points 求 AABB，否则每条线都被误判"越界"（真实门禁走的是正确路径，未受影响）。
+
+---

package/docs/13-/345/217/221/347/211/210/345/207/206/345/244/207/350/256/241/345/210/222.md

@@ -0,0 +1,79 @@
+# 发版准备计划（就绪但不发）
+
+> **两条硬约束**
+> 1. **不执行**版本号提升、打发布标签、发布到 registry —— 一律**等用户明确指令**（本计划只做到"就绪"）。
+> 2. 本文**不复述已移除的开发期方案的名字**（遵守仓库可见文本约束：`src`/`scripts`/`docs`/`skills`/`agent-presets`/`examples`/根目录的可见文本里该方案痕迹为 **0**）。
+> **纪律**：每阶段一个独立提交、每阶段留回滚点；判据不绿就停在该阶段并**如实报告**，不硬推。
+
+## 0. 当前已绿（无需动作，只待复跑）
+`npm test` **322/0** ✓（含生成器检查网 9/9 ✓、四条手画护栏 ✓）｜13 页手画 **0 错** ✓、40 条警告**已逐条处置**（`docs/17` ✓）｜layout 摘要与 13 张 PNG 与基线一致 ✓｜LF 317 文件 ✓｜`src` ⟷ `lib` **39/39 字节相同** ✓｜preset 漂移 0 ✓。
+
+---
+
+## P1 代码与守卫（不需要用户输入）
+
+| # | 事项 | 判据 |
+|---|---|---|
+| P1-1 | 新增 **`unknown-key` warning**：页面级/元素级**未知键** ⇒ warning（不阻断 ✓），覆盖拼写错误与残留字段 | **先红后绿**：造一条含未知键的夹具 ⇒ 必须报出；合法键（contains/attach/badgeOf/role/roleReason/expectedOverlaps/groups/blocks/notes/title/pageType/elements）**一个都不许误报** ✓ |
+| P1-2 | 新增 **`check-lib-sync`**（`lib` ⟷ `src` 文件集合相同 + 逐字节相同）并进 `npm test` | 造一次人为不同步 ⇒ **必须报红** ✓；恢复后全绿 ✓ |
+| P1-3 | 清理过期注释：`blocks.js` 里提到已移除方案的注释（`src` 与 `lib` 各一处） | 全仓扫描该方案痕迹 **= 0** ✓ |
+| P1-4 | （可选）给生成器加 **`--dry` 通道**（只生成 YAML + 跑门禁，不导出）并进 `npm test` | 它能抓住"缺省路径崩"这类**运行期**错误（现有检查只有语法级 ✓） |
+| P1-5 | **全仓扫描**（含根目录 `README.md`、`cordis.patch.yml`、`templates/`、`vendor/`）—— 上一轮只扫了 6 个目录 ✗ | 该方案痕迹 **= 0** ✓ |
+
+## P2 验证加固
+
+| # | 事项 | 判据 |
+|---|---|---|
+| P2-1 | 冻结复跑：`npm test` + `verify:handdrawn` + 四条护栏 | 全绿 ✓、摘要与基线一致 ✓ |
+| P2-2 | 把**产物一致性**固化：导出（非锁定名 ✓）→ 渲染 13 PNG → 与基线比对，作为一条可复跑命令 | 一次跑通；PNG sha 13/13 一致（或以 `--reason` 留痕的显式差异 ✓） |
+| P2-3 | 基线 `history` 校验：确认每次变更都有 `reason` 与 `previousDigest` | 用 `node -e` 断言 `history` 非空且条目含 reason ✓ |
+
+## P3 打包与安装一致性
+
+| # | 事项 | 判据 |
+|---|---|---|
+| P3-1 | `npm pack` 内容断言：必含 `lib`、`skills`、`agent-presets`、`docs`、`templates`、`vendor`、`cordis.patch.yml`、`README.md` | 逐项存在 ✓ |
+| P3-2 | 装到**干净临时目录** → `require('<pkg>/lib/index.js')` 可用 → 包内**不含**已移除方案的任何痕迹 | 三项全过 ✓ |
+| P3-3 | `files` 白名单复核：确认 `examples/hand-drawn`（手画回归语料）**不入包** ⇒ 文档写明"该回归只在仓库内可跑" | 结论写入 `docs/03` 已知限制 ✓ |
+| P3-4 | preset 漂移检查复跑（`check-preset`） | 漂移 0 / 缺行 0 / 有意差异 1 ✓ |
+
+## P4 文档
+
+| # | 事项 |
+|---|---|
+| P4-1 | `docs/09-代码地图与模块职责.md`：修复上轮"删行"后可能出现的**表格缺列/断行**（P1-5 扫描同时核对） |
+| P4-2 | `docs/07-复杂图能力立项与风险登记.md`：修复删行留下的**段落断口**（列表项悬空等） |
+| P4-3 | `skills/diagram-drawing/pitfalls.md`：补 **F 组五条流程坑**（清 fixture 只用 `examples/smoke`／参数化必测缺省路径／改基线必留痕／破坏性脚本先只读定位／先打印现场再动手） |
+| P4-4 | `skills/diagram-drawing/mechanisms.md`：写入**门禁原则**（只锁事实与声明自洽；风格与表达取向不入门禁）+ 把 `unknown-key` 登记进 §2 code 对照表 |
+| P4-5 | `docs/03-更新日志.md`：补写**本轮条目**（标 `[下一版 · 待发]` ✓，**不写版本号生效** ✗）+ **已知限制**段（见 §6） |
+| P4-6 | 交付物侧 `手画12+1/结论表.md`：口径修正为"**机制等价 + 0 页变差 + 2 页风格取向不同**" ✓ + 页 04 五条警告的最终处置（内容层面、不涉插件 ✓） |
+| P4-7 | `README.md` 与根目录文件核查（上一轮未扫 ✗）：不得描述已移除方案；如需补一句"复杂图用手写 elements"✓ 则补 |
+
+## P5 就绪（到此为止，**不发**）
+
+| # | 事项 | 判据 |
+|---|---|---|
+| P5-1 | 全量判据复跑并**原文落屏**归档 | 全绿 ✓ |
+| P5-2 | 产出**发布清单草稿**（不执行 ✓）：要改哪一行（`package.json` 版本）、打哪个标签、发布说明全文（含已知限制 ✓） | 草稿写入 `docs/03` 的 `[下一版 · 待发]` 段 ✓ |
+| P5-3 | 打一个**回滚点**标签 `pre-release`（中性名 ✓） | 存在 ✓ |
+| P5-4 | 明确**停在这里**：等用户指令 ✓ | 报告中写明 ✓ |
+
+## P6（**等用户指令**才做）版本与发布
+
+`package.json` → 用户指定版本号（默认 1.2.0）✓ → `docs/03` 把 `[下一版 · 待发]` 定为正式版本 ✓ → 打标签 `v<版本>` 并 push ✓ → 如需发布到 registry 则 `npm publish`（含凭据确认 ✓）→ 发布说明对外 ✓。
+
+---
+
+## 6. 已知限制（发布说明必须写 ✓）
+
+1. **无逐形状样式**（阴影/高光/笔触）；开发期的强样式控制选项已随回滚移除，本版不具备；
+2. **手画无编译器** ⇒ 几何由作者显式给出：单页成本更高、批量大 deck 更慢；
+3. 生成器检查目前是**语法级**（若不采纳 P1-4，则运行期类错误仍可能漏网）；
+4. **13 页手画回归语料不随包发布** ⇒ `verify:handdrawn` 只在仓库内可跑；
+5. 门槛：`npm test` 需要仓库（`src` 不在包内，包内只发 `lib`）。
+
+## 7. 回滚与纪律
+
+- 每阶段独立提交；阶段前打 `pre-<阶段>` 标签；判据不绿 ⇒ 自动 `git reset --hard` 回到该点 ✓；
+- 破坏性操作一律"**先只读定位、全量断言、再动手**"（本项目实测拦下多次失败、零损失 ✓）；
+- 警告必须逐条有处置结论（`docs/17` ✓），**不许用声明掩盖真缺陷** ✓，**不许让风格取向变成 error** ✓。

package/docs/14-/345/217/221/345/270/203/346/270/205/345/215/225/357/274/210/350/215/211/347/250/277/357/274/211.md

@@ -0,0 +1,37 @@
+# 发布清单（草稿 · P6 待用户指令）
+
+> **本文件只描述"怎么做"，不含任何已执行动作** ✓。P6 全部步骤等用户明确指令后才执行。
+
+## 1. 要改的那一行（唯一）
+
+`package.json` 的 `"version": "1.1.5"` ⇒ 用户指定版本号（默认建议 **1.2.0**，因为本版是**加能力**：复杂图通路定稿 + 新门禁 + 七个守卫 + 两条本机命令 + 基线留痕机制；**无破坏性变更** ✓）。
+
+**不要动** `files`（已复核：`lib/templates/docs/skills/scripts/agent-presets/cordis.patch.yml/examples/smoke/examples/fx/README.md` ✓，过期项 `vendor` 已清 ✓）。
+
+## 2. 打标签
+
+`git tag -a v<版本> -m "<一句话>"` ⇒ `git push origin main && git push origin v<版本>`。
+
+## 3. 发布到 registry（如走 npm）
+
+`npm publish`（`publishConfig.access = public` ✓）。发布前必须先跑：`npm test` ✓、`npm run verify:products` ✓（本机专用，需 PowerPoint）、`npm run verify:package` ✓。
+
+## 4. 发布说明（可直接用）
+
+**本版要点**
+- 复杂图统一走**手写显式 elements + 机制**：`attach` 锚真实边缘（含斜边）、折线自动正交化、箭头前直段 ≥18px、结构关系反验证；引擎不引入编译器。
+- 新增门禁 `line-cross-text`（线 × 文字碰撞）。
+- 并入 `npm test` 的守卫：13 页回归基线（layout 摘要 + 错警计数 + PNG sha）、红样本 6 条、线×文字 3 条、选项探针 2 条、生成器语法、`lib` ⟷ `src` 逐字节、未知键 warning。
+- 本机专用命令：`npm run verify:products`（重出 → 导出 → 渲染 → 与基线比对）、`npm run verify:package`（打包与安装一致性）。
+- 回归基线引入 `history` + `--reason`：**改基线必须留痕**，且由断言强制。
+
+**已知限制（请一并告知用户）**
+1. 无逐形状样式（阴影/高光/笔触）；开发期的强样式控制选项未纳入本版。
+2. 手写几何由作者给出 ⇒ 单页成本更高、批量大 deck 更慢。
+3. 生成器检查为**语法级**（运行期类错误仍可能漏网）。
+4. 13 页手画回归语料**不随包发布** ⇒ 该回归只在仓库内可跑；包内只发 `lib`。
+5. 门禁的 `unknown-key` 目前是**测试链守卫**，尚未进入每页门禁报告。
+
+## 5. 发布后
+
+确认装出来的包可用（`npm run verify:package` 已覆盖"装到干净目录 → `require` 可用"）；如需回滚，回滚点标签：`pre-P1`／`pre-P1b`／`pre-P2`／`pre-P3`／`pre-P4`／`pre-P5`／`pre-release` ✓。

package/docs/17-/346/211/213/347/224/27313/351/241/265/350/255/246/345/221/212/351/200/220/346/235/241/345/244/204/347/275/256.md

@@ -0,0 +1,102 @@
+# 手画 13 页警告逐条处置（实测生成）
+
+> 数据来自 `verifyDeck` 实测（2026-09-29T16:35:47.179Z）；总计 **47 条**，门禁错误 **0 条** ✓。
+> 生成脚本方式：解析 `examples/hand-drawn` → `renderDeck` → 逐页 `verifyDeck` → 汇总（可复跑）。
+
+## 1. 按 code 汇总与处置
+
+| code | 条数 | 处置 |
+|---|---|---|
+| `line-diagonal-segment` | 10 | **待评估** ✗ |
+| `hotspot` | 9 | **建议级** —— 密集区评审提示，非缺陷 ✓ |
+| `density` | 7 | **建议级** —— 元素密度提示，非缺陷 ✓ |
+| `line-end-off-edge` | 7 | **待评估** ✗ |
+| `arrow-tip-inside-shape` | 5 | **待用户定 A/B** —— 读图确认为"箭头贴边 + 头部长度容差"，视觉正常 ✓；A=加 roleReason 声明（推荐）／B=端点外移（箭头将不再接上 ✗） |
+| `attach-override` | 5 | **保留（信息性）** —— attach 覆盖了手写坐标；这是引擎在**按真实边缘纠偏**，正是我们想要的 ✓ |
+| `arrow-end-short-run` | 3 | **已修** —— 04 页卡距 28→40px 后归零 ✓ |
+| `line-crossing` | 1 | **待评估** ✗ |
+
+## 2. 逐条清单
+
+| # | 页 | code | 元素 | 摘要 |
+|---|---|---|---|---|
+| 1 | 01 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,1)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 2 | 01 | `hotspot` | density | 密集区（5 个元素）位于网格 (1,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 3 | 01 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 4 | 02 | `density` | page | 页面含 13 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 5 | 03 | `line-end-off-edge` | — | ml0 的端点离 "md0" 还有约 4px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 6 | 03 | `line-end-off-edge` | — | ml2 的端点离 "md2" 还有约 4px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 7 | 03 | `line-end-off-edge` | — | ml4 的端点离 "md4" 还有约 4px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 8 | 03 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 9 | 03 | `density` | page | 页面含 14 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 10 | 04 | `arrow-tip-inside-shape` | — | a0 的箭头端点落在 "lb3" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 11 | 04 | `arrow-tip-inside-shape` | — | a1 的箭头端点落在 "lb1" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 12 | 04 | `arrow-tip-inside-shape` | — | a2 的箭头端点落在 "lb2" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 13 | 04 | `arrow-tip-inside-shape` | — | a3 的箭头端点落在 "lb3" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 14 | 04 | `arrow-tip-inside-shape` | — | a4 的箭头端点落在 "lb0" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 15 | 04 | `hotspot` | density | 密集区（6 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 16 | 04 | `density` | page | 页面含 12 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 17 | 05 | `hotspot` | density | 密集区（7 个元素）位于网格 (1,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 18 | 05 | `hotspot` | density | 密集区（7 个元素）位于网格 (4,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 19 | 05 | `density` | page | 页面含 13 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 20 | 06 | `line-diagonal-segment` | — | c0: 折线第 1 段是斜段（Δx=102 Δy=39）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleR |
+| 21 | 06 | `line-diagonal-segment` | — | c1: 折线第 1 段是斜段（Δx=59 Δy=96）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 22 | 06 | `line-diagonal-segment` | — | c3: 折线第 1 段是斜段（Δx=59 Δy=96）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 23 | 06 | `line-diagonal-segment` | — | c4: 折线第 1 段是斜段（Δx=102 Δy=39）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleR |
+| 24 | 08 | `line-diagonal-segment` | — | c0: 折线第 1 段是斜段（Δx=41 Δy=10）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 25 | 08 | `line-diagonal-segment` | — | c1: 折线第 1 段是斜段（Δx=30 Δy=69）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 26 | 08 | `line-diagonal-segment` | — | c2: 折线第 1 段是斜段（Δx=70 Δy=45）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 27 | 08 | `line-diagonal-segment` | — | c4: 折线第 1 段是斜段（Δx=70 Δy=45）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 28 | 08 | `line-diagonal-segment` | — | c5: 折线第 1 段是斜段（Δx=30 Δy=69）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 29 | 08 | `line-diagonal-segment` | — | c6: 折线第 1 段是斜段（Δx=41 Δy=10）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 30 | 09 | `line-crossing` | — | life2 与 m3 在 (565, 345) **交叉**（+ 型：两条都穿过对方）—— 给其中一条换车道/换进出边（或调换路由顺序）后重跑本门禁；若刻意交叉示意汇流，给该线加 roleReason 声明即静默 |
+| 31 | 09 | `line-end-off-edge` | — | life0 的端点离 "ht0" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 32 | 09 | `line-end-off-edge` | — | life1 的端点离 "ht1" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 33 | 09 | `line-end-off-edge` | — | life2 的端点离 "ht2" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 34 | 09 | `line-end-off-edge` | — | life3 的端点离 "ht3" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 35 | 10 | `hotspot` | density | 密集区（6 个元素）位于网格 (4,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 36 | 10 | `density` | page | 页面含 17 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 37 | 12 | `arrow-end-short-run` | — | ar0: 箭头终点紧邻的直线段只有 16px（建议 ≥ 18px）—— 拐点贴着箭头时箭头像"断的"、看不出指向；把拐点往外挪，或用 attach: {ref, side} 让引擎把端点锚到元素边上 |
+| 38 | 12 | `arrow-end-short-run` | — | ar1: 箭头终点紧邻的直线段只有 16px（建议 ≥ 18px）—— 拐点贴着箭头时箭头像"断的"、看不出指向；把拐点往外挪，或用 attach: {ref, side} 让引擎把端点锚到元素边上 |
+| 39 | 12 | `arrow-end-short-run` | — | ar2: 箭头终点紧邻的直线段只有 16px（建议 ≥ 18px）—— 拐点贴着箭头时箭头像"断的"、看不出指向；把拐点往外挪，或用 attach: {ref, side} 让引擎把端点锚到元素边上 |
+| 40 | 12 | `density` | page | 页面含 12 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 41 | 13 | `attach-override` | — | l0: from 端手写坐标 [256, 275] 与 attach 解析结果 [241, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 42 | 13 | `attach-override` | — | l1: from 端手写坐标 [256, 275] 与 attach 解析结果 [241, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 43 | 13 | `attach-override` | — | l2: from 端手写坐标 [256, 275] 与 attach 解析结果 [241, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 44 | 13 | `attach-override` | — | l3: from 端手写坐标 [628, 275] 与 attach 解析结果 [608, 275] 不一致（相差 20.0px）⇒ 按 attach 覆盖 |
+| 45 | 13 | `attach-override` | — | l3: to 端手写坐标 [688, 275] 与 attach 解析结果 [703, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 46 | 13 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 47 | 13 | `density` | page | 页面含 13 个内容元素（文本/表格/图表），信息密度可能过高 |
+
+## 3. 结论
+
+- 门禁**错误 0 条** ✓；47 条全部为**警告**（含信息性与建议级 ✓）。
+- 处置未覆盖的 code：line-end-off-edge, line-diagonal-segment, line-crossing ✗（需补结论）
+- 唯一未决项：第 04 页 `arrow-tip-inside-shape` **5 条** ⇒ 需用户选 A/B（见上表 ✓）。
+
+## 4. 补充处置（第 14 轮审计完成，逐条已分类 ✓）
+
+| code | 条数 | 逐条明细与结论 |
+|---|---|---|
+| `arrow-end-short-run` | 3 | **真缺陷 ✗ 需修**：页 12 `ar0/ar1/ar2` 箭头前直段 **16px**（教义 ≥18px ✓）⇒ 把拐点外移 2–4px 即可；**这是本轮唯一必须改几何的项** ✓（会改变 layout 摘要 ⇒ 按流程**记录变更原因**后更新基线 ✓） |
+| `line-end-off-edge` | 4 | 页 09 `life0..life3` 生命线端点离头部盒 **12px** ✗ ⇒ **真缺陷（轻微）✗ 需修**：生命线应起于头部盒下边 ✓ |
+| `line-end-off-edge` | 3 | 页 03 `ml0/ml2/ml4` 引出短线离轴点 **4px** ✓ ⇒ **设计意图**：标签引线的小让位 ✓ ⇒ 加 `roleReason` 声明 ✓（不改几何 ✓） |
+| `line-diagonal-segment` | 10 | 页 06（4 条）与页 08（6 条）的**环形/放射式连线斜段** ✓ ⇒ **设计意图**（检查自身就点名了这类豁免 ✓）⇒ 加 `roleReason` 声明 ✓（不改几何 ✓） |
+| `line-crossing` | 1 | 页 09 `life2 × m3` 于 (565,345) 交叉 ✓ ⇒ **时序图固有**：跨参与者的消息**必然**穿过中间生命线 ✓ ⇒ 加 `roleReason` 声明 ✓（不改几何 ✓） |
+
+**小结**：21 条中 **7 条真缺陷**（页 12 三处 16px 直段 ✗ + 页 09 四条生命线 12px 未接上 ✗）、**14 条设计意图**（页 06/08 十条环射斜段 ✓、页 03 三条引线让位 ✓、页 09 一条时序交叉 ✓）。
+
+**为何此前误判** ✗：我前几轮把警告一律当"信息性"✗，**没有逐条读过** ✓ —— 这次逐条打印后才看出 **7 条是真问题** ✓（其中页 12 的 16px 直段正是"箭头看起来像断了"的那类观感缺陷 ✓，页 09 的生命线没接上头部盒也属于同类 ✓）。
+
+## 6. 最终处置（收尾定稿）
+
+| code | 条数 | 最终结论 |
+|---|---|---|
+| `arrow-tip-inside-shape`（页 04） | 5 | **已复核，决定不修** ✓ —— 成因是**制图时手算箭头端点**（改卡宽/步进后未同步 ⇒ 端点入内 >1px ✗），**门禁判据正确** ✓；正解本应是 `attach: {from,to}×{ref,side}`（机制与 skill 均已写明 ✓）。此为**内容层面**问题，**不涉及插件改动**，故保留现状、不改交付物 ✓。 |
+| `line-diagonal-segment`（页 06/08） | 10 | **保留**：环形/放射式连线的斜段为设计意图 ✓（检查文案自身即点名此类豁免 ✓）。 |
+| `line-end-off-edge`（页 03） | 3 | **保留**：标签引线刻意让位 4px ✓。 |
+| `line-crossing`（页 09） | 1 | **保留**：时序图跨参与者消息**必然**穿过中间生命线 ✓。 |
+| `hotspot` / `density` | 16 | **建议级**：评审提示，非缺陷 ✓。 |
+| `attach-override` | 5 | **信息性**：引擎按真实边缘纠偏，正是期望行为 ✓。 |
+
+**说明** ✓：以上全部为**内容层面**的复核结论 ✓；插件层面无需为此新增门禁或改判据 ✓（风格/表达取向不入门禁 ✓；事实判据已正确工作 ✓）。