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

@peterwangze/claude-trigger-router 1.12.0 → 1.13.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 (9) hide show

package/README.md +11 -7
package/config/trigger.smart-router.advanced.yaml +214 -0
package/config/trigger.smart-router.yaml +21 -138
package/dist/cli.js +358 -0
package/dist/cli.js.map +4 -4
package/docs/configuration-guide.md +7 -2
package/docs/release-notes-v1.13.0.md +49 -0
package/docs/releasing.md +10 -2
package/package.json +2 -1

package/README.md CHANGED Viewed

@@ -110,11 +110,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 +141,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 +149,11 @@ SmartRouter:
 ```bash
 ctr doctor
+ctr doctor --route-preview --route-text "请做架构设计"
 ctr ui
 ```
-`ctr doctor` 用来检查配置、服务启动、模型引用、上下文窗口、鉴权状态和可选模型探测。模型探测会消耗少量额度，所以会先征求确认。
+`ctr doctor` 用来检查配置、服务启动、模型引用、上下文窗口、鉴权状态和可选模型探测。`--route-preview` 可以在不调用上游模型、不消耗额度的情况下预演当前请求会命中哪个槽位或 SmartRouter 路径；模型探测会消耗少量额度，所以会先征求确认。
 `ctr ui` 默认打开：
@@ -218,14 +222,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.13.0.md](docs/release-notes-v1.13.0.md)
 - 发布验证：[docs/releasing.md](docs/releasing.md)
-## v1.12.0 发布定位
+## v1.13.0 发布定位
-`v1.12.0` 是流式传输韧性与远程中转稳定性修复版。它在 `v1.11.0` 首轮止血基础上继续修复用户复现的 socket 断连和中转卡顿：上游流式中途断开时返回可读 SSE error event，远程中转会在客户端断开时主动取消上游请求，并修复 SSE parser 在多字节字符跨 chunk 时的解析风险。
+`v1.13.0` 是核心路由用户体感与看护补强版。它把重点放回基础路由和 SmartRouter 的日常体验：用户可以用 `ctr doctor --route-preview --route-text "..."` 在不调用上游模型的情况下预演请求会走哪个模型、为什么、是否可能因为 SmartRouter 候选选择增加首包等待。
-这个版本不新增 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)。
+这个版本还收口了 SmartRouter 两模型起步模板、基础路由触发顺序说明和协作模式口径：默认仍是单模型 `route_only`，不默认并发调用多个模型。完整发布边界见 [docs/release-notes-v1.13.0.md](docs/release-notes-v1.13.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