# ibiz-front-cli

**Repository Path**: iBizModeling/ibiz-front-cli

## Basic Information

- **Project Name**: ibiz-front-cli
- **Description**: 新一代前端cli工具，包含知识查询、项目相关、插件相关、mcp server等内容。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-22
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ibiz-template/ibiz-front-cli

面向 iBiz 前端插件开发的命令行工具仓库，主要用于 iBiz 前端框架与 AI 集成。项目通过 AI skill 调用 CLI，完成文档查询、项目辅助、插件构建、技能安装等能力的统一编排与执行。

- 采用"入口层 + 能力层 + 技能层"三层架构，CLI 消费能力、Core 沉淀能力、Skill 对接 AI
- 支持知识查询（文档、模型、Design Token、语义化结构），均支持多种输出格式与模板版本
- 支持插件全生命周期：创建、诊断、本地/远程模式转换、构建发布
- 支持 AI 技能安装，一键将技能文件部署至 Claude Code、OpenCode、TRAE、Codex 等编程工具
- pnpm workspace + Turbo monorepo，子包独立构建、统一发布

## 技术栈

| 分类      | 技术                     | 说明                            |
| --------- | ------------------------ | ------------------------------- |
| 核心语言  | TypeScript               | 严格模式，ES2022 目标           |
| 构建工具  | Tsup                     | 基于 esbuild 的零配置打包       |
| 任务编排  | Turbo                    | Monorepo 构建缓存与任务流水线   |
| 发布管理  | Lerna                    | 版本管理与 npm 发布             |
| CLI 框架  | Commander                | 命令注册与参数解析              |
| 交互增强  | Prompts、Ora、Picocolors | 用户交互、进度指示、终端着色    |
| 日志输出  | Consola                  | 统一日志格式                    |
| 模板引擎  | Handlebars               | 插件模板渲染                    |
| 文件处理  | fs-extra                 | 增强的文件系统操作              |
| 模板拉取  | Giget                    | Git 仓库模板下载                |
| 文档解析  | gray-matter              | Markdown frontmatter 解析       |
| 模糊匹配  | fast-levenshtein         | 文本相似度计算与模糊匹配        |
| 版本比较  | semver                   | 语义化版本号比较与校验          |
| 代码规范  | ESLint + Prettier        | 代码检查与格式化                |
| 提交规范  | Commitlint + cz-git      | Conventional Commits 交互式提交 |
| Git Hooks | Husky + lint-staged      | 提交前自动检查                  |

## 快速开始

### 环境要求

- Node.js 18+
- pnpm 8.15.9

### 安装依赖

```bash
pnpm install
```

> monorepo 项目会自动安装 `packages/*` 下所有子包依赖。

### 本地运行

```bash
# 启动开发模式（监听文件变更）
pnpm dev

# 本地调试 CLI（需先构建）
pnpm build
node packages/cli/dist/bin.mjs --help
```

### 生产构建

```bash
pnpm build
```

构建产物输出至各子包的 `dist/` 目录，格式为 ESM，包含类型声明和 sourcemap。

## 目录结构说明

```
├── packages/
│   ├── cli/            - CLI 入口包，命令注册与参数解析
│   ├── core/           - 核心能力包，知识查询、项目分析、插件能力、技能安装
│   ├── skill/          - AI 技能包，提供 SKILL.md 供 AI 编程工具消费
│   └── llms/           - LLM 资源包，提供 llms.txt 与规范文档供 AI 快速集成
├── package.json        - 仓库根配置，统一脚本与开发依赖
├── pnpm-workspace.yaml - workspace 范围定义
├── turbo.json          - 任务编排规则
├── tsconfig.json       - 根级 TypeScript 配置
├── lerna.json          - 版本管理与发布配置
├── commitlint.config.js - 提交规范配置
├── eslint.config.js    - ESLint 配置
├── tsup.config.ts      - Tsup 构建配置
└── .husky/             - Git Hooks
```

## 包说明

### `packages/cli`

CLI 入口包，负责：

- 注册 `ibiz-front` 命令
- 解析命令行参数
- 组织命令分发
- 调用 `core` 包暴露的核心能力

`cli` 的定位是"能力消费层"，后续可接入 AI skill、脚本编排或其他宿主程序，在不改动核心实现的前提下复用已有能力。

### `packages/core`

核心能力包，承载：

- 知识查询能力（文档、模型、Design Token、语义化结构）
- 项目辅助能力（项目启动、结构分析、环境采集、问题反馈）
- 插件模板与构建能力（创建、诊断、模式转换、发布）
- AI 技能安装能力（技能下载、多编程工具适配）

将能力集中在 `core` 中，实现与 `cli` 的解耦，降低命令层复杂度，方便功能扩展、测试覆盖和多入口复用。

### `packages/skill`

AI 技能包，承载：

- 提供 `SKILL.md` 技能描述文件，定义 AI 编程工具的触发规则与使用指引
- 包含完整的命令使用说明、参数规范、工作流建议
- 通过 `ibiz-front install` 命令安装至 AI 编程工具目录

技能包是 CLI 与 AI 编程工具之间的桥梁，使得 AI 可以理解用户意图并正确调用 CLI 能力。

### `packages/llms`

LLM 资源包，承载：

- `llms.txt` 入口索引文件（遵循 [llms.txt](https://llmstxt.org) 规范），列出本包规范文档与相关工具包
- `doc/` 目录下的明细规范文档（如样式规范 `style-guide.md`），覆盖 ITCSS 架构、BEM 命名、CSS 变量与设计 Token 体系、Element Plus 覆盖、主题切换等
- 通过 npm 发布，AI 编程工具安装后按需读取建立上下文

`llms` 包作为"上下文沉淀层"，与 `skill`（技能层）互补：`skill` 暴露可调用的能力，`llms` 沉淀可消费的规范。

## 架构设计

项目采用"入口层 + 能力层 + 技能层"的三层架构：

```text
AI 编程工具（Claude Code / OpenCode / TRAE / Codex）
            ↓
      packages/skill（技能层）
            ↓
      ibiz-front CLI（入口层）
            ↓
      命令解析与分发
            ↓
      packages/core（能力层）
            ↓
知识查询 / 项目分析 / 插件模板 / 构建诊断 / 插件转换 / 插件发布 / 技能安装
            ↓
本地项目 / 模板资源 / 文档索引 / 环境信息
```

设计目标：

- 命令输入输出和业务能力解耦，避免 CLI 层堆积复杂逻辑
- `core` 同时服务 CLI、AI skill、脚本工具和其他接入方式
- `skill` 层负责 AI 编程工具的集成，将 CLI 能力以技能文件形式暴露给 AI
- 知识查询、项目分析、插件构建能力具备更好的复用性和可测试性
- 为后续增加更多命令、数据源、模板源和智能编排逻辑预留稳定边界

## 功能清单

状态说明：`已实现` 可直接使用，`开发中` CLI 入口已接入但能力未完整闭环。

### 知识查询

| 命令                         | 说明                                                                               | 状态     |
| ---------------------------- | ---------------------------------------------------------------------------------- | -------- |
| `ibiz-front list <type>`     | 列出指定知识类型的名称及描述清单，`type` 支持 `docs`、`model`、`token`、`semantic` | `已实现` |
| `ibiz-front docs <name>`     | 查询指定名称的文档                                                                 | `已实现` |
| `ibiz-front model <name>`    | 查询指定名称模型说明文档                                                           | `已实现` |
| `ibiz-front token <name>`    | 查询指定名称的 Design Token                                                        | `已实现` |
| `ibiz-front semantic <name>` | 查询指定名称组件语义化结构                                                         | `已实现` |

**知识查询通用选项：**

| 选项                    | 说明                                                    |
| ----------------------- | ------------------------------------------------------- |
| `-e, --env [env]`       | 运行环境（`PC` \| `MOB`），默认 `PC`                    |
| `-fmt, --format [fmt]`  | 输出格式（`json` \| `text` \| `markdown`），默认 `text` |
| `-V, --templ-version`   | 指定模板版本                                            |
| `-f, --filter [filter]` | 过滤条件（仅 `list` 命令）                              |

### 项目分析

| 命令                          | 说明                        | 状态     |
| ----------------------------- | --------------------------- | -------- |
| `ibiz-front start [path]`     | 快速启动项目                | `开发中` |
| `ibiz-front structure [path]` | 列出项目架构说明、目录说明  | `开发中` |
| `ibiz-front changelog [path]` | 列出变更日志                | `开发中` |
| `ibiz-front env [path]`       | 列出环境信息，用于 Bug 报告 | `开发中` |
| `ibiz-front bug [path]`       | 提交 Bug 至 iBiz 开源仓库   | `开发中` |

### 插件能力

| 命令                                                               | 说明                                           | 状态     |
| ------------------------------------------------------------------ | ---------------------------------------------- | -------- |
| `ibiz-front plugin <name> -t <type> -i <id> -d <desc> -o <output>` | 生成指定类型插件                               | `已实现` |
| `ibiz-front doctor <source>`                                       | 诊断指定插件，校验是否异常                     | `已实现` |
| `ibiz-front transform <source> <target>`                           | 插件模式转换，默认本地转远程；加 `-r` 反向转换 | `已实现` |
| `ibiz-front resource <source>`                                     | 获取插件编写参考文件清单                       | `已实现` |
| `ibiz-front content <path>`                                        | 获取框架源码文件内容                           | `已实现` |
| `ibiz-front publish <source>`                                      | 升级版本号并构建后发布到目标源                 | `已实现` |

### AI 技能安装

| 命令                 | 说明                       | 状态     |
| -------------------- | -------------------------- | -------- |
| `ibiz-front install` | 安装 AI 技能文件至编程工具 | `已实现` |

**`install` 命令参数说明：**

| 参数 / 选项         | 必填 | 说明                                                          |
| ------------------- | ---- | ------------------------------------------------------------- |
| `-t, --tool <tool>` | 否   | 编程工具（`CLAUDE_CODE` \| `OPEN_CODE` \| `TRAE` \| `CODEX`） |
| `-s, --scope`       | 否   | 安装范围（`USER` \| `PROJECT`），用户目录或项目目录           |

未指定参数时将通过交互式提示选择。

**`plugin` 命令参数说明：**

| 参数 / 选项                      | 必填 | 说明                                               |
| -------------------------------- | ---- | -------------------------------------------------- |
| `<name>`                         | 是   | 插件名称，仅允许字母和中划线                       |
| `-t, --pluginType <type>`        | 是   | 插件类型，见下方支持的插件类型列表                 |
| `-i, --pluginId <id>`            | 是   | 插件标识，仅允许字母、数字、下划线，必须以字母开头 |
| `-d, --pluginDescription <desc>` | 是   | 插件描述                                           |
| `-o, --outputDir <output>`       | 是   | 插件输出目录，必须是合法路径                       |
| `-m, --pluginMode [mode]`        | 否   | 插件模式（`LOCAL` \| `REMOTE`），默认 `REMOTE`     |
| `-e, --env [env]`                | 否   | 运行环境（`PC` \| `MOB`），默认 `PC`               |
| `-g, --pluginGroup [group]`      | 否   | 插件所属分组，默认 `@ibiz-template-plugin`         |

**支持的插件类型：**

| 分类     | 类型标识             | 说明                   | 描述                             |
| -------- | -------------------- | ---------------------- | -------------------------------- |
| 平台插件 | `AC_ITEM`            | 自填列表项绘制插件     | 自定义自填列表项的绘制逻辑       |
| 平台插件 | `CHART_RENDER`       | 图表绘制插件           | 自定义图表部件的绘制逻辑         |
| 平台插件 | `CUSTOM`             | 自定义部件绘制插件     | 自定义非标准部件的渲染与交互     |
| 平台插件 | `DATAVIEW_RENDER`    | 数据视图绘制插件       | 自定义数据视图部件的绘制逻辑     |
| 平台插件 | `EDITFORM_RENDER`    | 编辑表单绘制插件       | 自定义编辑表单部件的绘制逻辑     |
| 平台插件 | `EDITOR_CUSTOMSTYLE` | 编辑器自定义绘制插件   | 自定义编辑器控件的渲染外观与交互 |
| 平台插件 | `FORM_USERCONTROL`   | 表单自定义控件绘制插件 | 在表单中嵌入自定义控件           |
| 平台插件 | `GRID_COLRENDER`     | 数据表格列绘制插件     | 自定义数据表格列的绘制逻辑       |
| 平台插件 | `GRID_RENDER`        | 数据表格绘制插件       | 自定义数据表格部件的绘制逻辑     |
| 平台插件 | `LIST_RENDER`        | 列表绘制插件           | 自定义列表部件的绘制逻辑         |
| 平台插件 | `PORTLET_CUSTOM`     | 自定义门户部件绘制插件 | 自定义门户部件的渲染与布局       |
| 平台插件 | `SEARCHFORM_RENDER`  | 搜索表单绘制插件       | 自定义搜索表单的渲染外观与交互   |
| 平台插件 | `TOOLBAR_ITEM`       | 工具栏项绘制插件       | 自定义工具栏按钮的渲染与交互     |
| 平台插件 | `TOOLBAR_RENDER`     | 工具栏绘制插件         | 自定义工具栏部件的绘制逻辑       |
| 平台插件 | `TREE_RENDER`        | 树视图绘制插件         | 自定义树视图部件的绘制逻辑       |
| 平台插件 | `UILOGICNODE`        | 界面逻辑节点           | 扩展界面逻辑的节点类型           |
| 平台插件 | `VIEW_CUSTOM`        | 实体视图绘制插件       | 自定义实体视图的布局与交互逻辑   |
| 平台插件 | `DEMETHOD`           | 应用实体方法插件       | 扩展应用实体的方法行为           |
| 平台插件 | `APPCOUNTER`         | 应用计数器插件         | 扩展应用计数器的功能             |
| 平台插件 | `SEARCHBAR_RENDER`   | 搜索栏绘制插件         | 自定义搜索栏的渲染外观与交互     |
| 平台插件 | `WIZARDPANEL_RENDER` | 向导面板绘制插件       | 自定义向导面板的渲染与交互       |
| 平台插件 | `DEUIACTION`         | 应用实体界面行为       | 扩展应用实体的界面行为           |
| 平台插件 | `PANEL_ITEM`         | 面板部件成员绘制插件   | 自定义面板部件成员的绘制逻辑     |
| 全局插件 | `GLOBAL_PLUGIN`      | 全局插件               | 应用级别注入自定义逻辑与行为     |
| 主题插件 | `THEME_PLUGIN`       | 全局主题插件           | 自定义应用的视觉主题与样式风格   |

**`resource` 命令参数说明：**

| 参数 / 选项                     | 必填 | 说明                                                    |
| ------------------------------- | ---- | ------------------------------------------------------- |
| `<source>`                      | 是   | 插件所在目录（从 `README.md` frontmatter 读取插件类型） |
| `-e, --env [env]`               | 否   | 运行环境（`PC` \| `MOB`），默认 `PC`                    |
| `-fmt, --format [fmt]`          | 否   | 输出格式（`json` \| `text` \| `markdown`），默认 `text` |
| `-V, --templ-version [version]` | 否   | 指定模板版本                                            |

返回结构包含 `requiredFiles`（必读文件清单）与 `optionalFiles`（可选文件清单）两个数组，元素结构如下：

| 字段     | 说明                                              |
| -------- | ------------------------------------------------- |
| `role`   | 文件角色（如 `entry`、`ui`、`logic`、`consumer`） |
| `label`  | 文件名称                                          |
| `path`   | 文件路径（相对于框架源码根目录）                  |
| `reason` | 推荐原因，说明该文件对插件编写的参考价值          |

- `requiredFiles`：由框架通用参考文件清单与该插件类型的基础文件清单组成
- `optionalFiles`：由该插件类型下所有场景的补充文件清单聚合而成

**`content` 命令参数说明：**

| 参数 / 选项                     | 必填 | 说明                                                                                                        |
| ------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------- |
| `<path>`                        | 是   | 框架源码相对路径，与 `resource` 输出的 `path` 字段一致（如 `runtime/...` 对应 `@ibiz-template/runtime` 包） |
| `-e, --env [env]`               | 否   | 运行环境（`PC` \| `MOB`），默认 `PC`                                                                        |
| `-fmt, --format [fmt]`          | 否   | 输出格式（`json` \| `text` \| `markdown`），默认 `text`                                                     |
| `-V, --templ-version [version]` | 否   | 指定模板版本                                                                                                |

命令会按版本下载并缓存对应的 `@ibiz-template/*` 包至 `~/.ibiz-front-cli/cache/`，后续相同路径直接命中缓存。

**`publish` 命令参数说明：**

| 参数 / 选项                       | 必填 | 说明                                                             |
| --------------------------------- | ---- | ---------------------------------------------------------------- |
| `<source>`                        | 是   | 插件所在目录，须包含 `package.json` 与可执行的 `build` 脚本      |
| `-t, --targetType <targetType>`   | 是   | 目标源类型（`npm` \| `custom`），默认 `npm`                      |
| `-g, --target <target>`           | 是   | 目标源定位：`npm` 时为 registry URL，`custom` 时为 node 脚本路径 |
| `-r, --releaseType [releaseType]` | 否   | 版本号升级类型（`major` \| `minor` \| `patch`），默认 `patch`    |

执行流程：校验 `source` → 升级 `package.json` 版本号 → 依据锁文件探测包管理器并执行 `build` → 校验 `dist` 非空 → 按目标源类型发布。任意步骤异常时自动回退 `package.json` 版本号。

- `npm` 适配器：在 `source` 目录执行 `npm publish --access public --registry=<target>`，凭证由宿主 npm 配置（用户级 `.npmrc`、登录态等）提供，CLI 不接管 token
- `custom` 适配器：在 `source` 目录执行 `node <target>`，脚本通过 `process.cwd()` 自行获取上下文（dist 路径等）

## AI 集成说明

`ibiz-front-cli` 的目标是作为 iBiz 前端体系与 AI 协作的执行桥梁。推荐集成方式：AI skill 负责理解意图、组织任务，调用 `ibiz-front` 完成确定性的本地能力执行。

### 安装 AI 技能

使用 `install` 命令将技能文件安装至 AI 编程工具：

```bash
# 交互式安装（推荐）
ibiz-front install

# 指定编程工具和安装范围
ibiz-front install -t CLAUDE_CODE -s USER
```

支持的编程工具：

| 工具        | 标识          | 说明                    |
| ----------- | ------------- | ----------------------- |
| Claude Code | `CLAUDE_CODE` | Anthropic 官方 CLI 工具 |
| OpenCode    | `OPEN_CODE`   | 开源 AI 编程工具        |
| TRAE        | `TRAE`        | 字节跳动 AI 编程工具    |
| Codex       | `CODEX`       | OpenAI 编程工具         |

### 适合通过 CLI 暴露给 AI skill 的能力

- **知识查询**：查询文档、模型说明、Design Token、语义化结构
- **项目分析**：读取目录结构、环境信息、变更日志和诊断结果
- **插件构建**：生成模板、校验插件、插件模式转换

### 优势

- AI 负责理解问题和流程编排，CLI 负责落地执行
- 技能文件标准化，支持一键安装至多种 AI 编程工具
- 所有知识查询命令支持 `json` 格式输出，便于 AI 程序化消费
- 能力边界清晰，便于权限控制、日志追踪和问题定位

## 开发约定

- `cli` 只负责参数解析、命令注册、交互适配和结果输出
- `core` 负责承载可复用的查询、分析、模板、构建、技能安装等核心逻辑
- `skill` 负责定义 AI 编程工具可消费的技能描述与使用指引
- 新增命令时优先在 `core` 中设计能力接口，再由 `cli` 做一层命令封装
- 尽量让 `core` 的输入输出保持稳定，减少与具体终端交互方式的耦合
- 复杂能力优先以可测试的纯逻辑模块组织，再接入文件系统、模板源和环境依赖

新增命令流程：

1. 在 `packages/core` 中定义能力接口和实现
2. 在 `packages/cli/src/commands` 中增加命令注册与参数映射
3. 在 `packages/cli/src/commands/index.ts` 中加载命令
4. 如需 AI 集成，在 `packages/skill` 中更新 SKILL.md 技能描述
5. 执行 `pnpm build` 验证打包结果
6. 通过 `node packages/cli/dist/bin.mjs <command>` 进行本地调试

## 贡献与规范

### Git 提交规范

采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范，使用 `cz-git` 交互式提交：

```bash
pnpm commit
```

支持的提交类型：

| 类型       | 说明                        |
| ---------- | --------------------------- |
| `feat`     | 新增功能                    |
| `fix`      | 修复缺陷                    |
| `docs`     | 文档更新                    |
| `style`    | 代码格式（不影响运行）      |
| `refactor` | 代码重构                    |
| `perf`     | 性能优化                    |
| `test`     | 新增或修正测试              |
| `build`    | 构建系统或外部依赖变更      |
| `ci`       | CI 配置变更                 |
| `chore`    | 其他不修改 src 或测试的变更 |
| `revert`   | 回退之前的提交              |

### Git Hooks

- **pre-commit**：自动执行拼写检查（cspell）、代码格式化（lint-staged + prettier）、类型检查（typecheck）
- **commit-msg**：自动校验提交信息格式（commitlint）

### 代码规范

- ESLint：基于 `@eslint/js` + `typescript-eslint` 推荐规则 + Prettier 兼容配置
- Prettier：单引号、2 空格缩进、尾逗号 es5、行宽 100、分号
- TypeScript：严格模式，ES2022 目标，NodeNext 模块解析

## 许可证

[MIT](./LICENSE)