iter(g37): llms-full 增加组合配方章节

.ua/backlog.json

@@ -652,6 +652,14 @@
       "acceptance": "result({ status, title, description, extra }) 四档语义色 + 居中终态布局 + role=\"status\"；组件数 43→44 三处计数同步；npm run check 全绿",
       "status": "done",
       "notes": "自补：组件补充"
+    },
+    {
+      "id": "g37",
+      "title": "llms-full 增加组合配方章节",
+      "motivation": "清单只能描述单组件参数，Agent 拼多组件（表单+校验+提交反馈、表格+分页+批量、危险操作确认）时没有权威范例，容易各写一套",
+      "acceptance": "packages/tools/cli/recipes.md 作为唯一来源，ua docs 时追加到 llms-full.txt 末尾；缺少文件时不报错；npm run check 全绿",
+      "status": "open",
+      "notes": "自补：文档与 Agent 查询体验"
     }
   ]
 }

AGENTS.md

@@ -50,7 +50,7 @@
 
 2. **CLI**：`node packages/tools/cli/bin/ua.js list | info <name> | index | docs | style | verify | changelog`
 
-3. **静态索引**：`.ua/index.json`（机器可读索引）、`llms.txt`（速览）或 **`llms-full.txt`（全量 Agent 文档：逐组件参数 / 回调 / 手把手步骤 / 令牌，无图形纯文本，喂给 Agent 首选）**。
+3. **静态索引**：`.ua/index.json`（机器可读索引）、`llms.txt`（速览）或 **`llms-full.txt`（全量 Agent 文档：逐组件参数 / 回调 / 手把手步骤 / 令牌 / 组合配方，无图形纯文本，喂给 Agent 首选）**。
 
 ## 贡献新组件的强制约定
 

llms-full.txt

@@ -1353,3 +1353,85 @@ node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens
 - --ua-font-size-lg: 14px
 
 皮肤包只允许消费这些变量：写死 #hex 会被 verify 拦截，拼错变量名会被令牌引用校验拦截。
+
+
+# 组合配方（Recipes）
+
+> 单个组件的参数表说明「怎么用」，这些配方说明「怎么拼」。所有配方都只消费组件对外 API，不依赖内部文件。
+
+## 配方 1：表单校验 + 提交反馈
+
+```ts
+const name = signal('');
+const email = signal('');
+const formRef = form({ onSubmit: (ok) => (ok ? result({ status: 'success', title: '已保存' }) : toast.error('请检查表单')) }, [
+  formItem({ label: '名称', value: name, required: true, rules: [{ min: 2 }] }, textField({ value: name })),
+  formItem({ label: '邮箱', value: email, required: true, rules: [{ pattern: /^\S+@\S+$/ }] }, textField({ value: email })),
+]);
+```
+
+要点：
+- 校验规则挂在 `formItem`，值信号只有一个来源（`value` 同时给 `formItem` 与控件），避免两处各存一份。
+- 提交结果用 `toast`（轻量、瞬时）或 `result`（整页终态）表达，不要两者同时弹。
+
+## 配方 2：危险操作二次确认
+
+```ts
+const open = signal(false);
+const dangerOpen = (key: string) => {
+  open(true);
+  return modal({
+    title: `确认删除 ${key}？`,
+    open,
+    size: 'sm',
+    onClose: () => open(false),
+    footer: h('div', { class: 'row' },
+      button({ label: '取消', variant: 'ghost', onClick: () => open(false) }),
+      button({ label: '删除', variant: 'danger', onClick: () => { open(false); toast.success('已删除'); } })),
+  }, h('p', null, '删除后不可恢复。'));
+};
+```
+
+要点：
+- `modal` 自带焦点陷阱与 Esc 逐层关闭，不要在业务层再挂 Esc 监听。
+- 确认按钮用 `variant: 'danger'`，取消用 `ghost`，主次分明。
+
+## 配方 3：表格筛选 + 分页 + 批量操作
+
+```ts
+const picked = signal<string[]>([]);
+const page = signal(1);
+dataTable({
+  data: rows,
+  columns: [{ key: 'name', header: '名称', sortable: true }, { key: 'city', header: '城市' }],
+  pageSize: 10,
+  page,          // 同一 page 信号也给 pagination，二者自动联动
+  selectable: true,
+  selected: picked,
+  loading: saving,
+});
+pagination({ page, pageSize: 10, total: rows.length, jumpable: true, onChange: (p) => page(p) });
+```
+
+要点：
+- `page` 信号是表格与分页器的唯一共享状态；外部改页码前自己钳制范围（core 的 `setPage` 不做钳制）。
+- 选中一律存 `rowKey`，翻页/筛选后仍然稳定；全选只作用于当前可见行。
+- 批量操作按钮在 `picked().length === 0` 时禁用，避免空提交。
+
+## 配方 4：长列表数据加载与空态
+
+```ts
+const loading = signal(true);
+const items = signal<ListItem[]>([]);
+list({ items: items(), bordered: true, emptyText: loading() ? '加载中…' : '暂无数据' });
+```
+
+要点：
+- 空态文案随加载态切换；列表本身会在 `items` 为空时渲染 `empty`，不需要业务层再判断一次。
+- 需要骨架屏就换成 `skeleton`，加载完成再 `renderList` 成真实行。
+
+## 通用约定
+
+- 状态一律放信号（`signal` / `computed`），组件只读写信号，不持有业务数据副本。
+- 反馈分层：`toast` 右上角瞬时、`notification` 右下角可长读、`result` 整页终态、`alert` 页内常驻。
+- 样式不要写颜色与间距字面值，先跑 `ua tokens` 查 `--ua-*`（verify 会拦截未定义令牌与 `#hex`）。

packages/tools/cli/bin/ua.js

@@ -359,12 +359,21 @@ function renderAgentDocs(index, tokens) {
     }
     lines.push('---', '');
   }
+/*** 读取组合配方（与 CLI 同目录的 recipes.md），缺失时返回空串 ***/
+function loadRecipes() {
+  const p = path.join(ROOT, 'packages', 'tools', 'cli', 'recipes.md');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8').trim() : '';
+}
+
   const tokenList = loadTokenList(); // 令牌唯一来源：tokens.css（含字号、间距复合值）
   if (tokenList.length) {
     lines.push('## 设计令牌（--ua-*）', '');
     for (const t of tokenList) lines.push(`- ${t.cssVar}: ${t.value}${t.dark && t.dark !== t.value ? `（暗色 ${t.dark}）` : ''}`);
     lines.push('', '皮肤包只允许消费这些变量：写死 #hex 会被 verify 拦截，拼错变量名会被令牌引用校验拦截。', '');
   }
+
+  const recipes = loadRecipes(); // 组合配方：跨组件的拼装指导，清单参数表表达不了
+  if (recipes) lines.push('', recipes, '');
   return lines.join('\n');
 }
 

packages/tools/cli/recipes.md

@@ -0,0 +1,80 @@
+# 组合配方（Recipes）
+
+> 单个组件的参数表说明「怎么用」，这些配方说明「怎么拼」。所有配方都只消费组件对外 API，不依赖内部文件。
+
+## 配方 1：表单校验 + 提交反馈
+
+```ts
+const name = signal('');
+const email = signal('');
+const formRef = form({ onSubmit: (ok) => (ok ? result({ status: 'success', title: '已保存' }) : toast.error('请检查表单')) }, [
+  formItem({ label: '名称', value: name, required: true, rules: [{ min: 2 }] }, textField({ value: name })),
+  formItem({ label: '邮箱', value: email, required: true, rules: [{ pattern: /^\S+@\S+$/ }] }, textField({ value: email })),
+]);
+```
+
+要点：
+- 校验规则挂在 `formItem`，值信号只有一个来源（`value` 同时给 `formItem` 与控件），避免两处各存一份。
+- 提交结果用 `toast`（轻量、瞬时）或 `result`（整页终态）表达，不要两者同时弹。
+
+## 配方 2：危险操作二次确认
+
+```ts
+const open = signal(false);
+const dangerOpen = (key: string) => {
+  open(true);
+  return modal({
+    title: `确认删除 ${key}？`,
+    open,
+    size: 'sm',
+    onClose: () => open(false),
+    footer: h('div', { class: 'row' },
+      button({ label: '取消', variant: 'ghost', onClick: () => open(false) }),
+      button({ label: '删除', variant: 'danger', onClick: () => { open(false); toast.success('已删除'); } })),
+  }, h('p', null, '删除后不可恢复。'));
+};
+```
+
+要点：
+- `modal` 自带焦点陷阱与 Esc 逐层关闭，不要在业务层再挂 Esc 监听。
+- 确认按钮用 `variant: 'danger'`，取消用 `ghost`，主次分明。
+
+## 配方 3：表格筛选 + 分页 + 批量操作
+
+```ts
+const picked = signal<string[]>([]);
+const page = signal(1);
+dataTable({
+  data: rows,
+  columns: [{ key: 'name', header: '名称', sortable: true }, { key: 'city', header: '城市' }],
+  pageSize: 10,
+  page,          // 同一 page 信号也给 pagination，二者自动联动
+  selectable: true,
+  selected: picked,
+  loading: saving,
+});
+pagination({ page, pageSize: 10, total: rows.length, jumpable: true, onChange: (p) => page(p) });
+```
+
+要点：
+- `page` 信号是表格与分页器的唯一共享状态；外部改页码前自己钳制范围（core 的 `setPage` 不做钳制）。
+- 选中一律存 `rowKey`，翻页/筛选后仍然稳定；全选只作用于当前可见行。
+- 批量操作按钮在 `picked().length === 0` 时禁用，避免空提交。
+
+## 配方 4：长列表数据加载与空态
+
+```ts
+const loading = signal(true);
+const items = signal<ListItem[]>([]);
+list({ items: items(), bordered: true, emptyText: loading() ? '加载中…' : '暂无数据' });
+```
+
+要点：
+- 空态文案随加载态切换；列表本身会在 `items` 为空时渲染 `empty`，不需要业务层再判断一次。
+- 需要骨架屏就换成 `skeleton`，加载完成再 `renderList` 成真实行。
+
+## 通用约定
+
+- 状态一律放信号（`signal` / `computed`），组件只读写信号，不持有业务数据副本。
+- 反馈分层：`toast` 右上角瞬时、`notification` 右下角可长读、`result` 整页终态、`alert` 页内常驻。
+- 样式不要写颜色与间距字面值，先跑 `ua tokens` 查 `--ua-*`（verify 会拦截未定义令牌与 `#hex`）。