agentcss 0.25.6 → 0.27.0

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.25.6",
+  "libraryVersion": "0.27.0",
   "$comment": "机器可读的组件契约。slots = BEM 元素名（在本库里元素名就是插槽名），states.enum = 组件会在 DOM 上写出的 data-* 取值，states.legacyClass = 仍未收敛到 data 属性的历史状态类（INVARIANT I-8 未达标）。printPolicy = 这个组件在纸上会发生什么（空数组 = 原样保留）；pagination = 内容是否被分页裁过（server 不许与 expand 同时出现，否则展开的只是当前一页）。",
   "maturityCriteria": {
     "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",
@@ -249,11 +249,13 @@
       },
       "aria": {
         "roles": [
-          "img"
+          "img",
+          "region"
         ],
         "attrs": [
           "hidden",
-          "label"
+          "label",
+          "labelledby"
         ]
       },
       "usesOtherNamespaces": [],
@@ -2411,7 +2413,9 @@
         "legacyClass": []
       },
       "aria": {
-        "roles": [],
+        "roles": [
+          "region"
+        ],
         "attrs": [
           "hidden",
           "label"
@@ -2475,6 +2479,7 @@
       "aria": {
         "roles": [
           "alert",
+          "region",
           "status"
         ],
         "attrs": [

package/ai/pdf.js

@@ -75,6 +75,35 @@ const DEFAULT_MARGIN = '18mm 15mm';
  *    **找不到就明确报错，不许静默降级**。
  *    漂移由 `05-audit/pdf-export-gate.js` 的 E8 交叉核对（两边都找到时必须是同一个文件）。
  */
+/* Playwright 实际会用到的可执行文件名。只收这几个 —— 名字表越宽，
+   越可能在缓存目录里认错文件（例如 README、脚本）。 */
+const PW_EXE = [
+  'chrome', 'chrome.exe',
+  'chrome-headless-shell', 'chrome-headless-shell.exe',
+  'headless_shell', 'headless_shell.exe',
+  'Chromium', 'Google Chrome for Testing', 'Google Chrome for Testing.exe',
+];
+
+/** 在 Playwright 的 chromium* 目录里按文件名找可执行文件（有界递归，depth 层） */
+function scanForExe(dir, depth) {
+  let names;
+  try { names = fs.readdirSync(dir); } catch (e) { return null; }
+  const dirs = [];
+  for (const n of names) {
+    const p = path.join(dir, n);
+    let st;
+    try { st = fs.statSync(p); } catch (e) { continue; }
+    if (st.isDirectory()) { dirs.push(p); continue; }
+    if (PW_EXE.indexOf(n) !== -1) return p;
+  }
+  if (depth <= 0) return null;
+  for (const d of dirs) {
+    const hit = scanForExe(d, depth - 1);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 function chromeCandidates() {
   const out = [];
   if (process.env.AGENTCSS_CHROME) out.push(process.env.AGENTCSS_CHROME);
@@ -97,18 +126,28 @@ function chromeCandidates() {
     out.push('/usr/bin/google-chrome', '/usr/bin/google-chrome-stable',
       '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium');
   }
-  /* CI 上没有系统 Chrome：Playwright 装的那份也得认，否则"能导出"只在开发机上成立 */
-  for (const root of [path.join(os.homedir(), '.cache/ms-playwright'),
-    path.join(os.homedir(), 'Library/Caches/ms-playwright')]) {
+  /* CI 上没有系统 Chrome：Playwright 装的那份也得认，否则"能导出"只在开发机上成立。
+     ⚠️ **不写死目录布局**。Playwright 改过两次命名：
+          chrome-linux/chrome        → chrome-linux64/chrome
+          chrome-linux/headless_shell → chrome-headless-shell-linux64/chrome-headless-shell
+        写死布局的结果就是"某天起突然 no-chrome"（外部审计 F5 实测：
+        干净环境里 `npm ci && npx playwright install chromium` 之后依然找不到）。
+        ⇒ 在 chromium* 目录下按**可执行文件名**有界递归找，布局怎么变都还能找到。
+     ⚠️ Windows 的根目录是 %LOCALAPPDATA%\ms-playwright —— `~/.cache` 在 Windows 上不存在。 */
+  const roots = [
+    process.env.PLAYWRIGHT_BROWSERS_PATH,
+    process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'ms-playwright'),
+    path.join(os.homedir(), '.cache/ms-playwright'),
+    path.join(os.homedir(), 'Library/Caches/ms-playwright'),
+  ].filter(Boolean);
+  for (const root of roots) {
     let names;
     try { names = fs.readdirSync(root); } catch (e) { continue; }
     for (const n of names) {
       if (!/^chromium/.test(n)) continue;
-      for (const rel of ['chrome-linux/chrome',
-        'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
-        'chrome-win/chrome.exe', 'chrome-linux/headless_shell']) {
-        out.push(path.join(root, n, ...rel.split('/')));
-      }
+      /* 深度 4：macOS 的 .app 包多两层（见 browser.js 同一处注释） */
+      const hit = scanForExe(path.join(root, n), 4);
+      if (hit) out.push(hit);
     }
   }
   return out.filter(Boolean);
@@ -163,7 +202,7 @@ function paperSpec(name) {
   return PAPERS[k] ? { key: k, ...PAPERS[k] } : null;
 }
 
-/** 注入到 `<head>` 末尾（**必须在使用者样式之后**，否则同特异性被覆盖 —— E254）。 */
+/** 注入到 `<head>` 末尾（**必须在使用者样式之后**，否则同特异性被覆盖）。 */
 function injectSheet(html, css) {
   const style = '<style id="agentcss-paper" data-agentcss="paper">' + css + '</style>';
   if (/<\/head\s*>/i.test(html)) return html.replace(/<\/head\s*>/i, style + '</head>');
@@ -217,7 +256,7 @@ function exportPdf(o) {
     if (!Number.isInteger(b) || b < 1) {
       /* ⚠️ 用 String() 而不是 JSON.stringify：`JSON.stringify(NaN)` 是 `"null"`，
          于是 `--max-pages=abc` 会报「收到 null」—— 使用者据这句话会去查一个
-         根本不存在的 null（实测踩过，见 E264）。 */
+         根本不存在的 null（实测踩过）。 */
       return { ok: false, code: 'usage',
         message: '--max-pages 必须是 ≥1 的整数，收到 ' + String(o.budget) };
     }
@@ -351,4 +390,7 @@ function overBudgetMessage(got, budget, spec, margin, out, box, injected) {
 module.exports = {
   exportPdf, resolveChrome, normalizeMargin, paperSpec, PAPERS,
   DEFAULT_PAPER, DEFAULT_MARGIN,
+  /* 只为可测性导出：浏览器发现逻辑必须在"没有系统 Chrome"的机器上也能被验证，
+     否则它只会在 CI 上坏、而开发机永远绿。 */
+  chromeCandidates,
 };

package/ai/recipes.json

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": "1.0.0",
+  "$comment": [
+    "版式的「必有件」—— 只收**能从标记本身判定**的那几条。",
+    "每一条都对应 04-recipes/report/README.md 里「三种版式的取舍」表中的一格；",
+    "那张表是这套系统存在的理由：同一份内容换一个阅读目的，该留什么、该放弃什么。",
+    "",
+    "🔴 为什么有的写在 requires、有的写在 unchecked：",
+    "  requires  = 有标记可查（少一个类就是确定的缺件），因此可以直接判红；",
+    "  unchecked = 说得清但判不了（「方法要写明」是内容判断），因此**只打印、不判过**。",
+    "  把后者塞进 requires 只能靠关键词匹配，那会造出一种「看起来在检查」的假绿 ——",
+    "  这套库宁可写「这条没查」，也不写「查过了」。"
+  ],
+  "recipes": {
+    "report/finance": {
+      "label": "report · 金融研究版",
+      "root": ".rep.rep--finance",
+      "css": "04-recipes/report/report.css",
+      "doc": "04-recipes/report/README.md",
+      "why": "给要快速比数字的人看：行长最短、字号小一档，靠关键数字条先给结论。",
+      "requires": [
+        {
+          "selector": ".rep__keyline",
+          "label": "关键数字条",
+          "why": "这一版的读者先看数、后看论证；没有数字条，标题下面就是一大段文字，等于放弃了它唯一的长处。"
+        },
+        {
+          "selector": ".rep__risk",
+          "label": "风险披露",
+          "why": "金融口径的结论必须带约束条件。少了它，页面读起来像建议，而不是分析。"
+        }
+      ],
+      "unchecked": [
+        {
+          "label": "长论证不超过两屏",
+          "why": "篇幅是内容判断，没有可查的标记。超过两屏的推理在这一版里会被跳过 —— 那是作者该拆的，不是工具能判的。"
+        }
+      ]
+    },
+    "report/technical": {
+      "label": "report · 科研技术版",
+      "root": ".rep.rep--technical",
+      "css": "04-recipes/report/report.css",
+      "doc": "04-recipes/report/README.md",
+      "why": "给要逐条核对的人看：行长最窄、行距最松，图与表自动编号。",
+      "requires": [
+        {
+          "selector": ".rep__source",
+          "label": "来源脚注",
+          "why": "这一版的读者会顺着结论回查原始材料；没有来源，逐条核对就无从开始。"
+        }
+      ],
+      "unchecked": [
+        {
+          "label": "方法写明",
+          "why": "「写了方法」没有可查的标记：它可能是一节、也可能是一段。判它需要读懂内容，工具不假装能判。"
+        }
+      ]
+    },
+    "report/magazine": {
+      "label": "report · 杂志编辑版",
+      "root": ".rep.rep--magazine",
+      "css": "04-recipes/report/report.css",
+      "doc": "04-recipes/report/README.md",
+      "why": "给通读一遍的人看：行长最宽、不编号，靠版面节奏而不是编号导航。",
+      "requires": [
+        {
+          "selector": ".rep__pull",
+          "label": "引语块",
+          "why": "这一版靠「停顿」制造节奏；没有引语块，长文会变成一整片同样密度的灰。"
+        },
+        {
+          "selector": ".rep__fig--wide",
+          "label": "出血宽图",
+          "why": "宽图是这一版唯一的视觉重音。全篇只有正文列宽的图，读起来和别的版式没有区别。"
+        }
+      ],
+      "unchecked": [
+        {
+          "label": "审计级追溯",
+          "why": "这一版**有意放弃**了图/表编号（没有编号就引用不了「第几图」）。它不是缺件，是取舍；不作判据。"
+        }
+      ]
+    }
+  }
+}

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 };