feat: 初始化 TypeScript CLI 模板项目
建立完整的 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 文档，包含快速开始、开发约定和演进方向
This commit is contained in:
180
README.md
Normal file
180
README.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 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 与端到端命令测试
|
||||
- 发布流程和单文件打包
|
||||
Reference in New Issue
Block a user