@bkui-vue/cli

离线 BKUI Vue 组件知识库 CLI，供开发者、IDE 和 AI 助手查询组件 API、文档与 Demo，并检查业务项目中的 BKUI Vue 使用情况。

本包提供 bkui-vue 命令，与 TencentBlueKing/bkui-cli 相互独立，不占用 bkui 命令名。所有组件数据随包发布，查询和项目诊断无需联网。

能做什么

• 查询组件列表、API、实例方法、文档和 Demo 源码。
• 搜索组件、API 字段和 Demo，并校验知识库质量。
• 对比不同 BKUI Vue 版本的 API 和组件变化。
• 只读诊断业务项目环境、组件使用情况和常见问题。
• 生成经验证的代码片段、最小 Vite 示例和迁移检查报告。
• 为 IDE、Agent 和文档索引服务生成 AI 可读数据。

环境要求

• Node.js >= 20

安装

npm install -g @bkui-vue/cli

快速开始

# 查看组件列表
bkui-vue list

# 查询组件 API；组件名支持 Button、bk-button 等形式
bkui-vue info Button
bkui-vue info Button --detail

# 搜索 API、组件和 Demo
bkui-vue search row-key

# 查看 Demo 列表或源码
bkui-vue demo Button
bkui-vue demo Button basic

# 输出便于脚本或 AI 消费的 JSON
bkui-vue info Button --detail --format json

找不到组件时，CLI 会提示相近名称。info --detail 和 doc 会包含已抽取的实例方法。

组件知识查询

bkui-vue list
bkui-vue info <component> [--detail]
bkui-vue doc <component> --format markdown
bkui-vue demo <component> [demo]
bkui-vue search <query>
bkui-vue explain <component> --format markdown

explain 从结构化数据生成稳定的组件摘要，适合作为 AI 上下文。

数据质量与版本

# 校验当前知识库；CI 模式下存在 error 级问题时退出非 0
bkui-vue validate
bkui-vue validate --ci

# 查看抽取质量、覆盖率和快照变化
bkui-vue report
bkui-vue report --format markdown
bkui-vue report diff --from <old_snapshot> --to <new_snapshot> --format json

# 查看本地版本快照并指定版本查询
bkui-vue versions
bkui-vue info Button --version 3.0.1
bkui-vue diff --from 2.1.0-beta.11 --to 3.0.1

当前默认查询数据来自 data/current.json（BKUI Vue 2.1.0-beta.11）；包内还包含 3.0.1 版本快照。使用 bkui-vue versions 可查看默认版本、最新快照和本地可用版本。

list、info、doc、demo、search、explain、validate 支持 --version <version>。还可使用 --auto-detect，根据当前项目 package.json 中的 BKUI Vue 依赖协商快照；doctor 默认执行版本识别。

业务项目诊断

bkui-vue doctor --cwd <project_dir>
bkui-vue usage --cwd <project_dir> --format json
bkui-vue lint --cwd <project_dir> --ci
bkui-vue migrate --check --cwd <project_dir>

这些命令只读扫描业务项目，报告路径均相对 --cwd。默认跳过 node_modules、dist、coverage 和 .git。

migrate --check 目前只提供迁移诊断，不自动修改业务代码。

工程辅助

# 默认输出到 stdout
bkui-vue snippet Button basic

# 写文件必须显式使用 --force
bkui-vue snippet Button basic --output <file> --force

# init 默认只预览文件计划
bkui-vue init --cwd <project_dir>
bkui-vue init --cwd <project_dir> --force

snippet 只输出知识库中已经验证的 Demo。init 仅生成最小 Vite 示例，不负责创建完整业务项目。

AI 与工具集成

# 输出 llms.txt 或 llms-full.txt 内容
bkui-vue llms
bkui-vue llms --full

# 写入 llms.txt、llms-full.txt 和 context7-components.json
bkui-vue llms --write <output_dir>

包入口还提供只读 Public API：

import {
  buildIntegrationIndex,
  loadMetadata,
  searchComponents,
  validateMetadata,
} from '@bkui-vue/cli';

常用选项

| 选项 | 说明 | | --- | --- | | --format text\|json\|markdown | 设置输出格式；具体支持范围以 bkui-vue <command> --help 为准。 | | --lang zh\|en | 设置内容语言；英文不可用时回退到中文。 | | --detail | 输出完整组件信息，仅适用于 info。 | | --version <version> | 指定本地 BKUI Vue 数据快照。 | | --auto-detect | 根据当前项目依赖自动协商数据快照。 | | --cwd <project_dir> | 指定业务项目根目录。 | | --ci | 存在阻断级问题时退出非 0。 | | --cli-version | 输出 CLI 自身版本。 |

运行 bkui-vue --help 查看全部命令，运行 bkui-vue <command> --help 查看命令参数。

本地开发

git clone xxx/bkui-vue-cli.git
cd bkui-vue-cli
npm install
npm test
npm run typecheck
npm run build
npm run release:check

本地运行 CLI：

npm run build
npm start -- list

需要像全局命令一样调试时：

npm link
bkui-vue list

仓库已内置 data/current.json，克隆后可直接构建和测试，无需先执行数据抽取。

刷新组件数据

从本地 bkui-vue3 源码重新抽取组件知识库：

npm run extract -- \
  --bkui-vue-dir <bkui_vue3_repo> \
  --output data/current.json \
  --report data/report.json \
  --compact data/index.compact.json

npm run extract -- \
  --bkui-vue-dir <bkui_vue3_repo> \
  --source wiki \
  --version 3.0.1 \
  --knowledge-dir <bkui_knowledge_repo> \
  --report data/report/3.0.1.report.json

npm run release:check

• --source auto|wiki|legacy：默认 auto，优先读取 packages/*/demo/index.ts 的结构化 wiki 数据，缺失时回退到旧文档站数据。
• --version <version>：写入 data/versions/<version>.json 并维护 data/versions/index.json；未传版本时刷新 data/current.json。
• --knowledge-dir <bkui_knowledge_repo>：显式从 bkui-knowledge 补充 AI 避坑语义与组件级 examples；优先读取 knowledge/component-hints/vue3，并兼容旧 knowledge/component-apis/vue3 作为过渡 fallback。补强内容只写入本次抽取的版本快照。
• --report：生成包含 severity、建议操作、相对路径和覆盖率指标的质量报告。
• --compact：生成供 AI 和外部工具快速读取的组件索引。

skills/bkui-vue/SKILL.md 提供 AI 助手使用本 CLI 的识别与查询工作流。它会先区分 Vue 2 的 bk-magic-vue 与 Vue 3 的 bkui-vue / @bkui-vue/*，仅在 Vue 3 场景中使用本 CLI。

范围与限制

• 离线数据只覆盖随当前包发布的版本快照。
• 英文内容不可用时会回退到中文。
• 业务项目诊断和迁移检查保持只读。
• 不包含 MCP server 或自动迁移能力。

许可证

MIT