@peterwangze/claude-trigger-router 1.1.2 → 1.3.0

package/docs/configuration-guide.md

@@ -16,7 +16,7 @@ ctr setup
 如果你不确定自己属于哪种部署角色，先看 `docs/configuration-roles.md`。当前三条路径是：
 
 - 本地使用者：配置 `Models + Router.default`，运行 `ctr start / ctr status / ctr code`。
-- 服务维护者：用 `ctr deploy init --target server` 生成 server 配置，并用 admin/bootstrap key 管理服务。
+- 服务维护者：用 `ctr deploy init --target server` 生成 server 配置；服务所有者用 admin/bootstrap key 管理配置和 auth，日常值守可使用 managed `operator` key 执行重启和治理维护动作。
 - 远程使用者：拿到服务地址和 managed `client + read-only` key，再配置 `Runtime.remote_service` 或直接设置 Claude Code 的 `ANTHROPIC_BASE_URL`。
 
 ## 1. 推荐配置心智
@@ -96,7 +96,7 @@ Router:
 ctr start --daemon
 ```
 
-如果配置了非本机 `HOST` 但没有配置 `APIKEY` 或 active managed key，运行时会强制回退到 `127.0.0.1`。远程客户端访问该服务时，`Runtime.remote_service.auth_token` 应填写服务端生成的 managed `client + read-only` key；bootstrap `APIKEY` 只建议维护者使用。公网部署建议放在 HTTPS 反向代理后面。启用 `APIKEY` 或 managed key 后 `/ui` 也会受认证保护；远程浏览器访问 UI 时建议使用本地隧道、内网访问，或由反向代理处理认证。
+如果配置了非本机 `HOST` 但没有配置 `APIKEY` 或 active managed key，运行时会强制回退到 `127.0.0.1`。远程客户端访问该服务时，`Runtime.remote_service.auth_token` 应填写服务端生成的 managed `client + read-only` key；bootstrap `APIKEY` 只建议服务所有者使用。日常维护可以发放 managed `operator` key，用于重启、治理快照、定时快照、异常阈值和归档删除，但不能读写配置或管理 auth。公网部署建议放在 HTTPS 反向代理后面。启用 `APIKEY` 或 managed key 后 `/ui` 也会受认证保护；远程浏览器访问 UI 时建议使用本地隧道、内网访问，或由反向代理处理认证。
 
 远程客户端配置是可选路径，不是默认路径。最小写法：
 
@@ -111,7 +111,7 @@ Runtime:
 Router: {}
 ```
 
-这个配置允许本机没有 `Models`，用于连接远程服务并查看远程状态摘要。当前已落地的是远程服务连接配置、状态查询和注册摘要，不要把它理解成已经有自动远端请求转发、集群节点调度或托管控制面。
+这个配置允许本机没有 `Models`，用于连接远程服务、查看远程状态摘要，并让本地 `ctr` 代理把 `/v1/messages` 与 `/v1/chat/completions` 转发到远程服务。当前仍不要把它理解成已经有集群节点调度或托管控制面。
 
 相关状态接口：
 
@@ -213,6 +213,18 @@ SmartRouter:
       description: "复杂推理"
 ```
 
+默认情况下，`SmartRouter` 会启用语义增强和 sticky 稳定性修正，但不会自动启用 `sticky.alignment` 上下文摘要注入。Claude Code 会在每次请求里携带已有会话上下文；只有在你明确需要跨模型切换交接摘要，并接受额外一次 summarizer 调用带来的首包等待时，才建议显式开启：
+
+```yaml
+SmartRouter:
+  sticky:
+    enabled: true
+    alignment:
+      enabled: true
+      summarizer_model: "sonnet"
+      max_summary_tokens: 256
+```
+
 治理模块：
 
 ```yaml
@@ -255,7 +267,7 @@ Governance:
 - 本地使用时新建最小配置
 - 连接远程服务时写入 `Runtime.remote_service`，不要求先填写本地 provider/model
 - 部署为远程服务端时写入 `HOST: "0.0.0.0"`、bootstrap admin `APIKEY`、`Runtime.mode: "server"` 和可编辑的 `Models + Router.default` 起步模板，并且不会自动启动服务
-- 保存后按角色输出下一步：本地路径提示本地代理状态、`ctr code` 和路由模板；远程客户端路径提示 `ctr status`、远端 ready/status 和 `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY`；服务端路径提示 `ctr doctor` 与 `ctr start --daemon`
+- 保存后按角色输出下一步：本地路径提示本地代理状态、`ctr code` 和路由模板；远程客户端路径提示 `ctr status`、远端 ready/status、本地代理转发和可选直连 `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY`；服务端路径提示 `ctr doctor` 与 `ctr start --daemon`
 - 在当前配置损坏时 repair / rebuild
 
 当前对用户主流程已经补了打包态 E2E，覆盖：
@@ -287,7 +299,7 @@ Governance:
 - 远程服务状态摘要
 - Registration 模型和上游服务摘要
 
-这些信息来自现有 `/api/service-info` 和 `/api/remote-status`，不会引入新的平行运行时。
+这些信息来自现有 `/api/service-info` 和 `/api/remote-status`，不会引入新的平行运行时。启用 `Runtime.remote_service` 时，`/api/remote-status` 还会只读同步远端 `/api/registration` 的脱敏摘要，用于显示远端注册模型数和 upstream 服务数；它不会把远端注册写回本地配置。
 
 维护者工作台还会展示治理 Health 摘要。它来自 `/api/governance/health`，同样也包含在 `/api/governance/metrics` 的 `health` 字段里：
 
@@ -306,8 +318,9 @@ Health 摘要只解释已有 trace / metrics / anomaly 数据，不会改变路
 
 - `models`：可注册模型列表，字段复用 `Models[]` 的最小模型配置语义；多个相同 `id` 会编译成同一个 logical model pool。
 - `upstream_services`：上游服务引用列表，只保存服务 ID、base URL 和可选 token。
+- `strategy`：可选，当前支持 `priority` 和 `least-latency`；默认是 `priority`，显式设置 `least-latency` 后会优先选择已有成功延迟样本中平均延迟最低的健康 endpoint，没有样本时回退 priority。
 - `metadata.pool_endpoint_id`：可选，给某个 pool endpoint 一个稳定 ID。
-- `metadata.pool_priority`：可选，数值越小优先级越高；当前 pool 策略固定为 `priority`。
+- `metadata.pool_priority`：可选，数值越小优先级越高；在 `priority` 策略下直接决定 active endpoint，在 `least-latency` 没有延迟样本或延迟相同时作为稳定回退顺序。
 - `metadata.pool_enabled`：可选，设为 `false` 时该 endpoint 会保留在 pool 中但不会成为 active endpoint。
 - `metadata.upstream_service_id`：可选，将 endpoint 关联到 `upstream_services[].id`，用于维护者观测和后续调度。
 
@@ -316,6 +329,7 @@ Health 摘要只解释已有 trace / metrics / anomaly 数据，不会改变路
 ```yaml
 Registration:
   enabled: true
+  strategy: "least-latency"
   upstream_services:
     - id: "edge-router"
       base_url: "https://edge.example.com"
@@ -340,7 +354,7 @@ Registration:
         pool_priority: 20
 ```
 
-编译结果可以通过 `GET /api/models/compiled`、`POST /api/models/compiled/preview` 或 `/ui` 的 Compiled Models 区查看。当前阶段 pool 会把 priority active endpoint 编译成真实内部 provider；如果没有同名顶层 `Models[]` 覆盖，`Router.default: sonnet` 这类 logical model id 会解析到 active pool endpoint，并在治理 trace 中记录 `model_pool:<modelId>:<endpointId>`。运行时失败重试、health-aware routing、熔断和延迟窗口仍在后续 P2-4 中推进。
+编译结果可以通过 `GET /api/models/compiled`、`POST /api/models/compiled/preview` 或 `/ui` 的 Compiled Models 区查看。当前阶段 pool 会把 active endpoint 编译成真实内部 provider；如果没有同名顶层 `Models[]` 覆盖，`Router.default: sonnet` 这类 logical model id 会解析到 active pool endpoint，并在治理 trace 中记录 `model_pool:<modelId>:<endpointId>`。当当前 pool endpoint 返回非流式 upstream error 时，运行时会按当前策略选择下一个 enabled endpoint 做一次本地重试，并记录 `model_pool_fallback:<modelId>:<endpointId>`；失败 endpoint 会进入短冷却，连续失败达到阈值后会进入更长的 `open` 熔断状态，后续 logical model 解析和 fallback candidate 会优先跳过冷却或熔断中的 endpoint。成功响应会写入延迟窗口，compiled model pool、`/api/models/pool-health` 和 `/ui` 可看到 endpoint 的平均延迟；当 `Registration.strategy: "least-latency"` 时，这个延迟窗口会参与 active endpoint 和 fallback candidate 选择。启用远程客户端配置时，本地 `/api/remote-status` 会拉取远端 `/api/registration` 的只读脱敏摘要，帮助使用者确认远端服务端注册了多少模型和 upstream 服务，但不会自动同步或覆盖本地 `Registration`。
 
 当前明确不支持 `nodes`、`node_id`、`cluster` 这类集群/节点编排字段。
 
@@ -359,6 +373,15 @@ Models:
       supports_reasoning: false
       supports_tools: false
       supports_images: false
+
+  - id: long_context
+    api: "https://api.example.com/v1/messages"
+    key: "sk-xxx"
+    interface: "anthropic"
+    model: "vendor/long-context"
+    metadata:
+      context_window_tokens: 200000
+      safe_input_tokens: 180000
 ```
 
 当前行为：
@@ -366,8 +389,10 @@ Models:
 - `supports_reasoning: false`：忽略 `thinking`
 - `supports_tools: false`：工具能力退化为文本
 - `supports_images: false`：图片输入退化为文本说明
+- `context_window_tokens`：声明模型总上下文窗口；运行时按 `input + max_tokens + thinking budget` 判断是否能安全承载
+- `safe_input_tokens`：声明输入安全上限；已选模型放不下时会优先切到 `Router.longContext`
 
-如果你不确定，不建议一开始就配太多 capability hint，先让模型跑通主路径。
+多模型上下文大小差异明显时，建议同时配置小窗口模型和长上下文模型的上下文 metadata，并设置 `Router.longContext`。如果所有候选模型都放不下，运行时会在发往上游前返回明确的 context window 错误，避免让小模型隐性截断或质量劣化。如果你不确定，不建议一开始就配太多 capability hint，先让模型跑通主路径。
 
 ## 11. 建议的配置演进顺序
 

package/docs/release-notes-v1.2.0.md

@@ -0,0 +1,43 @@
+# v1.2.0 Release Notes
+
+`v1.2.0` 定位为“智能路由评测与治理增强版”。这个版本把多模型组合从“能配置、能路由”推进到“能用固定任务复现、能按维度解释质量差异、能在治理面看到收益和风险证据”。
+
+## 本次发布主线
+
+- `ctr eval --tasks`：导出固定任务、prompt、期望输出、rubric、质量维度和 result template，方便维护者建立稳定的多模型 A/B 输入。
+- `ctr eval --input results.json`：对已有多模型输出做 deterministic rubric 评分，输出 pass rate、quality、speed、latency、best run、维度均分和失败 findings。
+- `ctr eval --run --models "sonnet;haiku"`：通过 CTR `/v1/messages` 自动执行固定任务集，支持 `--base-url`、`--api-key`、`--timeout-ms`、`--concurrency`、`--max-tokens` 和 JSON 输出。
+- `ctr eval --run --models "sonnet;haiku" --judge-model sonnet`：自动执行后继续调用一个 LLM 裁判模型，回填 `judgeScore`、`judgeFindings` 和 `calibrationNotes`；`ctr eval --input results.json --judge-model sonnet` 也可对已有结果补裁判分。
+- 严格质量维度评分：固定任务与自定义任务都可以用 `qualityDimensions` 解释语义覆盖、完整性、交付格式、安全卫生等差异；任一必需维度低于阈值会让该结果失败。
+- 人工/裁判校准入口：`ctr eval` 输入可以附带 `humanScore`、`judgeScore`、`calibrationNotes` 和 `judgeFindings`，也可以用 `--judge-model` 自动生成裁判分；报告会输出 calibration summary 和高分歧样本，裁判失败会以 `judge_error` 进入 findings 但不会误计入 calibration score。
+- 治理收益观测增强：routing outcome、task comparison、quality evidence、context window guard、switch/alignment/cascade 等指标可通过 metrics、health、CSV 和 UI 进入维护者调优路径。
+- UI benchmark summary：维护者工作台会把 task comparison、quality evidence 和 `ctr eval --run` 下一步动作合并成 benchmark 摘要。
+- 发布链路继续使用 `release:verify` / `release:stage` / GitHub trusted publishing，并要求 tag 与 `package.json.version` 一致。
+
+## 发布边界
+
+本版本不把 CTR 宣称为完整云端平台或完整自动裁判系统。`--judge-model` 已提供可重复的裁判执行入口，但它仍应和人工复核一起作为校准信号使用。以下能力已经进入实施计划，但不作为 `v1.2.0` 的发布承诺：
+
+- 人工校准 UI 表单
+- 更完整的 benchmark 历史看板
+- 公网 server/cloud 一键部署默认推荐
+- 托管场景密钥轮换操作手册
+- 服务发现、节点/集群编排
+- 模型池主动健康探测、成本/速率元数据和更多调度策略
+
+对用户的建议口径是：`v1.2.0` 已经适合用来验证多模型组合是否带来质量/速度收益；如果要把服务暴露给多人或公网，应继续按 README 的安全边界使用 managed key、quota、audit 和 HTTPS/内网保护，不要把 cloud/server 形态理解为已经具备完整托管控制面。
+
+## 发布前必跑
+
+```bash
+npm run release:verify
+npm run release:stage
+```
+
+正式发布前确认：
+
+- `package.json` 与 `package-lock.json` 版本均为 `1.2.0`
+- `ctr version` 输出 `Version: 1.2.0`
+- `v1.2.0` tag 与包版本一致
+- npm trusted publisher 指向 `peterwangze/claude-trigger-router` 的 `publish.yml`
+- GitHub publish workflow 使用 Node 24 / npm 11.5.1+

package/docs/release-notes-v1.3.0.md

@@ -0,0 +1,39 @@
+# v1.3.0 Release Notes
+
+`v1.3.0` 定位为“基础路由常用体验版”。这个版本把 CTR 的最高频用户路径从“已经能配置多模型”推进到“新用户能配置、能诊断、能在 UI 看懂、也有 packaged smoke 防回退”。
+
+## 本次发布主线
+
+- 基础路由五槽位说明：README 围绕 `Router.default`、`Router.think`、`Router.longContext`、`Router.background`、`Router.webSearch` 补齐触发条件、推荐模型类型和常见误区。
+- 可复制基础路由模板：新增 `config/trigger.routing.yaml`，用于快速建立 default / thinking / long context / background / web search 的分流配置。
+- `ctr doctor` 路由槽位体检：检查默认模型是否存在、各槽位是否能解析到 `Models[].id`、thinking 能力是否匹配，以及上下文窗口元数据是否缺失。
+- `/ui` 使用者工作台路由解释：展示当前五槽位引用、上游 provider/model、能力提示和潜在 warning，帮助用户确认当前配置是否按预期生效。
+- Context window guide：在 `/ui` 中展示 default 与 longContext 容量、最大上下文候选、缺失元数据计数，并支持把推荐模型设为 `Router.longContext`。
+- packaged basic routing smoke：打包后 acceptance 覆盖 fresh setup、`ctr status`、`ctr code` 环境、五槽位解析，以及真实 `/v1/messages` 请求触发 longContext fallback。
+
+## 发布边界
+
+本版本不把 CTR 宣称为完整 SmartRouter 产品化版本，也不承诺完整云端托管平台。以下事项已经进入后续计划，但不作为 `v1.3.0` 的发布承诺：
+
+- SmartRouter 规则模板、候选模型配置向导、路由决策解释和慢路由/错路由调优建议。
+- benchmark 历史看板和人工校准 UI 表单。
+- 公网 server/cloud 一键部署默认推荐、托管级密钥轮换手册和集群编排。
+- 模型池主动健康探测、成本/速率元数据和更多调度策略。
+
+对用户的建议口径是：`v1.3.0` 已经适合把本地 Claude Code 的基础分流路径作为日常主路径使用；如果要启用 SmartRouter 候选模型或远程服务端，应继续按照 README 的边界说明使用，并等待后续版本把模板、解释和运维入口进一步收口。
+
+## 发布前必跑
+
+```bash
+npm run release:verify
+npm run release:stage
+```
+
+正式发布前确认：
+
+- `package.json` 与 `package-lock.json` 版本均为 `1.3.0`
+- `ctr version` 输出 `Version: 1.3.0`
+- `v1.3.0` tag 与包版本一致
+- npm registry 中不存在 `@peterwangze/claude-trigger-router@1.3.0`
+- npm trusted publisher 指向 `peterwangze/claude-trigger-router` 的 `publish.yml`
+- GitHub publish workflow 使用 Node 24 / npm 11.5.1+

package/docs/releasing.md

@@ -23,6 +23,8 @@
 推荐主流程：
 
 1. 更新版本号
+   - `v1.3.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
+   - 本次 `v1.3.0` 的发布边界以 `docs/release-notes-v1.3.0.md` 为准：主打基础路由常用体验，不宣称完整 SmartRouter 产品化版本或完整云端平台。
 2. 本地先执行发布包验证：
 
 ```bash

package/docs/remote-client-guide.md

@@ -46,23 +46,22 @@ ctr status
 ctr ui
 ```
 
-`doctor` checks the configured remote service and reports whether it is reachable and ready. `status` shows the local role and remote-service connection hint. `ui` shows remote health through `/api/remote-status`.
+`doctor` checks the configured remote service and reports whether it is reachable and ready. `status` shows the local role and remote-service connection hint. `ui` shows remote health through `/api/remote-status`, including the remote server's redacted registration summary when `/api/registration` is reachable.
 
-## Use with Claude Code
-
-When the maintainer gives you the direct server URL, Claude Code can point at it:
+## Use with Claude Code through local ctr
 
 ```bash
-export ANTHROPIC_BASE_URL="https://router.example.com"
-export ANTHROPIC_API_KEY="$CTR_REMOTE_AUTH_TOKEN"
-claude
+ctr setup
+ctr doctor
+ctr code
 ```
 
-If you are using the local `ctr` client profile, keep following the local workflow while remote status support evolves:
+With `Runtime.remote_service.enabled`, the local `ctr` service acts as a thin client proxy for model calls. Claude Code still talks to local `ctr`, while `ctr` forwards `/v1/messages` and `/v1/chat/completions` to the configured remote service with `Runtime.remote_service.auth_token`.
+
+You can still point Claude Code directly at the remote server when you do not want a local proxy:
 
 ```bash
-ctr setup
-ctr doctor
+export ANTHROPIC_BASE_URL="https://router.example.com"
+export ANTHROPIC_API_KEY="$CTR_REMOTE_AUTH_TOKEN"
+claude
 ```
-
-The current remote-service profile focuses on connection config, readiness checks and registration summaries. It does not yet claim full automatic remote request forwarding for every local command.

package/docs/server-maintainer-guide.md

@@ -39,7 +39,7 @@ ctr status
 
 ## 3. Issue client keys
 
-Keep the bootstrap `APIKEY` for maintainers. Use it only to open `/ui`, save config, restart, and manage auth.
+Keep the bootstrap `APIKEY` for service owners. Use it only to open `/ui`, save config, and manage auth.
 
 Create a managed key for remote users:
 
@@ -53,7 +53,7 @@ Recommended remote-user scopes:
 ["client", "read-only"]
 ```
 
-`client` allows model calls. `read-only` allows ready/status checks such as `/api/health`, `/api/service-info`, compiled model summaries and governance GET endpoints. Generated secrets are returned once.
+`client` allows model calls. `read-only` allows ready/status checks such as `/api/health`, `/api/service-info`, compiled model summaries and governance GET endpoints. `operator` is for day-to-day maintenance writes such as restart, governance snapshots, schedules, anomaly thresholds and archive deletion; it cannot read or save config and cannot manage auth keys. Generated secrets are returned once.
 
 ## 4. Expose safely
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterwangze/claude-trigger-router",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Intelligent trigger-based router for Claude Code with automatic task type detection and model routing",
   "bin": {
     "ctr": "dist/cli.js"