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 包发布

项目结构

.
├─ plugins/                 # 运行时插件目录，启动时会扫描这里的 *.js
├─ src/
│  ├─ bootstrap/            # CLI 应用装配
│  ├─ runtime/              # services/errors/output/config/plugin/task-registry
│  ├─ modules/              # 业务模块，按 command/use-case/presenter 划分
│  ├─ test/                 # 测试聚合入口
│  ├─ plugins/              # 插件示例源码
│  └─ ui/renderers/         # 纯渲染层
└─ dist/                    # 编译产物

快速开始

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

全局安装后的命令名

包名和命令名现在统一为：

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 示例

文本输出：

pnpm dev -- task list

JSON 输出：

pnpm dev -- --output json task run doctor

读取配置：

pnpm dev -- --output json config show

插件机制

运行时会扫描当前工作目录下的 plugins/*.js 文件，并尝试加载插件。

插件需要导出一个 CliPlugin 对象，可提供：

• modules: 新命令模块
• tasks: 新任务定义

项目里有两个相关位置：

• plugins/example-plugin.js 这是当前真正会被运行时扫描到的示例插件。
• src/plugins/example-plugin.js 这是源码层面的示例参考。

加载成功后，插件任务会自动出现在 task list 里。

开发约定

1. 新增命令模块

在 src/modules/<name>/ 下新增模块，至少拆成：

• command.ts: 只负责 CLI 参数解析和流程编排
• use-case.ts: 只负责业务逻辑
• presenter.ts: 只负责输出格式

然后在 registry.ts 注册。

2. 新增任务

在 src/modules/task/tasks/ 下新增一个 PluginTask，然后在 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

已有示例测试：

• use-case.test.ts
• task-registry.test.ts

执行：

pnpm test

发布 npm 包

发布前建议先检查打包内容：

pnpm pack:check

正式发布：

npm publish

当前发布配置已限制只发布：

• dist/
• README.md
• LICENSE

注意：repository、homepage、bugs 目前是占位地址，发布前应替换成你的真实仓库链接。

适合继续演进的方向

• 配置 schema 校验与迁移
• 插件签名与权限模型
• 错误码和 exit code 文档化
• fixture runner 与端到端命令测试
• 发布流程和单文件打包