iter(g34): ua info 支持组件 id 查询并输出可读 props 表

.ua/backlog.json

@@ -628,6 +628,14 @@
       "acceptance": "upload({ accept, multiple, hint, disabled, onChange }) 支持点击/拖拽/键盘选择、清单逐个移除、同名同大小去重、disabled 全禁；组件数 41→42 三处计数同步；npm run check 全绿",
       "status": "done",
       "notes": "自补：组件补充；不内置上传请求，onChange 回传副本"
+    },
+    {
+      "id": "g34",
+      "title": "ua info 支持组件 id 查询",
+      "motivation": "ua info 只认包名，Agent 按组件名查（如 ua info list / MCP get_component(list)）直接 not found，只能翻整包清单；输出还是原始 JSON，抄参数得自己解析",
+      "acceptance": "ua info <组件id> 输出 props 表 + 步骤 + 示例，ua info <包名> 出摘要且 --json 保留原始清单；MCP get_component 支持组件 id（返回 package + component）；npm run check 全绿",
+      "status": "open",
+      "notes": "自补：文档与 Agent 查询体验"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T03:44:14.447Z",
+  "generatedAt": "2026-10-26T03:45:25.126Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -130,7 +130,7 @@
     {
       "name": "@ui-arch/ui",
       "type": "skin-dom",
-      "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / image / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
+      "description": "DOM 皮肤组件库：表单 / 反馈 / 浮层 / 导航 / 数据展示，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌（组件全量见 api.exports 或刚体清单）",
       "tags": [
         "components",
         "dom",
@@ -1968,7 +1968,7 @@
         "exports": [
           "ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt",
           "ua list：列出注册表内所有包与组件数",
-          "ua info <name>：查看单个包的清单详情（api / 约定 / 文档步骤）",
+          "ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单",
           "ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
           "ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
           "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）",
@@ -1980,7 +1980,7 @@
           "MCP tool 入参 schema"
         ]
       },
-      "usage": "node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify",
+      "usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify",
       "conventions": [
         "零依赖：只用 node 标准库，Node >= 18",
         "清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生",
@@ -1990,7 +1990,7 @@
         "intro": "工程层工具包（private，不发布）。所有 Agent 与人都通过它读取组件库：清单驱动索引、文档、MCP 三件套，外加 style / verify 两道门禁。",
         "steps": [
           "装好依赖后先跑 npm run check 确认基线全绿（build → demo → style → typecheck → smoke → index → verify）",
-          "查组件：ua list 看全量，ua info <包名> 看单包 api 与约定",
+          "查组件：ua list 看全量，ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）",
           "查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码",
           "改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
           "在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens",

AGENTS.md

@@ -31,7 +31,7 @@
 
 **提交信息规范**：`COMMITTING.md`（`<type>(<scope>): <中文祈使句>`），`ua commit-lint` + commit-msg 钩子自动校验，迭代提交用 `iter(<条目id>): <subject>`。
 
-## Agent 查询组件库的三种方式
+## Agent 查询组件库的三种方式（`ua info <组件id>` 直接出 props/步骤/示例）
 
 1. **MCP（推荐）**：在 `~/.workbuddy/mcp.json` 注册：
 

README.md

@@ -40,7 +40,7 @@ accordion · alert · avatar · badge · breadcrumb · button · carousel · car
 ## Agent 接入
 
 - 静态：`llms.txt`（速览）/ **`llms-full.txt`（全量：逐组件参数 / 回调 / 手把手 / 令牌）**
-- 命令行：`node packages/tools/cli/bin/ua.js list | info <name> | docs | tokens | verify | mcp`
+- 命令行：`node packages/tools/cli/bin/ua.js list | info <包名|组件id> | docs | tokens | verify | mcp`
 - MCP：在 `~/.workbuddy/mcp.json` 注册 `ua mcp`，可用 `list_components` / `get_component` / `search_components` / `get_tokens`
 
 规范见 `AGENTS.md`（接入手册）、`ARCHITECTURE.md`（分层与依赖方向）、`CODING.md`（编码规范）、`ITERATION.md`（自动迭代协议）。

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T03:44:14.447Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T03:45:25.126Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -41,7 +41,7 @@
 ### @ui-arch/cli
 
 1. 装好依赖后先跑 npm run check 确认基线全绿（build → demo → style → typecheck → smoke → index → verify）
-2. 查组件：ua list 看全量，ua info <包名> 看单包 api 与约定
+2. 查组件：ua list 看全量，ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）
 3. 查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码
 4. 改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）
 5. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens
@@ -1254,7 +1254,7 @@ API 速览：
 
 - ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt
 - ua list：列出注册表内所有包与组件数
-- ua info <name>：查看单个包的清单详情（api / 约定 / 文档步骤）
+- ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单
 - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
 - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
 - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
@@ -1264,7 +1264,7 @@ API 速览：
 一行用法：
 
 ```
-node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify
+node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify
 ```
 
 约定：

llms.txt

@@ -45,7 +45,7 @@
 ## @ui-arch/ui (v0.1.0)
 
 - 类型: skin-dom · 目录: packages/skin/ui
-- 描述: DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / image / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。
+- 描述: DOM 皮肤组件库：表单 / 反馈 / 浮层 / 导航 / 数据展示，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌（组件全量见 api.exports 或刚体清单）
 - API:
   - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用
   - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮
@@ -104,13 +104,13 @@
 - API:
   - ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt
   - ua list：列出注册表内所有包与组件数
-  - ua info <name>：查看单个包的清单详情（api / 约定 / 文档步骤）
+  - ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单
   - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
   - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
   - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
   - ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
   - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components
-- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify`
+- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify`
 - 约定: 零依赖：只用 node 标准库，Node >= 18
 - 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生
 - 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段

packages/skin/ui/ua.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@ui-arch/ui",
   "type": "skin-dom",
-  "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / image / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
+  "description": "DOM 皮肤组件库：表单 / 反馈 / 浮层 / 导航 / 数据展示，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌（组件全量见 api.exports 或刚体清单）",
   "tags": [
     "components",
     "dom",

packages/tools/cli/bin/ua.js

@@ -121,15 +121,47 @@ function cmdList() {
   }
 }
 
-/*** 输出单包完整元数据 ***/
+/*** 摊平组件清单（带所属包），供 info / MCP 按组件 id 查询 ***/
-function cmdInfo(name) {
+function collectComponents(packages) {
+  const list = packages ?? loadIndex().packages;
+  return list.flatMap((pkg) => (pkg.docs?.components ?? []).map((comp) => ({ pkg, comp })));
+}
+
+/*** 渲染组件的人类可读说明：props 表 + 步骤 + 示例，便于直接抄进代码 ***/
+function formatComponent(pkg, comp) {
+  const lines = [`${comp.id} — ${comp.title ?? ''}  (${pkg.name}${comp.demo ? `, demo: ${comp.demo}` : ''})`, ''];
+  if ((comp.props ?? []).length) {
+    lines.push('props:');
+    const width = Math.max(...comp.props.map((x) => (x.n ?? '').length));
+    for (const x of comp.props) lines.push(`  ${(x.n ?? '').padEnd(width)}  ${(x.t ?? '').padEnd(30)} ${x.r ? '必填 ' : '     '}${x.d ?? ''}`);
+    lines.push('');
+  }
+  if ((comp.steps ?? []).length) {
+    lines.push('steps:');
+    comp.steps.forEach((t, i) => lines.push(`  ${i + 1}. ${t}`));
+    lines.push('');
+  }
+  if (comp.example) lines.push('example:', `  ${comp.example}`);
+  return lines.join('\n');
+}
+
+/*** 输出单包或单组件信息：默认人读摘要，--json 输出原始 JSON ***/
+function cmdInfo(name, args = []) {
   const { packages } = loadIndex();
-  const p = packages.find((x) => x.name === name || x.name === `@ui-arch/${name}`);
+  const asJson = args.includes('--json');
-  if (!p) {
+  const pkg = packages.find((x) => x.name === name || x.name === `@ui-arch/${name}`);
-    console.error(`not found: ${name}`);
+  if (pkg) {
+    if (asJson) return console.log(JSON.stringify(pkg, null, 2));
+    return console.log(
+      `${pkg.name}  v${pkg.version}  [${pkg.type}]  ${pkg.description}\n（--json 看完整清单；按组件查：ua info <组件id>）`,
+    );
+  }
+  const hit = collectComponents(packages).find((x) => x.comp.id === name);
+  if (!hit) {
+    console.error(`not found: ${name}（包名与组件 id 都没命中）`);
     process.exit(1);
   }
-  console.log(JSON.stringify(p, null, 2));
+  console.log(asJson ? JSON.stringify({ package: hit.pkg.name, ...hit.comp }, null, 2) : formatComponent(hit.pkg, hit.comp));
 }
 
 // ---- 静态文档站生成 ----
@@ -407,7 +439,7 @@ function cmdMcp() {
     },
     {
       name: 'get_component',
-      description: 'Get full metadata (API, usage, conventions) of one component',
+      description: 'Get one package by name, or one component by its id (returns props/steps/example)',
       inputSchema: {
         type: 'object',
         properties: { name: { type: 'string', description: 'package name, e.g. @ui-arch/table-core or table-core' } },
@@ -439,8 +471,10 @@ function cmdMcp() {
     }
     if (name === 'get_component') {
       const p = packages.find((x) => x.name === args.name || x.name === `@ui-arch/${args.name}`);
-      if (!p) throw new Error(`not found: ${args.name}`);
+      if (p) return p;
-      return p;
+      const hit = collectComponents(packages).find((x) => x.comp.id === args.name); // 退化到组件级查询
+      if (!hit) throw new Error(`not found: ${args.name}`);
+      return { package: hit.pkg.name, ...hit.comp };
     }
     if (name === 'search_components') {
       const q = String(args.query ?? '').toLowerCase();
@@ -910,10 +944,10 @@ switch (cmd) {
     break;
   case 'info':
     if (!args[0]) {
-      console.error('usage: ua info <package-name>');
+      console.error('usage: ua info <包名|组件id> [--json]');
       process.exit(1);
     }
-    cmdInfo(args[0]);
+    cmdInfo(args[0], args.slice(1));
     break;
   case 'docs':
     cmdDocs();

packages/tools/cli/ua.manifest.json

@@ -14,7 +14,7 @@
     "exports": [
       "ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt",
       "ua list：列出注册表内所有包与组件数",
-      "ua info <name>：查看单个包的清单详情（api / 约定 / 文档步骤）",
+      "ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单",
       "ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
       "ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
       "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）",
@@ -26,7 +26,7 @@
       "MCP tool 入参 schema"
     ]
   },
-  "usage": "node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify",
+  "usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify",
   "conventions": [
     "零依赖：只用 node 标准库，Node >= 18",
     "清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生",
@@ -36,7 +36,7 @@
     "intro": "工程层工具包（private，不发布）。所有 Agent 与人都通过它读取组件库：清单驱动索引、文档、MCP 三件套，外加 style / verify 两道门禁。",
     "steps": [
       "装好依赖后先跑 npm run check 确认基线全绿（build → demo → style → typecheck → smoke → index → verify）",
-      "查组件：ua list 看全量，ua info <包名> 看单包 api 与约定",
+      "查组件：ua list 看全量，ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）",
       "查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码",
       "改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
       "在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens",