@peterwangze/claude-trigger-router 1.2.0 → 1.4.0

package/README.md

@@ -11,11 +11,21 @@ Claude Trigger Router 是给 Claude Code 用的本地路由代理。
 - 想在 Claude Code 外层增加配置校验、健康检查、治理观测和 UI 工作台
 - 想从 `claude-code-router` 迁移到更清晰的 `Models + Router` 配置心智
 
-## v1.2.0 发布定位
+## v1.4.0 发布定位
 
-`v1.2.0` 是智能路由评测与治理增强版。它重点闭环多模型组合的可验证收益：用 `ctr eval --tasks` 固定任务契约，用 `ctr eval --run --models "sonnet;haiku"` 真实调用 CTR 跑多模型 A/B，再用 deterministic rubric 和质量维度解释不同模型在质量、速度、失败风险上的差异。
+`v1.4.0` 是 SmartRouter 常用体验版。它把 CTR 的智能路由从“有能力但需要理解内部机制”推进到“能复制模板、能配置候选、能看懂为什么选模、能发现切换割裂，并能按配置路径调优”。
 
-这个版本不把 CTR 宣称为完整云端平台或完整自动裁判系统。LLM 裁判、人工校准、UI benchmark 摘要、托管级一键部署、集群编排和更复杂模型池策略仍是后续演进事项。完整发布边界见 [docs/release-notes-v1.2.0.md](docs/release-notes-v1.2.0.md)。
+这个版本的目标是让用户能把规则和候选模型稳定用于高频任务：`config/trigger.smart-router.yaml` 提供可复制起步模板，`/ui` 展示 SmartRouter 规则、候选、route decision 和 switch continuity summary，health routing tuning 会把慢路由、错路由、上下文窗口和切换割裂转成 `configSuggestions`。它不把 benchmark 历史看板、完整 server/cloud 托管平台或更复杂模型池策略纳入发布承诺。完整发布边界见 [docs/release-notes-v1.4.0.md](docs/release-notes-v1.4.0.md)。
+
+## 版本路线
+
+从用户使用频率看，版本演进会优先回到最常用的基础路由和 SmartRouter 体验：
+
+- `v1.3.0`：基础路由常用体验，已收口 `Router.default` / `think` / `longContext` / `background` / `webSearch` 五槽位、doctor 诊断、UI 路由解释和 packaged smoke。
+- `v1.5.0`：多模型收益运营化，继续补 benchmark 历史看板、人工校准表单和评测/真实 trace 的统一解释。
+- `v1.6.0`：服务化与模型池安全体验，继续补服务端安全默认值、密钥轮换手册、主动 pool health、成本/速率元数据和更多调度策略。
+
+完整版本计划见 [docs/superpowers/plans/2026-05-07-core-routing-version-plan.md](docs/superpowers/plans/2026-05-07-core-routing-version-plan.md)。
 
 ## 功能概览
 
@@ -25,8 +35,8 @@ Claude Trigger Router 是给 Claude Code 用的本地路由代理。
 - **基础路由**：用 `Router.default`、`Router.think`、`Router.longContext` 等槽位指定不同任务的默认模型。
 - **SmartRouter**：先用显式规则命中高确定性任务，也可以在规则未命中时让路由模型从候选模型中自动选择。
 - **Governance 观测**：记录 trace、metrics、异常摘要和健康状态，帮助你理解路由选择和运行风险。
-- **路由评测**：`ctr eval --tasks` 查看固定任务契约，`ctr eval --input results.json` 离线评分，`ctr eval --run --models "sonnet;haiku"` 真实调用 CTR 做多模型 A/B。
-- **doctor 诊断**：检查配置、服务可启动性、鉴权安全状态、模型兼容策略和可选模型探测。
+- **路由评测**：`ctr eval --tasks` 查看固定任务契约，`ctr eval --input results.json` 离线评分，`ctr eval --run --models "sonnet;haiku"` 真实调用 CTR 做多模型 A/B；追加 `--judge-model` 后可调用一个 LLM 裁判模型给结果打分。
+- **doctor 诊断**：检查配置、服务可启动性、基础路由槽位、上下文窗口提示、鉴权安全状态、模型兼容策略和可选模型探测。
 - **UI 工作台**：`ctr ui` 打开本地页面，查看服务上下文、远程状态、鉴权安全状态、配置草稿、compiled models、capability warnings、治理 trace、metrics 和 Health 摘要。
 - **远程状态基础**：可配置 `Runtime.remote_service`，通过 `/api/remote-status` 查看远程服务健康、compiled model 摘要和治理告警摘要。默认用户不需要配置远程模式。
 
@@ -244,6 +254,27 @@ Router:
 
 推荐所有路由字段都引用 `Models[].id`，比如上面的 `sonnet`、`reasoner`。
 
+## 基础路由五个槽位
+
+日常使用优先理解这五个槽位。最小可用配置只需要 `default`；当你开始接入多个模型时，再逐步补 `think`、`longContext`、`background` 和 `webSearch`。
+
+| 槽位 | 何时触发 | 推荐放什么模型 |
+|---|---|---|
+| `Router.default` | 普通请求、规则未命中、其他槽位未配置时 | 稳定通用模型 |
+| `Router.think` | 请求包含 `thinking` 时 | 推理能力更强的模型 |
+| `Router.longContext` | 输入超过 `longContextThreshold`，或当前模型 `safe_input_tokens` 不够时 | 上下文窗口更大的模型 |
+| `Router.background` | Claude Code 轻量后台模型请求时 | 便宜、快、可本地化的模型 |
+| `Router.webSearch` | 请求包含 `web_search` 工具时 | 支持搜索工具或搜索结果处理稳定的模型 |
+
+可复制模板见 `config/trigger.routing.yaml`。它把五个槽位都写完整，并给模型补了 `metadata.context_window_tokens` / `metadata.safe_input_tokens`，方便 `ctr doctor` 和运行时提前识别大上下文请求。
+
+常见误区：
+
+- 不要把 `Router.longContext` 指向比默认模型窗口更小的模型。
+- 不确定某个模型是否支持 reasoning 时，先不要放进 `Router.think`；运行 `ctr doctor` 会提示能力不匹配。
+- `background` 可以先不配，未配置时会回到 `default`。
+- `webSearch` 不是“联网开关”，它只是 web search 请求出现时的模型槽位。
+
 ## 显式规则路由
 
 适合能用关键词稳定识别的任务，例如架构设计、代码审查、长文档评审。
@@ -267,6 +298,8 @@ SmartRouter:
 
 规则命中时优先使用规则指定模型；没命中时回到 `Router.default`。
 
+可复制的 SmartRouter 常用模板见 `config/trigger.smart-router.yaml`。它已经把 `coding`、`review`、`architecture`、`long_context` 和 `fast_reply` 五类高频任务写成规则，并保留 `router_model + candidates` 作为规则未命中时的智能兜底起点。
+
 ## 智能模型选择
 
 如果任务边界比较模糊，可以让 SmartRouter 用一个路由模型从候选模型中选择：
@@ -369,6 +402,7 @@ Health 摘要下方的 action 可以直接把 trace 表切到对应排查视图
 ctr eval --tasks
 ctr eval --input results.json
 ctr eval --run --models "sonnet;haiku"
+ctr eval --run --models "sonnet;haiku" --judge-model sonnet
 ```
 
 输入文件可以是数组，也可以是 `{ "results": [...] }`：
@@ -379,12 +413,27 @@ ctr eval --run --models "sonnet;haiku"
     "taskId": "coding_fix",
     "model": "provider,model",
     "output": "模型输出文本",
-    "latencyMs": 1200
+    "latencyMs": 1200,
+    "humanScore": 0.9,
+    "judgeScore": 0.85,
+    "calibrationNotes": "人工或外部 LLM 裁判的可选说明",
+    "judgeFindings": ["可选裁判发现"]
   }
 ]
 ```
 
-`ctr eval --tasks` 会列出固定任务的 prompt、expected output、关键词、字符数、延迟预算、质量维度和 result template；加 `--json` 可导出给后续自动执行器或外部脚本。当前内置任务覆盖 quick reply、coding、architecture、long context、server auth/deployment 和 model pool incident。评测会输出按模型和任务聚合的 pass rate、quality、speed、latency、best run、维度均分和失败 findings；它是离线 deterministic rubric，不等同于完整人工或 LLM 裁判评测。
+`ctr eval --tasks` 会列出固定任务的 prompt、expected output、关键词、字符数、延迟预算、质量维度和 result template；加 `--json` 可导出给后续自动执行器或外部脚本。当前内置任务覆盖 quick reply、coding、architecture、long context、server auth/deployment 和 model pool incident。评测会输出按模型和任务聚合的 pass rate、quality、speed、latency、best run、维度均分和失败 findings；默认是离线 deterministic rubric，不等同于人工复核。
+
+如果你已经有人工复核或外部 LLM 裁判结果，可以在输入里补 `humanScore` / `judgeScore`，范围是 `0..1`。报告会生成 calibration summary，并标出 deterministic rubric 与人工/裁判结果差异较大的任务，帮助维护者判断某个模型组合是否真的带来质量提升。
+
+也可以让 CTR 自动调用一个裁判模型：
+
+```bash
+ctr eval --input results.json --judge-model sonnet --base-url http://127.0.0.1:5678 --api-key <client-or-bootstrap-key>
+ctr eval --run --models "sonnet;haiku" --judge-model sonnet --base-url http://127.0.0.1:5678 --api-key <client-or-bootstrap-key>
+```
+
+裁判模型会通过同一个 CTR `/v1/messages` 入口收到固定 JSON rubric 提示，并返回 `judgeScore`、`judgeFindings` 和 `calibrationNotes`。如果裁判响应不可解析、超时或返回 HTTP 错误，报告会记录 `judge_error`，但不会把失败裁判误算进 calibration score。
 
 如果本机或远端 CTR 已启动，也可以显式自动跑固定任务集：
 
@@ -392,7 +441,7 @@ ctr eval --run --models "sonnet;haiku"
 ctr eval --run --models "sonnet;haiku" --base-url http://127.0.0.1:5678 --api-key <client-or-bootstrap-key>
 ```
 
-`--run` 会对每个模型逐个调用 `POST /v1/messages`，默认 `--concurrency 2`、`--timeout-ms 30000`、`--max-tokens 768`。多个模型用分号 `;` 分隔，因为 legacy 模型引用本身可能包含逗号。该模式会真实调用模型服务并消耗上游额度。
+`--run` 会对每个模型逐个调用 `POST /v1/messages`，默认 `--concurrency 2`、`--timeout-ms 30000`、`--max-tokens 768`。多个模型用分号 `;` 分隔，因为 legacy 模型引用本身可能包含逗号。追加 `--judge-max-tokens 256` 可调整裁判输出长度。该模式会真实调用模型服务并消耗上游额度；启用 `--judge-model` 时会额外消耗裁判模型额度。
 
 如果服务没有启动，`ctr ui` 会提示先运行：
 
@@ -424,6 +473,8 @@ ctr doctor
 - 当前监听地址；server/cloud 会提示远程客户端应设置的 `ANTHROPIC_BASE_URL`
 - 当前鉴权状态；如果 server/cloud 或公网监听没有配置 `APIKEY` / managed key，会提示安全风险
 - 如果启用了 `Runtime.remote_service`，会单独检查远程服务可达和 ready 状态
+- 基础路由槽位：`Router.default` / `think` / `longContext` / `background` / `webSearch` 是否能解析到模型
+- 上下文窗口提示：槽位模型是否缺少 `metadata.context_window_tokens` / `metadata.safe_input_tokens`，以及 `Router.longContext` 是否真的比默认模型更适合大上下文
 - 模型兼容策略和请求编译方式
 - capability hint 可能触发的运行时降级
 - 在你确认后，对模型发送最小探测请求
@@ -481,6 +532,7 @@ GET /api/auth/audit
 | `ctr eval --tasks` | 查看固定评测任务、prompt 和 rubric |
 | `ctr eval --input results.json` | 离线固定任务集评测 |
 | `ctr eval --run --models "sonnet;haiku"` | 自动调用 CTR 后评测固定任务集 |
+| `ctr eval --run --models "sonnet;haiku" --judge-model sonnet` | 自动执行并追加 LLM 裁判校准 |
 | `ctr ui` | 打开本地 UI 工作台 |
 | `ctr version` | 查看版本 |
 | `ctr upgrade` | 升级 |
@@ -508,6 +560,8 @@ setup 会自动探测旧配置，并优先提供迁移选项。迁移后的配
 ## 更多示例和文档
 
 - 最小示例：`config/trigger.example.yaml`
+- 基础路由五槽位示例：`config/trigger.routing.yaml`
+- SmartRouter 常用规则示例：`config/trigger.smart-router.yaml`
 - 高级示例：`config/trigger.advanced.yaml`
 - 配置细节：`docs/configuration-guide.md`
 - Models 迁移：`docs/models-migration-guide.md`

package/config/trigger.routing.yaml

@@ -0,0 +1,67 @@
+# Claude Trigger Router 基础路由配置示例
+# 用于理解 Router.default / think / longContext / background / webSearch 五个常用槽位。
+# 复制到 ~/.claude-trigger-router/config.yaml 后，先替换 API Key 和上游模型名。
+
+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: reasoner
+    api: "https://api.deepseek.com/chat/completions"
+    key: "sk-xxx"
+    interface: "openai"
+    model: "deepseek-reasoner"
+    thinking: "high"
+    metadata:
+      context_window_tokens: 64000
+      safe_input_tokens: 56000
+
+  - 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: 32768
+      safe_input_tokens: 24000
+
+Router:
+  # 默认槽位：普通对话、代码生成、规则未命中时使用。
+  default: "sonnet"
+
+  # 思考槽位：请求包含 thinking 时优先使用。
+  think: "reasoner"
+
+  # 长上下文槽位：输入超过阈值，或当前模型 safe_input_tokens 不够时使用。
+  longContext: "long_context"
+  longContextThreshold: 60000
+
+  # 后台槽位：Claude Code 轻量后台模型请求时使用。
+  background: "fast_background"
+
+  # 联网搜索槽位：请求包含 web_search 工具时使用。
+  webSearch: "sonnet"

package/config/trigger.smart-router.yaml

@@ -0,0 +1,213 @@
+# Claude Trigger Router SmartRouter rule template
+# 复制到 ~/.claude-trigger-router/config.yaml 后，先替换 API Key、模型名和本地模型地址。
+# 这个模板面向 v1.4.0 的高频智能路由场景：
+# coding / review / architecture / long context / fast reply。
+
+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