HIsheR
65 lines
5.2 KiB
Markdown
65 lines
5.2 KiB
Markdown
# AGENTS.md - Agent 接入手册
|
||
|
||
面向 AI Agent（以及新加入的人类协作者）的组件库使用规范。本文件同时是项目入口文档。
|
||
|
||
## 环境准备（新 Agent 必读，先跑通再干活）
|
||
|
||
1. **包管理器必须用 pnpm**：包间依赖用 `workspace:*` 协议，npm 不支持。安装依赖：`pnpm install`。
|
||
2. **构建工具**：TypeScript 5（`tsc`）。若环境未全局安装，可使用托管工作区的副本：`C:/Users/shawn/.workbuddy/binaries/node/workspace/node_modules/typescript`（本仓库历史即如此构建）。
|
||
3. **Node**：>= 18，ESM（`"type": "module"`）。
|
||
4. **验证自检**：装好后先跑 `npm run check`（build → demo → style → typecheck → smoke → index → verify）确认基线全绿，再开始改代码。
|
||
|
||
## 编码规范（强制）
|
||
|
||
所有 TS / JS 代码遵循 `CODING.md`：注释一律中文（函数级 `/*** 作用 ***/`、行尾 `// 短注释`），代码紧凑 + 行工整、卫语句单行，高可扩展、低抽象、可读性优先。
|
||
|
||
**注释强制门禁**：`npm run style`（即 `ua style`）机器检查——导出必须有 `/*** ***/` 注释、接口字段必须有行尾注释、行注释必须中文，并强制**分层包 src 下单文件 ≤ 200 行**（`types.ts` 与 `index.ts` 作为类型/导出汇总豁免）；有违规即退出码 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）：56 个 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` = build + demo + style + typecheck + smoke + index + verify，提交前必过。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致（docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、每个文档字段名必须在组件实现源码里真实出现（改名后忘改文档会直接报错）、反向也校验 `src/types.ts` 里 `<组件>Props`（可用清单的 `propsType` 覆盖接口名，`false` 表示无入参）每个字段都在文档 props 表登记（新加字段忘了写文档会报错）、demo 锚点必须在 `apps/demo/main.ts` 中存在，且该组件必须被 demo 真实调用 `id(` / `id.`），检查皮肤包样式表无硬编码颜色（`#hex` 一律禁止，必须走 `--ua-*` 令牌）与令牌引用有效（`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量），核对 README 的 `<!-- ua:components -->` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应。
|
||
|
||
**变更日志**：`CHANGELOG.md` 由 git 提交史生成（`npm run changelog`），**不进 `npm run check`**——它包含每个提交自身，提交后必然与历史差一条，只能作为「发版前刷新」步骤；`npm run changelog:check` 用于确认是否漂移。
|
||
|
||
**提交信息规范**：`COMMITTING.md`（`<type>(<scope>): <中文祈使句>`），`ua commit-lint` + commit-msg 钩子自动校验，迭代提交用 `iter(<条目id>): <subject>`。
|
||
|
||
## Agent 查询组件库的三种方式（`ua info <组件id>` 直接出 props/步骤/示例）
|
||
|
||
1. **MCP（推荐）**：在 `~/.workbuddy/mcp.json` 注册：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"ui-arch-registry": {
|
||
"command": "node",
|
||
"args": ["<仓库绝对路径>/packages/tools/cli/bin/ua.js", "mcp"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
可用工具：`list_components` / `get_component` / `search_components` / `get_tokens`（返回 --ua-* 令牌清单，避免硬编码颜色间距）。
|
||
|
||
2. **CLI**：`node packages/tools/cli/bin/ua.js list | info <name> | index | docs | style | verify | changelog`
|
||
|
||
3. **静态索引**：`.ua/index.json`（机器可读索引）、`llms.txt`（速览）或 **`llms-full.txt`（全量 Agent 文档：逐组件参数 / 回调 / 手把手步骤 / 令牌 / 组合配方，无图形纯文本，喂给 Agent 首选）**。
|
||
|
||
## 贡献新组件的强制约定
|
||
|
||
1. 按 `ARCHITECTURE.md` 分层模型确定目录归属：逻辑→core，渲染→skin，令牌→design，脚本→tools
|
||
2. 新包必须包含 `ua.manifest.json`（name/type/description/tags/api/usage），否则不会被索引；type 取值：headless-core / skin-dom / design-tokens / tooling
|
||
3. 行为逻辑放 core 包，DOM 渲染放 skin 包；皮肤间不互相依赖，公共逻辑下沉 core
|
||
4. 皮肤包禁止硬编码颜色/间距，一律使用 `--ua-*` 令牌
|
||
5. 选择类状态一律存 rowKey，不存行索引
|
||
6. 改动后运行 `npm run index` 刷新注册表；新增组件记得在 manifest 的 `docs.components` 里补参数表与手把手步骤，`npm run docs` 会同步生成人类版文档站与 llms-full.txt
|