runcc 0.1.0

package/CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+**cc-run** 是一个 Claude CLI 启动器，使用 TypeScript + Bun 开发。核心功能是在官方 API 和多个第三方 API endpoints 之间快速切换。这是一个单文件可执行 CLI 工具，可作为全局命令安装。
+
+## 开发命令
+
+```bash
+# 安装依赖
+bun install
+
+# 开发模式（直接运行 TypeScript 源码）
+bun run dev
+
+# 构建输出到 dist/index.js
+bun run build
+
+# 构建独立二进制可执行文件
+bun run build:bin
+
+# 全局安装（本地测试）
+bun install -g .
+
+# 配置验证测试工具
+bun test/dry-run.ts config
+bun test/dry-run.ts glm
+```
+
+**注意**: 项目无自动化测试框架、无 linting 配置、无 pre-commit hooks。
+
+## 核心架构
+
+项目采用三层架构设计：
+
+```
+┌─────────────────────────────────────────┐
+│          CLI Layer (commands)           │
+│  - 参数解析、用户交互、命令编排            │
+├─────────────────────────────────────────┤
+│        Business Logic (utils)           │
+│  - 启动器、环境变量、Claude 配置管理       │
+├─────────────────────────────────────────┤
+│         Data Layer (config)             │
+│  - 配置存储、类型定义、endpoints 管理     │
+└─────────────────────────────────────────┘
+```
+
+### 目录结构
+
+```
+src/
+├── index.ts              # CLI 入口，Commander 配置，命令路由
+├── commands/             # 命令实现层
+│   ├── run.ts           # 核心启动逻辑（官方/provider/配置模式）
+│   ├── proxy.ts         # 代理管理命令
+│   ├── list.ts          # 列出 endpoints（UTF-8 处理）
+│   ├── add.ts           # 添加自定义 endpoint
+│   └── remove.ts        # 删除 endpoint
+├── config/              # 配置数据层
+│   ├── types.ts         # TypeScript 类型定义
+│   ├── endpoints.ts     # 内置 endpoints (glm/deepseek/minimax)
+│   └── storage.ts       # ~/.cc-run/config.json 读写
+└── utils/               # 工具层
+    ├── launcher.ts      # spawn Claude 进程
+    ├── env.ts           # 环境变量构建
+    └── claude-settings.ts # ~/.claude/settings.json 读写
+```
+
+## 双配置文件系统
+
+### ~/.cc-run/config.json (启动器私有配置)
+
+存储自定义 endpoints、API tokens、最后使用的 endpoint、代理配置。
+
+### ~/.claude/settings.json (Claude 官方配置)
+
+存储 `proxy`、`apiUrl`、`anthropicApiKey`，由 Claude CLI 原生读取。
+
+**关键机制**: 使用 `--claude` 标志可以将第三方 endpoint 配置写入 `~/.claude/settings.json`，使原生 `claude` 命令默认使用该 endpoint。
+
+## 三种启动模式
+
+### 1. 官方模式 (`cc-run`)
+1. 备份当前 Claude 配置
+2. 清除第三方 endpoint 配置
+3. 根据 `clearForOfficial` 决定是否清除 proxy
+4. 启动 Claude（不设置第三方环境变量）
+5. 退出后恢复配置
+
+### 2. Provider 模式 (`cc-run glm`)
+1. 从内置或自定义 endpoints 查找配置
+2. 获取 token（首次提示输入并保存）
+3. 通过环境变量启动 Claude:
+   - `ANTHROPIC_BASE_URL`
+   - `ANTHROPIC_AUTH_TOKEN`
+   - `http_proxy`/`https_proxy`
+
+### 3. 配置模式 (`cc-run glm --claude`)
+1. 执行 provider 模式启动
+2. 额外写入 `~/.claude/settings.json`
+3. 使原生 `claude` 命令默认使用此 endpoint
+
+## 内置 Endpoints
+
+| 名称 | Endpoint URL |
+|------|--------------|
+| glm | https://open.bigmodel.cn/api/paas/v4/ |
+| deepseek | https://api.deepseek.com |
+| minimax | https://api.minimax.chat/v1 |
+
+**扩展点**: 添加内置 endpoint 需修改 `src/config/endpoints.ts`
+
+## 代码风格约定
+
+- **模块系统**: ES Modules（import 必须显式包含 `.js` 扩展名）
+- **类型系统**: 严格模式 TypeScript
+- **注释风格**: JSDoc 风格（中文）
+- **错误处理**: 使用 `process.exit(1)` 终止，无异常抛出
+- **文件组织**: 按功能分层，单一职责原则
+- **命名约定**:
+  - 文件名: kebab-case (`claude-settings.ts`)
+  - 函数: camelCase
+  - 类型: PascalCase
+  - 常量: UPPER_SNAKE_CASE
+
+## 关键技术实现
+
+### 环境变量隔离
+使用 `spawn` 的 `env` 选项实现环境变量隔离，避免污染全局环境。
+
+### 配置原子操作
+- 官方模式使用备份-修改-恢复模式确保配置安全
+- 文件操作使用同步 API (`readFileSync`, `writeFileSync`)
+- 目录不存在时自动创建 (`mkdirSync` with `recursive: true`)
+
+### UTF-8 输出处理
+`list.ts` 使用 `TextEncoder` 确保中文正确显示（标准 console.log 在某些环境下可能乱码）
+
+### 交互式输入
+使用 Node.js 原生 `readline` 模块实现 token 和代理地址输入
+
+## 依赖外部条件
+
+1. **Claude CLI**: 系统必须已安装 `claude` 命令
+2. **配置目录**: 自动创建 `~/.cc-run/` 和 `~/.claude/`
+3. **Node 版本**: >= 18.0.0

package/PLAN.md

@@ -0,0 +1,236 @@
+# CC 启动器实现计划
+
+## 项目概述
+
+使用 TypeScript + bun 创建 CC 启动器，支持切换不同的 API endpoint。
+
+## 命令格式
+
+| 命令 | 功能 |
+|------|------|
+| `cc-run` | **总是**启动官方 claude（根据配置决定是否临时清除 proxy 和第三方 endpoint） |
+| `cc-run --claude` | 恢复原生 `claude` 命令使用官方 endpoint（删除 ~/.claude/settings.json 中的第三方配置） |
+| `cc-run glm` | 使用 glm endpoint |
+| `cc-run glm --claude` | 使用 glm，并配置原生 `claude` 命令默认使用 glm |
+| `cc-run deepseek` | 使用 deepseek endpoint |
+| `cc-run deepseek --claude` | 使用 deepseek，并配置原生 `claude` 命令默认使用 deepseek |
+| `cc-run minimax` | 使用 minimax endpoint |
+| `cc-run add <name> <endpoint> <token>` | 添加自定义 endpoint |
+| `cc-run list` | 列出所有 endpoint |
+| `cc-run remove <name>` | 删除自定义 endpoint |
+| `cc-run proxy on` | 开启代理（修改 ~/.claude/settings.json） |
+| `cc-run proxy off` | 关闭代理（修改 ~/.claude/settings.json） |
+| `cc-run proxy reset` | 重置代理配置 |
+| `cc-run proxy status` | 查看代理状态 |
+| `cc-run proxy help` | 代理帮助信息 |
+
+## 项目结构
+
+```
+cc-run/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts              # CLI 入口
+│   ├── commands/
+│   │   ├── run.ts            # 启动命令
+│   │   ├── add.ts            # 添加 endpoint
+│   │   ├── list.ts           # 列出 endpoint
+│   │   ├── remove.ts         # 删除 endpoint
+│   │   └── proxy.ts          # 代理管理命令
+│   ├── config/
+│   │   ├── storage.ts        # 配置存储管理
+│   │   ├── endpoints.ts      # 内置 endpoint 定义
+│   │   └── types.ts          # 类型定义
+│   └── utils/
+│       ├── env.ts            # 环境变量设置
+│       └── launcher.ts       # 启动 claude
+└── README.md
+```
+
+## 内置 Endpoints
+
+| 名称 | Endpoint |
+|------|----------|
+| glm | https://open.bigmodel.cn/api/paas/v4/ |
+| deepseek | https://api.deepseek.com |
+| minimax | https://api.minimax.chat/v1 |
+
+## 配置存储
+
+### ~/.cc-run/config.json（启动器配置）
+`proxy.on/off` 会修改此文件的 proxy 配置，`cc-run <provider>` 会保存 token：
+```json
+{
+  "endpoints": [
+    {
+      "name": "my-custom",
+      "endpoint": "https://api.example.com/v1",
+      "token": "sk-xxxxxxxx"
+    }
+  ],
+  "tokens": {
+    "glm": "sk-xxxxxxxx",
+    "deepseek": "sk-yyyyyyyy",
+    "minimax": "sk-zzzzzzzz"
+  },
+  "lastUsed": "glm",
+  "proxy": {
+    "enabled": true,
+    "url": "http://agent.baidu.com:8891",
+    "clearForOfficial": false
+  }
+}
+```
+
+### ~/.claude/settings.json（Claude 官方配置）
+`proxy on/off` 会修改此文件的 proxy 配置：
+```json
+{
+  "proxy": "http://agent.baidu.com:8891"
+}
+```
+
+## Proxy 处理逻辑
+
+### cc-run proxy on
+1. 提示输入代理地址（首次）
+2. 保存到 `~/.cc-run/config.json`
+3. 修改 `~/.claude/settings.json`，添加 proxy 配置
+
+### cc-run proxy off
+1. 更新 `~/.cc-run/config.json`（enabled: false）
+2. 修改 `~/.claude/settings.json`，删除 proxy 配置
+
+## 运行逻辑
+
+### cc-run（无参数）
+
+总是启动官方 claude。启动前会检查并清理 `~/.claude/settings.json`：
+
+1. 读取当前的 `~/.claude/settings.json`
+2. 检查是否有 `proxy` 配置
+3. 检查是否有 `apiUrl` / `anthropicApiKey` 等第三方 endpoint 配置
+4. 根据清理策略清理：
+   - **proxy 清理**：由 `~/.cc-run/config.json` 中 `proxy.clearForOfficial` 决定
+   - **endpoint 清理**：总是清除第三方 endpoint 配置
+5. 启动 claude
+6. claude 退出后恢复被清除的配置
+
+**proxy 清理策略**（`~/.cc-run/config.json`）：
+```json
+{
+  "proxy": {
+    "clearForOfficial": true  // 启动官方 claude 时是否清除 proxy
+  }
+}
+```
+
+### cc-run <provider>
+
+使用指定 endpoint，通过环境变量启动。
+
+**Token 获取逻辑**：
+1. 检查 `~/.cc-run/config.json` 中是否已保存该 provider 的 token
+2. 如果没有，提示用户输入：
+   ```
+   请输入 glm 的 API Token: [输入框]
+   ```
+3. 保存 token 到 `~/.cc-run/config.json`：
+   ```json
+   {
+     "tokens": {
+       "glm": "sk-xxxxxxxx",
+       "deepseek": "sk-yyyyyyyy",
+       "minimax": "sk-zzzzzzzz"
+     }
+   }
+   ```
+4. 使用保存的 token 启动
+
+### cc-run <provider> --claude
+使用指定 endpoint，并**配置原生 `claude` 命令**的默认行为：
+1. 使用指定 endpoint 启动 cc-run
+2. 修改 `~/.claude/settings.json`，设置：
+   - `apiUrl`: 指定 provider 的 endpoint
+   - `anthropicApiKey`: 指定 provider 的 token
+3. 之后直接运行原生 `claude` 命令时，会使用这个第三方 endpoint
+4. **不影响** `cc-run` 无参数的行为（`cc-run` 仍然总是启动官方 claude）
+
+### cc-run --claude（无 provider）
+**恢复原生 `claude` 命令使用官方 endpoint**：
+1. 删除 `~/.claude/settings.json` 中的 `apiUrl` 和 `anthropicApiKey`
+2. 之后直接运行原生 `claude` 命令时，会使用官方 endpoint
+3. 不启动 cc-run
+
+> **注**：`--claude` 只影响原生 `claude` 命令，不影响 `cc-run`
+
+## 环境变量
+
+启动 CC 时设置：
+- `ANTHROPIC_BASE_URL` - API endpoint
+- `ANTHROPIC_AUTH_TOKEN` - API token
+- `http_proxy` / `https_proxy` - 代理（如果配置）
+
+## 关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/index.ts` | CLI 入口，使用 commander 解析参数 |
+| `src/config/storage.ts` | 配置文件读写、token 管理、endpoint 管理 |
+| `src/utils/token.ts` | Token 获取和保存逻辑（首次使用时提示输入） |
+| `src/commands/run.ts` | 核心启动逻辑，处理官方模式的 proxy 临时清除 |
+| `src/commands/proxy.ts` | 代理管理命令（on/off/reset/status/help） |
+| `src/utils/launcher.ts` | spawn claude 进程 |
+| `src/utils/claude-settings.ts` | 读写 `~/.claude/settings.json` 的 proxy 和 endpoint 配置 |
+| `src/config/types.ts` | TypeScript 类型定义 |
+
+## 代理命令实现要点
+
+| 命令 | 说明 |
+|------|------|
+| `cc-run proxy on` | 首次运行时提示输入代理地址，保存并修改 `~/.claude/settings.json` |
+| `cc-run proxy off` | 关闭代理，删除 `~/.claude/settings.json` 中的 proxy 配置 |
+| `cc-run proxy reset` | 重置代理配置 |
+| `cc-run proxy status` | 显示代理状态（是否启用、地址） |
+| `cc-run proxy help` | 显示代理相关帮助 |
+
+## 依赖
+
+```json
+{
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "bun-types": "latest"
+  }
+}
+```
+
+## 验证方式
+
+```bash
+# 1. 构建
+bun run build
+
+# 2. 测试 list
+bun run src/index.ts list
+
+# 3. 测试 add
+bun run src/index.ts add test https://api.test.com sk-test
+
+# 4. 测试 proxy
+bun run src/index.ts proxy status
+bun run src/index.ts proxy on
+bun run src/index.ts proxy off
+
+# 5. 测试 run（需要已有 token）
+bun run src/index.ts glm
+
+# 6. 全局安装后测试
+bun install -g
+cc-run list
+cc-run proxy status
+```

package/README.md

@@ -0,0 +1,188 @@
+# cc-run
+
+Claude CLI 启动器，支持切换不同的 API endpoint。
+
+## 功能特性
+
+- 🔄 快速切换官方/第三方 API endpoint
+- 🔐 保存和管理多个 API Token
+- 🌐 代理配置管理
+- ⚙️ 配置原生 `claude` 命令使用第三方 endpoint
+- 📝 自定义 endpoint 支持
+
+## 安装
+
+```bash
+# 全局安装
+bun install -g .
+
+# 或使用 npm
+npm install -g .
+```
+
+## 快速开始
+
+```bash
+# 查看所有可用的 endpoints
+cc-run list
+
+# 使用第三方 endpoint
+cc-run glm
+
+# 配置原生 claude 命令使用 glm
+cc-run glm --claude
+
+# 恢复原生 claude 使用官方 endpoint
+cc-run --claude
+
+# 启动官方 claude
+cc-run
+```
+
+## 命令说明
+
+### Endpoint 管理
+
+| 命令 | 说明 |
+|------|------|
+| `cc-run` | 启动官方 claude |
+| `cc-run glm` | 使用 glm endpoint |
+| `cc-run deepseek` | 使用 deepseek endpoint |
+| `cc-run minimax` | 使用 minimax endpoint |
+| `cc-run list` | 列出所有 endpoints |
+| `cc-run add <name> <endpoint> [token]` | 添加自定义 endpoint |
+| `cc-run remove <name>` | 删除自定义 endpoint |
+
+### 原生命令配置
+
+| 命令 | 说明 |
+|------|------|
+| `cc-run <provider> --claude` | 配置原生 `claude` 命令使用第三方 endpoint |
+| `cc-run --claude` | 恢复原生 `claude` 命令使用官方 endpoint |
+
+### 代理管理
+
+| 命令 | 说明 |
+|------|------|
+| `cc-run proxy on` | 开启代理 |
+| `cc-run proxy off` | 关闭代理 |
+| `cc-run proxy status` | 查看代理状态 |
+| `cc-run proxy reset` | 重置代理配置 |
+
+## 内置 Endpoints
+
+| 名称 | Endpoint |
+|------|----------|
+| glm | https://open.bigmodel.cn/api/paas/v4/ |
+| deepseek | https://api.deepseek.com |
+| minimax | https://api.minimax.chat/v1 |
+
+## 配置文件
+
+### ~/.cc-run/config.json
+
+```json
+{
+  "endpoints": [
+    {
+      "name": "my-custom",
+      "endpoint": "https://api.example.com/v1",
+      "token": "sk-xxxxxxxx"
+    }
+  ],
+  "tokens": {
+    "glm": "sk-xxxxxxxx",
+    "deepseek": "sk-yyyyyyyy",
+    "minimax": "sk-zzzzzzzz"
+  },
+  "lastUsed": "glm",
+  "proxy": {
+    "enabled": true,
+    "url": "http://agent.baidu.com:8891",
+    "clearForOfficial": false
+  }
+}
+```
+
+### ~/.claude/settings.json
+
+```json
+{
+  "proxy": "http://agent.baidu.com:8891"
+}
+```
+
+## 使用示例
+
+### 添加自定义 endpoint
+
+```bash
+cc-run add my-api https://api.my-service.com/v1 sk-my-token
+```
+
+### 切换 endpoint
+
+```bash
+# 使用 glm
+cc-run glm
+
+# 使用 deepseek
+cc-run deepseek
+
+# 使用自定义 endpoint
+cc-run my-api
+```
+
+### 配置代理
+
+```bash
+# 开启代理（首次会提示输入代理地址）
+cc-run proxy on
+
+# 查看代理状态
+cc-run proxy status
+
+# 关闭代理
+cc-run proxy off
+```
+
+### 配置原生命令
+
+```bash
+# 让原生 claude 命令使用 glm
+cc-run glm --claude
+
+# 之后直接使用 claude 命令即可
+claude "你好"
+
+# 恢复使用官方 endpoint
+cc-run --claude
+```
+
+## Token 管理
+
+首次使用某个 endpoint 时，如果未配置 token，会提示输入：
+
+```bash
+$ cc-run glm
+请输入 glm 的 API Token: [输入框]
+```
+
+Token 会被保存到 `~/.cc-run/config.json`，下次使用时无需再次输入。
+
+## 开发
+
+```bash
+# 安装依赖
+bun install
+
+# 运行开发模式
+bun run dev
+
+# 构建
+bun run build
+```
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,25 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "cc-run",
+      "dependencies": {
+        "commander": "^12.0.0",
+      },
+      "devDependencies": {
+        "@types/node": "^20.0.0",
+        "bun-types": "latest",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/node@20.19.30", "https://registry.npmmirror.com/@types/node/-/node-20.19.30.tgz", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-WJtwWJu7UdlvzEAUm484QNg5eAoq5QR08KDNx7g45Usrs2NtOPiX8ugDqmKdXkyL03rBqU5dYNYVQetEpBHq2g=="],
+
+    "bun-types": ["bun-types@1.3.6", "https://registry.npmmirror.com/bun-types/-/bun-types-1.3.6.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+
+    "commander": ["commander@12.1.0", "https://registry.npmmirror.com/commander/-/commander-12.1.0.tgz", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
+    "undici-types": ["undici-types@6.21.0", "https://registry.npmmirror.com/undici-types/-/undici-types-6.21.0.tgz", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+  }
+}