iter: d15 CLI 包补清单 + 文档组件数纠正

2026-10-23 16:57:22 +08:00
parent d3fc754b33
commit 1c03c8113a
8 changed files with 149 additions and 4 deletions
@@ -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 生成对无组件包不报错"
    }
  ]
 }
@@ -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 <name>：查看单个包的清单详情（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 <index|list|info <name>|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"
    }
  ]
 }
@@ -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 全绿"}
@@ -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
@@ -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，不发布）
@@ -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 <name>：查看单个包的清单详情（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 <index|list|info <name>|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）
@@ -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 <name>：查看单个包的清单详情（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 <index|list|info <name>|docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify`
+- 约定: 零依赖：只用 node 标准库，Node >= 18
+- 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 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 <name>：查看单个包的清单详情（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 <index|list|info <name>|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": []
+  }
+}