agentcss 0.24.2 → 0.25.1

package/START-HERE.md

@@ -39,7 +39,7 @@
 | 标签 / 徽章 | `02-primitives/badge/badge.css` | 141 | — | 有状态标记就要（"已披露""停牌"） |
 | 卡片 | `02-primitives/card/card.css` | 283 | — | 有分组内容就要 |
 | 单选 / 多选 | `02-primitives/choice/choice.css` | 424 | — | 单选 / 多选就要 |
-| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 541** (`select.js`) | 原生 select 的外观或交互不够用就要 |
+| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 631** (`select.js`) | 原生 select 的外观或交互不够用就要 |
 | 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 477** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
 | 开关 | `02-primitives/switch/switch.css` | 429 | — | 有"立即生效的设置"就要 |
 | 分隔线 | `02-primitives/separator/separator.css` | 73 | — | 要分开内容块就要 |
@@ -54,9 +54,9 @@
 | 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 401** (`pagination.js`) | 数据多到要翻页就要 |
 | 树形 | `03-patterns/tree/tree.css` | 122 | **必需 464** (`tree.js`) | 层级数据（文件 / 组织 / 分类）要展开就要 |
 | 侧边抽屉 | `03-patterns/drawer/drawer.css` | 129 | **必需 361** (`drawer.js`) | 要从侧边滑出面板就要 |
-| 弹窗 / 吐司 | `03-patterns/overlay/overlay.css` | 319 | **必需 638** (`overlay.js`) | 需要弹层（吐司 / 模态）就要 |
-| 状态（空 / 加载 / 错 / 成功） | `03-patterns/states/states.css` | 252 | — | **凡是会异步取数就要** |
-| 表单校验 | `03-patterns/form-validation/form-validation.css` | 263 | — | 提交前要校验就要 |
+| 弹窗 / 吐司 | `03-patterns/overlay/overlay.css` | 338 | **必需 684** (`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 | — | 写文档 / 长文就要 |
@@ -68,11 +68,11 @@
 | analysis-report | `04-recipes/analysis-report/analysis-report.css` | 226 | — |  |
 | app-shell | `04-recipes/app-shell/app-shell.css` | 588 | **必需 288** (`shell-nav.js`) |  |
 | detail-page | `04-recipes/detail-page/detail-page.css` | 190 | — |  |
-| report | `04-recipes/report/report.css` | 364 | — |  |
+| report | `04-recipes/report/report.css` | 369 | — |  |
 | table | `04-recipes/table/table.css` | 409 | — |  |
-| bar | `09-assets/bar/bar.css` | 166 | **必需 320** (`bar.js`) |  |
+| bar | `09-assets/bar/bar.css` | 181 | **必需 320** (`bar.js`) |  |
 | model-viewer | `09-assets/model-viewer/model-viewer.css` | 143 | **必需 423** (`model-viewer.js`) |  |
-| scientific-plot | `09-assets/scientific-plot/scientific-plot.css` | 141 | **必需 610** (`scientific-plot.js`) |  |
+| scientific-plot | `09-assets/scientific-plot/scientific-plot.css` | 141 | **必需 603** (`scientific-plot.js`) |  |
 | sparkline | `09-assets/sparkline/sparkline.css` | 158 | **必需 508** (`sparkline.js`) |  |
 
 ### 🔴 这些组件的 JS 是**必需的**（不是增强）

package/SUPPORT.md

@@ -17,14 +17,32 @@
 >   **那句推测是错的**：CI 的 `浏览器矩阵（firefox）` 作业一直在跑，而且是绿的
 >   （UA 自报 `X11; Linux x86_64; rv:155.0 Gecko/20100101 Firefox/155.0`）。
 >   ⚠️ 与 ❌ 都会低估覆盖面，和 ✅ 高估一样是失真。
+>
+> 🔴 现在有**四档**，不是三档：
+>   原来的三档里没有「人工实测过、但没有自动化守着」这一档，
+>   于是 7 行真机数据只能落进 `❌ 未验证`（「没有在真实环境跑过」）——
+>   而那句话对它们是**假的**。新增 `🔍` 之后，`❌` 才重新只表示它字面上的意思。
+>   ⇒ 加这一档**不是**为了把 ❌ 说成 ✅，`✅` 仍然只给自动化（定义见下）。
 
 ## 状态定义
 
-| 标记 | 含义 |
-|---|---|
-| ✅ 已验证 | 有自动化检查覆盖，且**跑的就是这个引擎**（有 UA 证据） |
-| ⚠️ 部分验证 | 只覆盖了部分功能或部分视口 |
-| ❌ 未验证 | **没有在真实环境跑过** |
+| 标记 | 含义 | 进不进入对外承诺 |
+|---|---|---|
+| ✅ 已验证 | 有**自动化检查**覆盖，且**跑的就是这个引擎**（作业自报 UA 为证） | 进入 |
+| 🔍 实测（人工一次） | 在**真实设备**上人工跑过能力探针，有完整 UA 与逐项结果；**没有自动化回归保护** | **不进入** |
+| ⚠️ 部分验证 | 只覆盖了部分功能或部分视口 | 部分 |
+| ❌ 未验证 | **没有在真实环境跑过** | 不进入 |
+
+🔴 **`🔍` 与 `✅` 不能互相代替，也不能相加。**
+
+| | 说的是什么 | 浏览器升级时谁会发现 |
+|---|---|---|
+| ✅ | 「有自动化检查在这个引擎里跑，有人替我们守着」 | 门禁会红 |
+| 🔍 | 「我们确实在这台设备上试过一次，之后没人再看」 | **没人** |
+
+⇒ 所以 `🔍` 永远**不升级**为发布承诺。它只回答一个问题：
+**"这个环境我们到底试没试过"** —— 而不是"能不能保证它一直能用"。
+把 `🔍` 读成 `✅`，就是这一页历史上记过的那种失真（见顶部两条更正）。
 
 ---
 
@@ -72,32 +90,72 @@ grep 一条都数不到），还有 `skip "…"`（这台机器跑不了的门
 
 ---
 
-## 尚未验证的环境
+## 移动环境：试过的 与 没试过的
+
+上面那张表是「有人守着」的自动化覆盖。移动端目前**没有**这种覆盖，
+但有另一类证据：**在真实设备上人工跑过能力探针**。两者必须分开看。
+
+### 试过一次的（🔍 人工实测，无回归保护）
+
+7 行数据来自在真实设备上打开 [`capability-probe.html`](10-review/webview/capability-probe.html)。
+完整 UA 与逐项结论在 [`docs/LAYER-BASELINE.md`](docs/LAYER-BASELINE.md)；
+15 项能力分别是什么、怎么自己复跑一遍，在 [`10-review/webview/RESULTS.md`](10-review/webview/RESULTS.md)。
+本节 7 行**全部是 `🔍`** —— 没有一行有自动化守着。
 
-| 平台 | 引擎 | 状态 | 说明 |
+| 入口 | UA 自述的环境 | 实测 | 缺什么 |
 |---|---|---|---|
-| iOS | WKWebView | ❌ | **未在真机或模拟器验证** |
-| iOS | Safari | ❌ | 未在真机验证 |
-| Android | Android WebView | ❌ | **未在真机验证** |
-| Android | Chrome（移动版）| ⚠️ | 仅用**桌面**引擎模拟了移动视口，**非真机引擎** |
+| Safari（系统浏览器） | iPhone · iOS 18_7 | **15 / 15** | 无 |
+| 微信 8.0.47 | Android 14 · XWEB（Chromium 146） | **14 / 15** | `scrollbar-width` —— 有 `::-webkit-scrollbar` 私有回退，观感可接受 |
+| 微信 8.0.79 | iPhone · iOS 26_6_2 ⚠️ 用户口述设备为平板，但 UA 与视口均为 iPhone ⇒ 在 iPad 上以兼容模式运行 | **15 / 15** | 无 |
+| 企业微信 5.0.12 | iPhone · iOS 18_7 ⚠️ 同上，兼容模式 | **15 / 15** | 无 |
+| 百度浏览器 13.51 | Android 14 · Chromium 97 | **11 / 15** | 🔴 `@layer`（阻塞切层）；`dvh`、`scrollbar-width` 有降级；原生 Popover 本库未使用 |
+| Safari 26.6.1 | iPad · 桌面版 UA | **15 / 15** | 无 |
+| QQ 浏览器 20.6.6 | iPhone · iOS 26_6_2 | **15 / 15** | 无 |
+
+### 没有真机数据的（❌ / ⚠️）
+
+| 平台 | 入口 / 宿主 | 状态 | 说明 |
+|---|---|---|---|
+| Android | **系统 WebView** | ❌ | **没有任何真机数据** —— 移动端最大的一块空白，也是用户量最大的入口 |
+| Android | Chrome（移动版） | ⚠️ | 只用**桌面**引擎模拟了移动视口，**不是真机引擎** |
+| iOS | 其它 WKWebView 宿主 App | ❌ | 微信 / 企微**这两个宿主**已测（见上表）；自建 App、抖音 / 小红书 / 支付宝等内置浏览器**都没有数据** |
+
+🔴 **「内核相同」不等于「宿主相同」。** 同一个 WKWebView，宿主 App 可以关掉部分能力
+（内联播放、脚本桥、缓存策略）。⇒ 上表按**入口**分行，不按内核归类 ——
+这正是探针页那句警告的意思：入口写不清楚，数据就没法用。
+
+### ⚠️ 就算是 🔍 的那 7 行，也只覆盖了「能力有没有」
+
+探针只回答「这个引擎认不认这 15 项语法」。它**不回答**：
+
+- 软键盘弹起时 `100vh` 塌不塌、输入框会不会被键盘盖住
+- 安全区（刘海 / 底部横条）有没有正确留白
+- 页面回弹、滚动惯性、`position: sticky` 在真机上顺不顺
+- VoiceOver / TalkBack 念出来对不对
+- 200% 字号下会不会裁字、320px 宽会不会横滚
 
-⚠️ 桌面 WebKit 自动化（上面那个 ✅）**不等于** iOS WKWebView：
-真机上的软键盘、可视视口变化、安全区、`100vh`、页面回弹、VoiceOver
-都没有被上面任何一项覆盖。
+这些没有任何一项被上面 7 行覆盖，**也没有被桌面 WebKit 的自动化覆盖**。
+⇒ 「能力 15/15」和「页面在真机上能用」是两个不同的问题，别把前者当成后者。
 
 ---
 
-## 已知风险（未验证带来的）
+## 已知风险与未覆盖项
 
-1. **`:has()`** —— 已在 `theme-toggle` 里避免使用；其余用法需在 WebKit 上实测
+1. **`:has()`** —— `theme-toggle` 里已避免使用；其余用法在**5 个 WebKit 系入口**上实测通过
+   （iPhone Safari / iOS 微信 / iOS 企微 / iPad Safari / iPhone QQ，见上表），
+   但那是人工一次、**没有自动化守着** ⇒ 后续改动仍需真机复跑
 2. **`backdrop-filter`** —— Firefox 与旧 WebKit 行为不一致，用了 `@supports` 兜底
-3. **`conic-gradient`**（环形进度）—— Safari 15.4+ 才支持
+3. **`conic-gradient`**（环形进度）—— **探针没有覆盖这一项，也没有真机数据**。
+   原来这里写的是「Safari 15.4+ 才支持」，那是**版本传闻**：按 `docs/LAYER-BASELINE.md`
+   的纪律，未经真机验证的版本结论不当事实引用 ⇒ 要结论就先把它加进探针、跑一次再说
 4. **滚动条样式** —— `::-webkit-scrollbar` 与 Firefox 的 `scrollbar-width` 是两套语法，组件里都写了
 5. **iOS 输入框的 `font-size < 16px` 会触发缩放** —— 输入类组件已避免
 6. **`@container`**（0.16.0 起使用，`[data-cq]` 标记的槽位）—— 与 `@layer` 同类：
    不支持时**整块丢弃**。区别在于**基础样式不在块里**，所以降级后与标记前完全一致；
    `container-query-check.js` 每次运行都会把 `@container` 剥掉再跑一遍，证明布局不塌。
-   Chromium 97 不会白屏，只会"按视口断点"（即旧行为）。
+   ⚠️ 这一条的依据是**剥离实验**（人为去掉 `@container` 看布局），
+   不是"在 Chromium 97 真机上跑过" —— 降级路径对，但旧内核上究竟怎么排版，
+   探针没有覆盖这一项，所以**没有真机结论**。
 
 ## 已知限制（已验证存在，不是"待验证"）
 
@@ -111,13 +169,17 @@ grep 一条都数不到），还有 `skip "…"`（这台机器跑不了的门
 
 ## 打算怎么补
 
-优先级从高到低：
+按「缺的到底是什么」排序，不是按好做程度：
 
-1. **Android WebView 真机**（用户量最大）
-2. **iOS WKWebView**（`100vh` / 滚动 / 输入框是重灾区）
-3. popover 的碰撞翻转（上面"已知限制"第 1 条）
+| 优先级 | 缺什么 | 为什么排这个位置 |
+|---|---|---|
+| 1 | **Android 系统 WebView 真机** | 唯一 **0 数据**的入口，且是用户量最大的一块 |
+| 2 | **已有 7 行的复跑** | 让「一次性实测」变成「跟得上浏览器升级」—— 不复跑，`🔍` 只会越来越旧 |
+| 3 | **真机整页验收**（软键盘 / 安全区 / 回弹 / 200% 字号 / 读屏） | 探针永远测不了这几项，只能拿设备点一遍 |
+| 4 | popover 的碰撞翻转（上面「已知限制」第 1 条） | 这是功能取舍，不是验证缺口 |
 
 ⚠️ 在补齐之前，请勿把「移动 WebView 支持」当作已验证的能力对外承诺。
+`🔍` 的作用是让读者看见「试过什么、还差什么」，它本身**不是**承诺。
 
-> 2026-10-31 记：前两项**卡在设备上** —— 手上没有可用的安卓机，也没有 iOS 设备，
-> 云真机需要账号。这条不是"忘了做"，是"缺外部条件"，所以不写进版本承诺。
+> 记：前两项**卡在设备上** —— 手上没有可用的安卓机，也没有 iOS 设备，
+> 云真机需要账号。这条不是「忘了做」，是「缺外部条件」，所以不写进版本承诺。

package/ai/START-HERE.md

@@ -74,9 +74,10 @@
 | 成熟度 | `ai/components.json` 的 `maturity` 是**算出来的**（判据在 `ai/components.meta.json`），不是人写的 |
 | 有没有 demo | 组件目录下有 `demo.html` 就能直接跑起来对照 |
 | 有没有门禁守 | `05-audit/check-all.sh`（`npm run gate`）一次跑全，逐项打印 `PASS`/`FAIL`/`SKIP` |
-| 浏览器支持 | README「浏览器支持」表：桌面 Chrome/Edge/Firefox 已验证；**iOS/Android WebView 未在真机验证** |
+| 浏览器支持 | README「浏览器支持」表：桌面 Chrome/Edge/Firefox 已验证（自动化）；iOS Safari / 微信 / 企微 / QQ 等 7 个入口**人工实测过能力探针**（`🔍`，无回归保护）；**Android 系统 WebView 无数据** |
 
-⚠️ **未在真机验证的项就是没验证**，不要替它打包票。
+⚠️ **`🔍` 只表示「人工试过一次」，不是「已验证」**。它没有自动化守着，
+也不代表页面在真机上能用 —— 别把两者混着说，更不要替它打包票。
 
 ## 5 · 什么时候应当沿用宿主项目现有技术
 

package/ai/cli.js

@@ -31,6 +31,9 @@ var fs = require('fs');
 var path = require('path');
 var validate = require('./validate.js');
 var patch = require('./patch.js');
+/* 打印导出。⚠️ 只在 `pdf` 子命令里用 —— 主路径不许因为它多加载任何东西
+   （`require` 是同步的，放在文件顶部是为了不把 CLI 拆成两截，代价是 ~2 KB 源码）。 */
+var pdfExport = require('./pdf.js');
 
 var AI = __dirname;
 
@@ -107,17 +110,22 @@ function flag(name, def) {
 // ---------------------------------------------------------------- check
 function cmdCheck(args) {
   var file = args[0];
-  if (!file) die('用法：ai check <doc.json> [--profile=creative|standard|strict]');
+  if (!file) die('用法：ai check <doc.json> [--profile=creative|standard|strict] [--medium=screen|paper]');
   var doc = readJSON(file);
   var profile = flag('profile', doc.profile || 'standard');
-  var r = validate.validateDoc(doc, { profile: profile });
+  /* 介质是**与档位正交**的第二根轴：
+     strict+paper 与 creative+paper 都必须合法，做成第四个 profile 会把两维压成一维。
+     默认 screen ⇒ 今天所有调用零成本；paper 才追加打印义务。 */
+  var medium = flag('medium', 'screen');
+  var r = validate.validateDoc(doc, { profile: profile, medium: medium });
   var json = isJson();
 
   if (json) {
     out(r);
     process.exit(r.ok ? 0 : 1);
   }
-  process.stdout.write('  === 契约校验（档位：' + r.profile + '）===\n\n');
+  process.stdout.write('  === 契约校验（档位：' + r.profile
+    + '，介质：' + r.medium + '）===\n\n');
   if (r.errors.length === 0) {
     process.stdout.write('  OK  ' + Object.keys(doc.nodes || {}).length +
       ' 个节点，无违规\n');
@@ -629,6 +637,97 @@ function cmdProfile() {
   process.exit(0);
 }
 
+// ---------------------------------------------------------------- pdf
+/* 退出码与其它子命令分开：调用方（CI / 编辑器）要能分清
+   ① 参数写错 ② 这台机器上没有浏览器 ③ 渲染失败 ④ 超预算。
+   合成一个 1 的话，"没有 Chrome"会被当成"页面有错"去查，方向就错了。 */
+var PDF_EXIT = {
+  usage: 2, 'no-chrome': 3, render: 4, timeout: 4, unreadable: 4, 'over-budget': 5
+};
+
+function cmdPdf(args) {
+  /* ⚠️ pdf 的参数错误一律退出 2（与 PDF_EXIT.usage 一致），**不能走 die()** ——
+     die() 退出 1，而 1 在这套约定里表示"进程/未分类失败"。
+     两种用法错误给两个退出码，调用方就没法按码分支了。 */
+  function bad(msg) {
+    if (isJson()) out({ ok: false, command: 'pdf', code: 'usage', message: msg });
+    else process.stderr.write('  [FAIL] ' + msg + '\n');
+    process.exit(PDF_EXIT.usage);
+  }
+  var src = args[0];
+  if (!src) {
+    bad('用法：agentcss pdf <页面.html|URL> --out <file.pdf> '
+      + '[--paper=a4|letter|a5|a3|legal] [--margin="18mm 15mm"] '
+      + '[--max-pages=N] [--chrome=<path>] [--json]');
+  }
+  var remote = /^https?:\/\//i.test(src);
+  var outFile = flag('out', null);
+  if (outFile === null || outFile === true) {
+    /* 远程地址推不出本地文件名，必须显式给 —— 猜一个出来只会让人找不到文件在哪 */
+    if (remote) bad('远程地址必须显式给 --out');
+    outFile = src.replace(/\.(html?|xhtml)$/i, '') + '.pdf';
+  }
+  var budget = flag('max-pages', null);
+  if (budget === true) bad('--max-pages 后面要跟数字（不设 = 无界）');
+  /* 先按字符串校验再转数字：让报错里出现**使用者打进去的那串字符**。
+     直接 Number() 再报错时，`abc` 已经变成 NaN，报「收到 NaN/null」是在念实现细节（E264）。 */
+  if (budget !== null && !/^\d+$/.test(String(budget))) {
+    bad('--max-pages 必须是 ≥1 的整数，收到 ' + JSON.stringify(String(budget)));
+  }
+  var chrome = flag('chrome', null);
+  if (chrome === true) bad('--chrome 后面要跟可执行文件路径');
+
+  var r = pdfExport.exportPdf({
+    src: src,
+    out: outFile,
+    paper: flag('paper', pdfExport.DEFAULT_PAPER),
+    margin: flag('margin', pdfExport.DEFAULT_MARGIN),
+    budget: budget === null ? null : Number(budget),
+    chrome: chrome
+  });
+
+  var box = r.mediaBox
+    ? Math.round(r.mediaBox.width) + '×' + Math.round(r.mediaBox.height) + 'pt' : '?';
+  var report = {
+    ok: r.ok,
+    command: 'pdf',
+    code: r.ok ? null : r.code,
+    message: r.ok ? null : r.message,
+    out: r.out || null,
+    pages: r.pages === undefined ? null : r.pages,
+    budget: r.budget === undefined ? null : r.budget,
+    paper: r.paper || null,
+    paperSize: box,
+    margin: r.margin || null,
+    bytes: r.bytes || null,
+    injected: r.injected === undefined ? null : r.injected,
+    chrome: r.chrome || null,
+    ms: r.ms || null
+  };
+  if (isJson()) {
+    out(report);
+    process.exit(r.ok ? 0 : (PDF_EXIT[r.code] || 4));
+  }
+  if (!r.ok) {
+    process.stderr.write('  [FAIL] ' + r.message + '\n');
+    if (r.code === 'over-budget') {
+      process.stderr.write('         （退出码 ' + (PDF_EXIT[r.code] || 4)
+        + '：预算超了不是渲染出错，产物是完整的）\n');
+    }
+    process.exit(PDF_EXIT[r.code] || 4);
+  }
+  process.stdout.write('  OK  ' + r.out + '\n');
+  process.stdout.write('      ' + r.pages + ' 页 · ' + report.paperSize + ' · '
+    + (r.margin ? '边距 ' + r.margin : '边距由页面决定')
+    + ' · ' + r.bytes + ' 字节 · ' + r.ms + ' ms\n');
+  process.stdout.write('      预算 ' + (r.budget === null ? '未设（无界）' : r.budget + ' 页')
+    + ' · ' + (r.injected
+      ? '纸幅 ' + r.paper
+      : '纸幅由页面自己的 CSS 决定（远程页面：未注入 @page，--paper/--margin 不生效）')
+    + '\n');
+  process.exit(0);
+}
+
 function cmdCapabilities() {
   var doc = readJSON(path.join(AI, 'capabilities.json'));
   if (isJson()) { out(doc); process.exit(0); }
@@ -656,7 +755,8 @@ var CMDS = {
   tree: cmdTree,
   profile: cmdProfile,
   capabilities: cmdCapabilities,
-  pitfalls: cmdPitfalls
+  pitfalls: cmdPitfalls,
+  pdf: cmdPdf
 };
 
 function main() {
@@ -664,7 +764,7 @@ function main() {
   if (!argv.length || argv[0] === 'help' || argv[0] === '--help') {
     process.stdout.write(
       'agentcss ai —— 独立校验入口（零依赖、不联网、不依赖任何模型）\n\n' +
-      '  ai check        <doc.json> [--profile=creative|standard|strict] [--json]\n' +
+      '  ai check        <doc.json> [--profile=creative|standard|strict] [--medium=screen|paper] [--json]\n' +
       '  ai validate     <file.json> --schema=contract|components|tokens|tokensAudience|tokensTree|deprecations|patch [--json]\n' +
       '  ai diff         <改动前.json> <改动后.json> [--json]   按语义 id 比对\n' +
       '  ai patch        <doc.json> <patch.json> [-o out.json] [--json]\n' +
@@ -675,11 +775,31 @@ function main() {
       '  ai pitfalls     [--component=<id>] [--scope=component|layout|process|writing] [--tag=<t>] [--json]\n' +
       '  ai profile      [--json]   列出三档及其差异\n' +
       '  ai capabilities [--json]   列出可协商的能力\n' +
+      '  ai pdf          <页面.html|URL> --out <file.pdf> [--paper=a4|letter|a5|a3|legal]\n' +
+      '                  [--margin="18mm 15mm"] [--max-pages=N] [--chrome=<path>] [--json]\n' +
+      '                  HTML → PDF。零依赖（用你机器上已装的 Chrome），@page 由导出方给。\n' +
+      '\n' +
+      '  打印：`--medium=paper` 才会校验 printPolicy 与 pageBudget；默认 screen 零成本。\n' +
+      '  每个组件的纸面行为：ai/components.json 的 printPolicy。\n' +
       '\n' +
-      '  每个子命令都支持 --json；失败时输出 {ok:false, command, error} 并以非 0 退出。\n');
+      '  每个子命令都支持 --json；失败时输出 {ok:false, command, error} 并以非 0 退出。\n' +
+      '  前缀 `ai` 可写可不写：`agentcss ai components` 与 `agentcss components` 等价。\n');
     process.exit(0);
   }
   var name = argv.shift();
+  /* 🔴 `ai` 是可选的**前缀别名**（2026-11-02 补）：
+     帮助里的命令一直写成 `ai components`，AGENTS.md / llms.txt / STABILITY.md /
+     VERIFY-RELEASE.md 也都教 `npx agentcss ai components --json` ——
+     而分发器只认 `components`，于是「照着文档敲第一条命令」直接得到
+     「未知子命令：ai」。消费者视角的硬伤：文档里最靠前的那条命令不能用，
+     后面写得再准也读不到。
+     两种写法都认，免得已经抄下去的人再改一遍。 */
+  if (name === 'ai') {
+    name = argv.length ? argv.shift() : '';
+    if (!name) {
+      die('`agentcss ai` 后面要跟子命令（可用：' + Object.keys(CMDS).join(' / ') + '）');
+    }
+  }
   CURRENT_CMD = name;
   var fn = CMDS[name];
   if (!fn) die('未知子命令：' + name + '（可用：' + Object.keys(CMDS).join(' / ') + '）');