# 架构图（Archify 生成）

> **产物不入库**：本目录只提交 `<名字>.architecture.json` 源。要看图，先按下方[改图与重新生成](#改图与重新生成)里的 `archify deliver` 命令重出到本地；
> HTML 与 PNG 已被 `.gitignore` 忽略，不会被误提交，因此 git 里看不到它们不是缺文件。

**当前版本：一张总图 + 四张平面展开图 + 三张专题图，共八张**（对应[架构确定](../架构确定.md)与[00 总览](../00-总览.md)，2026-09-06 更新）

每张图都是 `<名字>.architecture.json`（图的源，Archify Typed JSON IR）+ `<名字>.architecture.html`（可交互成品：深浅主题、引导视图、说明卡、路径追踪、导出 PNG/JPEG/WebP/SVG）+ `<名字>-preview-light/-dark.png`（4140 宽预览，由成品页自身的 PNG 导出生成，不是截图）。**改图改 JSON**，然后重新 `validate` 与 `deliver`。

末列是**交付当时（2026-09-06）的量度**，不是对图的现状声明——改过图之后以 JSON 为准，不必回来同步这一列。

| 图 | 名字 | 它回答什么 | 交付时 节点/连线/卡片 |
|---|---|---|---|
| 总图 | `four-planes` | 四个平面怎么分、部件之间怎么连、交付线怎么闭环 | 14 节点 / 19 连线 / 7 卡片 |
| 平面展开 | `plane-knowledge` | 知识平面三个部件各自必须做到什么、一条主张与一个候选的一生 | 15 / 18 / 5 |
| | `plane-execution` | 执行平面六个部件、一次运行的主线、换工具时换掉的是什么 | 20 / 22 / 5 |
| | `plane-control` | 控制平面四个部件、一次判定与一次阻断、改进闭环 | 18 / 22 / 6 |
| | `plane-accountability` | 人出现在哪几处状态转换、每处判断的是什么、怎样不把人耗干 | 15 / 20 / 6 |
| 专题 | `topic-invariants` | 每条不变量约束哪几条边、违反时是什么症状 | 22 / 21 / 6 |
| | `topic-l0-l3` | 同一套部件在四档下的形态、下一档要你加什么、什么时候不许升档 | 22 / 10 / 6 |
| | `topic-boundary` | 第六条不变量：权威侧与消费侧、可执行前提怎么否掉一条推论 | 20 / 16 / 6 |

**八张图共用一套图例**（`frontend` 冻结的声明 / `database` 写下来并被回读 / `backend` 执行动作 / `security` 判定与阻断 / `external` 人），
共用一套写作规格（只写语义不变量，见下），因此可以互相对读：在总图上看到一个部件，进对应的平面展开图看它内部；在平面图上看到一条纪律，进专题图看它属于哪条不变量。

## 本轮（2026-09-06）落实了「下一版要求」的哪几条

上一版在此处记了三条要求，本轮全部执行，逐条对账如下。

**要求一 · 详细度：一张总图 + 四张平面展开图 + 若干专题图。** 已完成，八张全部 `validate --quality showcase` **0 错 0 警**（9/9 artifact 检查）。
交付当时节点总数从 14 开到 146（总图 14 + 四张平面图 68 + 三张专题图 64）——这是对本轮这件已完成事件的量度。

**要求二 · 内容边界：沿用正文写作规格（D-020）。** 已执行：八张图上无具名工具、文件名、字段名、阈值与效果数字；
出现的数字只有三类——章号与原则号、决策号、以及正文已有的来源统计（节点上的「归因 N」与连线括号里的独立来源数，出处 [00 §4](../00-总览.md)、[00 §6](../00-总览.md)、[架构确定 §5.1](../架构确定.md#component-stats)）。

**顺带处理的会漂计数**：总图卡片标题「六条不变量（…）」→「不变量（…）」（[审计记录 040](../审计记录/040-会漂计数的综合审计与推荐.md) P-07）；
`human` 的 sublabel「五处判断」→「少数检查点」、责任平面视图说明「人只在五处状态转换出现」→「少数状态转换处」（依据 [40 §1](../40-人的检查点与授权.md)「把人的判断集中在少数状态转换处」，个数由卡片自己的枚举呈现）。
新增七张图的标签、卡片标题与视图说明**一律不写「数 + 名词」**：写「不变量」「消费侧推论」「可执行前提」「人出现的状态转换」，个数由画出来的节点呈现。
仍保留的基数是三类：`meta.title` 里「四个平面 · 十四个部件 · 一条交付线」（这一版的专名）、正文原词（「三类工件」「交接分两层」「四档不是必经阶段」）、以及下面那张对照表里对已完成事件的量度。

## 总图为了画出那两条关系，动了什么

上一版把「超限与门禁失败 → 升级到人」与「不可逆动作 → 只能由人授权」**刻意没画成边**，理由记作「会压过交付线」。本轮复核确认：那不是可读性偏好，是**在原坐标下拓扑不可解**——
`human` 在证据与追踪以西、`guard` 在其以东，而交付线的 `verify → evidence` 必须从东侧下来插进 `evidence`，于是任何「守卫绕底走到人」的路线都要穿它；八组走法实测最小错误数恒为 1，且每次都撞在交付线上。

结论是「原骨架不可解」，不是「这两条边不可画」。本轮重排了两个坐标，两条边随即变成西侧短边：

- **控制行次序改为：守卫与权限边界 · 评估与演进 · 证据与追踪 · 验证与测试**（守卫与证据对调）。`verify → evidence` 退化成同行短边，底部走廊整条空出来。
- 「超限、门禁失败、告警升级到人（21）」走守卫左侧 → 西侧竖廊 → 人的右侧；「不可逆动作只能由人授权（17）」走人的底部 → 西侧竖廊 → 下方走廊 → 守卫底部。两条边零相交、零走廊冲突。
- 连带改动：**「动作或阶段转换前阻断并回显原因（29）」的落点从上下文装配改为状态工件**。这不是走线调整而是语义调整，依据是 [31 §1](../31-守卫与权限边界.md)「给 20 状态工件 阻断结论、屏障范围与失败回边」——改指之后这条边才有章节级出处，此前挂在上下文装配上只有平面级出处。
- 同时补画：「范围与预算在创建时固化、执行中只能收窄（15）」（守卫 → 执行者与模型）、「确定性判断先由程序做、模型只判残余（18）」（工具与执行环境 → 验证与测试），并给「确认并冻结意图」「每轮先读状态」补上括号里的来源数。

## 本轮如实记下的取舍（不是「全部达成」）

1. **总图仍有两条 [00 §4](../00-总览.md) 的关系没画成边**：「子执行者只回结构化结果（18）」（三种端点组合分别 4/7/5 个穿节点错）与「状态转换处提取记忆候选并经治理写回（15）」（忠实端点对实测 10 错）。它们已由执行平面展开图与不变量专题图的卡片承接——**这是「移到平面展开图」，不是「画了」**。
2. **各图内部也有降级**：控制平面图把控制→执行的「独立验证者给出裁定与定位（22）」、执行→控制的两条（18）、控制→知识的（15）收进卡片；执行平面图把「动作或阶段转换前阻断（29）」降级为接口桩的 sublabel、把「超限与停机升级到人（21）」留在节点语义里；不变量专题图六条各只画了一到三条边，其余进卡片。每张图的成品页里都能读到这些语义，但**它们不在连线上**。
3. **一处形态与图例不严格对齐**：证据与追踪在本套图里一律用「判定与阻断」一色（与控制平面其余部件同色，保平面带的视觉整体），而它的形态严格说是「写下来并被回读」。这是沿用上一版总图的着色，已知取舍。
4. **跨边界专题图的图例 `external` 标注为「人 / 外部权威侧」**，因为那张图上没有「人」节点，唯一的 external 是不归我们管的对方。其余七张写「人」。
5. **viewBox 宽度上限约 1395**：1440 视口下 sublabel 的投影字号须 ≥6px，超宽会被 `composition/desktop-readability` 判死。本轮八张图全部靠**往下长**解决，没有缩字号、删标签或压节点。这条对以后改图同样成立。
6. **`archify visual-check` 仍是 fail**（四种视口都报 `viewer/viewport-overflow`，整页放不进一屏）。**这不是缺陷，是取舍**——每一页都是文档（图 + 说明卡），本来就要滚动。

## 这一版比上一版多了什么

下表是 2026-09-03 那次的对照（**表内的数是对已完成事件的量度，不改**）。本轮的量度见上面「落实了哪几条」一节。

| | 旧版（2026-09-02） | 2026-09-03 版 |
|---|---|---|
| 部件 | 12（24 与 25 合并，缺 23 方法库） | **14，与 00 总览 §2 一一对应** |
| 连线 | 12，无证据标注 | 15，**括号内是明确画出该关系的独立来源数**（00 总览 §4） |
| 节点标注 | 无 | **「归因 N」= 把该类失败归因到本部件的独立来源数**（00 总览 §6，即排查顺序；来源基数见[架构确定](../架构确定.md)） |
| 引导视图 | 3（交付线 / 知识平面 / 控制与责任） | **5，即四个闭环 + 责任平面**（00 总览 §3） |
| 卡片 | 3（三个平面） | **6**：六条不变量、三个平面、L0–L3 四档、**一次运行的两个属性**（产出类型 × 起点状态，00 §3） |
| 图例 | Archify 默认的 Web 应用分类（前端 / 后端 / 数据库 / 安全 / 外部系统）——**对这张图完全不对** | 改写为这五类实际共享的**形态**：冻结的声明 / 执行动作 / 写下来并被回读 / 判定与阻断 / 人。颜色与布局未动 |
| L0–L3 卡 | 四行档位说明 | 首行补一条落地结论：**部件数不等于文件数**——原文、L0 的文件数与“照章建目录”这个错法见[文件树与落地路径 §1](../../templates/文件树与落地路径.md#not-14-files)（2026-09-04），卡上点破它 |
| 上下文闭环视图的说明 | "装配 → 使用 → 外部化" | 补一句实测：**视图的职责不只是限量，还要把人带到应答条款**——四个开着的问题答案都已在正文里，找不到的直接原因是视图没把元治理两章算作目标章（2026-09-04，D-058 第 ③ 项） |

## 读法

**总图**：四个虚线框是责任、知识、执行、控制四个平面；**绿色粗线是交付线**（人确认意图 → 派生工作项与用例 → 每轮先读状态 → 派发切片 → 装配上下文 → 执行 → 环境回读与三态裁定 → 证据写回状态）；**紫色虚线是回流**（记忆治理后的晋升、证据喂给演进、失败驱动规则增删）；**红色虚线是控制平面的阻断与升级**。
本轮起，「超限与门禁失败 → 升级到人」与「不可逆动作 → 只能由人授权」**已经画出来了**，都在图的西侧。

**四张平面展开图**：每张图里，部件主节点挂着它的子节点（取自各章 §1「它必须做到的」与「它自己维护什么」），边上写「必须做到 / 自己维护」；
另外三个平面各出现一个**接口桩**节点，桩上的边照 [00 §4](../00-总览.md) 带括号里的独立来源数。卡片写该章最硬的几条原则并注明 `§2 Pn`。

**三张专题图**：按主题切不按平面切。不变量专题图是「不变量 → 它约束的边 → 违反时的症状」三列；L0–L3 专题图是四条横带加一条「升不上去的时候」；跨边界专题图是中间一条边界带、左右两段角色相反的关系。

## 改图与重新生成

```bash
archify validate architecture docs/架构图/<名字>.architecture.json --quality showcase
archify deliver  architecture docs/架构图/<名字>.architecture.json docs/架构图/<名字>.architecture.html --quality showcase
```

`validate` 会逐条报出标签压组件、连线穿节点、走廊交叉、桌面视口下文字过密等问题，并给出可直接照抄的修法（`labelAt`、`labelDy`、`via` 坐标）。**showcase 档必须 0 错 0 警**——八张图当前都是 9/9 artifact 检查通过、0 错 0 警。
一次修复只加一个几何控制；连续两轮错误数没有创新低就停下如实报告，不要靠删标签过关。

**PNG 预览的重出方式（2026-09-06 换了做法，比原来简单得多）**：用 Playwright 驱动 Chromium 打开成品页 → 点主题按钮并**确认 `document.documentElement.getAttribute("data-theme")` 是想要的那个** → 点「导出 → PNG（无损图像）」→ 用浏览器的 download 事件落盘。
不再需要原来那套「钩住页面自己的 `URL.createObjectURL` 拿 Blob、再同源 POST 回本地小服务」的绕法。导出分辨率仍是页面自己决定的 4140 宽。
**只在节点、连线、边界或图例变化时才需要重出**——引导视图说明与卡片只在 HTML 里，不进导出图。

历史版本（保留供对照）：`three-planes.*`（三平面，人尚未单列）、`ai-dev-system.*`（五部件 + 两胶水，最初按示例画的）。

生成工具：[tt-a1i/archify](https://github.com/tt-a1i/archify) v2.17.0-dev.1（`npm install -g` 自仓库 `archify/` 子目录安装；仓库根目录没有 package.json，直接 `npm i -g github:tt-a1i/archify` 会失败）。