agentcss 0.26.0 → 0.27.1

package/START-HERE.md

@@ -47,7 +47,7 @@
 | 进度条 / 环 | `02-primitives/progress/progress.css` | 228 | — | 有耗时过程要给进度就要 |
 | 浮层气泡 | `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/tabs/tabs.css` | 181 | **必需 316** (`tabs.js`) | 同层级内容切换就要 |
 | 折叠面板 | `03-patterns/accordion/accordion.css` | 453 | **必需 389** (`accordion.js`) | 长表单分段就要 |
 | 动作菜单 | `03-patterns/dropdown/dropdown.css` | 135 | **必需 575** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
 | 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 299** (`tooltip.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

@@ -58,10 +58,12 @@
 | 组件清单与成熟度 | `node ai/cli.js components --maturity=stable` |
 | 某个组件踩过的坑 | `node ai/cli.js pitfalls --component=<id>`（数据在 `ai/pitfalls.json`） |
 | 写文案 / 做演示 / 发页面时的坑 | `node ai/cli.js pitfalls --scope=writing`（数据在 `ai/pitfalls-writing.json`，不挂组件） |
-| 令牌名与取值 | `node ai/cli.js tokens --mode=dark`、`node ai/cli.js tree`（分层视图） |
+| 令牌名与取值 | `node ai/cli.js tokens --set=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 离线、可审计、跑完即退。

package/ai/cdp.js

@@ -0,0 +1,152 @@
+/*
+ * cdp.js — 零依赖 Chrome DevTools Protocol 管道客户端。
+ *
+ * shot 与 pdf 共用这一份实现。调试走 fd 3/4，以 NUL 分隔 JSON；不开放端口，
+ * 不连接使用者的浏览器，也不引入 Puppeteer 运行时依赖。
+ */
+'use strict';
+
+var { spawn } = require('child_process');
+
+/** 启动一个隔离的 headless Chrome，并返回有界的 CDP 请求接口。 */
+function connect(chromePath, profile) {
+  var args = [
+    '--headless=new',
+    '--disable-gpu',
+    '--disable-extensions',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--hide-scrollbars',
+    '--remote-debugging-pipe',
+    '--user-data-dir=' + profile,
+    'about:blank'
+  ];
+  /* 只有明确以 root 在容器中运行时才允许调用方关闭沙箱。 */
+  if (process.env.AGENTCSS_NO_SANDBOX === '1') args.unshift('--no-sandbox');
+  var child = spawn(chromePath, args, {
+    stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+    windowsHide: true
+  });
+
+  var buf = Buffer.alloc(0);
+  var pending = Object.create(null);
+  var waiters = [];
+  var listeners = [];
+  var nextId = 0;
+  var dead = null;
+  var stderr = '';
+
+  function failAll(err) {
+    dead = dead || err;
+    Object.keys(pending).forEach(function (k) {
+      clearTimeout(pending[k].timer);
+      pending[k].reject(dead);
+    });
+    pending = Object.create(null);
+    waiters.splice(0).forEach(function (w) {
+      clearTimeout(w.timer);
+      w.reject(dead);
+    });
+  }
+
+  var commandPipe = child.stdio[3];
+  var eventPipe = child.stdio[4];
+  if (!commandPipe || !eventPipe) {
+    failAll(new Error('无法建立 CDP 管道（Chrome 没能启动）'));
+  }
+  /* 🔴 必须有 error 监听。浏览器起不来时管道会以 EPIPE/ECONNRESET 结束，
+     而 Node 的流在没有 error 监听时**直接抛出** —— 那就成了"本工具崩了"，
+     和"这份 PDF 没导出来"是两件事，也让调用方看不到结构化结论。 */
+  if (commandPipe) commandPipe.on('error', function (e) { failAll(e); });
+  if (eventPipe) eventPipe.on('error', function (e) { failAll(e); });
+
+  function dispatch(msg) {
+    if (msg.id !== undefined && pending[msg.id]) {
+      var p = pending[msg.id];
+      delete pending[msg.id];
+      clearTimeout(p.timer);
+      if (msg.error) p.reject(new Error(p.method + '：' + (msg.error.message || JSON.stringify(msg.error))));
+      else p.resolve(msg.result);
+      return;
+    }
+    if (!msg.method) return;
+    for (var L = 0; L < listeners.length; L++) {
+      if (listeners[L].method === msg.method) listeners[L].fn(msg.params, msg.sessionId);
+    }
+    for (var i = waiters.length - 1; i >= 0; i--) {
+      var w = waiters[i];
+      if (w.method === msg.method && (!w.sessionId || w.sessionId === msg.sessionId)) {
+        waiters.splice(i, 1);
+        clearTimeout(w.timer);
+        w.resolve(msg.params);
+      }
+    }
+  }
+
+  if (eventPipe) eventPipe.on('data', function (chunk) {
+    buf = Buffer.concat([buf, chunk]);
+    var i;
+    while ((i = buf.indexOf(0)) >= 0) {
+      var raw = buf.subarray(0, i).toString('utf8');
+      buf = buf.subarray(i + 1);
+      try { dispatch(JSON.parse(raw)); } catch (e) { /* 忽略不完整的非 JSON 浏览器输出 */ }
+    }
+  });
+  child.stdio[1].on('data', function () { /* Chrome 常规 stdout 不属于协议 */ });
+  child.stdio[2].on('data', function (chunk) {
+    stderr = (stderr + chunk.toString('utf8')).slice(-4000);
+  });
+  child.on('error', function (e) { failAll(e); });
+  child.on('exit', function (code) {
+    failAll(new Error('Chrome 提前退出（退出码 ' + code + '）'));
+  });
+
+  function send(method, params, sessionId, timeoutMs) {
+    return new Promise(function (resolve, reject) {
+      if (dead) return reject(dead);
+      var id = ++nextId;
+      var limit = timeoutMs || 15000;
+      var timer = setTimeout(function () {
+        delete pending[id];
+        reject(new Error(method + ' 超时（' + limit + 'ms 没有回应）'));
+      }, limit);
+      pending[id] = { resolve: resolve, reject: reject, timer: timer, method: method };
+      try {
+        var message = { id: id, method: method, params: params || {} };
+        /* 顶层命令不能带 sessionId:null；Chrome 只接受“字段不存在”或字符串。 */
+        if (sessionId !== undefined && sessionId !== null) message.sessionId = sessionId;
+        commandPipe.write(JSON.stringify(message) + '\0');
+      } catch (e) {
+        clearTimeout(timer);
+        delete pending[id];
+        reject(e);
+      }
+    });
+  }
+
+  function waitEvent(method, sessionId, timeoutMs) {
+    return new Promise(function (resolve, reject) {
+      var limit = timeoutMs || 15000;
+      var timer = setTimeout(function () {
+        var at = waiters.findIndex(function (w) {
+          return w.method === method && w.sessionId === sessionId;
+        });
+        if (at >= 0) waiters.splice(at, 1);
+        reject(new Error('等 ' + method + ' 超时（' + limit + 'ms）'));
+      }, limit);
+      waiters.push({ method: method, sessionId: sessionId,
+        resolve: resolve, reject: reject, timer: timer });
+    });
+  }
+
+  return {
+    send: send,
+    waitEvent: waitEvent,
+    on: function (method, fn) { listeners.push({ method: method, fn: fn }); },
+    close: function () { try { child.kill(); } catch (e) { /* 已退出 */ } },
+    stderr: function () { return stderr; },
+    child: child
+  };
+}
+
+module.exports = { connect: connect };