My AI CLI 项目模板

一个适合初学者的 Node.js / TypeScript AI CLI 项目模板，借鉴了 Gemini CLI 的工程架构思想。

🌟 核心架构与设计思想（借鉴 Gemini CLI）

1. 架构解耦（Decoupled Architecture）：
   • commands/ 目录：仅负责命令行参数解析与用户交互。
   • core/ 目录：处理业务逻辑、LLM API 调用与会话状态管理。
2. 类型与 Schema 校验（Type & Schema Validation）：使用 TypeScript + Zod 防止非法参数和配置错误。
3. 副作用隔离（Isolated Side Effects）：环境配置读写、文件操作和日志打印统一封装在 utils/ 中，便于拓展与测试。
4. 双模式支持（Mock & Real API）：未配置 AI_API_KEY 时自动进入 Mock 模式，便于本地快速调优与测试。

📁 目录结构

dfyz9-cli/
├─ src/
│  ├─ index.ts              # CLI 程序总入口（命令注册与解析）
│  ├─ commands/
│  │  ├─ chat.ts            # chat 对话命令
│  │  └─ config.ts          # config 配置管理命令
│  ├─ core/
│  │  ├─ llm.ts             # LLM API 客户端（支持 Mock 与 OpenAI 兼容接口）
│  │  └─ session.ts         # 上下文会话管理
│  ├─ utils/
│  │  ├─ logger.ts          # 彩色终端日志工具
│  │  └─ env.ts             # 环境变量与 .env 文件读写
│  └─ types/
│     └─ index.ts           # 类型与 Zod Schema 定义
├─ tests/
│  └─ llm.test.ts           # Vitest 单元测试
├─ .env.example             # 环境变量示例文件
├─ package.json             # 项目配置与依赖说明
├─ tsconfig.json            # TypeScript 编译配置
└─ README.md                # 项目说明文档

🚀 快速开始

1. 安装依赖

npm install

2. 开发模式运行命令

# 测试问候命令
npm run dev -- hello -n 开发者

# 查看当前配置
npm run dev -- config show

# 设置 API Key（自动保存至 .env）
npm run dev -- config set-key your_api_key_here

# 发送 AI 对话（未设置 API Key 时自动启用 Mock 回复）
npm run dev -- chat "什么是 TypeScript？"

3. 运行单元测试

npm run test

4. 项目构建打包

npm run build

🚀 自动发布（GitHub Actions + npm OIDC）

项目已配置好 打 tag 自动发布到 npm 的流水线：推送 v* 标签后，GitHub Actions 会自动执行 测试 → 构建 → 通过 npm Trusted Publisher（OIDC） 发布到 npm。全程不需要任何 token。

发布流程

# 1. 手动升级版本号（与将要打的 tag 保持一致）
npm version patch      # 或 minor / major

# 2. 提交并推送
git push origin main

# 3. 打 tag 并推送（触发发布）
git push origin v$(node -p "require('./package.json').version")
# 或者手动打 tag：git tag v0.5.0 && git push origin v0.5.0

首次使用前需要配置

1. npm Trusted Publisher（OIDC）：npm 经典 token 已于 2025-12 废弃、粒度 token 每 90 天过期， 本项目使用 npm 官方推荐的 Trusted Publisher（OIDC） 认证，CI 里完全不需要 NPM_TOKEN。 首次配置（只需一次）：
   1. 登录 npmjs.com → Access Tokens → Trusted Publishers → Add trusted publisher；
   2. 选择 GitHub，填写 Owner difyz9、Repository hello-cli、Workflow filename release.yml （必须与仓库里的 workflow 文件名完全一致、区分大小写）；
   3. 点 Set up connection 完成。
   前提条件：
   • workflow 已配置 id-token: write 权限、发布前自动升级 npm ≥ 11.5.1；
   • 发布命令带 --provenance（这是 OIDC 认证的开关，不能去掉）；
   • package.json 的 repository 字段指向本仓库；
   • 包必须先手动发布过至少一版（Trusted Publisher 只能在包已存在时配置）。
2. bin 路径不能以 ./ 开头：npm 11 在发布时会校验 bin 字段，"./dist/index.js" 会被判为 非法并静默移除（导致安装后没有 myai 命令）。必须写成 "dist/index.js"（不带 ./）。
3. 包名可用性：当前包名为 dfyz9-cli，若后续改名字请先在 package.json 中确认可用再发布。

产物说明

| 产物 | 内容 | | ---- | ---- | | npm 包 | npm i -g dfyz9-cli 即可安装（安装后命令行命令为 myai） |

可选：仓库里保留了 .goreleaser.yaml + sea-config.json，如需手动生成各平台独立二进制 （不依赖 Node），本地执行 goreleaser release --snapshot --clean 即可预览，但 CI 不再自动做这一步。

相关文件

• .github/workflows/release.yml — 发布流水线（tag 触发、OIDC 发布）
• package.json — 包名 / 版本 / bin / engines 配置

⚠️ 注意事项

1. Trusted Publisher 配置必须精确匹配：Owner / Repository / Workflow filename 任一不一致， OIDC 发布会失败（报错是误导性的 E404 Not Found，实际是认证失败，并非包不存在）。
2. 版本号必须与 tag 一致：npm publish 发布的是 package.json 里的版本号，必须与 v* 标签 一致（如 tag v0.5.0 ↔ version 0.5.0），否则发布会失败或版本错乱。
3. 发布即生效、不可撤回：npm 包发布后无法删除已发布的版本号，测试新流水线时记得先升版本号。