temp/UI

Files

T

shawn 0de9b6e66e init: @ui-arch 私人组件库 monorepo

- core/table-core: Headless 表格内核（排序/筛选/分页/选择插件 + 冒烟 9 项）
- core/frame: signal/computed/effect + hyperscript 微框架（零依赖）
- skin/ui: 16 个 DOM 组件（含自绘 select、滑动指示条 tabs、行选择 dataTable、form 表单校验）
- design/tokens: --ua-* 设计令牌（light/dark）
- tools/cli: ua 命令行（index/list/info/docs/style/mcp）+ MCP 注册表服务
- apps: demo 演示站（esbuild 单文件）+ docs 双轨文档（人类版 + llms-full.txt）

2026-10-23 14:58:53 +08:00

3.4 KiB

Raw Blame History

AGENTS.md - Agent 接入手册

面向 AI Agent（以及新加入的人类协作者）的组件库使用规范。本文件同时是项目入口文档。

环境准备（新 Agent 必读，先跑通再干活）

包管理器必须用 pnpm：包间依赖用 workspace:* 协议，npm 不支持。安装依赖：pnpm install。
构建工具：TypeScript 5（tsc）。若环境未全局安装，可使用托管工作区的副本：C:/Users/shawn/.workbuddy/binaries/node/workspace/node_modules/typescript（本仓库历史即如此构建）。
Node：>= 18，ESM（"type": "module"）。
验证自检：装好后先跑 npm run check（build → style → typecheck → smoke → index）确认基线全绿，再开始改代码。

编码规范（强制）

所有 TS / JS 代码遵循 CODING.md：注释一律中文（函数级 /*** 作用 ***/、行尾 // 短注释），代码紧凑 + 行工整、卫语句单行，高可扩展、低抽象、可读性优先。

注释强制门禁：npm run style（即 ua style）机器检查——导出必须有 /*** ***/ 注释、接口字段必须有行尾注释、行注释必须中文；有违规即退出码 1，改完才能提交。

项目结构（权威定义见 ARCHITECTURE.md）

分层目录，依赖方向单向 apps → skin → core → design：

packages/core/table-core（@ui-arch/table-core）：Headless 表格逻辑内核
packages/core/frame（@ui-arch/frame）：signal + hyperscript 微框架
packages/skin/ui（@ui-arch/ui）：16 个 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
apps/docs：文档站，纯产物（ua docs 生成）

门禁一条龙：npm run check = style + typecheck + smoke + index，提交前必过。

Agent 查询组件库的三种方式

MCP（推荐）：在 ~/.workbuddy/mcp.json 注册：

{
  "mcpServers": {
    "ui-arch-registry": {
      "command": "node",
      "args": ["<仓库绝对路径>/packages/tools/cli/bin/ua.js", "mcp"]
    }
  }
}

可用工具：list_components / get_component / search_components。

CLI：node packages/tools/cli/bin/ua.js list | info <name> | index
静态索引：.ua/index.json（机器可读索引）、llms.txt（速览）或 llms-full.txt（全量 Agent 文档：逐组件参数 / 回调 / 手把手步骤 / 令牌，无图形纯文本，喂给 Agent 首选）。

贡献新组件的强制约定

按 ARCHITECTURE.md 分层模型确定目录归属：逻辑→core，渲染→skin，令牌→design，脚本→tools
新包必须包含 ua.manifest.json（name/type/description/tags/api/usage），否则不会被索引；type 取值：headless-core / skin-dom / design-tokens / tooling
行为逻辑放 core 包，DOM 渲染放 skin 包；皮肤间不互相依赖，公共逻辑下沉 core
皮肤包禁止硬编码颜色/间距，一律使用 --ua-* 令牌
选择类状态一律存 rowKey，不存行索引
改动后运行 npm run index 刷新注册表；新增组件记得在 manifest 的 docs.components 里补参数表与手把手步骤，npm run docs 会同步生成人类版文档站与 llms-full.txt

3.4 KiB Raw Blame History Unescape Escape