From d461a3ed33bad95a7ed703761d5831fc4f682c32 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 11:45:46 +0800 Subject: [PATCH] =?UTF-8?q?iter(g34):=20ua=20info=20=E6=94=AF=E6=8C=81?= =?UTF-8?q?=E7=BB=84=E4=BB=B6=20id=20=E6=9F=A5=E8=AF=A2=E5=B9=B6=E8=BE=93?= =?UTF-8?q?=E5=87=BA=E5=8F=AF=E8=AF=BB=20props=20=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/backlog.json | 8 +++++ .ua/index.json | 10 +++--- AGENTS.md | 2 +- README.md | 2 +- llms-full.txt | 8 ++--- llms.txt | 6 ++-- packages/skin/ui/ua.manifest.json | 2 +- packages/tools/cli/bin/ua.js | 56 +++++++++++++++++++++++------ packages/tools/cli/ua.manifest.json | 6 ++-- 9 files changed, 71 insertions(+), 29 deletions(-) diff --git a/.ua/backlog.json b/.ua/backlog.json index dc2d795..d56fb9f 100644 --- a/.ua/backlog.json +++ b/.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 查询体验" } ] } diff --git a/.ua/index.json b/.ua/index.json index e239a87..8d07d32 100644 --- a/.ua/index.json +++ b/.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 ：查看单个包的清单详情（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 |docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify", + "usage": "node packages/tools/cli/bin/ua.js |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", diff --git a/AGENTS.md b/AGENTS.md index 2471e7e..2291f18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,7 @@ **提交信息规范**：`COMMITTING.md`（`(): <中文祈使句>`），`ua commit-lint` + commit-msg 钩子自动校验，迭代提交用 `iter(<条目id>): `。 -## Agent 查询组件库的三种方式 +## Agent 查询组件库的三种方式（`ua info <组件id>` 直接出 props/步骤/示例） 1. **MCP（推荐）**：在 `~/.workbuddy/mcp.json` 注册： diff --git a/README.md b/README.md index eb9748d..ed216df 100644 --- a/README.md +++ b/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 | 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`（自动迭代协议）。 diff --git a/llms-full.txt b/llms-full.txt index 9ee2ee2..351f4df 100644 --- a/llms-full.txt +++ b/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 ：查看单个包的清单详情（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 |docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify +node packages/tools/cli/bin/ua.js |docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify ``` 约定： diff --git a/llms.txt b/llms.txt index 5612ef9..4787183 100644 --- a/llms.txt +++ b/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 ：查看单个包的清单详情（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 |docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify` +- 用法: `node packages/tools/cli/bin/ua.js |docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify` - 约定: 零依赖：只用 node 标准库，Node >= 18 - 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生 - 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段 diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index af3e679..0977e12 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/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", diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js index f757901..fc76f0f 100644 --- a/packages/tools/cli/bin/ua.js +++ b/packages/tools/cli/bin/ua.js @@ -121,15 +121,47 @@ function cmdList() { } } -/*** 输出单包完整元数据 ***/ -function cmdInfo(name) { +/*** 摊平组件清单（带所属包），供 info / MCP 按组件 id 查询 ***/ +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}`); - if (!p) { - console.error(`not found: ${name}`); + const asJson = args.includes('--json'); + const pkg = packages.find((x) => x.name === name || x.name === `@ui-arch/${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}`); - return p; + if (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 '); + console.error('usage: ua info <包名|组件id> [--json]'); process.exit(1); } - cmdInfo(args[0]); + cmdInfo(args[0], args.slice(1)); break; case 'docs': cmdDocs(); diff --git a/packages/tools/cli/ua.manifest.json b/packages/tools/cli/ua.manifest.json index 2e48719..bbffe8b 100644 --- a/packages/tools/cli/ua.manifest.json +++ b/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 ：查看单个包的清单详情（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 |docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify", + "usage": "node packages/tools/cli/bin/ua.js |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",