npm - @peterwangze/claude-trigger-router - Versions diffs - 1.12.0 → 1.14.0 - Mend

@peterwangze/claude-trigger-router 1.12.0 → 1.14.0

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 (10) hide show

package/README.md +14 -8
package/config/trigger.smart-router.advanced.yaml +214 -0
package/config/trigger.smart-router.yaml +21 -138
package/dist/cli.js +422 -19
package/dist/cli.js.map +4 -4
package/docs/configuration-guide.md +13 -2
package/docs/release-notes-v1.13.0.md +49 -0
package/docs/release-notes-v1.14.0.md +51 -0
package/docs/releasing.md +10 -2
package/package.json +2 -1

package/README.md CHANGED Viewed

@@ -7,7 +7,7 @@ Claude Trigger Router 是给 Claude Code 用的本地模型路由代理。Claude
 ## 你会得到什么
 - 一个本地 Claude Code 代理：默认监听 `127.0.0.1:5678`。
-- 一份统一模型配置：用 `Models[]` 管供应商、接口、API key 和模型名。
+- 一份统一模型配置：用 `Models[].id/api/key/interface/model` 管模型接入。
 - 基础路由：用 `Router.default`、`think`、`longContext`、`background`、`webSearch` 覆盖高频场景。
 - SmartRouter：用规则、语义匹配、候选模型画像和 LLM 路由选择更合适的模型。
 - 治理与 UI：通过 `ctr doctor` 和 `ctr ui` 看配置、健康状态、路由原因、trace 和协作证据。
@@ -76,6 +76,8 @@ Router:
 `interface` 表示上游接口协议，不是厂商名。OpenRouter、DeepSeek 和大多数 OpenAI-compatible 服务通常用 `openai`；Anthropic 官方接口用 `anthropic`。
+新配置只推荐写 `id/api/key/interface/model/thinking/metadata`。旧字段 `api_base_url/api_key/protocol` 只作为历史配置兼容读取，不作为新配置入口。
 ## 配多个模型
 每个 `Models[]` 项都是一个可被路由引用的模型接入项。路由字段建议引用 `Models[].id`，不要把供应商和模型名散落在各处。
@@ -110,11 +112,14 @@ Router:
 | `background` | Claude Code 轻量后台请求 |
 | `webSearch` | 带 web search 工具的请求 |
+基础路由的实际判断顺序是：显式上游模型 -> `longContext` 阈值 -> `background` -> `think` -> `webSearch` -> `default`。因此超长输入会先进入长上下文槽位；`background` 当前只识别 Claude Code 发出的 `claude-3-5-haiku*` 后台模型请求；如果请求模型已经是 `provider,model` 这类上游引用，基础槽位不会再覆盖。最终定模后还会执行 context window guard，如果已选模型放不下，会优先 fallback 到 `Router.longContext`。
 可复制模板：
 - [config/trigger.example.yaml](config/trigger.example.yaml)：最小配置
 - [config/trigger.routing.yaml](config/trigger.routing.yaml)：基础路由五槽位
-- [config/trigger.smart-router.yaml](config/trigger.smart-router.yaml)：SmartRouter 常用规则
+- [config/trigger.smart-router.yaml](config/trigger.smart-router.yaml)：SmartRouter 两模型起步模板
+- [config/trigger.smart-router.advanced.yaml](config/trigger.smart-router.advanced.yaml)：SmartRouter 多候选高级模板
 - [config/trigger.advanced.yaml](config/trigger.advanced.yaml)：高级治理示例
 ## SmartRouter
@@ -138,7 +143,7 @@ SmartRouter:
 - `SmartRouter.rules` 负责能被关键词稳定识别的任务。
 - `SmartRouter.candidates` 负责规则未命中时的智能兜底。
 - `SmartRouter.routing_budget.latency_budget_ms` 和 `confidence_threshold` 用来控制速度/质量取舍。
-- `SmartRouter.collaboration.mode` 可表达 `route_only`、`verify_only`、`compare_then_arbiter`、`cascade_on_evidence` 这类协作路径。
+- `SmartRouter.collaboration.mode` 可表达 `route_only`、`verify_only`、`compare_then_arbiter`、`cascade_on_evidence` 这类策略 contract；当前默认仍是单模型 `route_only`，不会默认并发调用多个模型。
 从 `v1.10.0` 开始，SmartRouter 会把真实 trace 中的质量、失败、延迟、cascade、shadow 和人工校准证据纳入候选模型画像，并在 route decision 中展示 `routingMode`、`collaborationMode` 和 `routingEvidence`。
@@ -146,10 +151,11 @@ SmartRouter:
 ```bash
 ctr doctor
+ctr doctor --route-preview --route-text "请做架构设计"
 ctr ui
 ```
-`ctr doctor` 用来检查配置、服务启动、模型引用、上下文窗口、鉴权状态和可选模型探测。模型探测会消耗少量额度，所以会先征求确认。
+`ctr doctor` 用来检查配置、服务启动、模型引用、上下文窗口、鉴权状态和可选模型探测。`--route-preview` 可以在不调用上游模型、不消耗额度的情况下预演当前请求会命中哪个槽位或 SmartRouter 路径；模型探测会消耗少量额度，所以会先征求确认。
 `ctr ui` 默认打开：
@@ -218,14 +224,14 @@ ANTHROPIC_AUTH_TOKEN=<managed-key>
 - 配置指南：[docs/configuration-guide.md](docs/configuration-guide.md)
 - Models 迁移：[docs/models-migration-guide.md](docs/models-migration-guide.md)
 - CLI 测试矩阵：[docs/cli-test-matrix.md](docs/cli-test-matrix.md)
-- 发布说明：[docs/release-notes-v1.12.0.md](docs/release-notes-v1.12.0.md)
+- 发布说明：[docs/release-notes-v1.14.0.md](docs/release-notes-v1.14.0.md)
 - 发布验证：[docs/releasing.md](docs/releasing.md)
-## v1.12.0 发布定位
+## v1.14.0 发布定位
-`v1.12.0` 是流式传输韧性与远程中转稳定性修复版。它在 `v1.11.0` 首轮止血基础上继续修复用户复现的 socket 断连和中转卡顿：上游流式中途断开时返回可读 SSE error event，远程中转会在客户端断开时主动取消上游请求，并修复 SSE parser 在多字节字符跨 chunk 时的解析风险。
+`v1.14.0` 是配置产品化最终收口版。它把重点放在用户每天会接触的配置入口：README、配置指南、setup、doctor、`/ui`、保存 API 和 compiled preview 都统一到 `Models[].id/api/key/interface/model/thinking/metadata` 字段心智。
-这个版本不新增 SmartRouter 协作模式、不改变远程客户端配置心智；`v1.10.0` 的 routing advisor、confidence threshold、latency budget 和 collaboration contract 继续保留。完整发布边界见 [docs/release-notes-v1.12.0.md](docs/release-notes-v1.12.0.md)。
+旧字段 `api_base_url/api_key/protocol` 继续兼容读取，但 doctor 修复、UI 保存和配置写回会回到推荐字段。这个版本还让路由槽位、capability warning、保存/预览 warning contract 在 CLI 和 UI 中保持一致。完整发布边界见 [docs/release-notes-v1.14.0.md](docs/release-notes-v1.14.0.md)。
 ## License

package/config/trigger.smart-router.advanced.yaml ADDED Viewed

@@ -0,0 +1,214 @@
+# Claude Trigger Router SmartRouter advanced template
+# 复制到 ~/.claude-trigger-router/config.yaml 后，先替换 API Key、模型名和本地模型地址。
+# 这个模板面向已经跑通最小 SmartRouter 的用户，覆盖更多高频智能路由场景：
+# coding / review / architecture / long context / fast reply。
+# 如果你第一次启用 SmartRouter，请优先使用 config/trigger.smart-router.yaml。
+HOST: "127.0.0.1"
+PORT: 5678
+LOG: true
+LOG_LEVEL: "debug"
+Models:
+  - id: sonnet
+    api: "https://openrouter.ai/api/v1/chat/completions"
+    key: "sk-xxx"
+    interface: "openai"
+    model: "anthropic/claude-sonnet-4"
+    thinking: "auto"
+    metadata:
+      context_window_tokens: 200000
+      safe_input_tokens: 180000
+  - id: reviewer
+    api: "https://openrouter.ai/api/v1/chat/completions"
+    key: "sk-xxx"
+    interface: "openai"
+    model: "anthropic/claude-sonnet-4"
+    thinking: "auto"
+    metadata:
+      context_window_tokens: 200000
+      safe_input_tokens: 180000
+  - id: architect
+    api: "https://openrouter.ai/api/v1/chat/completions"
+    key: "sk-xxx"
+    interface: "openai"
+    model: "anthropic/claude-opus-4"
+    thinking: "high"
+    metadata:
+      context_window_tokens: 200000
+      safe_input_tokens: 180000
+  - id: long_context
+    api: "https://openrouter.ai/api/v1/chat/completions"
+    key: "sk-xxx"
+    interface: "openai"
+    model: "google/gemini-2.5-pro"
+    thinking: "auto"
+    metadata:
+      context_window_tokens: 1000000
+      safe_input_tokens: 900000
+  - id: fast_background
+    api: "http://localhost:11434/v1/chat/completions"
+    key: "ollama"
+    interface: "openai"
+    model: "qwen2.5-coder:latest"
+    thinking: "off"
+    metadata:
+      context_window_tokens: 32000
+      safe_input_tokens: 24000
+Router:
+  default: "sonnet"
+  think: "architect"
+  longContext: "long_context"
+  longContextThreshold: 60000
+  background: "fast_background"
+  webSearch: "sonnet"
+SmartRouter:
+  enabled: true
+  analysis_scope: "last_message"
+  rules:
+    - name: "long_context"
+      priority: 95
+      enabled: true
+      description: "长文档、长上下文、全文总结或需要大窗口承载的请求"
+      patterns:
+        - type: exact
+          keywords:
+            - "长上下文"
+            - "长文档"
+            - "全文总结"
+            - "large context"
+            - "long context"
+        - type: regex
+          pattern: "(长上下文|长文档|全文总结|long context|large context)"
+      model: "long_context"
+      semantic_profile:
+        prototype: "长文档 长上下文 全文 总结 大窗口 large context long document"
+    - name: "architecture"
+      priority: 90
+      enabled: true
+      description: "架构设计、系统设计、技术方案和模块拆分"
+      patterns:
+        - type: exact
+          keywords:
+            - "架构设计"
+            - "系统设计"
+            - "技术方案"
+            - "模块拆分"
+            - "architecture"
+            - "system design"
+        - type: regex
+          pattern: "(架构|系统设计|技术方案|模块拆分|architecture|system design)"
+      model: "architect"
+      semantic_profile:
+        prototype: "架构 系统设计 技术方案 模块边界 演进路线 architecture system design"
+    - name: "review"
+      priority: 80
+      enabled: true
+      description: "代码审查、风险检查、安全检查和回归风险评估"
+      patterns:
+        - type: exact
+          keywords:
+            - "代码审查"
+            - "code review"
+            - "review code"
+            - "检查代码"
+            - "安全风险"
+            - "回归风险"
+        - type: regex
+          pattern: "(代码|code).{0,8}(审查|review|检查|审核)"
+      model: "reviewer"
+      semantic_profile:
+        prototype: "代码审查 风险 安全 回归 regression review bug finding"
+    - name: "coding"
+      priority: 70
+      enabled: true
+      description: "实现功能、修复 bug、重构代码和补测试"
+      patterns:
+        - type: exact
+          keywords:
+            - "实现"
+            - "写代码"
+            - "修复 bug"
+            - "补测试"
+            - "implement"
+            - "refactor"
+            - "feature"
+        - type: regex
+          pattern: "(实现|编写|修复|重构|补测试|implement|refactor|feature|bug)"
+      model: "sonnet"
+      semantic_profile:
+        prototype: "实现 功能 修复 bug 重构 单元测试 编程 coding implementation"
+    - name: "fast_reply"
+      priority: 10
+      enabled: true
+      description: "简单问题、快速答复、短答案和低成本后台任务"
+      patterns:
+        - type: exact
+          keywords:
+            - "快速回答"
+            - "简单回答"
+            - "不用详细"
+            - "quick"
+            - "short answer"
+            - "simple"
+        - type: regex
+          pattern: "(快速回答|简单回答|不用详细|quick|short answer|simple)"
+      model: "fast_background"
+      semantic_profile:
+        prototype: "快速 简单 短答案 低成本 fast quick short answer simple"
+  router_model: "sonnet"
+  candidates:
+    - model: "sonnet"
+      description: "通用 coding、日常调试、多轮任务和默认 Claude Code 体验"
+    - model: "reviewer"
+      description: "代码审查、风险识别、安全检查和回归影响判断"
+    - model: "architect"
+      description: "架构设计、系统方案、复杂权衡和高质量长推理"
+    - model: "long_context"
+      description: "长文档、超长上下文、全文总结和大规格输入"
+    - model: "fast_background"
+      description: "快速短答、低成本后台任务和简单重复问题"
+  cache_ttl: 600000
+  max_tokens: 256
+  fallback: "default"
+  router_hint:
+    include_task_summary: true
+    include_top_route_candidates: true
+  sticky:
+    enabled: true
+    session_ttl_ms: 3600000
+    fingerprint_similarity_threshold: 0.82
+    break_on_explicit_route: true
+    # Claude Code 的请求本身会携带会话上下文。
+    # 只有明确需要跨模型交接摘要，并接受额外 summarizer 调用时，再开启 alignment。
+    alignment:
+      enabled: false
+      summarizer_model: "sonnet"
+      max_summary_tokens: 256
+  semantic:
+    enabled: true
+    mode: "embedding"
+    threshold: 0.2
+    prototypes:
+      coding: "实现 功能 修复 bug 重构 单元测试 编程 coding implementation"
+      review: "代码审查 风险 安全 回归 regression review bug finding"
+      architecture: "架构 系统设计 技术方案 模块边界 演进路线 architecture system design"
+      long_context: "长文档 长上下文 全文 总结 大窗口 large context long document"
+      fast_reply: "快速 简单 短答案 低成本 fast quick short answer simple"
+Governance:
+  enabled: true

package/config/trigger.smart-router.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
-# Claude Trigger Router SmartRouter rule template
-# 复制到 ~/.claude-trigger-router/config.yaml 后，先替换 API Key、模型名和本地模型地址。
-# 这个模板面向 v1.4.0 的高频智能路由场景：
-# coding / review / architecture / long context / fast reply。
+# Claude Trigger Router SmartRouter starter template
+# 复制到 ~/.claude-trigger-router/config.yaml 后，先替换 API Key 和上游模型名。
+# 这个模板只需要两个模型：默认模型 + 复杂任务模型。
+# 更多候选、semantic/sticky/governance 和本地 fast model 见 config/trigger.smart-router.advanced.yaml。
 HOST: "127.0.0.1"
 PORT: 5678
@@ -20,76 +20,26 @@ Models:
       context_window_tokens: 200000
       safe_input_tokens: 180000
-  - id: reviewer
-    api: "https://openrouter.ai/api/v1/chat/completions"
-    key: "sk-xxx"
-    interface: "openai"
-    model: "anthropic/claude-sonnet-4"
-    thinking: "auto"
-    metadata:
-      context_window_tokens: 200000
-      safe_input_tokens: 180000
-  - id: architect
-    api: "https://openrouter.ai/api/v1/chat/completions"
+  - id: reasoner
+    api: "https://api.deepseek.com/chat/completions"
     key: "sk-xxx"
     interface: "openai"
-    model: "anthropic/claude-opus-4"
+    model: "deepseek-reasoner"
     thinking: "high"
     metadata:
-      context_window_tokens: 200000
-      safe_input_tokens: 180000
-  - id: long_context
-    api: "https://openrouter.ai/api/v1/chat/completions"
-    key: "sk-xxx"
-    interface: "openai"
-    model: "google/gemini-2.5-pro"
-    thinking: "auto"
-    metadata:
-      context_window_tokens: 1000000
-      safe_input_tokens: 900000
-  - id: fast_background
-    api: "http://localhost:11434/v1/chat/completions"
-    key: "ollama"
-    interface: "openai"
-    model: "qwen2.5-coder:latest"
-    thinking: "off"
-    metadata:
-      context_window_tokens: 32000
-      safe_input_tokens: 24000
+      context_window_tokens: 64000
+      safe_input_tokens: 56000
 Router:
   default: "sonnet"
-  think: "architect"
-  longContext: "long_context"
+  think: "reasoner"
+  longContext: "sonnet"
   longContextThreshold: 60000
-  background: "fast_background"
-  webSearch: "sonnet"
 SmartRouter:
   enabled: true
   analysis_scope: "last_message"
   rules:
-    - name: "long_context"
-      priority: 95
-      enabled: true
-      description: "长文档、长上下文、全文总结或需要大窗口承载的请求"
-      patterns:
-        - type: exact
-          keywords:
-            - "长上下文"
-            - "长文档"
-            - "全文总结"
-            - "large context"
-            - "long context"
-        - type: regex
-          pattern: "(长上下文|长文档|全文总结|long context|large context)"
-      model: "long_context"
-      semantic_profile:
-        prototype: "长文档 长上下文 全文 总结 大窗口 large context long document"
     - name: "architecture"
       priority: 90
       enabled: true
@@ -100,12 +50,11 @@ SmartRouter:
             - "架构设计"
             - "系统设计"
             - "技术方案"
-            - "模块拆分"
             - "architecture"
             - "system design"
         - type: regex
-          pattern: "(架构|系统设计|技术方案|模块拆分|architecture|system design)"
-      model: "architect"
+          pattern: "(架构|系统设计|技术方案|architecture|system design)"
+      model: "reasoner"
       semantic_profile:
         prototype: "架构 系统设计 技术方案 模块边界 演进路线 architecture system design"
@@ -119,95 +68,29 @@ SmartRouter:
             - "代码审查"
             - "code review"
             - "review code"
-            - "检查代码"
-            - "安全风险"
-            - "回归风险"
+            - "风险评估"
         - type: regex
           pattern: "(代码|code).{0,8}(审查|review|检查|审核)"
-      model: "reviewer"
+      model: "reasoner"
       semantic_profile:
         prototype: "代码审查 风险 安全 回归 regression review bug finding"
-    - name: "coding"
-      priority: 70
-      enabled: true
-      description: "实现功能、修复 bug、重构代码和补测试"
-      patterns:
-        - type: exact
-          keywords:
-            - "实现"
-            - "写代码"
-            - "修复 bug"
-            - "补测试"
-            - "implement"
-            - "refactor"
-            - "feature"
-        - type: regex
-          pattern: "(实现|编写|修复|重构|补测试|implement|refactor|feature|bug)"
-      model: "sonnet"
-      semantic_profile:
-        prototype: "实现 功能 修复 bug 重构 单元测试 编程 coding implementation"
-    - name: "fast_reply"
-      priority: 10
-      enabled: true
-      description: "简单问题、快速答复、短答案和低成本后台任务"
-      patterns:
-        - type: exact
-          keywords:
-            - "快速回答"
-            - "简单回答"
-            - "不用详细"
-            - "quick"
-            - "short answer"
-            - "simple"
-        - type: regex
-          pattern: "(快速回答|简单回答|不用详细|quick|short answer|simple)"
-      model: "fast_background"
-      semantic_profile:
-        prototype: "快速 简单 短答案 低成本 fast quick short answer simple"
+  # 规则未命中时，真实请求会先调用 router_model 选择候选模型。
+  # 如果你希望首包更快，可以先删除 router_model/candidates，只保留上面的 rules。
   router_model: "sonnet"
   candidates:
     - model: "sonnet"
       description: "通用 coding、日常调试、多轮任务和默认 Claude Code 体验"
-    - model: "reviewer"
-      description: "代码审查、风险识别、安全检查和回归影响判断"
-    - model: "architect"
-      description: "架构设计、系统方案、复杂权衡和高质量长推理"
-    - model: "long_context"
-      description: "长文档、超长上下文、全文总结和大规格输入"
-    - model: "fast_background"
-      description: "快速短答、低成本后台任务和简单重复问题"
+    - model: "reasoner"
+      description: "架构设计、代码审查、复杂推理和严谨分析"
   cache_ttl: 600000
-  max_tokens: 256
+  max_tokens: 192
   fallback: "default"
   router_hint:
     include_task_summary: true
     include_top_route_candidates: true
-  sticky:
-    enabled: true
-    session_ttl_ms: 3600000
-    fingerprint_similarity_threshold: 0.82
-    break_on_explicit_route: true
-    # Claude Code 的请求本身会携带会话上下文。
-    # 只有明确需要跨模型交接摘要，并接受额外 summarizer 调用时，再开启 alignment。
-    alignment:
-      enabled: false
-      summarizer_model: "sonnet"
-      max_summary_tokens: 256
   semantic:
     enabled: true
     mode: "embedding"
-    threshold: 0.2
-    prototypes:
-      coding: "实现 功能 修复 bug 重构 单元测试 编程 coding implementation"
-      review: "代码审查 风险 安全 回归 regression review bug finding"
-      architecture: "架构 系统设计 技术方案 模块边界 演进路线 architecture system design"
-      long_context: "长文档 长上下文 全文 总结 大窗口 large context long document"
-      fast_reply: "快速 简单 短答案 低成本 fast quick short answer simple"
-Governance:
-  enabled: true
+    threshold: 0.25