runcc 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/skills/publish/SKILL.md +23 -2
- package/CHANGELOG.md +11 -0
- package/CLAUDE.md +121 -105
- package/dist/index.js +11 -5
- package/package.json +1 -1
|
@@ -1,14 +1,35 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: publish
|
|
3
|
-
description: 自动化 npm
|
|
3
|
+
description: 自动化 npm 包发布准备工作流。预检查 → 询问版本 → npm version → 测试 → 构建 → CHANGELOG → 提交 → 推送 → 打印发布命令（用户手动执行 npm publish）。触发词：发布新版本/publish to npm/bump version/release。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# NPM 发布工作流
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
预检查 → 提交未保存更改 → 询问版本 → npm version → 测试 → 构建 → CHANGELOG → 提交 → 推送 → 打印发布命令
|
|
9
9
|
|
|
10
10
|
## 工作流程
|
|
11
11
|
|
|
12
|
+
### 0. 预检查（重要！）
|
|
13
|
+
|
|
14
|
+
在开始任何操作前，**必须先检查 git 状态**：
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# 检查当前分支
|
|
18
|
+
git branch --show-current
|
|
19
|
+
|
|
20
|
+
# 检查工作区状态
|
|
21
|
+
git status --short
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**如果工作区干净**：直接进入步骤 1。
|
|
25
|
+
|
|
26
|
+
**如果有未提交更改**：使用 `AskUserQuestion` 询问用户：
|
|
27
|
+
- 先提交更改（**必须使用 `/commit-commands:commit` skill**）
|
|
28
|
+
- 丢弃更改（`git restore .`）
|
|
29
|
+
- 中止流程
|
|
30
|
+
|
|
31
|
+
**关键原因**：`npm version` 命令要求工作目录必须是干净状态，否则会报错退出。
|
|
32
|
+
|
|
12
33
|
### 1. 询问目标版本
|
|
13
34
|
|
|
14
35
|
使用 `AskUserQuestion` 询问用户要升级到什么版本：
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.1.4] - 2026-01-19
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- Support `runcc -- <args>` syntax for directly launching official Claude mode with argument passthrough
|
|
12
|
+
- This provides a more concise way to launch official Claude when no provider is needed
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
- Updated usage examples in error messages to include the new `runcc -- <args>` syntax
|
|
16
|
+
- Enhanced publish skill with better pre-check workflow documentation
|
|
17
|
+
- Reorganized CLAUDE.md with clearer structure
|
|
18
|
+
|
|
8
19
|
## [0.1.3] - 2026-01-19
|
|
9
20
|
|
|
10
21
|
### Changed
|
package/CLAUDE.md
CHANGED
|
@@ -4,146 +4,162 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|
|
4
4
|
|
|
5
5
|
## 项目概述
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**runcc** 是一个 TypeScript CLI 工具，用于在 Claude Code 中切换不同的 API 端点。它允许用户使用第三方 API 提供商（GLM、DeepSeek、Minimax）或自定义端点，同时保持与 Claude 原生配置的无缝集成。
|
|
8
8
|
|
|
9
9
|
## 开发命令
|
|
10
10
|
|
|
11
|
+
### 运行与构建
|
|
11
12
|
```bash
|
|
12
|
-
#
|
|
13
|
-
bun
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
bun run dev
|
|
17
|
-
|
|
18
|
-
# 构建输出到 dist/index.js
|
|
19
|
-
bun run build
|
|
20
|
-
|
|
21
|
-
# 构建独立二进制可执行文件
|
|
22
|
-
bun run build:bin
|
|
23
|
-
|
|
24
|
-
# 全局安装（本地测试）
|
|
25
|
-
bun install -g .
|
|
13
|
+
bun run dev # 开发模式运行
|
|
14
|
+
bun run build # 编译到 dist/
|
|
15
|
+
bun run build:bin # 编译独立二进制文件
|
|
16
|
+
```
|
|
26
17
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
bun test
|
|
18
|
+
### 测试
|
|
19
|
+
```bash
|
|
20
|
+
bun test # 运行所有测试
|
|
21
|
+
bun test --watch # 监视模式
|
|
22
|
+
bun run test:unit # 仅单元测试
|
|
23
|
+
bun run test:integration # 仅集成测试
|
|
30
24
|
```
|
|
31
25
|
|
|
32
|
-
|
|
26
|
+
### 发布
|
|
27
|
+
```bash
|
|
28
|
+
/publish # 使用 publish skill 自动化发布流程
|
|
29
|
+
```
|
|
33
30
|
|
|
34
31
|
## 核心架构
|
|
35
32
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
```
|
|
33
|
+
### 双配置系统
|
|
34
|
+
|
|
35
|
+
1. **RunCC Config** (`~/.runcc/config.json`)
|
|
36
|
+
- 存储自定义端点、API token、代理设置
|
|
37
|
+
- 通过 `src/config/storage.ts` 管理
|
|
38
|
+
- 结构示例：
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"endpoints": [...],
|
|
42
|
+
"tokens": {"glm": "sk-...", "deepseek": "sk-..."},
|
|
43
|
+
"lastUsed": "glm",
|
|
44
|
+
"proxy": {"enabled": true, "url": "http://...", "clearForOfficial": false}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
2. **Claude Settings** (`~/.claude/settings.json`)
|
|
49
|
+
- Claude 原生配置文件
|
|
50
|
+
- 通过 `src/utils/claude-settings.ts` 管理
|
|
51
|
+
- 包含 proxy、apiUrl、anthropicApiKey 和 env 配置
|
|
52
|
+
- 结构示例：
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"proxy": "http://...",
|
|
56
|
+
"apiUrl": "https://...",
|
|
57
|
+
"anthropicApiKey": "sk-...",
|
|
58
|
+
"env": {
|
|
59
|
+
"ANTHROPIC_BASE_URL": "...",
|
|
60
|
+
"ANTHROPIC_AUTH_TOKEN": "..."
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**关键设计模式：临时修改模式** - 在官方模式下启动时，临时清除第三方配置并在 Claude 退出后恢复。
|
|
50
66
|
|
|
51
67
|
### 目录结构
|
|
52
68
|
|
|
53
69
|
```
|
|
54
70
|
src/
|
|
55
|
-
├── index.ts # CLI
|
|
56
|
-
├── commands/ #
|
|
57
|
-
│ ├── run.ts #
|
|
58
|
-
│ ├──
|
|
59
|
-
│ ├──
|
|
60
|
-
│ ├──
|
|
61
|
-
│ └──
|
|
62
|
-
├── config/
|
|
63
|
-
│ ├── types.ts # TypeScript
|
|
64
|
-
│ ├── endpoints.ts #
|
|
65
|
-
│ └── storage.ts #
|
|
66
|
-
└── utils/
|
|
67
|
-
├──
|
|
68
|
-
├──
|
|
69
|
-
|
|
71
|
+
├── index.ts # CLI 入口，使用 Commander.js
|
|
72
|
+
├── commands/ # CLI 命令实现
|
|
73
|
+
│ ├── run.ts # 核心启动逻辑，支持官方/提供商/配置模式
|
|
74
|
+
│ ├── list.ts # 列出可用端点
|
|
75
|
+
│ ├── add.ts # 添加自定义端点
|
|
76
|
+
│ ├── remove.ts # 删除自定义端点
|
|
77
|
+
│ └── proxy.ts # 代理管理（on/off/reset/status/help）
|
|
78
|
+
├── config/
|
|
79
|
+
│ ├── types.ts # TypeScript 接口定义
|
|
80
|
+
│ ├── endpoints.ts # 内置端点定义和模型映射
|
|
81
|
+
│ └── storage.ts # 配置文件 CRUD 操作
|
|
82
|
+
└── utils/
|
|
83
|
+
├── claude-settings.ts # Claude 配置读写、备份/恢复
|
|
84
|
+
├── launcher.ts # 进程启动和退出码处理
|
|
85
|
+
├── env.ts # ANTHROPIC_* 环境变量构建
|
|
86
|
+
├── passthrough-args.ts # -- 分隔符后的参数解析
|
|
87
|
+
└── output.ts # UTF-8 安全输出（修复中文显示）
|
|
70
88
|
```
|
|
71
89
|
|
|
72
|
-
|
|
90
|
+
### 关键设计决策
|
|
73
91
|
|
|
74
|
-
|
|
92
|
+
1. **UTF-8 处理**：在编译后的二进制文件中 monkey-patch `console.log/error` 确保中文字符正确显示
|
|
75
93
|
|
|
76
|
-
|
|
94
|
+
2. **临时修改模式**：启动官方 Claude 时临时清除第三方配置，退出后恢复
|
|
77
95
|
|
|
78
|
-
|
|
96
|
+
3. **环境变量策略**：使用 `ANTHROPIC_*` 环境变量而非文件修改来使用第三方 API
|
|
79
97
|
|
|
80
|
-
|
|
98
|
+
4. **模型映射**：支持将 Claude 模型层级（haiku/opus/sonnet）映射到提供商特定模型
|
|
81
99
|
|
|
82
|
-
|
|
100
|
+
5. **代理灵活性**：支持每会话代理配置，可选在官方模式下清除（clearForOfficial）
|
|
83
101
|
|
|
84
|
-
|
|
102
|
+
6. **参数透传**：通过 `--` 分隔符支持透传参数给 Claude CLI
|
|
85
103
|
|
|
86
|
-
|
|
87
|
-
1. 备份当前 Claude 配置
|
|
88
|
-
2. 清除第三方 endpoint 配置
|
|
89
|
-
3. 根据 `clearForOfficial` 决定是否清除 proxy
|
|
90
|
-
4. 启动 Claude（不设置第三方环境变量）
|
|
91
|
-
5. 退出后恢复配置
|
|
104
|
+
7. **交互式提示**：使用 Node.js readline 在未预配置时获取 token 和代理输入
|
|
92
105
|
|
|
93
|
-
|
|
94
|
-
1. 从内置或自定义 endpoints 查找配置
|
|
95
|
-
2. 获取 token（首次提示输入并保存）
|
|
96
|
-
3. 通过环境变量启动 Claude:
|
|
97
|
-
- `ANTHROPIC_BASE_URL`
|
|
98
|
-
- `ANTHROPIC_AUTH_TOKEN`
|
|
99
|
-
- `http_proxy`/`https_proxy`
|
|
106
|
+
## 测试策略
|
|
100
107
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
108
|
+
- **单元测试**：测试独立模块（storage、endpoints、env 等）
|
|
109
|
+
- **集成测试**：测试命令工作流（run、list、add、remove、proxy）
|
|
110
|
+
- **测试夹具**：`src/__tests__/fixtures/` 下的 mock 实现（mock-fs、mock-readline、mock-process）
|
|
111
|
+
- **环境隔离**：使用 `CC_RUN_TEST_HOME` 环境变量
|
|
112
|
+
- **手动测试**：`test/` 目录下的 dry-run、mock-claude、verify-passthrough
|
|
105
113
|
|
|
106
|
-
|
|
114
|
+
测试文件位于 `src/__tests__/`，使用 Bun Test 框架。
|
|
107
115
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
116
|
+
## 发布流程
|
|
117
|
+
|
|
118
|
+
项目包含自定义 **publish skill**，自动化 npm 发布：
|
|
119
|
+
1. 预检查（git 状态必须干净）
|
|
120
|
+
2. 版本 bump（`npm version`，创建 commit + tag）
|
|
121
|
+
3. 运行测试
|
|
122
|
+
4. 构建
|
|
123
|
+
5. 生成/更新 CHANGELOG
|
|
124
|
+
6. Git 提交
|
|
125
|
+
7. Git push（需用户确认）
|
|
126
|
+
8. 输出 `npm publish` 命令供手动执行
|
|
127
|
+
|
|
128
|
+
## 安装测试
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
./test-install.sh # 完整的安装/测试/卸载循环
|
|
132
|
+
```
|
|
113
133
|
|
|
114
|
-
|
|
134
|
+
## 技术栈
|
|
115
135
|
|
|
116
|
-
|
|
136
|
+
- **Runtime**: Bun
|
|
137
|
+
- **Language**: TypeScript (strict mode, ES2022 target)
|
|
138
|
+
- **CLI Framework**: Commander.js ^12.0.0
|
|
139
|
+
- **Testing**: Bun Test
|
|
140
|
+
- **Minimum Node**: >=18.0.0
|
|
141
|
+
- **License**: Apache-2.0
|
|
117
142
|
|
|
118
|
-
|
|
119
|
-
- **类型系统**: 严格模式 TypeScript
|
|
120
|
-
- **注释风格**: JSDoc 风格（中文）
|
|
121
|
-
- **错误处理**: 使用 `process.exit(1)` 终止，无异常抛出
|
|
122
|
-
- **文件组织**: 按功能分层，单一职责原则
|
|
123
|
-
- **命名约定**:
|
|
124
|
-
- 文件名: kebab-case (`claude-settings.ts`)
|
|
125
|
-
- 函数: camelCase
|
|
126
|
-
- 类型: PascalCase
|
|
127
|
-
- 常量: UPPER_SNAKE_CASE
|
|
143
|
+
## 内置 Endpoints
|
|
128
144
|
|
|
129
|
-
|
|
145
|
+
| 名称 | Endpoint |
|
|
146
|
+
|------|----------|
|
|
147
|
+
| glm | https://open.bigmodel.cn/api/paas/v4/ |
|
|
148
|
+
| deepseek | https://api.deepseek.com |
|
|
149
|
+
| minimax | https://api.minimax.chat/v1 |
|
|
130
150
|
|
|
131
|
-
|
|
132
|
-
使用 `spawn` 的 `env` 选项实现环境变量隔离，避免污染全局环境。
|
|
151
|
+
## Claude Code 技能
|
|
133
152
|
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
- 文件操作使用同步 API (`readFileSync`, `writeFileSync`)
|
|
137
|
-
- 目录不存在时自动创建 (`mkdirSync` with `recursive: true`)
|
|
153
|
+
项目在 `.claude/skills/` 中包含 Claude Code 技能：
|
|
154
|
+
- **publish** - 自动化 npm 发布工作流（预检查 → 版本 bump → 测试 → 构建 → CHANGELOG → 提交 → 推送）
|
|
138
155
|
|
|
139
|
-
|
|
140
|
-
`list.ts` 使用 `TextEncoder` 确保中文正确显示（标准 console.log 在某些环境下可能乱码）
|
|
156
|
+
这体现了项目的 dogfooding 方法——使用 Claude Code 工具管理自己的开发工作流。
|
|
141
157
|
|
|
142
|
-
|
|
143
|
-
使用 Node.js 原生 `readline` 模块实现 token 和代理地址输入
|
|
158
|
+
## 发布到 npm 的文件
|
|
144
159
|
|
|
145
|
-
|
|
160
|
+
- `dist/` - 编译后的 JavaScript
|
|
161
|
+
- `package.json` - 包元数据
|
|
162
|
+
- `README.md` - 用户文档
|
|
163
|
+
- `CHANGELOG.md` - 版本历史
|
|
146
164
|
|
|
147
|
-
|
|
148
|
-
2. **配置目录**: 自动创建 `~/.runcc/` 和 `~/.claude/`
|
|
149
|
-
3. **Node 版本**: >= 18.0.0
|
|
165
|
+
**排除**：`src/`、`test/`、`*.test.ts`、`tsconfig.json`、`runcc` 二进制文件
|
package/dist/index.js
CHANGED
|
@@ -2452,7 +2452,7 @@ function validateDashPosition(argv) {
|
|
|
2452
2452
|
return;
|
|
2453
2453
|
}
|
|
2454
2454
|
if (dashIndex === 0) {
|
|
2455
|
-
|
|
2455
|
+
return;
|
|
2456
2456
|
}
|
|
2457
2457
|
const beforeDash = userArgs.slice(0, dashIndex);
|
|
2458
2458
|
const hasValidPrefix = beforeDash.some((arg) => !arg.startsWith("-") || arg === "--claude");
|
|
@@ -2510,9 +2510,10 @@ program2.argument("[provider]", "provider 名称 (glm, deepseek, minimax 或自
|
|
|
2510
2510
|
console.error("❌ 参数位置不正确");
|
|
2511
2511
|
console.error("");
|
|
2512
2512
|
console.error("正确的用法示例:");
|
|
2513
|
-
console.error(" runcc
|
|
2514
|
-
console.error(" runcc
|
|
2515
|
-
console.error(" runcc
|
|
2513
|
+
console.error(" runcc -- <claude参数> # 启动官方 Claude 并透传参数");
|
|
2514
|
+
console.error(" runcc glm -- <claude参数> # 使用 glm provider 并透传参数");
|
|
2515
|
+
console.error(" runcc --claude -- <参数> # 恢复官方配置并透传参数");
|
|
2516
|
+
console.error(" runcc glm --claude -- <参数> # 配置原生 claude 命令使用 glm");
|
|
2516
2517
|
console.error("");
|
|
2517
2518
|
console.error("说明: -- 分隔符用于将后续参数透传给 Claude CLI");
|
|
2518
2519
|
process.exit(1);
|
|
@@ -2520,4 +2521,9 @@ program2.argument("[provider]", "provider 名称 (glm, deepseek, minimax 或自
|
|
|
2520
2521
|
throw error;
|
|
2521
2522
|
}
|
|
2522
2523
|
});
|
|
2523
|
-
|
|
2524
|
+
var userArgs = process.argv.slice(2);
|
|
2525
|
+
if (userArgs[0] === "--") {
|
|
2526
|
+
program2.parse([process.argv[0], process.argv[1]]);
|
|
2527
|
+
} else {
|
|
2528
|
+
program2.parse();
|
|
2529
|
+
}
|