@blueking/bk-ai-kit

一条命令，把一套跨工具（Cursor + CodeBuddy）的前端 AI 辅助开发体系装进 Vue 3 + bkui-vue 前端仓库。

核心理念 「复用机制，生成内容」：

• 机制内核（自进化引擎 learn-lesson、会话记忆 Hook、双工具同源治理、诊断）→ 原样复制。
• 项目内容（Design Token 值、核心规则、脚手架、模块结构）→ 由编辑器里的 /generate-ai-kit 按你的 design-guideline.md 生成。

CLI 只做确定性的事（铺文件 / 建 symlink / 写配置）；判断性的事交给 AI。

快速开始

npm i -D @blueking/bk-ai-kit
npx bk-ai-kit init

init 会：

1. 把套件复制到 .cursor/skills/（generate-ai-kit 编排 + 全量素材，以及可立即运行的 diagnose-ai-setup）。
2. 建 .codebuddy/{rules,skills} → .cursor/... 的 symlink（Windows / 无权限时退化为复制并警告）。
3. 写 ai-kit.config.json（记录所有占位值 + 套件版本）。

⚠️ MVP 重要约定：init 不做占位替换。完成时 .cursor/ 里的资产仍带 {{...}}、尚非可用态。

必做的下一步

在编辑器（Cursor / CodeBuddy）里运行：

/generate-ai-kit

它读取 ai-kit.config.json + 你喂入的 design-guideline.md，完成全部占位替换并生成项目内容（token / 规则 / 脚手架 / 并入 bkui-vue 组件库通用经验），并把内核落位到最终位置。

自检

npx bk-ai-kit diagnose

跑健康体检（rules frontmatter / skills 命名 / 双工具 symlink / Token 卫生 / 经验库索引同步）。存在 ❌ 时退出码为 1，可一行接入 CI：

- run: npx bk-ai-kit diagnose

diagnose 优先读 ai-kit.config.json 取路径，缺失时回落默认。

命令

| 命令 | 说明 | |------|------| | init | 复制套件 + 建 symlink + 写 ai-kit.config.json（不做占位替换） | | diagnose | 健康体检，读 config 取路径，可进 CI | | upgrade | 只重铺内核、不动已生成内容（v2，未实现） |

init 选项

缺省走交互（能从目标 package.json 推断的先推断）；非 TTY 或 --yes 时直接用推断/flag 值。

--dry-run, -n        只预览将要进行的操作，不写任何文件
--yes, -y            非交互，全部用推断/flag 值
--force              覆盖本套件自己写过的资产/配置（仍不会删除你的非空真实目录）
--tool <v>           cursor | codebuddy | both（默认 both）
--prefix <v>         Token 前缀
--scope <v>          前端包 rule 前缀
--frontendPkg <v>    前端包根（相对仓库根）
--projectGlobs <v>   通用规则 globs
--docsDir <v>        详细文档目录
--lessonsDir <v>     经验库目录
--tokensScssDir <v>  Token SCSS 产物目录

在已有项目上 init（安全契约）

绝大多数场景是给已有项目接入，所以 init 遵循一份安全契约——安全压倒便利：

• 幂等：重复跑 init 收敛到同一结果。已是套件自己产物的（正确 symlink / 套件写的 config）→ 跳过或就地更新；第二次跑无任何变更。
• 非破坏：对你的真实内容（手写文件、非空真实目录）绝不删改——--force 也不会删。
• 可预览：--dry-run 列出将创建 / 合并 / 跳过 / 冲突的每一项，不写盘。
• 可备份：任何覆盖动作先写 <目标>.bak-<时间戳> 再覆盖。

具体规则：

• 资产（.cursor/skills/generate-ai-kit、diagnose-ai-setup）：已存在则跳过；--force 才整覆盖，且覆盖前先备份。
• ai-kit.config.json 用合并而非整覆盖：重跑 = 补缺失键 + 保留你已调的值（含自定义键）+ 只更新 aiKitVersion；无变化则幂等跳过；--force 才整覆盖（先备份）。
• .codebuddy/{rules,skills} 是真实非空目录（项目已用 CodeBuddy）：默认跳过 symlink 并报告差异文件 + 精确迁移命令；要自动接管用 --adopt-codebuddy（备份原目录 → 非冲突文件并入 .cursor/ → 再建 symlink，同名文件保留 .cursor 版本、你的版本留在备份里）。只有空目录会被安全替换为 symlink。

接入前建议先预览：

npx bk-ai-kit init --dry-run

备份产物为 *.bak-<时间戳>，确认无误后可自行删除，或加入 .gitignore。

ai-kit.config.json

贯穿全流程的单一配置，被 init（写）、diagnose（取路径）、/generate-ai-kit（读占位值 + 执行替换）、upgrade（v2）共同消费。

{
  "aiKitVersion": "0.1.0",
  "tool": "both",
  "prefix": "acme",
  "scope": "app-v1",
  "frontendPkg": "packages/app",
  "projectGlobs": "src/**",
  "frontendPkgGlobs": "packages/app/**",
  "docsDir": "packages/app/docs/ai-rules",
  "lessonsDir": "packages/app/docs/ai-rules",
  "tokensScssDir": "packages/app/src/styles/tokens"
}

套件构成

| 层 | 复用范围 | init 处理 | |----|---------|------------| | kernel（机制） | 项目无关 | 随套件复制，由 /generate-ai-kit 落位 + 替换路径/前缀占位 | | component-library（组件库级） | bkui-vue 经验 | 随套件并入（bkui-vue 为前提） | | templates（项目内容） | 因项目而异 | 由 /generate-ai-kit 按 design-guideline.md + 工程分析填占位 |

Token 的机制随包走（分层 SCSS：_primitive 无损镜像 + _semantic UI 契约，无构建链），值按项目从自己的 design-guideline.md 现生成、不打包。

要求

• Node >= 16.7.0
• 目标仓库为 git 仓库、含 package.json

License

MIT