agentcss 0.25.6 → 0.27.0

package/CONTRIBUTING.md

@@ -27,23 +27,45 @@
 npm ci                 # 按锁文件装（验证 lockfile 真能装）
 npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
+npm run gate:pre-commit # 提交前：五道秒级判据（实测约 7s）
 ```
 
+三档不是"快慢"的区别，是**判断边界**的区别：
+
+| 档 | 什么时候跑 | 能证明什么 |
+|---|---|---|
+| `gate:pre-commit` | 每次 `git commit` 前 | 契约 / 页面结构 / 文案 / 行为核心 / 类型没被改坏 |
+| `gate:fast` | push 前 | 加上静态层的全部判据（不含浏览器） |
+| `gate` | 收尾、发版前 | 全部，含浏览器、视觉基线、打包闭包 |
+
+`gate:pre-commit` 走绿只说明"可以提交"，**不说明可以发版**。想让它自动跑，
+把 `bash 05-audit/check-all.sh --pre-commit` 写进 `.git/hooks/pre-commit` 即可；
+本仓不替使用者装 hook —— 提交节奏是个人选择。
+
 全量的门禁条数由 `05-audit/check-all.sh` 实算，**不在文档里写死** —— 新增一道门禁
 就会变，写下来的第二天就是第二个会漂的真值（I-7）。默认 `min(核数, 6)` 路并发；
 组件层要起浏览器，还要逐张比浅色 / 暗色 / RTL 三套视觉基线（按平台分集，
 只比本平台那套）。条数、耗时、并发效率一律以**本轮门禁打印的结果**为准。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。
 
-### 全量为什么**不**在 CI 上跑（这不是缺口，是结论）
+### CI 跑什么、不跑什么（边界，不是缺口）
 
 `.github/workflows/gate.yml` 分三层：`quick`（`MODE=fast`，静态 + 视觉）、
-`contract`（API 契约，需 Chromium）、`browsers`（nightly，三引擎矩阵）。
+`contract`（API 契约，需 Chromium）、`browsers`（三引擎矩阵）。
 **没有任何一处是 `MODE=full`**，而且不该有 —— 实测在 Linux runner 上跑全量会
 FAIL 10+ 道（字体渲染不同 ⇒ 视觉 diff 必然不一致；路径/编码不同 ⇒ 体积类误报；
 shallow clone ⇒ 依赖 git 状态的判据语义不同；浏览器版本不同 ⇒ 截图基线不匹配）。
 
 **一个长期红的 CI 比没有 CI 更糟**：大家会习惯性忽略它，真正的新问题也一起被忽略。
+
+触发面（2026-11-05 调整）：
+
+| 事件 | 跑哪些 | 为什么 |
+|---|---|---|
+| 直推 `master` | 只 `quick` | 这个仓库一直是直推，之前**完全没有 CI 保护**；quick 约 3–4 分钟，能挡住"本地没跑就推" |
+| PR | `quick` + `contract` | 合并前要契约 |
+| nightly / 手动 | 全部三个 job | 三引擎矩阵成本高，不该每次 push 都烧 |
+
 所以边界是：
 
 - **CI 负责**：跨平台可靠的那部分（静态契约、类型、API 形态、单引擎行为）
@@ -52,10 +74,29 @@ shallow clone ⇒ 依赖 git 状态的判据语义不同；浏览器版本不同
 `browsers` job 已覆盖三引擎的组件行为契约，但它**不替代**本机全量：
 它不跑视觉基线（基线按平台分集）、不跑 RTL/响应式/无障碍全量。
 
+### 私有词表（维护者；缺失时 leak 判据会变弱）
+
+`leak-scan` 的「真实代号 / 用户名」两类要靠一份**不随包分发**的词表才能生效。
+它放在 `internal/private-terms.txt`（已被 `.gitignore` 挡住，也不在 `package.json`
+的 `files` 里）。文件不在时，脚本会打印：
+
+```
+⚠️ 私有词表未加载（0 条）⇒ 真实代号 / 用户名判据**本次未覆盖**
+```
+
+**这不是通过**。本地开发把它放回去即可；CI 上因为拿不到这个文件，需要：
+
+1. GitHub 仓库 → Settings → Secrets and variables → Actions → 新建
+   `FL_PRIVATE_TERMS`，值就是词表全文（多行）；
+2. `gate.yml` 的 `quick` job 会把它写进 `internal/private-terms.txt` 再跑门禁；
+3. 没配时日志里会有一条 `::notice`，明确写着"这一类在 CI 上不覆盖"。
+
+⚠️ 不要把词表直接提交进仓库 —— 那等于把要防的东西本身公开了。
+
 ### 失败时先读哪里
 
 `selftest-all` 报红时，除屏幕上那 4 行摘要，**完整子输出会落盘**到
-`internal/tmp/selftest-fail-<脚本名>.log`（`internal/` 已被忽略，不进仓库）。
+`internal/tmp/selftest-fail-<脚本名>.log`（`internal/` 是本地忽略目录，不进仓库）。
 不可复现的红最需要这个 —— 摘要往往不够定位。
 
 只想验一条反向控制时，用 `SKIP_SELFTESTS="a.py,b.py" python3 05-audit/selftest-all.py`

package/README.md

@@ -10,10 +10,29 @@ npm install agentcss
 
 The npm package is `agentcss`; the repository is `frontend-lib`. They are different things: the package name is what you install, the repository name is where the source lives.
 
+### Module format: ESM-only
+
+The JS entry points (`esm/*.mjs`) are **ESM only** — `exports` has no `require` condition.
+
+| You write | Node **≥ 20.19 / ≥ 22.12** | Node 18 – 20.18 |
+|---|---|---|
+| `import 'agentcss'` | ✅ | ✅ |
+| `require('agentcss')` | ✅ (Node's built-in require(ESM)) | ❌ `ERR_REQUIRE_ESM` |
+
+- On older runtimes use `await import('agentcss')`, or consume the CSS entry points only
+  (`agentcss/tokens.css` etc. are not JS and work on any Node version).
+- The shipped `*.js` files under `02-primitives/**` and `03-patterns/**` are **classic
+  scripts** for `<script>` tags, not CommonJS modules — they attach to `window.*`.
+- `"type": "commonjs"` is deliberate: it describes how those classic scripts are
+  *parsed*. Flipping it to `module` would make bundlers re-interpret them as ESM,
+  which is a breaking change.
+
 ## Docs and live demos
 
 - **Every demo page, one index** — https://owain323.github.io/frontend-lib/
 - **Component documentation with search** — https://owain323.github.io/frontend-lib/guide/
+- **How this project is organized** — [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+  (what each layer is, how the automated checks work — in plain language)
 
 Both are generated from `ai/components.json` and the per-component `README.md`
 files, so a page cannot quietly go missing from the index when a component is

package/README.zh-CN.md

@@ -15,6 +15,8 @@
 
 - **全部示例页，一个索引** —— https://owain323.github.io/frontend-lib/
 - **带搜索的组件文档** —— https://owain323.github.io/frontend-lib/guide/
+- **这个项目是怎么组成的** —— [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+  （四层组件、自动检查系统，用平话讲）
 
 两者都由 `ai/components.json` 与各组件的 `README.md` **生成**：
 新增组件时索引不会悄悄漏掉它，文档页里的每条链接都指向真实存在的文件。
@@ -60,6 +62,22 @@ npm install agentcss
 
 装出来的目录名就是 `agentcss`，`dist-tags.latest` 指向当前版本。
 
+### 模块格式：ESM-only（请先读这一条）
+
+`agentcss` 的 JS 入口（`esm/*.mjs`）**只有 ESM**，`exports` 里没有 `require` 条件。
+
+| 你的写法 | Node **≥ 20.19 / ≥ 22.12** | Node 18 ~ 20.18 |
+|---|---|---|
+| `import 'agentcss'` | ✅ | ✅ |
+| `require('agentcss')` | ✅（Node 自带的 require(ESM)） | ❌ `ERR_REQUIRE_ESM` |
+
+- 走 `require` 的旧环境请改用 `await import('agentcss')`，或只用 CSS 入口
+  （`agentcss/tokens.css` 这类**不是 JS**，任何 Node 版本都能直接引用）。
+- 包里的 `*.js`（`02-primitives/**`、`03-patterns/**`）是给 `<script>` 用的**经典脚本**，
+  不是 CommonJS 模块 —— 它们挂 `window.*`，不需要 bundler。
+- `type` 字段保持 `commonjs` 是**有意**的：它描述的是那批经典脚本的解析方式。
+  把它改成 `module` 会让 bundler 用 ESM 语义重新解析它们，属于破坏性变更。
+
 另外两条**同样真实可用**的路（内容与 registry 上那一份同源）：
 
 ```bash

package/SECURITY.md

@@ -44,10 +44,22 @@
 下面两处会把字符串**当 HTML 解析**。它们是**有意的 API**，不是疏漏 ——
 `popover` 要能放任意块级内容，`drawer` 要能放整页内容，只收文本就废了。
 
-| 文件 | 入口 | 谁负责净化 |
-|---|---|---|
-| `02-primitives/popover/popover.js` | `opts.html` | 调用方 |
-| `03-patterns/drawer/drawer.js` | `opt.content` | 调用方 |
+| 文件 | 入口 | 净化钩子 | 谁负责净化 |
+|---|---|---|---|
+| `02-primitives/popover/popover.js` | `opts.html` | `opts.sanitize` / `Popover.setSanitizer(fn)` | 调用方（或接钩子） |
+| `03-patterns/drawer/drawer.js` | `opt.content`（字符串） | `opt.sanitize` / `Drawer.setSanitizer(fn)` | 调用方（或接钩子） |
+
+**0.26.0 起有钩子，但默认不改变行为**：不传 `sanitize`、也不调 `setSanitizer()`
+时，两处仍然直接把字符串当 HTML 解析 —— 与 0.25.x 完全一致（静默"自动净化"
+会让既有页面里的 `<b>` / `<svg>` 突然消失，那也是一种破坏）。
+接 DOMPurify 只需一行：
+
+```js
+Popover.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+Drawer.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+```
+
+逐次覆盖优先于模块级：`Popover.attach(el, { html: s, sanitize: fn })`。
 
 **为什么本库不做净化**：净化需要一个 HTML 解析器或一份允许列表实现，而本库的目标是
 零运行时依赖 + Chromium 97 可用。给一个"看起来安全"的半吊子净化，比明确说

package/START-HERE.md

@@ -39,39 +39,39 @@
 | 标签 / 徽章 | `02-primitives/badge/badge.css` | 141 | — | 有状态标记就要（"已披露""停牌"） |
 | 卡片 | `02-primitives/card/card.css` | 283 | — | 有分组内容就要 |
 | 单选 / 多选 | `02-primitives/choice/choice.css` | 434 | — | 单选 / 多选就要 |
-| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 631** (`select.js`) | 原生 select 的外观或交互不够用就要 |
-| 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 480** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
+| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 652** (`select.js`) | 原生 select 的外观或交互不够用就要 |
+| 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 503** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
 | 开关 | `02-primitives/switch/switch.css` | 429 | — | 有"立即生效的设置"就要 |
 | 分隔线 | `02-primitives/separator/separator.css` | 73 | — | 要分开内容块就要 |
 | 加载骨架 | `02-primitives/skeleton/skeleton.css` | 114 | — | 数据还没到、先把版式占住就要 |
 | 进度条 / 环 | `02-primitives/progress/progress.css` | 228 | — | 有耗时过程要给进度就要 |
-| 浮层气泡 | `02-primitives/popover/popover.css` | 187 | **必需 325** (`popover.js`) | 要一段信息贴着触发元素浮出来就要 |
-| 日期区间 | `02-primitives/date-range/date-range.css` | 206 | **必需 310** (`date-range.js`) | 要选起止日期就要 |
+| 浮层气泡 | `02-primitives/popover/popover.css` | 187 | **必需 345** (`popover.js`) | 要一段信息贴着触发元素浮出来就要 |
+| 日期区间 | `02-primitives/date-range/date-range.css` | 206 | **必需 332** (`date-range.js`) | 要选起止日期就要 |
 | 标签页 | `03-patterns/tabs/tabs.css` | 172 | **必需 316** (`tabs.js`) | 同层级内容切换就要 |
 | 折叠面板 | `03-patterns/accordion/accordion.css` | 453 | **必需 389** (`accordion.js`) | 长表单分段就要 |
-| 动作菜单 | `03-patterns/dropdown/dropdown.css` | 135 | **必需 555** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
-| 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 284** (`tooltip.js`) | 图标按钮或缩写需要一句话解释就要 |
-| 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 401** (`pagination.js`) | 数据多到要翻页就要 |
-| 树形 | `03-patterns/tree/tree.css` | 122 | **必需 464** (`tree.js`) | 层级数据（文件 / 组织 / 分类）要展开就要 |
-| 侧边抽屉 | `03-patterns/drawer/drawer.css` | 145 | **必需 378** (`drawer.js`) | 要从侧边滑出面板就要 |
-| 弹窗 / 吐司 | `03-patterns/overlay/overlay.css` | 338 | **必需 697** (`overlay.js`) | 需要弹层（吐司 / 模态）就要 |
+| 动作菜单 | `03-patterns/dropdown/dropdown.css` | 135 | **必需 575** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
+| 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 299** (`tooltip.js`) | 图标按钮或缩写需要一句话解释就要 |
+| 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 428** (`pagination.js`) | 数据多到要翻页就要 |
+| 树形 | `03-patterns/tree/tree.css` | 122 | **必需 484** (`tree.js`) | 层级数据（文件 / 组织 / 分类）要展开就要 |
+| 侧边抽屉 | `03-patterns/drawer/drawer.css` | 145 | **必需 416** (`drawer.js`) | 要从侧边滑出面板就要 |
+| 弹窗 / 吐司 | `03-patterns/overlay/overlay.css` | 338 | **必需 734** (`overlay.js`) | 需要弹层（吐司 / 模态）就要 |
 | 状态（空 / 加载 / 错 / 成功） | `03-patterns/states/states.css` | 269 | — | **凡是会异步取数就要** |
 | 表单校验 | `03-patterns/form-validation/form-validation.css` | 274 | — | 提交前要校验就要 |
 | 列表增删 | `03-patterns/list/list.css` | 162 | 可选 201 (`flip.js`，FLIP 增删动画，纯增强) | 列表会动态增删就要 |
 | 导航 / 目录 | `03-patterns/nav/nav.css` | 314 | **必需 425** (`nav.js`) · 可选 111 (`toc.js`，自动生成目录，纯增强) | 顶部要导航，或长文要目录就要 |
-| 长文排版 | `03-patterns/content/content.css` | 286 | — | 写文档 / 长文就要 |
+| 长文排版 | `03-patterns/content/content.css` | 298 | — | 写文档 / 长文就要 |
 | delta | `02-primitives/delta/delta.css` | 113 | — |  |
 | metric | `02-primitives/metric/metric.css` | 157 | — |  |
 | timeline | `02-primitives/timeline/timeline.css` | 152 | — | 有一串按时间排的事件（公告 / 大事记 / 版本记录）就要 |
-| upload | `02-primitives/upload/upload.css` | 490 | 可选 676 (`upload.js`，拖放 / 文件列表 / 校验；没有它基础形态照常工作) |  |
+| upload | `02-primitives/upload/upload.css` | 490 | 可选 709 (`upload.js`，拖放 / 文件列表 / 校验；没有它基础形态照常工作) |  |
 | reveal | `03-patterns/reveal/reveal.css` | 93 | 可选 175 (`reveal.js`，入场动效，纯增强；没有它内容直接可见) |  |
 | analysis-report | `04-recipes/analysis-report/analysis-report.css` | 226 | — |  |
 | app-shell | `04-recipes/app-shell/app-shell.css` | 588 | **必需 289** (`shell-nav.js`) |  |
 | detail-page | `04-recipes/detail-page/detail-page.css` | 190 | — |  |
 | report | `04-recipes/report/report.css` | 369 | — |  |
 | table | `04-recipes/table/table.css` | 409 | — |  |
-| bar | `09-assets/bar/bar.css` | 181 | **必需 324** (`bar.js`) |  |
-| model-viewer | `09-assets/model-viewer/model-viewer.css` | 143 | **必需 432** (`model-viewer.js`) |  |
+| bar | `09-assets/bar/bar.css` | 181 | **必需 348** (`bar.js`) |  |
+| model-viewer | `09-assets/model-viewer/model-viewer.css` | 143 | **必需 464** (`model-viewer.js`) |  |
 | scientific-plot | `09-assets/scientific-plot/scientific-plot.css` | 141 | **必需 604** (`scientific-plot.js`) |  |
 | sparkline | `09-assets/sparkline/sparkline.css` | 158 | **必需 508** (`sparkline.js`) |  |
 
@@ -122,11 +122,15 @@
 | `report/` | `04-recipes/report/` | 报告版式系统 v1：共享基础 + 三种版式取舍（杂志 / 科研技术 / 金融研究） |
 | `table/` | `04-recipes/table/` | 专业数据表格：列级格式与单位，三种用途预设 |
 
-## 抄完先做这三件事
+## 抄完先做这几件事
 
-1. **看效果** —— 每个组件目录下有 `demo.html`，抄完对照着比
-2. **跑一遍无障碍** —— 浏览器控制台里（或用 axe）确认对比度达标
-3. **别改类名** —— 类名是 API（`.btn` `.btn--primary` `.field__input`），
+1. **查一遍结构** —— `node ai/cli.js check 你的页面.html`
+   查的是产物：类名在库里存不存在、引没引到定义它的样式表、图有没有 alt、
+   表有没有名字、标题有没有跳级。**它不联网、不开浏览器，一秒出结果。**
+2. **看一眼** —— `node ai/cli.js shot 你的页面.html --out shot-{width}.png --width=390,1440 --full`
+   390 那张是按真 390 宽度排的（不是把宽图裁一刀），顺手报横向溢出与 JS 报错。
+3. **跑一遍无障碍** —— 浏览器控制台里（或用 axe）确认对比度达标
+4. **别改类名** —— 类名是 API（`.btn` `.btn--primary` `.field__input`），
    改名等于换组件。**要改样式就改令牌**，全库会一起变
 
 ---
@@ -146,6 +150,9 @@ CSS 类跨框架通用，React 组件会绑死框架。
 
 > **抄 `tierA-tokens.css`（A 档）或 `tokens.css`（B/C 档）→ 再抄你要的那几个 CSS → 保留类名。**
 
+**让模型来写页面时**，另有一份按「它需要知道什么」组织的清单：`ai/START-HERE.md`
+（`ai components` / `ai pitfalls` / `ai check` / `ai shot` / `ai scaffold` 都在那里）。
+
 ---
 
 ## 你可能还想找的（有 / 没有，一次说清）

package/ai/START-HERE.md

@@ -61,7 +61,9 @@
 | 令牌名与取值 | `node ai/cli.js tokens --mode=dark`、`node ai/cli.js tree`（分层视图） |
 | 组件真实长什么样 | 该组件目录下的 `demo.html` |
 | 英文一页速览 | `llms.txt` / `llms-full.txt`（发现层；本文件是中文详版） |
-| 页面怎么搭 | `04-recipes/` 下的示例 |
+| 页面怎么搭 | `04-recipes/` 下的示例；要写报告/长文就先 `node ai/cli.js scaffold list` |
+| 写完了对不对 | `node ai/cli.js check <页面.html>`（类名/结构/版式必有件） |
+| 写完好不看 | `node ai/cli.js shot <页面.html> --out shot-{width}.png --width=390,1440 --full` |
 | 令牌怎么改 | README「主题定制」（覆盖 CSS 变量，不需重新编译） |
 
 **类名即 API**（`.btn`、`.btn--primary`）。改样式改**令牌**，不要改类名，
@@ -71,7 +73,7 @@
 
 | 信号 | 怎么看 |
 |---|---|
-| 成熟度 | `ai/components.json` 的 `maturity` 是**算出来的**（判据在 `ai/components.meta.json`），不是人写的 |
+| 成熟度 | `ai/components.json` 的 `maturity` 是**算出来的**（判据在 `ai/components.meta.json`），不是人写的。它判的是**机制完整**：有 demo、有专属门禁、没有旧 `.is-*` 状态类、没有行为债。**它不判**视觉质量、真实模型生成效果、真机表现 —— `40/40 stable` 不等于 `40/40 好看`，更不等于有人在生产里用过 |
 | 有没有 demo | 组件目录下有 `demo.html` 就能直接跑起来对照 |
 | 有没有门禁守 | `05-audit/check-all.sh`（`npm run gate`）一次跑全，逐项打印 `PASS`/`FAIL`/`SKIP` |
 | 浏览器支持 | README「浏览器支持」表：桌面 Chrome/Edge/Firefox 已验证（自动化）；iOS Safari / 微信 / 企微 / QQ 等 7 个入口**人工实测过能力探针**（`🔍`，无回归保护）；**Android 系统 WebView 无数据** |
@@ -92,11 +94,42 @@
 npm ci                 # 按锁文件安装（首次）
 npm test               # 单元测试
 npm run test:types     # 类型契约：正例必过 + 反例必挂
-npm run gate:fast      # 静态检查（约 45 秒，改代码时跑）
-npm run gate           # 全量检查（含浏览器，提交前跑）
-node ai/cli.js check <doc.json>   # 校验契约文档（读 JSON，不解析原始 HTML）
+npm run gate:pre-commit # 提交前档（约 7 秒：契约 / 页面 / 文案 / 行为核心 / 类型）
+npm run gate:fast      # 静态层全部（约 4 分钟，不含浏览器类判据）
+npm run gate           # 全量（含浏览器与视觉基线；**发版前**跑，不是提交前）
+node ai/cli.js check <doc.json>   # 校验契约文档（计划：节点类型 / 组件档位）
+node ai/cli.js check <页面.html>  # 校验产物（类名 / 结构 / 版式必有件）
+node ai/cli.js shot  <页面.html> --out shot-{width}.png --width=390,1440 --full
+                                  # 截图（真实视口），顺带报横向溢出与 JS 报错
+node ai/cli.js scaffold report/finance --out report.html
+                                  # 生成最小壳（正确骨架 + 必有件位置），不含内容
 ```
 
+**退出码可以直接分支**（全部子命令同一套）：
+
+| 码 | 含义 | 你该做什么 |
+|---|---|---|
+| 0 | 通过 | — |
+| 1 | **判定不通过**（页面/文档确实有错） | 读 `findings` / `errors`，改产物 |
+| 2 | 用法错误（开关名、取值、重复、空值） | 改调用 |
+| 3 | 环境不具备（没有浏览器 / 没有 node） | 换机器或跳过，别改代码 |
+| 4 | 渲染失败 | 看 message |
+| 5 | 超出预算（产物是完整的） | 拆文档或放宽预算 |
+| 6 | 工具内部错误 | 报 bug，别改自己的参数 |
+
+> `1` 和 `2` 分开是有原因的：把「页面有 3 个错」和「`--profile` 拼错了」都返回 1，
+> 自动修复循环会去改**错的那一边**。
+
+**计划与产物是两件事，判据不重叠**：
+
+| 查什么 | 命令 | 能发现 | 发现不了 |
+|---|---|---|---|
+| 计划（doc.json） | `check <doc.json>` | 节点类型、组件是否在档位内、介质义务 | 写出来的 HTML 对不对 |
+| 产物（.html） | `check <页面.html>` | 类名未定义 / 引错样式表 / 缺 alt、caption、scope / 标题跳级 / 版式缺件 | 页面**好看不好看**（那要 `shot` 看一眼） |
+
+> 两个命令都**不联网、不启动浏览器**；`shot` 用你机器上已装的 Chrome/Edge，
+> 不打包浏览器（理由同 `ai pdf`）。
+
 改动本库**自身**时的分层（决定该动哪一层）：
 
 | 层 | 文件 | 性质 |
@@ -112,7 +145,8 @@ node ai/cli.js check <doc.json>   # 校验契约文档（读 JSON，不解析原
 
 有人问过要不要把 `ai/*.json` 包成一个 MCP server。结论是**不做**：
 
-1. 十一个子命令**全是只读查询** —— MCP 版本只是换一层传输，一个新能力都没有。
+1. 十四个子命令**全是本机命令**（读契约 / 校验文件 / 调本机浏览器）——
+   MCP 版本只是换一层传输，一个新能力都没有。
 2. 它会是**第二份真值**：命令怎么调、参数叫什么、返回什么形状，都得再写一遍。
    CLI 改了 server 没改，就多一处只有用户能发现的错（`--json` 那次已经踩过同类）。
 3. 用户要多信任一个常驻进程（安装、权限、升级），而 CLI 离线、可审计、跑完即退。