@yk-ui/for-agents

为 AI 编码助手提供 @yk-ui 组件库的上下文知识，让开发者用 vibe coding 产出规范页面。

包结构

src/
  rules/              # 约束规则（7 篇）
  skills/             # 页面最佳实践（4 篇）
  components/         # 组件知识库（按 base/grid 分组）
  index.json          # 清单入口
scripts/
  sync-components.js  # 同步脚本

三层内容

| 层 | 作用 | 数量 | | ---------- | ---------------- | ----------------- | | rules | 约束 AI 决策边界 | 7 篇 | | skills | 高频页面最佳实践 | 4 篇 | | components | 组件知识库 | base 60+ / grid 2 |

消费方使用

1. 安装

pnpm add @yk-ui/for-agents

2. 软链接到 AI 工具目录

根据使用的 AI 工具，将 node_modules/@yk-ui/for-agents/src/ 软链到项目根的 AI 上下文目录。

Cursor

ln -s ../../node_modules/@yk-ui/for-agents/src .cursor/rules/yk-ui

Claude Code

ln -s ../../node_modules/@yk-ui/for-agents/src .claude/skills/yk-ui

Trae / 通用

ln -s ../node_modules/@yk-ui/for-agents/src .ai/yk-ui

3. 在项目 AGENTS.md 中引用

在消费方项目的 AGENTS.md 或 CLAUDE.md 中追加：

## 组件库上下文

本项目使用 @yk-ui 组件库，AI 编码前必须先读取以下上下文：

- 入口清单：.ai/yk-ui/index.json
- 规则约束：.ai/yk-ui/rules/\*.md（必读 component-first.md 与 self-check.md）
- 页面模板：.ai/yk-ui/skills/\*.md（按页面类型选读）
- 组件参考：.ai/yk-ui/components/（按需检索）

生成页面后必须执行 self-check.md 的清单自检并报告符合度。

日常维护

新增组件后同步 reference

当 @yk-ui/base 或 @yk-ui/grid 新增组件后，在 for-agents 目录运行：

cd packages/for-agents
pnpm sync

脚本会：

1. 扫描 packages/base/src/*/index.js 与 packages/grid/src/ 提取组件清单
2. 读取每个组件源码 + 类型声明 + vuepress 文档
3. 生成/更新 src/components/base/*.md 或 src/components/grid/*.md 的结构化骨架
4. 更新 src/index.json 清单

保护机制（重要）

脚本仅生成结构化段（Props/Slots/Events/Methods），手工补充的"决策提示"段通过 HTML 注释标记保护，重复执行不覆盖：

<!-- MANUAL:START -->

## 决策提示

- 何时用本组件...
<!-- MANUAL:END -->

• 修改结构化段的内容会被下次 sync 覆盖
• 修改 MANUAL 区块的内容会保留
• 新增组件时脚本自动创建完整文件（含空的 MANUAL 区块）

新增/修改 rules 或 skills

直接编辑 src/rules/*.md 或 src/skills/*.md，无需运行脚本。

修改后更新 src/index.json 的对应条目（标题/路径）。

版本同步策略

• for-agents 独立版本号
• 当 base 或 grid 发生 breaking change 时，需手动 bump for-agents 版本并同步 reference
• 建议在 base/grid 的 release 流程中加一步：检查 for-agents 是否需要同步

重点说明

1. 不构建、不打包：本包直接发布 src 源码，对齐 @yk-ui/utils 策略，文档包无需构建产物
2. 单一事实源：index.json 是全局清单入口，AI 工具与脚本都从它读取
3. 软链而非拷贝：消费方软链 src/ 到 AI 工具目录，包升级后自动生效，无需重复同步
4. 不绑定 AI 工具：通用 .md 格式，消费方按需映射到自己的工具协议（Cursor / Claude Code / Trae 等）
5. 保护机制：MANUAL 区块不会被脚本覆盖，结构化段会被覆盖
6. 直包组件简化：wrap-element-ui 模式产出的组件不重复生成 props 表，仅标注等价关系 + 决策提示
7. 职责边界 = UI 渲染规范：本包聚焦 @yk-ui/base / @yk-ui/grid / @yk-ui/theme 的 UI 组件使用规范，不覆盖 @yk-ui/utils（xe-utils 全量透传，AI 已有训练知识）与 @yk-ui/request（HTTP 客户端属业务项目层约定，由消费方在自身 AGENTS.md 中规定 baseURL/拦截器/token 注入等）

与本仓库 .trae/skills/ 的关系

• @yk-ui/for-agents 面向消费方，与具体 AI 工具解耦
• 本仓库 .trae/skills/ 面向本仓库贡献者（如 wrap-element-ui），两者职责不同
• wrap-element-ui skill 产出的新组件，需由 sync-components.js 同步到 for-agents/src/components/，形成闭环