agentcss 0.26.0 → 0.27.1

package/ai/scaffold.js

@@ -0,0 +1,195 @@
+/*
+ * scaffold.js — 三个「最小壳」：正确的骨架，不含内容
+ *
+ * ============================================================================
+ * 🔴 为什么给壳，而不是给模板引擎
+ * ----------------------------------------------------------------------------
+ * 这一层最容易做歪的方向是"喂一段内容，吐一页报告" —— 那需要解析输入、
+ * 决定结构、再选版式，最后产出的东西**没法被断言**（对不对取决于读的人）。
+ *
+ * 这里只做一件事：把**前置条件**给对。漏一条 `<link>`、少一层 `.rep__grid`、
+ * 把文章标题写成 h3，页面不会报错，只会静默地长得不对 —— 而这些都是
+ * "知道就不会错、不知道就一定会错"的东西。
+ *
+ * ⇒ 壳只保证三件事：
+ *   ① 引对了样式表（少一个 = 那部分完全没样式）
+ *   ② 骨架层级对（.rep > header > .rep__grid > .rep__body/.rep__aside）
+ *   ③ 每一版**必有件**的位置留出来了（ai/recipes.json 里那几条）
+ *
+ * ⚠️ 三个壳都必须能通过 `ai check --html --recipe=<自己>`。
+ *    这不是口号：05-audit/html-check-gate.js 每次都会把三个壳跑一遍，
+ *    壳和判据一旦对不上就红。壳里少写一个必有件，门禁当场抓到。
+ */
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+var AI = __dirname;
+
+/** 壳里出现的 CSS 清单（相对库根）。只列真正用到的，不多引。 */
+var SHEETS = [
+  '01-tokens/tokens.css',
+  '01-tokens/typography.css',
+  '01-tokens/page.css',
+  '04-recipes/table/table.css',
+  '04-recipes/report/report.css'
+];
+
+function head(title, cssPrefix) {
+  var p = String(cssPrefix || 'node_modules/agentcss').replace(/\/+$/, '');
+  var links = SHEETS.map(function (s) {
+    return '<link rel="stylesheet" href="' + p + '/' + s + '">';
+  }).join('\n');
+  return '<!doctype html>\n'
+    + '<html lang="zh-CN">\n'
+    + '<head>\n'
+    + '<meta charset="utf-8">\n'
+    + '<meta name="viewport" content="width=device-width, initial-scale=1">\n'
+    + '<title>' + title + '</title>\n'
+    + links + '\n'
+    + '</head>\n';
+}
+
+/* 表格：三个壳共用。caption + th[scope] 是硬要求，壳里就写对，
+   免得使用者照着抄的时候把这两条一起漏掉。 */
+function table() {
+  return '          <div class="table">\n'
+    + '            <table>\n'
+    + '              <caption>表 1 · 三组对比（写"这张表比的是什么"，不是"这是数据"）</caption>\n'
+    + '              <thead>\n'
+    + '                <tr><th scope="col">项目</th><th scope="col">A 组</th>'
+    + '<th scope="col">B 组</th><th scope="col">C 组</th></tr>\n'
+    + '              </thead>\n'
+    + '              <tbody>\n'
+    + '                <tr><th scope="row">指标一</th><td>—</td><td>—</td><td>—</td></tr>\n'
+    + '                <tr><th scope="row">指标二</th><td>—</td><td>—</td><td>—</td></tr>\n'
+    + '              </tbody>\n'
+    + '            </table>\n'
+    + '          </div>\n';
+}
+
+function figure(wide) {
+  return '          <figure class="rep__fig' + (wide ? ' rep__fig--wide' : '') + '">\n'
+    + '            <!-- 放图：09-assets/scientific-plot 的容器 id，或直接 <img src alt> -->\n'
+    + '            <div id="chart"></div>\n'
+    + '            <figcaption class="rep__cap">图 1 · 图说（说清"看什么"，不是"这是什么"）</figcaption>\n'
+    + '          </figure>\n';
+}
+
+function section(title, body) {
+  return '        <section class="rep__sec">\n'
+    + '          <h3>' + title + '</h3>\n'
+    + body
+    + '        </section>\n';
+}
+
+/* 三种版式各自的那一段。顺序刻意与 README 的取舍表一致。 */
+var VARIANTS = {
+  'report/finance': {
+    label: 'report · 金融研究版',
+    rootClass: 'rep rep--finance',
+    title: '标题：把结论写在标题里',
+    kicker: '行业跟踪 · 金融研究版',
+    standfirst: '导语：先说结论与它成立的条件，再说依据。读者读完这一段就该知道要不要往下看。',
+    before: '    <!-- 关键数字条：这一版的读者先看数、后看论证（ai/recipes.json: rep__keyline） -->\n'
+      + '    <div class="rep__keyline">\n'
+      + '      <div><b>读数一</b><span>—</span></div>\n'
+      + '      <div><b>读数二</b><span>—</span></div>\n'
+      + '      <div><b>读数三</b><span>—</span></div>\n'
+      + '    </div>\n',
+    body: '',
+    after: '    <!-- 风险披露：这一版必须有（ai/recipes.json: rep__risk） -->\n'
+      + '    <p class="rep__risk">风险披露：把结论的适用条件、数据口径与不确定性写在这里。'
+      + '没有这一段的金融结论读起来像建议，而不是分析。</p>\n',
+    aside: '次要读数放这里。放不下的大图不要塞边注 —— 边注只有 14em。'
+  },
+  'report/technical': {
+    label: 'report · 科研技术版',
+    rootClass: 'rep rep--technical',
+    title: '标题：说清对象与方法',
+    kicker: '实验报告 · 科研技术版',
+    standfirst: '导语：一句话说清做了什么、得到什么、结论的置信边界在哪。',
+    before: '',
+    body: '',
+    after: '    <!-- 来源脚注：这一版必须有（ai/recipes.json: rep__source） -->\n'
+      + '    <p class="rep__source">来源：数据出处、采集时间与口径。逐条核对的人会顺着这里回查原始材料。</p>\n',
+    aside: '术语与口径写这里。这一版的读者会逐条核对，边注用来放"不影响主线但需要说明"的东西。'
+  },
+  'report/magazine': {
+    label: 'report · 杂志编辑版',
+    rootClass: 'rep rep--magazine',
+    title: '标题：用一个具体的画面开头',
+    kicker: '长报道 · 杂志编辑版',
+    standfirst: '导语：把读者带进场景，而不是先给结论。这一版是通读的，不是查数的。',
+    before: '    <!-- 引语块：这一版靠停顿制造节奏（ai/recipes.json: rep__pull） -->\n'
+      + '    <blockquote class="rep__pull">一句能被单独引用的话。它应该是全文的转折点，不是摘要。</blockquote>\n',
+    body: '',
+    after: '',
+    aside: '短提醒放这里。这一版没有编号，边注是唯一的"旁白"通道。'
+  }
+};
+
+/**
+ * @param {string} id      版式名（见 ai/recipes.json）
+ * @param {object} [opts]  `{cssPrefix}` —— 样式表前缀，默认 `node_modules/agentcss`
+ * @returns {{ok:true, html:string, id:string, requires:string[]}|{ok:false, message:string}}
+ */
+function render(id, opts) {
+  opts = opts || {};
+  var v = VARIANTS[id];
+  if (!v) {
+    return { ok: false, message: '未知版式：' + id + '（可用：' + Object.keys(VARIANTS).join(' / ') + '）' };
+  }
+  var wide = id === 'report/magazine';
+
+  var body = '        <section class="rep__sec">\n'
+    + '          <h3>第一节：先给判断，再给依据</h3>\n'
+    + '          <p>正文。这一段的每句话都应该能被上一段的数字或下一段的图支撑；'
+    + '撑不住的删掉。</p>\n'
+    + figure(wide)
+    + table()
+    + '        </section>\n'
+    + section('第二节：把限制写清楚', '          <p>适用的边界、数据口径、以及"这一版有意不做什么"。</p>\n');
+
+  var html = head(v.title, opts.cssPrefix)
+    + '<body class="page">\n'
+    + '<main class="wrap">\n'
+    + '  <!-- 由 `agentcss ai scaffold` 生成：只给壳，不给内容。\n'
+    + '       写完跑：agentcss ai check 本文件 --recipe=' + id + ' -->\n'
+    + '  <article class="' + v.rootClass + '">\n'
+    + '    <header>\n'
+    + '      <p class="rep__kicker">' + v.kicker + '</p>\n'
+    + '      <h2 class="rep__title">' + v.title + '</h2>\n'
+    + '      <p class="rep__standfirst">' + v.standfirst + '</p>\n'
+    + '      <ul class="rep__meta"><li>作者</li><li>日期</li><li>版本 v1</li></ul>\n'
+    + '    </header>\n'
+    + v.before
+    + '    <div class="rep__grid">\n'
+    + '      <div class="rep__body">\n'
+    + body
+    + '      </div>\n'
+    + '      <aside class="rep__aside">' + v.aside + '</aside>\n'
+    + '    </div>\n'
+    + v.after
+    + '  </article>\n'
+    + '</main>\n'
+    + '</body>\n'
+    + '</html>\n';
+
+  var requires = [];
+  try {
+    var all = JSON.parse(fs.readFileSync(path.join(AI, 'recipes.json'), 'utf8'));
+    requires = ((all.recipes[id] || {}).requires || []).map(function (r) { return r.selector; });
+  } catch (e) { /* 读不到就不报；门禁会盯 recipes.json */ }
+
+  return { ok: true, html: html, id: id, requires: requires };
+}
+
+function list() {
+  return Object.keys(VARIANTS).map(function (k) {
+    return { id: k, label: VARIANTS[k].label };
+  });
+}
+
+module.exports = { render: render, list: list, VARIANTS: VARIANTS, SHEETS: SHEETS };

package/ai/shot.js

@@ -0,0 +1,237 @@
+/*
+ * shot.js — 把页面截成 PNG（给定宽度、可选整页）
+ *
+ * ============================================================================
+ * 🔴 为什么不用 `chrome --screenshot --window-size=390,844`
+ * ----------------------------------------------------------------------------
+ * 因为它**会撒谎**。Windows 上窗口有最小宽度，`--window-size=390` 拿到的
+ * 实际视口是 **500px**（实测 innerWidth=500），而 `--screenshot` 只按 390 裁一刀。
+ * 结果是一张"看起来是 390 宽"的图：文字在右边缘被切掉、媒体查询按 500 生效 ——
+ * 你据此判断"窄屏没问题"，其实从没看过 390。
+ *
+ * 这类失败最贵的地方在于**它不报错**：图是好的、能打开、只是内容不对。
+ * 所以这里走 Chrome 的调试管道（`--remote-debugging-pipe`，零依赖、不开端口），
+ * 用 `Emulation.setDeviceMetricsOverride` 把视口**设成**要的那个数，再截。
+ *
+ * ============================================================================
+ * 为什么是管道而不是 `--remote-debugging-port`
+ * ----------------------------------------------------------------------------
+ * 端口版要处理：端口占用、防火墙弹窗（Windows 首次监听会弹）、启动竞态
+ * （等调试端口文件出现的时机）、以及同一个 profile 被复用时的锁。
+ * 管道版把这些全绕开：读写走子进程的 fd 3/4，消息以 `\0` 分隔的 JSON。
+ * 代价是自己拼十几行帧处理 —— 比处理上面四件事便宜得多。
+ *
+ * ============================================================================
+ * 它**不是**视觉基线
+ * ----------------------------------------------------------------------------
+ * 基线（逐字节比对）由 `05-audit/shot-baseline.py` 管，那套要考虑字体、
+ * 双平台产物与指纹。这里的产物是给人/给 Agent **看一眼**的：
+ * 同一台机器、同样参数，两次逐字节一致（门禁验的就是这条）；
+ * 换一台机器不保证 —— 字体光栅化不一样，别拿它当跨机器判据。
+ */
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+var { pathToFileURL } = require('url');
+var pdf = require('./pdf.js');
+var connect = require('./cdp.js').connect;
+
+var DEFAULT_WIDTHS = [1440];
+var DEFAULT_HEIGHT = 900;
+var DEFAULT_WAIT = 800;
+/* 整页截图的高度上限。PNG 面积是 W×H×scale²，超了内存与耗时都会失控；
+   截断**不静默**：结果里带 truncatedAt，人/Agent 能看见。 */
+var MAX_FULL_HEIGHT = 10000;
+
+/** 页面在某个宽度下的量：溢出多少、谁溢出、有多高。 */
+var PROBE_JS = [
+  '(function(){',
+  '  var d = document.documentElement;',
+  '  var vw = d.clientWidth;',
+  '  var over = [];',
+  '  var all = document.querySelectorAll("body *");',
+  '  for (var i = 0; i < all.length && over.length < 40; i++) {',
+  '    var e = all[i], r = e.getBoundingClientRect();',
+  '    if (r.width === 0 && r.height === 0) continue;',
+  '    if (r.right > vw + 1 || r.left < -1) {',
+  '      var cls = typeof e.className === "string" ? e.className : "";',
+  '      over.push(e.tagName.toLowerCase() + (cls ? "." + cls.trim().split(/\\s+/).join(".") : "")',
+  '        + " @" + Math.round(r.right));',
+  '    }',
+  '  }',
+  '  return JSON.stringify({',
+  '    viewport: vw, scrollWidth: d.scrollWidth, scrollHeight: d.scrollHeight,',
+  '    overflow: over.slice(0, 6), overflowCount: over.length',
+  '  });',
+  '})()'
+].join('\n');
+
+function slugWidth(w) { return String(w); }
+
+/**
+ * @param {object} o
+ * @param {string} o.src             本地 HTML 路径或 http(s) URL
+ * @param {string} o.out             输出文件；多宽度时须含 `{width}`
+ * @param {number[]} [o.widths]      视口宽度，默认 [1440]
+ * @param {number} [o.height]        视口高度，默认 900
+ * @param {boolean} [o.full]         整页（否则只截首屏）
+ * @param {number} [o.scale]         设备像素比，默认 1
+ * @param {number} [o.wait]          加载后额外等待（毫秒），默认 800
+ * @param {string} [o.chrome]
+ * @param {number} [o.timeoutMs]
+ * @returns {Promise<object>}
+ */
+async function shoot(o) {
+  o = o || {};
+  var t0 = Date.now();
+  if (!o.src) return { ok: false, code: 'usage', message: '缺少 src' };
+  if (!o.out) return { ok: false, code: 'usage', message: '缺少 out' };
+
+  var widths = o.widths && o.widths.length ? o.widths : DEFAULT_WIDTHS;
+  for (var i = 0; i < widths.length; i++) {
+    if (!Number.isInteger(widths[i]) || widths[i] < 200 || widths[i] > 4000) {
+      return { ok: false, code: 'usage',
+        message: '宽度必须是 200–4000 的整数，收到 ' + JSON.stringify(widths[i]) };
+    }
+  }
+  var height = o.height || DEFAULT_HEIGHT;
+  if (!Number.isInteger(height) || height < 200 || height > 4000) {
+    return { ok: false, code: 'usage',
+      message: '高度必须是 200–4000 的整数，收到 ' + JSON.stringify(o.height) };
+  }
+  var scale = o.scale === undefined ? 1 : Number(o.scale);
+  if (!(scale > 0 && scale <= 3)) {
+    return { ok: false, code: 'usage', message: '--scale 必须在 (0, 3]，收到 ' + JSON.stringify(o.scale) };
+  }
+
+  var remote = /^https?:\/\//i.test(o.src);
+  if (!remote) {
+    var srcAbs = path.resolve(o.src);
+    if (!fs.existsSync(srcAbs)) return { ok: false, code: 'usage', message: '找不到输入文件：' + srcAbs };
+    o.src = srcAbs;
+  }
+
+  var outTpl = String(o.out);
+  if (widths.length > 1 && outTpl.indexOf('{width}') < 0) {
+    return { ok: false, code: 'usage',
+      message: '截多个宽度时 --out 必须含 {width}（例：shot-{width}.png），'
+        + '否则 ' + widths.length + ' 张图会写进同一个文件，最后只剩一张' };
+  }
+
+  var chrome = pdf.resolveChrome(o.chrome);
+  if (chrome.error) return { ok: false, code: 'no-chrome', message: chrome.error };
+
+  var profile = fs.mkdtempSync(path.join(os.tmpdir(), 'agentcss-shot-'));
+  var cdp = connect(chrome.path, profile);
+  var shots = [];
+  var consoleErrors = [];
+  var budget = o.timeoutMs || 90000;
+  var deadline = Date.now() + budget;
+
+  try {
+    var target = await cdp.send('Target.createTarget', { url: 'about:blank' });
+    var attached = await cdp.send('Target.attachToTarget', { targetId: target.targetId, flatten: true });
+    var sid = attached.sessionId;
+
+    await cdp.send('Page.enable', {}, sid);
+    await cdp.send('Runtime.enable', {}, sid);
+    /* JS 异常要收集：截出一张"布局正确但内容没渲染"的图是最坏的产物，
+       而它通常就是一行 TypeError 造成的。 */
+    cdp.on('Runtime.exceptionThrown', function (p) {
+      if (consoleErrors.length >= 20) return;
+      var d = (p && p.exceptionDetails) || {};
+      var txt = (d.exception && d.exception.description) || d.text || '未捕获异常';
+      consoleErrors.push(String(txt).split('\n')[0]);
+    });
+    cdp.on('Runtime.consoleAPICalled', function (p) {
+      if (consoleErrors.length >= 20) return;
+      if (!p || p.type !== 'error') return;
+      var parts = (p.args || []).map(function (a) {
+        return a.value === undefined ? (a.description || a.type) : String(a.value);
+      });
+      consoleErrors.push('console.error: ' + parts.join(' '));
+    });
+
+    for (var w = 0; w < widths.length; w++) {
+      if (Date.now() > deadline) {
+        return { ok: false, code: 'timeout', message: '超出时间预算 ' + budget + 'ms', chrome: chrome.path, shots: shots };
+      }
+      var width = widths[w];
+      var w0 = Date.now();
+
+      await cdp.send('Emulation.setDeviceMetricsOverride', {
+        width: width, height: height, deviceScaleFactor: scale, mobile: false
+      }, sid);
+
+      var loaded = cdp.waitEvent('Page.loadEventFired', sid, 30000);
+      var nav = await cdp.send('Page.navigate', { url: remote ? o.src : pathToFileURL(o.src).href }, sid);
+      if (nav && nav.errorText) {
+        return { ok: false, code: 'render',
+          message: '页面加载失败（' + nav.errorText + '）：' + o.src, chrome: chrome.path, shots: shots };
+      }
+      await loaded;
+      if (o.wait) await new Promise(function (r) { setTimeout(r, o.wait); });
+
+      var probe = await cdp.send('Runtime.evaluate', {
+        expression: PROBE_JS, returnByValue: true
+      }, sid);
+      var info = {};
+      try { info = JSON.parse(probe.result.value); } catch (e) { info = {}; }
+
+      var clipH = height;
+      var truncated = null;
+      if (o.full) {
+        var want = info.scrollHeight || height;
+        clipH = Math.min(want, MAX_FULL_HEIGHT);
+        if (want > MAX_FULL_HEIGHT) truncated = want;
+      }
+
+      var shot = await cdp.send('Page.captureScreenshot', {
+        format: 'png',
+        captureBeyondViewport: !!o.full,
+        clip: { x: 0, y: 0, width: width, height: clipH, scale: 1 }
+      }, sid);
+      var png = Buffer.from(shot.data, 'base64');
+      if (png.length < 8 || png.readUInt32BE(0) !== 0x89504e47) {
+        return { ok: false, code: 'render', message: '产出的不是 PNG（' + png.length + ' 字节）',
+          chrome: chrome.path, shots: shots };
+      }
+
+      var outFile = path.resolve(outTpl.replace(/\{width\}/g, slugWidth(width)));
+      fs.mkdirSync(path.dirname(outFile), { recursive: true });
+      fs.writeFileSync(outFile, png);
+
+      shots.push({
+        width: width, out: outFile, bytes: png.length, ms: Date.now() - w0,
+        png: { width: png.readUInt32BE(16), height: png.readUInt32BE(20) },
+        full: !!o.full,
+        truncatedAt: truncated,
+        viewport: info.viewport === undefined ? null : info.viewport,
+        scrollWidth: info.scrollWidth === undefined ? null : info.scrollWidth,
+        scrollHeight: info.scrollHeight === undefined ? null : info.scrollHeight,
+        overflow: info.overflow || [],
+        overflowCount: info.overflowCount || 0
+      });
+    }
+
+    return {
+      ok: true, code: null, message: null, chrome: chrome.path,
+      scale: scale, wait: o.wait === undefined ? DEFAULT_WAIT : o.wait,
+      shots: shots, consoleErrors: consoleErrors, ms: Date.now() - t0
+    };
+  } catch (e) {
+    return { ok: false, code: 'render', message: String(e && e.message || e), chrome: chrome.path, shots: shots };
+  } finally {
+    cdp.close();
+    /* 清理必须**在进程退出前**做完：CLI 随后就 exit，挂 setTimeout 等于每截一张图
+       就在系统临时目录里留一个 Chrome profile（pdf.js 那边实测漏过 6 个）。
+       先等一下再删：Windows 上子进程刚 kill 时还握着文件句柄。 */
+    await new Promise(function (r) { setTimeout(r, 120); });
+    try { fs.rmSync(profile, { recursive: true, force: true, maxRetries: 3 }); }
+    catch (e) { /* 偶发 EBUSY，交给系统清理 */ }
+  }
+}
+
+module.exports = { shoot: shoot, DEFAULT_WIDTHS: DEFAULT_WIDTHS, DEFAULT_HEIGHT: DEFAULT_HEIGHT, DEFAULT_WAIT: DEFAULT_WAIT };

package/ai/validate.js

@@ -32,7 +32,11 @@ var path = require('path');
 var AI_DIR = __dirname;
 
 // ---------------------------------------------------------------- 能力白名单
-// ⚠️ 改这个表 = 改工具的能力边界。加关键字 ⇒ 必须同时实现它，否则别加。
+// ⚠️ 改这个表 = 改工具的能力边界。
+//   🔴 表里有的关键字**必须真的实现**：白名单只负责"允许出现"，
+//      不负责"校验它"。两者不一致 ⇒ schema 里写了、校验器当没看见 ⇒ **静默假绿**。
+//      （本轮审计 F4：`uniqueItems` / `not` 在表里挂了很久但没实现，
+//        `validate({type:'array',uniqueItems:true},[1,1])` 返回 ok:true。）
 var SUPPORTED_KEYWORDS = [
   '$schema', '$id', '$comment', '$ref', 'definitions', 'title',
   'type', 'required', 'properties', 'additionalProperties', 'patternProperties',
@@ -57,15 +61,30 @@ function isPlainObject(v) {
  */
 // 哪些键的"值"本身还是 schema
 var SUBSCHEMA_KEYS = [
-  'items', 'additionalProperties', 'patternProperties', 'allOf', 'anyOf',
+  'items', 'additionalProperties', 'allOf', 'anyOf',
   'oneOf', 'not', 'propertyNames', 'contains', 'if', 'then', 'else'
 ];
-// 哪些键是"名字 → schema"的容器（它们的**键**是字段名，不是关键字）
-var CONTAINER_KEYS = ['properties', 'definitions', '$defs', 'dependentSchemas'];
+/* 哪些键是"名字 → schema"的容器：它们的**键**不是关键字。
+   🔴 `patternProperties` 必须在这里，不能当普通子 schema ——
+      它的键是**正则**（`^--[a-z][a-z0-9-]*$`），
+      当成关键字检查就会报"用了没实现的关键字"，而 schema 本身完全合法。
+      这个错 0.26.0 就有，只是预扫当时只覆盖 4 份文件、碰巧都没用 patternProperties
+      ⇒ 直到本轮把预扫扩到全部 8 份才暴露（`tokens.audience` 第一个撞上）。 */
+var CONTAINER_KEYS = ['properties', 'definitions', '$defs', 'dependentSchemas',
+                      'patternProperties'];
+
+/* 扫哪些文件：**目录里现找**，不手写清单。
+   手写清单必漂 —— 0.26.0 时 `ai/` 下有 8 份 schema，这里只列了 4 份
+   （behaviors / deprecations / tokensAudience / tokensTree 从来没被扫过），
+   于是那四份里出现未知关键字也不会有人知道。 */
+function schemaFiles() {
+  return fs.readdirSync(AI_DIR).filter(function (f) {
+    return /\.schema\.json$/.test(f);
+  }).sort();
+}
 
 function assertSchemasUseOnlySupported() {
-  var files = ['contract.schema.json', 'components.schema.json',
-               'tokens.schema.json', 'patch.schema.json'];
+  var files = schemaFiles();
   var unknown = [];
 
   function checkNode(schema, f, ptr) {
@@ -118,6 +137,27 @@ function typeOk(expected, value) {
   return true;
 }
 
+/* JSON Schema 的"相等"是**深比较**：`{a:1}` 与 `{a:1}` 是两个对象但相等。
+   用 `===` 判重会把重复项全放过，而且是静默的。 */
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (var i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    var ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    for (var j = 0; j < ka.length; j++) {
+      if (!Object.prototype.hasOwnProperty.call(b, ka[j])) return false;
+      if (!deepEqual(a[ka[j]], b[ka[j]])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
 function resolveRef(root, ref) {
   if (ref.charAt(0) !== '#' || ref.indexOf('#/') !== 0) {
     throw new Error('只支持文档内 $ref：' + ref);
@@ -178,6 +218,18 @@ function validate(schema, data, root, ptr, errors) {
     if (schema.maxItems !== undefined && data.length > schema.maxItems) {
       errors.push({ path: ptr, msg: '元素多于 ' + schema.maxItems + ' 个' });
     }
+    /* `uniqueItems: true` = 元素两两不相等。O(n²) 深比较 —— 这里的数据都是
+       几十个以内，可读性比复杂度重要；真要上千个再换哈希。 */
+    if (schema.uniqueItems === true) {
+      for (var ui = 0; ui < data.length; ui++) {
+        for (var uj = ui + 1; uj < data.length; uj++) {
+          if (deepEqual(data[ui], data[uj])) {
+            errors.push({ path: ptr + '/' + uj,
+              msg: '第 ' + uj + ' 个元素与第 ' + ui + ' 个重复（uniqueItems）' });
+          }
+        }
+      }
+    }
     if (schema.items) {
       data.forEach(function (v, i) {
         validate(schema.items, v, root, ptr + '/' + i, errors);
@@ -228,6 +280,13 @@ function validate(schema, data, root, ptr, errors) {
       errors.push({ path: ptr, msg: '必须恰好满足 oneOf 中的一条，实际满足 ' + n + ' 条' });
     }
   }
+  /* `not`：**必须不**满足里面的约束。子校验用独立的 errors 数组 ——
+     借用外层数组的话，"不满足 not" 会被记成"满足了"的错，方向正好反了。 */
+  if (schema.not !== undefined) {
+    if (validate(schema.not, data, root, ptr, []).length === 0) {
+      errors.push({ path: ptr, msg: '不应满足 not 里的约束（实际满足了）' });
+    }
+  }
   return errors;
 }
 

package/dist/01-tokens/page.css

@@ -1 +1 @@
-.page {margin:0;min-height:100vh;min-height:100dvh;background:var(--paper);color:var(--text-primary);font-family:var(--sans);font-size:var(--fs-base);line-height:var(--lh-base);-webkit-text-size-adjust:100%;padding-block:calc(env(safe-area-inset-top, 0px) + var(--sp-6)) calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));padding-inline:max(env(safe-area-inset-right, 0px), var(--sp-4)) max(env(safe-area-inset-left, 0px), var(--sp-4));}.page *, .page *::before, .page *::after {box-sizing:border-box;}.page .wrap {margin-inline:auto;max-width:min(var(--measure-page), 100%);}.page .wrap--prose {max-width:min(var(--measure-prose), 100%);}.page h1 {font-family:var(--sans);font-size:var(--fs-2xl);font-weight:500;letter-spacing:var(--tracking-title);line-height:var(--lh-tight);margin:0 0 var(--sp-3);max-width:var(--measure-title);}.page h2 {font-size:var(--fs-lg);margin:var(--sp-7) 0 var(--sp-3);}.page .rule-top {border-top:1px solid var(--border-decor);padding-top:var(--sp-4);}.page .rule-bottom {border-bottom:1px solid var(--border-decor);padding-bottom:var(--sp-2);margin-bottom:var(--sp-4);}.page code {font-family:var(--mono);font-size:0.9em;background:var(--surface-sunken);padding:1px 4px;border-radius:var(--r-xs);}:where(.page) pre {overflow-x:auto;}.page .box {background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);padding:var(--sp-5);}.page .box.bad {background:var(--surface-sunken);}.page .cmp {display:grid;grid-template-columns:minmax(0, 1fr) minmax(0, 1fr);gap:var(--sp-4);}.page .cmp--wide-first {grid-template-columns:minmax(0, 1.55fr) minmax(0, 1fr);}@media (max-width:640px) {.page .cmp, .page .cmp--wide-first, .page .cmp--clip {grid-template-columns:minmax(0, 1fr);}}.page .cmp__pane {padding:var(--sp-4);border:1px solid var(--border-decor);border-radius:var(--r-md);background:var(--surface-sunken);min-width:0;}.page .cmp--clip .cmp__pane {overflow:hidden;}.page .cmp__pane > h3 {margin:0 0 var(--sp-3);font-size:var(--fs-sm);font-weight:500;}.page .cmp__bad > h3 {color:var(--danger);}.page .cmp__good > h3 {color:var(--success);}.page .cmp__why {margin:var(--sp-3) 0 0;font-size:var(--fs-xs);line-height:1.6;color:var(--text-secondary);}
+.page {margin:0;min-height:100vh;min-height:100dvh;background:var(--paper);color:var(--text-primary);font-family:var(--sans);font-size:var(--fs-base);line-height:var(--lh-base);-webkit-text-size-adjust:100%;padding-block:calc(env(safe-area-inset-top, 0px) + var(--sp-6)) calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));padding-inline:max(env(safe-area-inset-right, 0px), var(--sp-4)) max(env(safe-area-inset-left, 0px), var(--sp-4));}@media print {.page {min-height:0;padding-block-end:0;}}.page *, .page *::before, .page *::after {box-sizing:border-box;}.page .wrap {margin-inline:auto;max-width:min(var(--measure-page), 100%);}.page .wrap--prose {max-width:min(var(--measure-prose), 100%);}.page h1 {font-family:var(--sans);font-size:var(--fs-2xl);font-weight:500;letter-spacing:var(--tracking-title);line-height:var(--lh-tight);margin:0 0 var(--sp-3);max-width:var(--measure-title);}.page h2 {font-size:var(--fs-lg);margin:var(--sp-7) 0 var(--sp-3);}.page .rule-top {border-top:1px solid var(--border-decor);padding-top:var(--sp-4);}.page .rule-bottom {border-bottom:1px solid var(--border-decor);padding-bottom:var(--sp-2);margin-bottom:var(--sp-4);}.page code {font-family:var(--mono);font-size:0.9em;background:var(--surface-sunken);padding:1px 4px;border-radius:var(--r-xs);}:where(.page) pre {overflow-x:auto;}.page .box {background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);padding:var(--sp-5);}.page .box.bad {background:var(--surface-sunken);}.page .cmp {display:grid;grid-template-columns:minmax(0, 1fr) minmax(0, 1fr);gap:var(--sp-4);}.page .cmp--wide-first {grid-template-columns:minmax(0, 1.55fr) minmax(0, 1fr);}@media (max-width:640px) {.page .cmp, .page .cmp--wide-first, .page .cmp--clip {grid-template-columns:minmax(0, 1fr);}}.page .cmp__pane {padding:var(--sp-4);border:1px solid var(--border-decor);border-radius:var(--r-md);background:var(--surface-sunken);min-width:0;}.page .cmp--clip .cmp__pane {overflow:hidden;}.page .cmp__pane > h3 {margin:0 0 var(--sp-3);font-size:var(--fs-sm);font-weight:500;}.page .cmp__bad > h3 {color:var(--danger);}.page .cmp__good > h3 {color:var(--success);}.page .cmp__why {margin:var(--sp-3) 0 0;font-size:var(--fs-xs);line-height:1.6;color:var(--text-secondary);}

package/dist/03-patterns/tabs/tabs.css

@@ -1 +1 @@
-.tabs {display:flex;flex-direction:column;gap:var(--sp-4);}.tabs--manual .tabs__tab[aria-selected="true"] {color:var(--text-secondary);font-weight:400;}@media (hover:hover) and (pointer:fine) {.tabs--manual .tabs__tab[aria-selected="true"]:hover {color:var(--text-primary);}}.tabs__list {display:flex;gap:var(--sp-1);border-bottom:1px solid var(--border-decor);position:relative;overflow-x:auto;overflow-y:hidden;scrollbar-width:none;}.tabs__list::-webkit-scrollbar {display:none;}.tabs--vertical {flex-direction:row;gap:var(--sp-4);}.tabs--vertical .tabs__list {flex-direction:column;border-bottom:0;border-inline-end:1px solid var(--border-decor);}.tabs__tab {appearance:none;background:none;border:0;margin-bottom:-1px;padding:var(--sp-3) var(--sp-4);font:inherit;font-size:var(--fs-base);color:var(--text-secondary);cursor:pointer;border-bottom:2px solid transparent;transition:color var(--dur-fast) var(--ease-out), border-color var(--dur-fast) var(--ease-out);white-space:nowrap;flex:0 0 auto;}.tabs--vertical .tabs__tab {margin-bottom:0;margin-inline-end:-1px;border-bottom:0;border-inline-end:2px solid transparent;text-align:start;}.tabs__tab[aria-selected="true"] {color:var(--text-primary);font-weight:600;border-bottom-color:var(--accent);}.tabs--vertical .tabs__tab[aria-selected="true"] {border-inline-end-color:var(--accent);}@media (hover:hover) and (pointer:fine) {.tabs__tab:not([aria-disabled="true"]):hover {color:var(--text-primary);background:var(--surface-sunken);}}.tabs__tab[aria-disabled="true"] {color:var(--text-tertiary);cursor:not-allowed;}.tabs__tab:focus-visible {outline:2px solid var(--accent);outline-offset:-2px;border-radius:var(--r-sm) var(--r-sm) 0 0;}.tabs__panel {padding:var(--sp-4) 0;}.tabs__panel[hidden] {display:none;}@media (prefers-reduced-motion:no-preference) {.tabs__panel--enter {animation:tabs-fade var(--dur-base) var(--ease-out);}}@keyframes tabs-fade {from {opacity:0;}to {opacity:1;}}
+.tabs {display:flex;flex-direction:column;gap:var(--sp-4);}.tabs--manual .tabs__tab[aria-selected="true"] {color:var(--text-secondary);font-weight:400;}@media (hover:hover) and (pointer:fine) {.tabs--manual .tabs__tab[aria-selected="true"]:hover {color:var(--text-primary);}}.tabs__list {display:flex;gap:var(--sp-1);border-bottom:1px solid var(--border-decor);position:relative;overflow-x:auto;overflow-y:hidden;scrollbar-width:none;}.tabs__list::-webkit-scrollbar {display:none;}.tabs--vertical {flex-direction:row;gap:var(--sp-4);}.tabs--vertical .tabs__list {flex-direction:column;border-bottom:0;border-inline-end:1px solid var(--border-decor);}.tabs__tab {appearance:none;background:none;border:0;margin-bottom:-1px;padding:var(--sp-3) var(--sp-4);font:inherit;font-size:var(--fs-base);color:var(--text-secondary);cursor:pointer;border-bottom:2px solid transparent;transition:color var(--dur-fast) var(--ease-out), border-color var(--dur-fast) var(--ease-out);white-space:nowrap;flex:0 0 auto;}.tabs--vertical .tabs__tab {margin-bottom:0;margin-inline-end:-1px;border-bottom:0;border-inline-end:2px solid transparent;text-align:start;}.tabs__tab[aria-selected="true"] {color:var(--text-primary);font-weight:600;border-bottom-color:var(--accent);}.tabs--vertical .tabs__tab[aria-selected="true"] {border-inline-end-color:var(--accent);}@media (hover:hover) and (pointer:fine) {.tabs__tab:not([aria-disabled="true"]):hover {color:var(--text-primary);background:var(--surface-sunken);}}.tabs__tab[aria-disabled="true"] {color:var(--text-tertiary);cursor:not-allowed;}.tabs__tab:focus-visible {outline:2px solid var(--accent);outline-offset:-2px;border-radius:var(--r-sm) var(--r-sm) 0 0;}.tabs__panel {padding:var(--sp-4) 0;}.tabs__panel[hidden] {display:none;}@media (prefers-reduced-motion:no-preference) {.tabs__panel--enter {animation:tabs-fade var(--dur-base) var(--ease-out);}}@keyframes tabs-fade {from {opacity:0;}to {opacity:1;}}@media print {.tabs__panel--enter {animation:none;transition:none;opacity:1;}}

package/dist/COSTS.md

@@ -18,22 +18,22 @@
 
 | 档 | 组件 | tokens（必付） | CSS | JS | **合计** | 源码版合计 | 差 |
 |---|---|---:|---:|---:|---:|---:|---:|
-| primitive | `badge` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 24.7 KB | −21.2 KB |
+| primitive | `badge` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 24.6 KB | −21.2 KB |
 | primitive | `button` | 2.9 KB | 1.0 KB | — | **3.9 KB** | 28.3 KB | −24.4 KB |
 | primitive | `card` | 2.9 KB | 0.9 KB | — | **3.9 KB** | 26.0 KB | −22.1 KB |
 | primitive | `choice` | 2.9 KB | 1.1 KB | — | **4.1 KB** | 28.1 KB | −24.0 KB |
 | primitive | `combobox` | 2.9 KB | 1.0 KB | 5.7 KB | **9.6 KB** | 31.8 KB | −22.2 KB |
-| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.8 KB | **6.6 KB** | 28.9 KB | −22.4 KB |
-| primitive | `delta` | 2.9 KB | 0.3 KB | — | **3.2 KB** | 24.7 KB | −21.5 KB |
-| primitive | `input` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 25.8 KB | −21.9 KB |
+| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.8 KB | **6.6 KB** | 28.9 KB | −22.3 KB |
+| primitive | `delta` | 2.9 KB | 0.3 KB | — | **3.2 KB** | 24.6 KB | −21.4 KB |
+| primitive | `input` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 25.8 KB | −21.8 KB |
 | primitive | `metric` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.1 KB | −21.7 KB |
-| primitive | `popover` | 2.9 KB | 0.8 KB | 2.3 KB | **6.1 KB** | 29.7 KB | −23.7 KB |
+| primitive | `popover` | 2.9 KB | 0.8 KB | 2.3 KB | **6.1 KB** | 29.7 KB | −23.6 KB |
 | primitive | `progress` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 26.2 KB | −22.5 KB |
 | primitive | `select` | 2.9 KB | 0.8 KB | 4.3 KB | **8.1 KB** | 33.1 KB | −25.0 KB |
 | primitive | `separator` | 2.9 KB | 0.2 KB | — | **3.2 KB** | 23.2 KB | −20.0 KB |
 | primitive | `skeleton` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 23.8 KB | −20.4 KB |
-| primitive | `switch` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 30.3 KB | −26.5 KB |
-| primitive | `timeline` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.2 KB | −21.7 KB |
+| primitive | `switch` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 30.2 KB | −26.5 KB |
+| primitive | `timeline` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.1 KB | −21.7 KB |
 | primitive | `upload` | 2.9 KB | 1.4 KB | 4.5 KB | **8.8 KB** | 39.7 KB | −30.9 KB |
 | pattern | `accordion` | 2.9 KB | 1.3 KB | 1.8 KB | **6.0 KB** | 36.4 KB | −30.4 KB |
 | pattern | `content` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 26.8 KB | −22.9 KB |
@@ -42,18 +42,18 @@
 | pattern | `form-validation` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 26.8 KB | −23.1 KB |
 | pattern | `list` | 2.9 KB | 0.6 KB | — | **3.5 KB** | 24.3 KB | −20.8 KB |
 | pattern | `nav` | 2.9 KB | 1.2 KB | 2.6 KB | **6.8 KB** | 33.0 KB | −26.2 KB |
-| pattern | `overlay` | 2.9 KB | 1.2 KB | 3.8 KB | **7.9 KB** | 39.3 KB | −31.3 KB |
-| pattern | `pagination` | 2.9 KB | 0.8 KB | 2.8 KB | **6.5 KB** | 32.8 KB | −26.3 KB |
-| pattern | `reveal` | 2.9 KB | 0.3 KB | 1.2 KB | **4.4 KB** | 26.5 KB | −22.0 KB |
+| pattern | `overlay` | 2.9 KB | 1.2 KB | 3.8 KB | **7.9 KB** | 39.2 KB | −31.3 KB |
+| pattern | `pagination` | 2.9 KB | 0.8 KB | 2.8 KB | **6.5 KB** | 32.7 KB | −26.3 KB |
+| pattern | `reveal` | 2.9 KB | 0.3 KB | 1.2 KB | **4.4 KB** | 26.4 KB | −22.0 KB |
 | pattern | `states` | 2.9 KB | 0.9 KB | — | **3.8 KB** | 26.3 KB | −22.5 KB |
-| pattern | `tabs` | 2.9 KB | 0.7 KB | 2.0 KB | **5.6 KB** | 29.1 KB | −23.5 KB |
+| pattern | `tabs` | 2.9 KB | 0.7 KB | 2.0 KB | **5.7 KB** | 29.2 KB | −23.5 KB |
 | pattern | `tooltip` | 2.9 KB | 0.5 KB | 2.0 KB | **5.4 KB** | 28.7 KB | −23.3 KB |
 | pattern | `tree` | 2.9 KB | 0.6 KB | 3.1 KB | **6.6 KB** | 30.3 KB | −23.7 KB |
 
 ## 三、全库
 
 - 全部组件都用上（min，含 tokens 一份）：**72.6 KB**
-- 源码版（带注释）全库 gzip：386.4 KB
+- 源码版（带注释）全库 gzip：386.7 KB
 
 > ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 69% 是注释，字节口径）。
 > 它的用途只有一个 —— 让人看清"dist 到底省了多少"。

package/docs/ACCESSIBILITY.md

@@ -5,8 +5,8 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.26.0` |
-| 声明日期 | 2026-11-04 |
+| 声明适用版本 | agentcss `0.27.1` |
+| 声明日期 | 2026-11-06 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |
 | 不在范围 | 使用者拿这些组件拼出来的业务页面（那是你的无障碍责任，不是库的） |