agentcss 0.16.1 → 0.24.0

package/CONTRIBUTING.md

@@ -1,5 +1,26 @@
 # 参与贡献
 
+## 语言
+
+**中文优先；英文入口只有 `README.md`。** 这条写在这里，是为了让后来的人不必再反复问一遍：
+
+| 文件 | 语言 | 说明 |
+|---|---|---|
+| `README.md` | 英文 | 对外主入口；`README.zh-CN.md` 是中文详版 |
+| 组件 `README.md` / `demo.html` / CSS 注释 | 中文 | 使用者读的是取舍理由，不是 API 签名 |
+| `API.md` / `SUPPORT.md` / `docs/` / `CONTRIBUTING.md` | 中文 | 契约、边界与工作方式 |
+| `ai/START-HERE.md` | **中文（有意）** | 见下 |
+
+`ai/START-HERE.md` 是给 AI 编码代理看的导航页，它保持中文：
+
+它指向的每一份文档都是中文。只把这一页翻成英文，等于把人送到一面中文墙前 ——
+还会多出一份要同步的真值。英文读者走 `README.md`；语言中立的契约在
+`ai/components.json`（机器可读，不含叙述）；组件的实际行为看 `demo.html`。
+
+⚠️ 这是**记录在案的例外，不是漂移**。若有一天真要面向英文用户，正确做法是
+**整套文档双语**（组件 README + demo 文案 + CSS 注释一起），而不是先翻这一页 ——
+翻一页不会让库变得可用，只会让"其它文档仍是中文"这个事实看不见。
+
 ## 先跑一遍门禁（这一步别跳）
 
 ```bash
@@ -8,7 +29,7 @@ npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
 ```
 
-全量是 **215 道门禁**（4 路并发实测约 9 分钟 / 退出码 0；单道耗时累加 1691 秒，
+全量是 **220 道门禁**（4 路并发实测约 9 分钟 / 退出码 0；单道耗时累加 1691 秒，
 组件层要起浏览器，还要逐张比 96 张视觉截图。0.11.15 起默认 4 路并发）。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。
 

package/README.md

@@ -46,7 +46,7 @@ This is an optional toolbox, not a spec every page must obey.
 - Adding it to an existing site: keep that site's existing framework and styles where they work, and fill only the gap you actually have.
 - When the output is not a web page (slides, documents, email), the layout rules here do not apply.
 
-`ai/START-HERE.md` is the short entry point for tools (~90 lines); `START-HERE.md` at the repository root is the three-step checklist for people.
+**Discovery files for agents:** `llms.txt` (short, English, with the CLI commands), `llms-full.txt` (one page: every component plus its known failure modes), `AGENTS.md` (ten lines: contract, query, validate). `ai/START-HERE.md` is the longer navigation for tools (Chinese, like the component docs); `START-HERE.md` at the repository root is the three-step checklist for people.
 
 ---
 
@@ -171,9 +171,9 @@ Three mistakes the template above already avoids:
 
 ## Components
 
-**37** components (stable 37 / beta 0). Each directory holds a `README.md` (why it is built this way) and a `demo.html` (markup you can copy).
+**40** components (stable 40 / beta 0). Each directory holds a `README.md` (why it is built this way) and a `demo.html` (markup you can copy).
 
-### primitives (15)
+### primitives (17)
 
 | Component | Root class | Purpose |
 |---|---|---|
@@ -212,7 +212,7 @@ Three mistakes the template above already avoids:
 | `tooltip` | `tooltip` | Hover and focus hints |
 | `tree` | `tree` | Expandable tree |
 
-### recipes (4)
+### recipes (5)
 
 | Component | Root class | Purpose |
 |---|---|---|
@@ -247,6 +247,18 @@ Two builds ship:
 
 The source tree keeps every comment — that is documentation, not payload.
 
+**One frozen ceiling.** The whole library is held to a single budget recorded in
+[`05-audit/budget.json`](05-audit/budget.json): a hard ceiling, a reserve that absorbs
+normal additions *without anyone editing a number*, and a ratchet that tightens the
+budget when the library shrinks. The rules — and what would have to be true to raise
+the ceiling — are in [`docs/BUDGET.md`](docs/BUDGET.md).
+
+**Stability.** Since `0.23.0` the public surface is frozen: token names, class names,
+JS members, CLI subcommands and their `--json` shape, contract fields and file paths
+do not disappear or change meaning. Removals go through the deprecation flow, with at
+least one minor version of lead time. What that covers — and what it honestly does
+not — is in [`docs/STABILITY.md`](docs/STABILITY.md).
+
 ---
 
 ## Browser support
@@ -268,7 +280,7 @@ Colour comes from tokens only. Component CSS never writes `@media (prefers-color
 
 ## Machine-readable contract
 
-`ai/components.json` describes each component for tools: usable class names, how state is expressed, required behaviours, maturity. `agentcss ai` (the `bin` entry) validates and queries it.
+`ai/components.json` describes each component for tools: usable class names, how state is expressed, required behaviours, maturity. `ai/pitfalls.json` carries the known failure modes, joined to components by id; `ai/pitfalls-writing.json` holds the ones that happen while writing prose, building demos and publishing pages — those have no component to join to, and keeping them apart is what stops them from showing up as component defects. `agentcss ai` (the `bin` entry) validates and queries both — every subcommand accepts `--json`.
 
 ## Accessibility
 

package/README.zh-CN.md

@@ -45,8 +45,10 @@
   本库只在你确实缺一块时补上去。
 - 输出形态不是网页（PPT / 文档 / 邮件）时，本库的网页布局规则**不适用**。
 
-`ai/START-HERE.md` 是给 AI 用的短入口（约 90 行），`START-HERE.md`（根目录）是给
-人类复用者的三步清单（组件表由脚本生成，不会漂移）。
+**给 AI 的发现层**：`llms.txt`（短，英文，含命令行用法）、`llms-full.txt`（一页看全 40 个组件
+和各自的已知翻车点）、`AGENTS.md`（十行：契约在哪、怎么查、怎么验）。
+`ai/START-HERE.md` 是更长的中文导航；`START-HERE.md`（根目录）是给人类复用者的三步清单
+（组件表由脚本生成，不会漂移）。
 
 ## 安装
 
@@ -183,7 +185,7 @@ dist/01-tokens/tokens.css          ← 拷这个
 01-tokens/tokens.css              ← 源码（带 31.6 KB 注释），用于阅读
 ```
 
-- **别拷源码目录**除非你要读它：全库 CSS 有 67% 是注释（字节口径；字符口径会低报 12 个百分点），`page.css` 一个文件
+- **别拷源码目录**除非你要读它：全库 CSS 有 68% 是注释（字节口径；字符口径会低报 12 个百分点），`page.css` 一个文件
   17.5 KB 里 15.1 KB 是注释。
 - **JS 也拷 `dist/`**：那一份去了注释但没压缩（理由见「体积」一节）。
 
@@ -250,11 +252,19 @@ dist/01-tokens/tokens.css          ← 拷这个
 
 ## 体积：默认给你的已经是干净产物
 
-源码目录（`01-tokens/` `02-primitives/` …）里的 CSS **带着全部注释** —— 实测全库 CSS
-有 **67% 是注释**（399.3 KB 原始里 267.8 KB），`page.css` 单个就有 86%。
+源码目录（`01-tokens/` `02-primitives/` …）里的 CSS **带着全部注释** ——
+实测全库 CSS 有 **约七成是注释**（精确体积由 `dist/COSTS.md` 现算），`page.css` 单个就有 86%。
 
 那些注释是写给你看的取舍理由（为什么这么定、踩过什么坑），不是写给你浏览器看的。
-**注释让你看代码时处处撞墙，构建工具还会把 67% 的字节原样传下去。**
+**注释让你看代码时处处撞墙；从源码目录引入的话，构建工具还会把 68% 的字节原样打进产物。**
+
+**一个冻结的上限。** 整套库受一份账本约束（[`05-audit/budget.json`](05-audit/budget.json)）：
+硬天花板 + 一份「常规新增组件不用改任何数字」的储备 + 一个只在体积下降时收紧的棘轮。
+规则、以及「什么情况才允许抬天花板」，在 [`docs/BUDGET.md`](docs/BUDGET.md)。
+
+**稳定性。** 自 `0.23.0` 起公开面冻结：令牌名、类名、JS 成员、CLI 子命令与 `--json`
+形状、契约字段、文件路径 —— 不消失、不改语义；删除走废弃流程，至少留一个次版本的
+迁移窗口。它覆盖什么、又诚实地覆盖不到什么，在 [`docs/STABILITY.md`](docs/STABILITY.md)。
 
 ⇒ 所以 `import 'agentcss/tokens.css'` **默认给你去注释后的产物**，
 源码版放在 `agentcss/src/*`：

package/START-HERE.md

@@ -35,16 +35,16 @@
 | 组件 | 文件 | 行数 | JS | 什么时候要 |
 |---|---|---|---|---|
 | 按钮 | `02-primitives/button/button.css` | 357 | — | 几乎总要 |
-| 输入框 | `02-primitives/input/input.css` | 239 | — | 有表单就要 |
+| 输入框 | `02-primitives/input/input.css` | 253 | — | 有表单就要 |
 | 标签 / 徽章 | `02-primitives/badge/badge.css` | 141 | — | 有状态标记就要（"已披露""停牌"） |
 | 卡片 | `02-primitives/card/card.css` | 283 | — | 有分组内容就要 |
-| 单选 / 多选 | `02-primitives/choice/choice.css` | 395 | — | 单选 / 多选就要 |
+| 单选 / 多选 | `02-primitives/choice/choice.css` | 424 | — | 单选 / 多选就要 |
 | 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 541** (`select.js`) | 原生 select 的外观或交互不够用就要 |
 | 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 477** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
-| 开关 | `02-primitives/switch/switch.css` | 370 | — | 有"立即生效的设置"就要 |
+| 开关 | `02-primitives/switch/switch.css` | 429 | — | 有"立即生效的设置"就要 |
 | 分隔线 | `02-primitives/separator/separator.css` | 73 | — | 要分开内容块就要 |
-| 加载骨架 | `02-primitives/skeleton/skeleton.css` | 96 | — | 数据还没到、先把版式占住就要 |
-| 进度条 / 环 | `02-primitives/progress/progress.css` | 172 | — | 有耗时过程要给进度就要 |
+| 加载骨架 | `02-primitives/skeleton/skeleton.css` | 114 | — | 数据还没到、先把版式占住就要 |
+| 进度条 / 环 | `02-primitives/progress/progress.css` | 228 | — | 有耗时过程要给进度就要 |
 | 浮层气泡 | `02-primitives/popover/popover.css` | 187 | **必需 323** (`popover.js`) | 要一段信息贴着触发元素浮出来就要 |
 | 日期区间 | `02-primitives/date-range/date-range.css` | 206 | **必需 301** (`date-range.js`) | 要选起止日期就要 |
 | 标签页 | `03-patterns/tabs/tabs.css` | 172 | **必需 316** (`tabs.js`) | 同层级内容切换就要 |
@@ -53,7 +53,7 @@
 | 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 280** (`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` | 129 | **必需 336** (`drawer.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 | — | 提交前要校验就要 |
@@ -62,11 +62,14 @@
 | 长文排版 | `03-patterns/content/content.css` | 286 | — | 写文档 / 长文就要 |
 | 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`，拖放 / 文件列表 / 校验；没有它基础形态照常工作) |  |
 | 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 | **必需 288** (`shell-nav.js`) |  |
 | detail-page | `04-recipes/detail-page/detail-page.css` | 190 | — |  |
 | report | `04-recipes/report/report.css` | 364 | — |  |
-| table | `04-recipes/table/table.css` | 387 | — |  |
+| table | `04-recipes/table/table.css` | 409 | — |  |
 | bar | `09-assets/bar/bar.css` | 166 | **必需 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`) |  |
@@ -91,6 +94,7 @@
 | 侧边抽屉 | `drawer.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
 | 弹窗 / 吐司 | `overlay.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
 | 导航 / 目录 | `nav.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| app-shell | `shell-nav.js` | 键盘 — · ARIA ✓ · 焦点 ✓ |
 | bar | `bar.js` | 键盘 — · ARIA ✓ · 焦点 — |
 | model-viewer | `model-viewer.js` | 键盘 — · ARIA — · 焦点 — |
 | scientific-plot | `scientific-plot.js` | 键盘 — · ARIA ✓ · 焦点 — |
@@ -111,6 +115,7 @@
 | 示例 | 目录 | 它示范什么 |
 |---|---|---|
 | `analysis-report/` | `04-recipes/analysis-report/` | 组合型研究报告：正文 + 辅助栏并排，窄屏退回单栏 |
+| `app-shell/` | `04-recipes/app-shell/` | 应用外壳：侧栏 + 顶栏 + 主区；sticky 侧栏自滚、min-width 防撑破、窄屏收走侧栏 |
 | `data-showcase/` | `04-recipes/data-showcase/` | 四种数据表达方式对照：我到底该用哪个 |
 | `detail-page/` | `04-recipes/detail-page/` | 实体详情页骨架：字段齐全 / 部分缺失 / 无数据，三态同构（DOM 不变） |
 | `longform/` | `04-recipes/longform/` | 单栏长文排版与阅读节奏 |

package/ai/START-HERE.md

@@ -1,5 +1,12 @@
 # AI 使用入口（frontend-lib）
 
+> **English readers:** this index is Chinese, on purpose — the documents it points to
+> (component READMEs, demos, UI copy) are Chinese too, so an English translation of
+> *this page alone* would just walk you into Chinese walls. Start with
+> [`README.md`](../README.md) (English), then use the language-neutral
+> [`ai/components.json`](components.json) for contracts and each component's
+> `demo.html` for behaviour. Language policy: [`CONTRIBUTING.md`](../CONTRIBUTING.md#语言).
+
 > **本文件只做导航，不复制契约与组件文档。** 要细节就去它指的地方看。
 
 ## 0 · 先记住一件事
@@ -30,8 +37,8 @@
 > 它的值直接从 `ai/components.json` 与目录实际内容读出来 —— **不信上面的说法，信这个**。
 
 <!-- ==== AI-INVENTORY-BEGIN ==== -->
-- 组件 **37** 个（`stable` 37）
-- `04-recipes/`（页面级示例）：`analysis-report`（组合型研究报告：正文 + 辅助栏并排，窄屏退回单栏） · `data-showcase`（四种数据表达方式对照：我到底该用哪个） · `detail-page`（实体详情页骨架：字段齐全 / 部分缺失 / 无数据，三态同构（DOM 不变）） · `longform`（单栏长文排版与阅读节奏） · `report`（报告版式系统 v1：共享基础 + 三种版式取舍（杂志 / 科研技术 / 金融研究）） · `table`（专业数据表格：列级格式与单位，三种用途预设）
+- 组件 **40** 个（`stable` 40）
+- `04-recipes/`（页面级示例）：`analysis-report`（组合型研究报告：正文 + 辅助栏并排，窄屏退回单栏） · `app-shell`（应用外壳：侧栏 + 顶栏 + 主区；sticky 侧栏自滚、min-width 防撑破、窄屏收走侧栏） · `data-showcase`（四种数据表达方式对照：我到底该用哪个） · `detail-page`（实体详情页骨架：字段齐全 / 部分缺失 / 无数据，三态同构（DOM 不变）） · `longform`（单栏长文排版与阅读节奏） · `report`（报告版式系统 v1：共享基础 + 三种版式取舍（杂志 / 科研技术 / 金融研究）） · `table`（专业数据表格：列级格式与单位，三种用途预设）
 - `09-assets/`（图表与可视化）：`bar`（柱状图，含图表规范的裁剪铁律） · `echarts-adapter`（把令牌喂给 ECharts，按需引入；本库不含 ECharts） · `model-viewer`（惰性加载的 3D 模型查看器） · `scientific-plot`（二维科学绘图：坐标轴 / 误差棒 / 置信区间带 / 对数轴） · `sparkline`（迷你趋势线，没有坐标轴的走势提示）
 <!-- ==== AI-INVENTORY-END ==== -->
 
@@ -49,8 +56,11 @@
 |---|---|
 | 有哪些组件、多大、JS 是否必需 | 根目录 `START-HERE.md`（组件表由 `05-audit/fix-start-here.py` 生成，不会漂移） |
 | 组件清单与成熟度 | `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`（分层视图） |
 | 组件真实长什么样 | 该组件目录下的 `demo.html` |
+| 英文一页速览 | `llms.txt` / `llms-full.txt`（发现层；本文件是中文详版） |
 | 页面怎么搭 | `04-recipes/` 下的示例 |
 | 令牌怎么改 | README「主题定制」（覆盖 CSS 变量，不需重新编译） |
 
@@ -97,7 +107,31 @@ node ai/cli.js check <doc.json>   # 校验契约文档（读 JSON，不解析原
 > 本文件（就是那份贴进 system prompt 的极简版）的适用范围是
 > **维护 frontend-lib 自身或严格按本库范式写页面**，不是所有 HTML 任务的通用规则。
 
-## 7 · 三句话版本
+## 7 · 为什么没有 MCP server
+
+有人问过要不要把 `ai/*.json` 包成一个 MCP server。结论是**不做**：
+
+1. 十一个子命令**全是只读查询** —— MCP 版本只是换一层传输，一个新能力都没有。
+2. 它会是**第二份真值**：命令怎么调、参数叫什么、返回什么形状，都得再写一遍。
+   CLI 改了 server 没改，就多一处只有用户能发现的错（`--json` 那次已经踩过同类）。
+3. 用户要多信任一个常驻进程（安装、权限、升级），而 CLI 离线、可审计、跑完即退。
+
+**什么情况下该重新考虑**（不是"永远不做"）：
+
+- 宿主环境**跑不了子进程**（浏览器端、沙箱化的 agent 运行时），CLI 根本调不到；
+- 出现需要**跨调用保持状态**的查询（现在没有：每次查询都无状态）。
+
+真要做，形状是给 `cli.js` 套一层 stdio 适配，**不要**重写实现：
+
+```js
+// 伪代码：把 tool 参数翻译成 argv，其余全部复用
+server.tool('ai_query', async (a) => runCli([a.cmd].concat(a.args, ['--json'])));
+```
+
+⚠️ 别在 server 里重新实现筛选（`--maturity` / `--scope` / `--component`）——
+那些判据在 CLI 里有门禁守，复制一份出去等于把门禁绕开。
+
+## 8 · 三句话版本
 
 1. 这是**可选**资产；不适用就用别的，别硬套。
 2. 查组件去根目录 `START-HERE.md` 和组件自己的 `demo.html`，别猜。

package/ai/behaviors.json

@@ -116,6 +116,14 @@
       "reveal": [
         "n/a",
         "不是浮层：入场由 IntersectionObserver 触发，没有打开/关闭状态"
+      ],
+      "upload": [
+        "n/a",
+        "不是浮层：拖放区常驻可见，没有打开/关闭状态，Esc 不参与（Esc 在表单里应当冒泡给外层对话框）"
+      ],
+      "shell-nav": [
+        "n/a",
+        "本层不接任何键：Esc 与点遮罩由抽屉组件的 dismissable 核处理（那是组件级的模态契约，不是外壳的）"
       ]
     },
     "focus-return": {
@@ -202,6 +210,14 @@
       "reveal": [
         "n/a",
         "不改焦点、不接管键盘"
+      ],
+      "upload": [
+        "n/a",
+        "本组件从不\"打开\"任何东西，也就没有打开前的位置要归还；移除文件后焦点留在原地的下一个移除按钮上（removeAt 里局部删节点、不重建列表，就是为这个）"
+      ],
+      "shell-nav": [
+        "n/a",
+        "焦点归位同样在抽屉里做：本层只负责\"打开时把焦点交给谁\"（当前页那一项），关闭后的归位由抽屉的 focus-return 核回给菜单按钮"
       ]
     },
     "roving": {
@@ -288,6 +304,14 @@
       "reveal": [
         "n/a",
         "不是复合控件：没有一组可聚焦项要在其间移动"
+      ],
+      "upload": [
+        "n/a",
+        "文件列表不是\"一组选项\"：每行的移除按钮都是独立的 Tab 站，方向键不应在行间移动焦点（那是 menu/listbox 的语义，会误导读屏）"
+      ],
+      "shell-nav": [
+        "n/a",
+        "侧栏是链接列表，不是 menu / listbox：每项都是独立 Tab 站，方向键在条目间移动焦点是错的语义"
       ]
     },
     "typeahead": {
@@ -374,6 +398,14 @@
       "reveal": [
         "n/a",
         "不是复合控件：没有可键入定位的集合"
+      ],
+      "upload": [
+        "n/a",
+        "没有可跳转的选项集合：列表是\"已选中的文件\"，用户不会按字母去找其中某一个"
+      ],
+      "shell-nav": [
+        "n/a",
+        "没有可跳转的选项集合；用户不会按字母去找导航条目"
       ]
     }
   }

package/ai/cli.js

@@ -57,11 +57,31 @@ function out(obj) {
   process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
 }
 
+var CURRENT_CMD = '';
+
+/* 🔴 失败也必须能被机器读。
+   以前 die() 只往 stderr 写一行中文，`--json` 的调用方拿到的是
+   退出码 1 + 空 stdout —— 它分不清「参数写错了」和「进程崩了」。
+   现在：带 --json 时，失败输出一个**单一 JSON 文档**，与成功路径一样可解析。 */
 function die(msg) {
+  if (isJson()) {
+    out({
+      ok: false,
+      command: CURRENT_CMD || null,
+      error: { kind: 'usage', message: String(msg) }
+    });
+    process.exit(1);
+  }
   process.stderr.write('[FAIL] ' + msg + '\n');
   process.exit(1);
 }
 
+/** 是否要求 JSON 输出。`--json` / `--json=true` 都认，`--json=false` 不认。 */
+function isJson() {
+  var v = flag('json', false);
+  return v === true || v === 'true';
+}
+
 /**
  * 读命令行开关。支持两种写法：
  *   --profile strict
@@ -91,7 +111,7 @@ function cmdCheck(args) {
   var doc = readJSON(file);
   var profile = flag('profile', doc.profile || 'standard');
   var r = validate.validateDoc(doc, { profile: profile });
-  var json = flag('json', false) === true || flag('json', false) === 'true';
+  var json = isJson();
 
   if (json) {
     out(r);
@@ -135,6 +155,10 @@ function cmdValidate(args) {
   var schema = readJSON(path.join(AI, SCHEMAS[which]));
   var data = readJSON(file);
   var r = validate.validate(schema, data);
+  if (isJson()) {
+    out({ ok: r.ok, schema: which, file: file, errors: r.errors || [] });
+    process.exit(r.ok ? 0 : 1);
+  }
   if (r.ok) {
     process.stdout.write('  OK  ' + file + ' 符合 ' + which + ' 契约\n');
     process.exit(0);
@@ -184,7 +208,7 @@ function cmdDiff(args) {
     else if (JSON.stringify(cx || []) !== JSON.stringify(cy || [])) moved.push(id);
   });
 
-  var json = flag('json', false) === true || flag('json', false) === 'true';
+  var json = isJson();
   var res = { added: added, removed: removed, changed: changed, moved: moved };
   if (json) { out(res); process.exit(0); }
 
@@ -209,24 +233,139 @@ function cmdPatch(args) {
   var doc = readJSON(fdoc);
   var p = readJSON(fpatch);
   var r = patch.apply(doc, p);
+
   if (!r.ok) {
+    if (isJson()) {
+      out({ ok: false, applied: 0, errors: r.errors || [] });
+      process.exit(1);
+    }
     r.errors.forEach(function (e) {
       process.stdout.write('  [FAIL] ' + e.path + '  ' + e.msg + '\n');
     });
     process.stdout.write('\n  ⇒ 补丁**未应用**，原文档没有被改动\n');
     process.exit(1);
   }
+
   var det = patch.isDeterministic(doc, p);
+  var o = flag('o', null);
+  if (o) fs.writeFileSync(o, JSON.stringify(r.doc, null, 2) + '\n');
+
+  /* --json 永远输出**一个** JSON 文档：{ok, applied, deterministic, out, doc}。
+     旧版只在"没写 -o"时把 doc 裸打出来 ⇒ 带 -o 时调用方什么也拿不到。 */
+  if (isJson()) {
+    out({
+      ok: true, applied: r.applied, deterministic: det,
+      out: o || null, doc: r.doc
+    });
+    process.exit(det ? 0 : 1);
+  }
+
   process.stdout.write('  OK  已应用 ' + r.applied + ' 个操作 · 确定性：' +
     (det ? '是（同输入两次结果一致）' : '否（🔴 不可回放）') + '\n');
-  if (!det) process.exit(1);
-  var o = flag('o', null);
-  if (o) {
-    fs.writeFileSync(o, JSON.stringify(r.doc, null, 2) + '\n');
-    process.stdout.write('  已写出 ' + o + '\n');
-  } else if (flag('json', false)) {
-    out(r.doc);
+  if (o) process.stdout.write('  已写出 ' + o + '\n');
+  process.exit(det ? 0 : 1);
+}
+
+// ---------------------------------------------------------------- 翻车点
+/* 已知翻车点：`ai/pitfalls.json` 是**人工策展**的事实文件，不是构建产物。
+   为什么不塞进 components.json：那份是机器生成的契约，加一条叙述性字段
+   会让生成器每次重新生成时都要决定"保留还是覆盖"。两份文件各管一件事。 */
+/* 分两份文件，因为读者不同：
+   · `pitfalls.json`         —— 组件 / 版式 / 交付过程。能对上组件的写进 `components`，
+                                `ai components --json` 会把它们挂到组件上。
+   · `pitfalls-writing.json` —— 写文案、做演示、发页面时的失效模式，`components` 恒空。
+   合成一份的代价：`components` 字段会混进一堆「没有组件可挂」的条目，
+   读的人分不清「这个组件没有坑」和「这条本来就不属于组件」。 */
+var PITFALL_FILES = ['pitfalls.json', 'pitfalls-writing.json'];
+var PITFALLS = null;
+
+function pitfallsDoc() {
+  if (PITFALLS) return PITFALLS;
+  var merged = { schemaVersion: '1.0.0', files: [], pitfalls: [] };
+  for (var i = 0; i < PITFALL_FILES.length; i++) {
+    var f = PITFALL_FILES[i];
+    var d = null;
+    try {
+      d = readJSON(path.join(AI, f));
+    } catch (e) {
+      /* 🔴 读不到要**吵**。静默跳过会让 `--scope=writing` 返回 0 条，
+         而 0 条会被读成「这类没有翻车点」—— 实际是「这份文件不存在」。
+         写 stderr 而不是 stdout：stdout 要留给 JSON。 */
+      process.stderr.write('[WARN] 读不到 ai/' + f +
+        '：该文件覆盖的翻车点本次**未提供**\n');
+      continue;
+    }
+    merged.files.push(f);
+    if (d.schemaVersion) merged.schemaVersion = d.schemaVersion;
+    var list = d.pitfalls || [];
+    for (var j = 0; j < list.length; j++) merged.pitfalls.push(list[j]);
   }
+  PITFALLS = merged;
+  return PITFALLS;
+}
+
+function pitfallsFor(id) {
+  var all = pitfallsDoc().pitfalls || [];
+  var outList = [];
+  for (var i = 0; i < all.length; i++) {
+    if ((all[i].components || []).indexOf(id) >= 0) {
+      outList.push({ id: all[i].id, title: all[i].title });
+    }
+  }
+  return outList;
+}
+
+function cmdPitfalls(args) {
+  var doc = pitfallsDoc();
+  var list = (doc.pitfalls || []).slice();
+  var comp = flag('component', null);
+  var scope = flag('scope', null);
+  var tag = flag('tag', null);
+
+  if (comp) {
+    // 拼错的组件名要**吵**：静默返回 0 条会被读成"这个组件没坑"。
+    var ids = readJSON(path.join(AI, 'components.json')).components.map(function (c) {
+      return c.id;
+    });
+    if (ids.indexOf(comp) < 0) {
+      die('未知组件：' + comp + '（可用：' + ids.join(' / ') + '）');
+    }
+    list = list.filter(function (x) {
+      return (x.components || []).indexOf(comp) >= 0;
+    });
+  }
+  if (scope) {
+    list = list.filter(function (x) { return x.scope === scope; });
+  }
+  if (tag) {
+    list = list.filter(function (x) { return (x.tags || []).indexOf(tag) >= 0; });
+  }
+
+  if (isJson()) {
+    /* `files` 是**覆盖面**，不是元数据：调用方看到只加载了一份文件时，
+       才知道「writing 0 条」是这类没有坑，还是那份文件根本没读到。 */
+    out({
+      schemaVersion: doc.schemaVersion,
+      files: doc.files,
+      count: list.length,
+      pitfalls: list
+    });
+    process.exit(0);
+  }
+
+  process.stdout.write('  === 已知翻车点（' + list.length + ' 条' +
+    (comp ? ' · 组件 ' + comp : '') + (scope ? ' · scope ' + scope : '') + '）===\n\n');
+  if (!list.length) {
+    process.stdout.write('  （没有匹配项）\n');
+    process.exit(0);
+  }
+  list.forEach(function (x) {
+    process.stdout.write('  [' + ((x.components || []).length
+      ? x.components.join(',') : x.scope) +
+      '] ' + x.title + '\n');
+    process.stdout.write('      现象：' + x.symptom + '\n');
+    process.stdout.write('      改法：' + x.fix + '\n');
+  });
   process.exit(0);
 }
 
@@ -237,7 +376,16 @@ function cmdComponents(args) {
   var list = doc.components.filter(function (c) {
     return !m || c.maturity === m;
   });
-  if (flag('json', false)) { out(list); process.exit(0); }
+  /* 🔴 每个组件都带上自己的翻车点（id + 标题），字段恒存在（空数组也写）。
+     形状恒定比"有值才出现"好：调用方不用写 if，也不会因为某个组件
+     恰好没有翻车点而少一个键。 */
+  var joined = list.map(function (c) {
+    var one = {};
+    for (var k in c) if (Object.prototype.hasOwnProperty.call(c, k)) one[k] = c[k];
+    one.pitfalls = pitfallsFor(c.id);
+    return one;
+  });
+  if (isJson()) { out(joined); process.exit(0); }
   process.stdout.write('  === 组件契约（' + list.length + ' 个）===\n\n');
   list.forEach(function (c) {
     process.stdout.write('  ' + (c.maturity === 'stable' ? '✅' :
@@ -251,6 +399,11 @@ function cmdComponents(args) {
       process.stdout.write('       ⚠️ 未收敛状态类: .is-' +
         c.states.legacyClass.join(' .is-') + '\n');
     }
+    var ps = pitfallsFor(c.id);
+    if (ps.length) {
+      process.stdout.write('       ⚠️ 翻车点 ' + ps.length + ' 条: ' +
+        ps.map(function (x) { return x.title; }).join(' / ') + '\n');
+    }
   });
   process.stdout.write('\n  ✅ stable  🟡 beta（状态仍在 class 里，I-8 未达标）  🔴 alpha\n');
   process.exit(0);
@@ -391,7 +544,7 @@ function collectAssets() {
 
 function cmdAssets(args) {
   var rows = collectAssets();
-  if (flag('json', false)) { out(rows); process.exit(0); }
+  if (isJson()) { out(rows); process.exit(0); }
   var miss = rows.filter(function (r) { return !r.contract; });
   process.stdout.write('  === 全部资产（' + rows.length + ' 项）===\n');
   process.stdout.write('  契约内 ' + (rows.length - miss.length) + ' 项 · 契约外 ' + miss.length + ' 项\n\n');
@@ -406,7 +559,7 @@ function cmdAssets(args) {
 function cmdTokens(args) {
   var doc = readJSON(path.join(AI, 'tokens.json'));
   var set = flag('set', null);
-  if (flag('json', false)) {
+  if (isJson()) {
     out(set ? doc.sets[set] : doc);
     process.exit(0);
   }
@@ -429,7 +582,7 @@ function cmdTree(args) {
   var doc = readJSON(path.join(AI, 'tokens.tree.json'));
   var set = flag('set', null);
   var cat = flag('cat', null);
-  if (flag('json', false)) {
+  if (isJson()) {
     out(cat && set ? doc.sets[set][cat] : (set ? doc.sets[set] : doc));
     process.exit(0);
   }
@@ -458,7 +611,7 @@ function cmdTree(args) {
 
 function cmdProfile() {
   var doc = readJSON(path.join(AI, 'profiles.json'));
-  if (flag('json', false)) { out(doc); process.exit(0); }
+  if (isJson()) { out(doc); process.exit(0); }
   process.stdout.write('  === 三档 Profile ===\n\n');
   Object.keys(doc.profiles).forEach(function (k) {
     var p = doc.profiles[k];
@@ -478,7 +631,7 @@ function cmdProfile() {
 
 function cmdCapabilities() {
   var doc = readJSON(path.join(AI, 'capabilities.json'));
-  if (flag('json', false)) { out(doc); process.exit(0); }
+  if (isJson()) { out(doc); process.exit(0); }
   process.stdout.write('  === 能力协商 ===\n\n');
   Object.keys(doc.capabilities).forEach(function (k) {
     var c = doc.capabilities[k];
@@ -502,7 +655,8 @@ var CMDS = {
   tokens: cmdTokens,
   tree: cmdTree,
   profile: cmdProfile,
-  capabilities: cmdCapabilities
+  capabilities: cmdCapabilities,
+  pitfalls: cmdPitfalls
 };
 
 function main() {
@@ -510,19 +664,23 @@ 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]\n' +
-      '  ai validate     <file.json> --schema=contract|components|tokens|tokensAudience|tokensTree|deprecations|patch\n' +
-      '  ai diff         <改动前.json> <改动后.json>      按语义 id 比对\n' +
-      '  ai patch        <doc.json> <patch.json> [-o out.json]\n' +
-      '  ai components   [--maturity=stable|beta|alpha]\n' +
+      '  ai check        <doc.json> [--profile=creative|standard|strict] [--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' +
+      '  ai components   [--maturity=stable|beta|alpha] [--json]\n' +
       '  ai assets       [--json]   组件之外的资产：布局 / 微行为核 / 示例页 / 适配器\n' +
-      '  ai tokens       [--set=light|dark]\n' +
-      '  ai tree         [--set=light|dark] [--cat=color]\n' +
-      '  ai profile      列出三档及其差异\n' +
-      '  ai capabilities 列出可协商的能力\n');
+      '  ai tokens       [--set=light|dark] [--json]\n' +
+      '  ai tree         [--set=light|dark] [--cat=color] [--json]\n' +
+      '  ai pitfalls     [--component=<id>] [--scope=component|layout|process|writing] [--tag=<t>] [--json]\n' +
+      '  ai profile      [--json]   列出三档及其差异\n' +
+      '  ai capabilities [--json]   列出可协商的能力\n' +
+      '\n' +
+      '  每个子命令都支持 --json；失败时输出 {ok:false, command, error} 并以非 0 退出。\n');
     process.exit(0);
   }
   var name = argv.shift();
+  CURRENT_CMD = name;
   var fn = CMDS[name];
   if (!fn) die('未知子命令：' + name + '（可用：' + Object.keys(CMDS).join(' / ') + '）');
   try {