@peterwangze/claude-trigger-router 1.0.1 → 1.0.3

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.
Files changed (4) hide show
  1. package/README.md +296 -295
  2. package/dist/cli.js +174 -37
  3. package/dist/cli.js.map +2 -2
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,295 +1,296 @@
1
- # Claude Trigger Router
2
-
3
- 面向 Claude Code 的本地模型路由代理。它接管 Claude Code 发出的上游请求，再按你的规则和路由策略分发到不同模型。
4
-
5
- 核心目标只有两件事：
6
-
7
- - 让你用 `Models[].id` 管理模型，而不是到处手写 `provider,model`
8
- - 让你只关心模型接入信息，消息格式转换由路由层统一处理
9
-
10
- ## 快速开始
11
-
12
- ### 1. 安装
13
-
14
- ```bash
15
- npm install -g @peterwangze/claude-trigger-router
16
- ```
17
-
18
- 如果 npm registry 还没有同步到最新公开包，或者当前包尚未完成首次公开发布，可以先临时改用 GitHub 安装：
19
-
20
- ```bash
21
- npm install -g github:peterwangze/claude-trigger-router
22
- ```
23
-
24
- ### 2. 运行初始化向导
25
-
26
- ```bash
27
- ctr setup
28
- ```
29
-
30
- `ctr setup` 会：
31
-
32
- - 检查当前配置是否可复用
33
- - 检测旧版 `~/.ccr/config.yaml`
34
- - 尝试迁移成新的 `Models` 配置
35
- - 提供 `openrouter` / `deepseek` / `openai-compatible` / `anthropic` / `siliconflow` / `custom` 预设
36
- - 在需要时询问最少必要字段
37
- - 保存配置后启动服务并进入 Claude Code
38
-
39
- ### 3. 使用最小配置
40
-
41
- 如果你更喜欢手动编辑，也可以先执行：
42
-
43
- ```bash
44
- ctr init
45
- ```
46
-
47
- 然后把 `~/.claude-trigger-router/config.yaml` 调整为：
48
-
49
- ```yaml
50
- Models:
51
- - id: sonnet
52
- api: "https://openrouter.ai/api/v1/chat/completions"
53
- key: "sk-xxx"
54
- interface: "openai"
55
- model: "anthropic/claude-sonnet-4"
56
- thinking: "auto"
57
-
58
- Router:
59
- default: "sonnet"
60
- ```
61
-
62
- ### 4. 启动服务
63
-
64
- ```bash
65
- ctr start
66
- ```
67
-
68
- 确认配置可用后，可改为后台运行：
69
-
70
- ```bash
71
- ctr start --daemon
72
- ```
73
-
74
- ### 5. 启动 Claude Code
75
-
76
- ```bash
77
- ctr code
78
- ```
79
-
80
- `ctr code` 会检查目标端口上是否真的是 Claude Trigger Router，然后再注入 `ANTHROPIC_BASE_URL` 并拉起 Claude Code。
81
-
82
- ## 新配置心智
83
-
84
- 推荐始终从 `Models` 出发。每个模型接入项描述的是“这个模型怎么连”，而不是“内部 provider 怎么拼”。
85
-
86
- 每个模型的最少必填字段是：
87
-
88
- | 字段 | 是否必填 | 说明 |
89
- |------|----------|------|
90
- | `id` | 必填 | 模型唯一标识，供 Router / TriggerRouter / SmartRouter / Governance 引用 |
91
- | `api` | 必填 | 上游接口地址 |
92
- | `key` | 必填 | 对应 API Key |
93
- | `interface` | 必填 | 接口类型，当前支持 `openai` / `anthropic` |
94
- | `model` | 必填 | 目标模型名 |
95
- | `thinking` | 可选 | 思考强度，推荐 `off / auto / on / low / medium / high` |
96
-
97
- 额外可选项：
98
-
99
- - `metadata.vendor_hint`
100
- - `metadata.supports_reasoning`
101
- - `metadata.supports_tools`
102
- - `metadata.supports_images`
103
-
104
- 兼容性说明：
105
-
106
- - 当前实现仍兼容旧字段 `api_base_url` / `api_key` / `protocol`
107
- - 保存和对外展示优先使用新字段 `api` / `key` / `interface`
108
- - `thinking` 既支持简写字符串，也支持 `{ mode, effort, budget_tokens }` 对象
109
-
110
- ## 接口类型怎么选
111
-
112
- `interface` 只表示目标上游期望的消息协议类型，不等于“厂商名”。
113
-
114
- 常见映射如下：
115
-
116
- | 场景 | `api` 示例 | `interface` |
117
- |------|------------|-------------|
118
- | OpenAI 官方 | `https://api.openai.com/v1/chat/completions` | `openai` |
119
- | Anthropic 官方 | `https://api.anthropic.com/v1/messages` | `anthropic` |
120
- | OpenRouter | `https://openrouter.ai/api/v1/chat/completions` | `openai` |
121
- | DeepSeek | `https://api.deepseek.com/chat/completions` | `openai` |
122
- | SiliconFlow / 本地兼容服务 | 对应兼容地址 | `openai` |
123
-
124
- 路由层会按 `interface` 把统一消息转换成目标上游请求体。
125
-
126
- 当前统一转换已覆盖：
127
-
128
- - 文本消息
129
- - 图片输入
130
- - tool call / tool result
131
- - `thinking`
132
-
133
- 如果目标模型声明不支持某项能力，路由会做显式降级，并给出 warning。
134
-
135
- ## 常见路由配置
136
-
137
- ### 单模型
138
-
139
- ```yaml
140
- Models:
141
- - id: sonnet
142
- api: "https://openrouter.ai/api/v1/chat/completions"
143
- key: "sk-xxx"
144
- interface: "openai"
145
- model: "anthropic/claude-sonnet-4"
146
-
147
- Router:
148
- default: "sonnet"
149
- ```
150
-
151
- ### 规则路由
152
-
153
- ```yaml
154
- Models:
155
- - id: sonnet
156
- api: "https://openrouter.ai/api/v1/chat/completions"
157
- key: "sk-xxx"
158
- interface: "openai"
159
- model: "anthropic/claude-sonnet-4"
160
-
161
- - id: opus
162
- api: "https://openrouter.ai/api/v1/chat/completions"
163
- key: "sk-xxx"
164
- interface: "openai"
165
- model: "anthropic/claude-opus-4"
166
-
167
- Router:
168
- default: "sonnet"
169
-
170
- TriggerRouter:
171
- enabled: true
172
- analysis_scope: "last_message"
173
- rules:
174
- - name: "architecture"
175
- priority: 90
176
- enabled: true
177
- patterns:
178
- - type: exact
179
- keywords: ["架构设计", "system design"]
180
- model: "opus"
181
- ```
182
-
183
- ### 规则 + 智能路由
184
-
185
- ```yaml
186
- Models:
187
- - id: sonnet
188
- api: "https://openrouter.ai/api/v1/chat/completions"
189
- key: "sk-xxx"
190
- interface: "openai"
191
- model: "anthropic/claude-sonnet-4"
192
-
193
- - id: reasoner
194
- api: "https://api.deepseek.com/chat/completions"
195
- key: "sk-xxx"
196
- interface: "openai"
197
- model: "deepseek-reasoner"
198
- thinking: "high"
199
-
200
- Router:
201
- default: "sonnet"
202
- think: "reasoner"
203
-
204
- SmartRouter:
205
- enabled: true
206
- router_model: "sonnet"
207
- candidates:
208
- - model: "sonnet"
209
- description: "通用编程与调试"
210
- - model: "reasoner"
211
- description: "复杂推理与严谨分析"
212
- ```
213
-
214
- 完整示例见 `config/trigger.example.yaml`。
215
-
216
- ## warning 与 capability hint
217
-
218
- 如果你已经知道某个模型不支持完整能力，可以在配置里显式声明：
219
-
220
- ```yaml
221
- Models:
222
- - id: restricted
223
- api: "https://api.example.com/v1/chat/completions"
224
- key: "sk-xxx"
225
- interface: "openai"
226
- model: "vendor/text-only"
227
- thinking: "high"
228
- metadata:
229
- supports_reasoning: false
230
- supports_tools: false
231
- supports_images: false
232
- ```
233
-
234
- 当前行为：
235
-
236
- - `supports_reasoning: false` 时，请求里的 `thinking` 会被忽略
237
- - `supports_tools: false` 时，工具定义和 tool call/result 会退化为文本
238
- - `supports_images: false` 时，图片块会退化为文本说明
239
-
240
- 这些信息会出现在：
241
-
242
- - `ctr setup` 的配置提示
243
- - `POST /api/config` 返回的 `warnings`
244
- - `GET /api/models/compiled`
245
- - `/ui` 的 Draft Config Preview 和 Capability Warnings
246
-
247
- ## `/ui` 可以做什么
248
-
249
- 访问 `http://127.0.0.1:3456/ui` 后，可以直接：
250
-
251
- - 编辑 `Models` 草稿
252
- - 预览 compiled model map
253
- - 查看 `errors / warnings / capabilityWarnings`
254
- - 保存当前草稿配置
255
- - 对部分 warning 执行快捷修正
256
-
257
- `/ui` 的新增模型卡片和 Provider template 现在也共用同一份 preset 目录，不同模板会带出各自的默认模型、示例项和 placeholder。
258
-
259
- 适合用来做配置校准，但主线配置入口仍然建议优先用 `ctr setup` 或直接编辑配置文件。
260
-
261
- ## 旧配置迁移
262
-
263
- 如果你还在使用旧的 `Providers + provider,model` 配置：
264
-
265
- - 当前版本仍然兼容旧格式
266
- - `ctr setup` 会优先尝试迁移旧 `ccr` 配置
267
- - 路由字段推荐逐步改成直接引用 `Models[].id`
268
-
269
- 迁移后的核心变化是：
270
-
271
- - `provider,model` -> `modelId`
272
- - `api_base_url` -> `api`
273
- - `api_key` -> `key`
274
- - `protocol` -> `interface`
275
-
276
- 详见 `docs/models-migration-guide.md`。
277
-
278
- ## 常用命令
279
-
280
- ```bash
281
- ctr setup
282
- ctr init
283
- ctr start
284
- ctr start --daemon
285
- ctr stop
286
- ctr restart --daemon
287
- ctr status
288
- ctr code
289
- ```
290
-
291
- ## 推荐阅读
292
-
293
- - 配置模板与分工建议：`docs/configuration-guide.md`
294
- - 旧配置迁移：`docs/models-migration-guide.md`
295
- - 完整示例：`config/trigger.example.yaml`
1
+ # Claude Trigger Router
2
+
3
+ 面向 Claude Code 的本地模型路由代理。它接管 Claude Code 发出的上游请求，再按你的规则和路由策略分发到不同模型。
4
+
5
+ 核心目标只有两件事：
6
+
7
+ - 让你用 `Models[].id` 管理模型，而不是到处手写 `provider,model`
8
+ - 让你只关心模型接入信息，消息格式转换由路由层统一处理
9
+
10
+ ## 快速开始
11
+
12
+ ### 1. 安装
13
+
14
+ ```bash
15
+ npm install -g @peterwangze/claude-trigger-router
16
+ ```
17
+
18
+ 如果 npm registry 还没有同步到最新公开包，或者当前包尚未完成首次公开发布，可以先临时改用 GitHub 安装：
19
+
20
+ ```bash
21
+ npm install -g github:peterwangze/claude-trigger-router
22
+ ```
23
+
24
+ ### 2. 运行初始化向导
25
+
26
+ ```bash
27
+ ctr setup
28
+ ```
29
+
30
+ `ctr setup` 会：
31
+
32
+ - 优先检查当前配置是否可直接复用
33
+ - 检测旧版 `~/.ccr/config.yaml` 或 `~/.claude-code-router/config.yaml` 并优先提供迁移
34
+ - 在需要新建时，先确认接入方式与 provider 预设，再带出默认模型和默认模型 ID 供确认
35
+ - 只生成最小可用配置（`Models + Router.default`），高级路由稍后再补
36
+ - 保存配置后启动服务并进入 Claude Code
37
+
38
+ ### 3. 使用最小配置
39
+
40
+ 如果你更喜欢手动编辑，也可以先执行：
41
+
42
+ ```bash
43
+ ctr init
44
+ ```
45
+
46
+ 然后把 `~/.claude-trigger-router/config.yaml` 调整为：
47
+
48
+ ```yaml
49
+ Models:
50
+ - id: sonnet
51
+ api: "https://openrouter.ai/api/v1/chat/completions"
52
+ key: "sk-xxx"
53
+ interface: "openai"
54
+ model: "anthropic/claude-sonnet-4"
55
+ thinking: "auto"
56
+
57
+ Router:
58
+ default: "sonnet"
59
+ ```
60
+
61
+ ### 4. 启动服务
62
+
63
+ ```bash
64
+ ctr start
65
+ ```
66
+
67
+ 确认配置可用后，可改为后台运行：
68
+
69
+ ```bash
70
+ ctr start --daemon
71
+ ```
72
+
73
+ ### 5. 启动 Claude Code
74
+
75
+ ```bash
76
+ ctr code
77
+ ```
78
+
79
+ `ctr code` 会检查目标端口上是否真的是 Claude Trigger Router，然后再注入 `ANTHROPIC_BASE_URL` 并拉起 Claude Code。
80
+
81
+ ## 新配置心智
82
+
83
+ 推荐始终从 `Models` 出发。每个模型接入项描述的是“这个模型怎么连”，而不是“内部 provider 怎么拼”。
84
+
85
+ 每个模型的最少必填字段是：
86
+
87
+ | 字段 | 是否必填 | 说明 |
88
+ |------|----------|------|
89
+ | `id` | 必填 | 模型唯一标识，供 Router / TriggerRouter / SmartRouter / Governance 引用 |
90
+ | `api` | 必填 | 上游接口地址 |
91
+ | `key` | 必填 | 对应 API Key |
92
+ | `interface` | 必填 | 接口类型，当前支持 `openai` / `anthropic` |
93
+ | `model` | 必填 | 目标模型名 |
94
+ | `thinking` | 可选 | 思考强度，推荐 `off / auto / on / low / medium / high` |
95
+
96
+ 额外可选项：
97
+
98
+ - `metadata.vendor_hint`
99
+ - `metadata.supports_reasoning`
100
+ - `metadata.supports_tools`
101
+ - `metadata.supports_images`
102
+
103
+ 兼容性说明：
104
+
105
+ - 当前实现仍兼容旧字段 `api_base_url` / `api_key` / `protocol`
106
+ - 保存和对外展示优先使用新字段 `api` / `key` / `interface`
107
+ - `thinking` 既支持简写字符串，也支持 `{ mode, effort, budget_tokens }` 对象
108
+
109
+ ## 接口类型怎么选
110
+
111
+ `interface` 只表示目标上游期望的消息协议类型，不等于“厂商名”。
112
+
113
+ 常见映射如下：
114
+
115
+ | 场景 | `api` 示例 | `interface` |
116
+ |------|------------|-------------|
117
+ | OpenAI 官方 | `https://api.openai.com/v1/chat/completions` | `openai` |
118
+ | Anthropic 官方 | `https://api.anthropic.com/v1/messages` | `anthropic` |
119
+ | OpenRouter | `https://openrouter.ai/api/v1/chat/completions` | `openai` |
120
+ | DeepSeek | `https://api.deepseek.com/chat/completions` | `openai` |
121
+ | SiliconFlow / 本地兼容服务 | 对应兼容地址 | `openai` |
122
+
123
+ 路由层会按 `interface` 把统一消息转换成目标上游请求体。
124
+
125
+ 当前统一转换已覆盖：
126
+
127
+ - 文本消息
128
+ - 图片输入
129
+ - tool call / tool result
130
+ - `thinking`
131
+
132
+ 如果目标模型声明不支持某项能力，路由会做显式降级，并给出 warning。
133
+
134
+ ## 常见路由配置
135
+
136
+ ### 单模型
137
+
138
+ ```yaml
139
+ Models:
140
+ - id: sonnet
141
+ api: "https://openrouter.ai/api/v1/chat/completions"
142
+ key: "sk-xxx"
143
+ interface: "openai"
144
+ model: "anthropic/claude-sonnet-4"
145
+
146
+ Router:
147
+ default: "sonnet"
148
+ ```
149
+
150
+ ### 规则路由
151
+
152
+ ```yaml
153
+ Models:
154
+ - id: sonnet
155
+ api: "https://openrouter.ai/api/v1/chat/completions"
156
+ key: "sk-xxx"
157
+ interface: "openai"
158
+ model: "anthropic/claude-sonnet-4"
159
+
160
+ - id: opus
161
+ api: "https://openrouter.ai/api/v1/chat/completions"
162
+ key: "sk-xxx"
163
+ interface: "openai"
164
+ model: "anthropic/claude-opus-4"
165
+
166
+ Router:
167
+ default: "sonnet"
168
+
169
+ TriggerRouter:
170
+ enabled: true
171
+ analysis_scope: "last_message"
172
+ rules:
173
+ - name: "architecture"
174
+ priority: 90
175
+ enabled: true
176
+ patterns:
177
+ - type: exact
178
+ keywords: ["架构设计", "system design"]
179
+ model: "opus"
180
+ ```
181
+
182
+ ### 规则 + 智能路由
183
+
184
+ ```yaml
185
+ Models:
186
+ - id: sonnet
187
+ api: "https://openrouter.ai/api/v1/chat/completions"
188
+ key: "sk-xxx"
189
+ interface: "openai"
190
+ model: "anthropic/claude-sonnet-4"
191
+
192
+ - id: reasoner
193
+ api: "https://api.deepseek.com/chat/completions"
194
+ key: "sk-xxx"
195
+ interface: "openai"
196
+ model: "deepseek-reasoner"
197
+ thinking: "high"
198
+
199
+ Router:
200
+ default: "sonnet"
201
+ think: "reasoner"
202
+
203
+ SmartRouter:
204
+ enabled: true
205
+ router_model: "sonnet"
206
+ candidates:
207
+ - model: "sonnet"
208
+ description: "通用编程与调试"
209
+ - model: "reasoner"
210
+ description: "复杂推理与严谨分析"
211
+ ```
212
+
213
+ 完整示例见 `config/trigger.example.yaml`。
214
+
215
+ ## warning 与 capability hint
216
+
217
+ 如果你已经知道某个模型不支持完整能力，可以在配置里显式声明：
218
+
219
+ ```yaml
220
+ Models:
221
+ - id: restricted
222
+ api: "https://api.example.com/v1/chat/completions"
223
+ key: "sk-xxx"
224
+ interface: "openai"
225
+ model: "vendor/text-only"
226
+ thinking: "high"
227
+ metadata:
228
+ supports_reasoning: false
229
+ supports_tools: false
230
+ supports_images: false
231
+ ```
232
+
233
+ 当前行为：
234
+
235
+ - `supports_reasoning: false` 时，请求里的 `thinking` 会被忽略
236
+ - `supports_tools: false` 时，工具定义和 tool call/result 会退化为文本
237
+ - `supports_images: false` 时，图片块会退化为文本说明
238
+
239
+ 这些信息会出现在：
240
+
241
+ - `ctr setup` 的配置提示
242
+ - `POST /api/config` 返回的 `warnings`
243
+ - `GET /api/models/compiled`
244
+ - `/ui` 的 Draft Config Preview 和 Capability Warnings
245
+
246
+ ## `/ui` 可以做什么
247
+
248
+ 访问 `http://127.0.0.1:3456/ui` 后，可以直接：
249
+
250
+ - 编辑 `Models` 草稿
251
+ - 预览 compiled model map
252
+ - 查看 `errors / warnings / capabilityWarnings`
253
+ - 保存当前草稿配置
254
+ - 对部分 warning 执行快捷修正
255
+
256
+ `/ui` 的新增模型卡片和 Provider template 现在也共用同一份 preset 目录，不同模板会带出各自的默认模型、示例项和 placeholder。
257
+
258
+ 适合用来做配置校准，但主线配置入口仍然建议优先用 `ctr setup` 或直接编辑配置文件。
259
+
260
+ ## 旧配置迁移
261
+
262
+ 如果你还在使用旧的 `Providers + provider,model` 配置：
263
+
264
+ - 当前版本仍然兼容旧格式
265
+ - `ctr setup` 会优先尝试迁移旧 `ccr` / `claude-code-router` 配置
266
+ - 路由字段推荐逐步改成直接引用 `Models[].id`
267
+
268
+ 迁移后的核心变化是：
269
+
270
+ - `provider,model` -> `modelId`
271
+ - `api_base_url` -> `api`
272
+ - `api_key` -> `key`
273
+ - `protocol` -> `interface`
274
+
275
+ 详见 `docs/models-migration-guide.md`。
276
+
277
+ ## 常用命令
278
+
279
+ ```bash
280
+ ctr setup
281
+ ctr init
282
+ ctr version
283
+ ctr upgrade
284
+ ctr start
285
+ ctr start --daemon
286
+ ctr stop
287
+ ctr restart --daemon
288
+ ctr status
289
+ ctr code
290
+ ```
291
+
292
+ ## 推荐阅读
293
+
294
+ - 配置模板与分工建议：`docs/configuration-guide.md`
295
+ - 旧配置迁移：`docs/models-migration-guide.md`
296
+ - 完整示例：`config/trigger.example.yaml`