shenjianZ
1a7c800391
建立完整的 CLI 产品基础骨架，支持多种演进方向 - 添加项目基础配置（package.json、tsconfig、pnpm-lock.yaml、.gitignore、.npmignore） - 实现运行时基础设施（RuntimeServices 统一注入、日志、输出模式、配置存储、插件加载、任务注册表） - 采用 command/use-case/presenter 三层架构组织业务模块（demo、config、task） - 添加 UI 渲染层（banner、panel、table、主题样式） - 实现插件机制，支持运行时扫描加载外部模块和任务 - 支持 text/json 双输出模式，便于集成与调试 - 添加统一错误模型 AppError 和 CLI 错误边界处理 - 基于 node:test 建立测试基座，包含示例测试用例 - 配置 npm 发布脚本和包元数据 - 编写完整 README 文档，包含快速开始、开发约定和演进方向
181 lines
4.5 KiB
Markdown
181 lines
4.5 KiB
Markdown
# CLI Template V1
|
|
|
|
一个面向长期演进的 TypeScript CLI 模板。它不是只服务 AI 编程场景，而是可以作为多种 CLI 产品的基础骨架：
|
|
|
|
- 桌面软件控制 CLI
|
|
- 配置初始化与环境诊断 CLI
|
|
- 工作流与自动化任务 CLI
|
|
- 再进一步扩展成 Agent / AI 助手型 CLI
|
|
|
|
## 当前能力
|
|
|
|
- TypeScript + Node 20
|
|
- `RuntimeServices` 统一注入运行时能力
|
|
- `command / use-case / presenter` 分层
|
|
- 模块注册表、任务注册表、运行时插件加载
|
|
- `text / json` 双输出模式
|
|
- 配置文件持久化服务
|
|
- 统一错误模型与 CLI 错误边界
|
|
- `node:test` 测试基座
|
|
- 可作为 npm CLI 包发布
|
|
|
|
## 项目结构
|
|
|
|
```text
|
|
.
|
|
├─ plugins/ # 运行时插件目录，启动时会扫描这里的 *.js
|
|
├─ src/
|
|
│ ├─ bootstrap/ # CLI 应用装配
|
|
│ ├─ runtime/ # services/errors/output/config/plugin/task-registry
|
|
│ ├─ modules/ # 业务模块，按 command/use-case/presenter 划分
|
|
│ ├─ test/ # 测试聚合入口
|
|
│ ├─ plugins/ # 插件示例源码
|
|
│ └─ ui/renderers/ # 纯渲染层
|
|
└─ dist/ # 编译产物
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev -- --help
|
|
pnpm dev -- demo
|
|
pnpm dev -- config init
|
|
pnpm dev -- --output json config show
|
|
pnpm dev -- --output json task list
|
|
pnpm dev -- --output json task run doctor
|
|
pnpm test
|
|
```
|
|
|
|
## 全局安装后的命令名
|
|
|
|
包名和命令名现在统一为：
|
|
|
|
```bash
|
|
npm install -g cli-template-v1
|
|
cli-template-v1 --help
|
|
cli-template-v1 task list
|
|
cli-template-v1 --output json config show
|
|
```
|
|
|
|
这样用户安装的包名和实际执行命令一致，不会出现安装了 `cli-template-v1`，却要执行 `cli-starter` 的割裂体验。
|
|
|
|
## CLI 示例
|
|
|
|
文本输出：
|
|
|
|
```bash
|
|
pnpm dev -- task list
|
|
```
|
|
|
|
JSON 输出：
|
|
|
|
```bash
|
|
pnpm dev -- --output json task run doctor
|
|
```
|
|
|
|
读取配置：
|
|
|
|
```bash
|
|
pnpm dev -- --output json config show
|
|
```
|
|
|
|
## 插件机制
|
|
|
|
运行时会扫描当前工作目录下的 `plugins/*.js` 文件，并尝试加载插件。
|
|
|
|
插件需要导出一个 `CliPlugin` 对象，可提供：
|
|
|
|
- `modules`: 新命令模块
|
|
- `tasks`: 新任务定义
|
|
|
|
项目里有两个相关位置：
|
|
|
|
- [plugins/example-plugin.js](/D:/VScodeProject/cli-codex/plugins/example-plugin.js)
|
|
这是当前真正会被运行时扫描到的示例插件。
|
|
- [src/plugins/example-plugin.js](/D:/VScodeProject/cli-codex/src/plugins/example-plugin.js)
|
|
这是源码层面的示例参考。
|
|
|
|
加载成功后，插件任务会自动出现在 `task list` 里。
|
|
|
|
## 开发约定
|
|
|
|
### 1. 新增命令模块
|
|
|
|
在 `src/modules/<name>/` 下新增模块，至少拆成：
|
|
|
|
- `command.ts`: 只负责 CLI 参数解析和流程编排
|
|
- `use-case.ts`: 只负责业务逻辑
|
|
- `presenter.ts`: 只负责输出格式
|
|
|
|
然后在 [registry.ts](/D:/VScodeProject/cli-codex/src/modules/registry.ts) 注册。
|
|
|
|
### 2. 新增任务
|
|
|
|
在 `src/modules/task/tasks/` 下新增一个 `PluginTask`，然后在 [registry.ts](/D:/VScodeProject/cli-codex/src/modules/task/tasks/registry.ts) 注册。
|
|
|
|
### 3. 使用配置存储
|
|
|
|
通过 `services.configStore.read/write/patch` 读写 `cli-template-v1.config.json`，不要在业务模块里直接操作文件系统。
|
|
|
|
### 4. 使用输出模式
|
|
|
|
通过 `services.output.mode` 判断当前模式，通过 `services.output.writeText/writeData` 输出，避免在 presenter 或 use-case 外随意 `console.log`。
|
|
|
|
### 5. 使用统一错误
|
|
|
|
抛出 `AppError`，携带：
|
|
|
|
- `code`
|
|
- `exitCode`
|
|
- `details`
|
|
|
|
CLI 会自动按 text/json 两种模式输出错误结果。
|
|
|
|
## 测试
|
|
|
|
当前测试基座基于 Node 内置测试框架，入口在：
|
|
|
|
- [all.test.ts](/D:/VScodeProject/cli-codex/src/test/all.test.ts)
|
|
|
|
已有示例测试：
|
|
|
|
- [use-case.test.ts](/D:/VScodeProject/cli-codex/src/modules/config/use-case.test.ts)
|
|
- [task-registry.test.ts](/D:/VScodeProject/cli-codex/src/runtime/task-registry.test.ts)
|
|
|
|
执行：
|
|
|
|
```bash
|
|
pnpm test
|
|
```
|
|
|
|
## 发布 npm 包
|
|
|
|
发布前建议先检查打包内容：
|
|
|
|
```bash
|
|
pnpm pack:check
|
|
```
|
|
|
|
正式发布：
|
|
|
|
```bash
|
|
npm publish
|
|
```
|
|
|
|
当前发布配置已限制只发布：
|
|
|
|
- `dist/`
|
|
- `README.md`
|
|
- `LICENSE`
|
|
|
|
注意：`repository`、`homepage`、`bugs` 目前是占位地址，发布前应替换成你的真实仓库链接。
|
|
|
|
## 适合继续演进的方向
|
|
|
|
- 配置 schema 校验与迁移
|
|
- 插件签名与权限模型
|
|
- 错误码和 exit code 文档化
|
|
- fixture runner 与端到端命令测试
|
|
- 发布流程和单文件打包
|