diff --git a/.ua/backlog.json b/.ua/backlog.json index dc583e2..0e7c796 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -168,6 +168,14 @@ "acceptance": "新增 drawer.ts：open 信号驱动，placement 左右、width 可调（窄屏 92vw 上限）、footer 操作区、遮罩 / × / Esc 关闭、打开聚焦首个可交互元素；只消费 --ua-* 令牌 + reduced-motion 兜底；导出 / manifest / 文档 / llms-full.txt / demo 同步；npm run check 全绿", "status": "done", "notes": "遮罩开合用 opacity+visibility（与 tooltip/popover 同模式），面板靠 transform:translateX 滑入；width 走 inline style（调用方数据驱动的表现值不进 CSS）；demo 新增 sec-drawer（订单详情 + footer 关闭 + tag/badge 组合）" + }, + { + "id": "d15", + "title": "CLI 包补 ua.manifest.json 并修正文档里的过期组件数", + "motivation": "工具链自身不在注册表里，Agent 无法通过 MCP/llms 发现 ua 的 6 个子命令；AGENTS.md 与 ARCHITECTURE.md 仍写 17 个组件（实际 27）", + "acceptance": "packages/tools/cli/ua.manifest.json（type: tooling）描述 index/list/info/docs/style/verify/mcp 七个子命令与约定，索引包数变 5；AGENTS.md 与 ARCHITECTURE.md 的组件数改成 27；llms.txt / llms-full.txt 重新生成且 CLI 段落可读；npm run check 全绿", + "status": "done", + "notes": "tooling 类型在 ORDER 表外，排序自然落到末尾（??9 兜底），无需改 CLI 排序逻辑；CLI 清单 docs.components 留空，故不参与 verify 的组件级校验；顺带确认 docs 生成对无组件包不报错" } ] } diff --git a/.ua/index.json b/.ua/index.json index cc5fe48..feb55c9 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-23T08:56:29.143Z", + "generatedAt": "2026-10-23T08:57:12.133Z", "repoRoot": ".", "packages": [ { @@ -1270,6 +1270,53 @@ }, "version": "0.1.0", "dir": "packages/skin/ui" + }, + { + "name": "@ui-arch/cli", + "type": "tooling", + "description": "ua 命令行与 MCP 注册表服务：把各包 ua.manifest.json 汇总成机器可读索引（.ua/index.json）、Agent 全量文档（llms-full.txt）与人类文档站，并提供清单一致性门禁。", + "tags": [ + "cli", + "tooling", + "mcp", + "docs", + "gate" + ], + "api": { + "entry": "bin/ua.js", + "exports": [ + "ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt", + "ua list：列出注册表内所有包与组件数", + "ua info ：查看单个包的清单详情（api / 约定 / 文档步骤）", + "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 mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components" + ], + "keyTypes": [ + "ua.manifest.json 清单结构", + "MCP tool 入参 schema" + ] + }, + "usage": "node packages/tools/cli/bin/ua.js |docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify", + "conventions": [ + "零依赖：只用 node 标准库，Node >= 18", + "清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生", + "门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段" + ], + "docs": { + "intro": "工程层工具包（private，不发布）。所有 Agent 与人都通过它读取组件库：清单驱动索引、文档、MCP 三件套，外加 style / verify 两道门禁。", + "steps": [ + "装好依赖后先跑 npm run check 确认基线全绿（build → style → typecheck → smoke → index → verify）", + "查组件：ua list 看全量，ua info <包名> 看单包 api 与约定", + "改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）", + "提交前 npm run check：style 查注释规范，verify 查清单 ↔ 文档 ↔ 演示锚点是否一致", + "在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components" + ], + "components": [] + }, + "version": "0.1.0", + "dir": "packages/tools/cli" } ] } diff --git a/.ua/iterations.log b/.ua/iterations.log index 83a21ec..5ea7de8 100644 --- a/.ua/iterations.log +++ b/.ua/iterations.log @@ -19,3 +19,4 @@ {"time": "2026-10-23T16:55:10+08:00", "id": "d12", "result": "done", "summary": "新增可关闭标签 tag（五档语义色 + closable/onClose，无状态委托调用方重渲染）；demo 用 renderList 演示真实删除；manifest/llms 同步，check 全绿"} {"time": "2026-10-23T16:55:55+08:00", "id": "d13", "result": "done", "summary": "dataTable 列定义新增皮肤层 TableColumn（align + format），内核 ColumnDef 不变；表头/单元格共用对齐类，format 走 textContent；demo/manifest/llms 同步，check 全绿"} {"time": "2026-10-23T16:56:36+08:00", "id": "d14", "result": "done", "summary": "新增抽屉 drawer：open 信号驱动侧滑、placement/width 可配、footer 操作区、遮罩/×/Esc 关闭并聚焦首元素；demo/manifest/llms 同步，check 全绿"} +{"time": "2026-10-23T16:57:22+08:00", "id": "d15", "result": "done", "summary": "CLI 包补 ua.manifest.json（type: tooling，七个子命令 + 约定），注册表 5 包；修正 AGENTS/ARCHITECTURE 过期组件数 17→27；check 全绿"} diff --git a/AGENTS.md b/AGENTS.md index efae679..47eebe2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架 -- `packages/skin/ui`（@ui-arch/ui）：17 个 DOM 组件，样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：27 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private） - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index fb9576b..2770ee9 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 17 个组件 + ui.css +│ │ └── ui/ # 27 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/llms-full.txt b/llms-full.txt index 7979dcb..aac0838 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-23T08:56:29.143Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-23T08:57:12.133Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -38,6 +38,14 @@ 4. 调用组件：const el = textField({ value: name })，把 el 挂到你的容器或配合 h() 组合 5. 读写状态：name() 读、name('张三') 写，界面自动同步，无需手动操作 DOM +### @ui-arch/cli + +1. 装好依赖后先跑 npm run check 确认基线全绿（build → style → typecheck → smoke → index → verify） +2. 查组件：ua list 看全量，ua info <包名> 看单包 api 与约定 +3. 改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料） +4. 提交前 npm run check：style 查注释规范，verify 查清单 ↔ 文档 ↔ 演示锚点是否一致 +5. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components + ## @ui-arch/ui（skin-dom）v0.1.0 27 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。 @@ -820,6 +828,34 @@ import '@ui-arch/tokens/tokens.css'; then use var(--ua-color-accent) etc. in any --- +## @ui-arch/cli（tooling）v0.1.0 + +工程层工具包（private，不发布）。所有 Agent 与人都通过它读取组件库：清单驱动索引、文档、MCP 三件套，外加 style / verify 两道门禁。 + +API 速览： + +- ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt +- ua list：列出注册表内所有包与组件数 +- ua info ：查看单个包的清单详情（api / 约定 / 文档步骤） +- 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 mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components + +一行用法： + +``` +node packages/tools/cli/bin/ua.js |docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify +``` + +约定： + +- 零依赖：只用 node 标准库，Node >= 18 +- 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生 +- 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段 + +--- + ## 设计令牌（--ua-*） - --ua-color-bg: #ffffff（暗色 #101216） diff --git a/llms.txt b/llms.txt index 1940753..41af853 100644 --- a/llms.txt +++ b/llms.txt @@ -79,3 +79,20 @@ - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调 - 约定: 语义色 variant 四档：default|info / success / warning / danger，一律来自令牌，禁止硬编码颜色 + +## @ui-arch/cli (v0.1.0) + +- 类型: tooling · 目录: packages/tools/cli +- 描述: ua 命令行与 MCP 注册表服务：把各包 ua.manifest.json 汇总成机器可读索引（.ua/index.json）、Agent 全量文档（llms-full.txt）与人类文档站，并提供清单一致性门禁。 +- API: + - ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt + - ua list：列出注册表内所有包与组件数 + - ua info ：查看单个包的清单详情（api / 约定 / 文档步骤） + - 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 mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components +- 用法: `node packages/tools/cli/bin/ua.js |docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify` +- 约定: 零依赖：只用 node 标准库，Node >= 18 +- 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生 +- 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段 diff --git a/packages/tools/cli/ua.manifest.json b/packages/tools/cli/ua.manifest.json new file mode 100644 index 0000000..0d0b811 --- /dev/null +++ b/packages/tools/cli/ua.manifest.json @@ -0,0 +1,36 @@ +{ + "name": "@ui-arch/cli", + "type": "tooling", + "description": "ua 命令行与 MCP 注册表服务：把各包 ua.manifest.json 汇总成机器可读索引（.ua/index.json）、Agent 全量文档（llms-full.txt）与人类文档站，并提供清单一致性门禁。", + "tags": ["cli", "tooling", "mcp", "docs", "gate"], + "api": { + "entry": "bin/ua.js", + "exports": [ + "ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt", + "ua list：列出注册表内所有包与组件数", + "ua info ：查看单个包的清单详情（api / 约定 / 文档步骤）", + "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 mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components" + ], + "keyTypes": ["ua.manifest.json 清单结构", "MCP tool 入参 schema"] + }, + "usage": "node packages/tools/cli/bin/ua.js |docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify", + "conventions": [ + "零依赖：只用 node 标准库，Node >= 18", + "清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生", + "门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段" + ], + "docs": { + "intro": "工程层工具包（private，不发布）。所有 Agent 与人都通过它读取组件库：清单驱动索引、文档、MCP 三件套，外加 style / verify 两道门禁。", + "steps": [ + "装好依赖后先跑 npm run check 确认基线全绿（build → style → typecheck → smoke → index → verify）", + "查组件：ua list 看全量，ua info <包名> 看单包 api 与约定", + "改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）", + "提交前 npm run check：style 查注释规范，verify 查清单 ↔ 文档 ↔ 演示锚点是否一致", + "在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components" + ], + "components": [] + } +}