@chatbi-v/cli
v2.1.0
Published
Standardized CLI tooling for ChatBI Monorepo
Readme
@chatbi-v/cli
ChatBI-V 统一开发工具。基于 沙箱 (Sandbox) 与 零显式依赖 (Zero-Install) 架构设计，助力开发者快速构建、预览和部署 ChatBI 插件与应用。
模块功能说明
- 项目初始化: 快速生成 App、Plugin 或 Monorepo 模板。
- 环境编排: 自动管理内核版本，支持项目级版本锁定。
- 开发预览: 内置热更新开发服务器，支持沙箱环境下的实时预览。
- 依赖同步: 自动化同步内核定义，解决开发环境配置难题。
安装和使用方法
安装 CLI
npm install -g @chatbi-v/cli
# 或使用 pnpm
pnpm add -g @chatbi-v/cli初始化项目
chatbi-cli init my-app --project-type app启动开发环境
chatbi-cli devAPI 文档链接
请访问 CLI 详细文档 或运行 chatbi-cli --help 查看指令详情。
开发注意事项
- 权限说明: 部分命令涉及全局目录 (
~/.chatbi-v-core) 的读写。 - Node 版本: 建议使用 Node.js >= 18.0.0。
- 沙箱隔离: 开发过程中请勿手动修改
.chatbi-v-core目录内容。
核心理念
1. 零显式依赖 (Zero-Install)
开发者在初始化项目后，无需在本地项目 package.json 中安装庞大的 @chatbi-v/core 或相关内核依赖。CLI 通过虚拟上下文技术，在运行时自动链接到全局沙箱环境，保持项目轻量化。
2. 全局沙箱 (Global Sandbox)
内核依赖统一管理在用户根目录下的 ~/.chatbi-v-core 中。一次安装，多项目共享。支持多版本管理与无缝升级。
3. CoreKit 驱动
内置 CoreKit 开发套件，为 App 提供高性能预览服务器，为 Plugin 提供“托管式 Shell”调试环境，确保开发体验与生产环境高度一致。
快速开始
安装 CLI
npm install -g @chatbi-v/cli
# 或使用 pnpm
pnpm add -g @chatbi-v/cli初始化项目
创建一个独立应用 (App)
chatbi-cli init my-app --project-type app创建一个插件 (Plugin)
chatbi-cli init my-plugin --project-type plugin创建一个 Monorepo 工作空间
chatbi-cli init my-workspace --project-type monorepo启动开发环境
进入项目目录后执行：
npm run dev
# 或者直接使用 cli
chatbi-cli dev- App/Plugin 模式: 直接启动当前项目。
- Monorepo 模式: 自动扫描并提供交互式菜单，选择要启动的子应用或插件。
常用命令
| 命令 | 别名 | 描述 |
| :--- | :--- | :--- |
| init | i | 初始化新项目 (App/Plugin/Monorepo) |
| dev | d | 启动开发服务器 (支持热更新与沙箱加载) |
| build | b | 构建生产环境产物 |
| use | - | 切换使用的内核版本 (项目级或全局 --global) |
| ls | - | 列出本地已安装的所有沙箱版本 |
| update | - | 更新或修复全局沙箱内核版本 |
| sync | s | 同步内核依赖与虚拟环境 (支持 -v, --core-version) |
| doctor | - | 诊断并自动修复项目环境问题 |
| bench | - | 运行 CLI 性能基准测试 |
| add | - | 在 Monorepo 项目中添加新插件 |
| gl | - | 使用 AI 助手生成代码、文档或组件 |
| discover | - | 发现并列出当前工作空间的所有包 |
高级特性
版本锁定 (.chatbi-version)
在项目根目录创建一个 .chatbi-version 文件，内容为指定的版本号（如 1.0.11）。CLI 会优先使用该文件定义的版本，确保团队开发环境的高度一致。
极速预览
得益于 CoreKit 托管容器，插件项目的冷启动时间通常在 3 秒以内，且支持秒级 HMR 热更新。
性能基准 (Benchmark)
你可以通过运行 chatbi-cli bench 来验证当前环境下的性能表现。
典型指标：
- 项目初始化: ≤ 2s
- 增量编译 (HMR): ≤ 0.5s
- 核心依赖占用: ≤ 150MB (多项目共享)
常见问题 (FAQ)
Q: 为什么我修改了 package.json 但没看到依赖安装？
A: 核心依赖由沙箱承载，项目本身是“零依赖”的。如果你需要添加第三方库（如 lodash），请正常使用 npm install。
Q: 如何更新到最新的内核版本？
A: 运行 chatbi-cli update 即可自动同步最新的沙箱环境。
Q: 插件模式下如何调试？
A: 运行 dev 后，访问控制台输出的 Preview URL，即可在模拟的真实容器中实时调试你的插件。
更多文档
许可证
MIT License @ 2025 ChatBI-V Team