@peterwangze/claude-trigger-router 1.11.0 → 1.13.0

package/docs/configuration-guide.md

@@ -213,7 +213,9 @@ SmartRouter:
       description: "复杂推理"
 ```
 
-如果想直接从常用规则起步，可以复制 `config/trigger.smart-router.yaml`。模板已经覆盖 `coding`、`review`、`architecture`、`long_context`、`fast_reply` 五类高频任务，并把每条规则引用的模型都写在 `Models[]` 中，便于 `ctr doctor` 和 `/ui` 做一致校验。
+如果想直接从常用规则起步，可以复制 `config/trigger.smart-router.yaml`。默认模板只需要默认模型和复杂任务模型，先覆盖 `architecture` / `review` 这类高确定性任务；更多候选、`coding` / `long_context` / `fast_reply`、semantic/sticky/governance 和本地 fast model 放在 `config/trigger.smart-router.advanced.yaml`，避免新用户第一步就被高级能力压住。
+
+`SmartRouter.collaboration.mode` 当前是策略 contract 和 trace/UI 解释信号。默认 `route_only` 仍只选择一个模型；`verify_only` 会提示后续治理更加关注低置信结果；`compare_then_arbiter` 和 `cascade_on_evidence` 不代表当前默认会并发调用多个模型，只有后续 runtime 明确支持或你显式接入额外治理链路时才会产生额外模型调用。
 
 默认情况下，`SmartRouter` 会启用语义增强和 sticky 稳定性修正，但不会自动启用 `sticky.alignment` 上下文摘要注入。Claude Code 会在每次请求里携带已有会话上下文；只有在你明确需要跨模型切换交接摘要，并接受额外一次 summarizer 调用带来的首包等待时，才建议显式开启：
 
@@ -413,6 +415,8 @@ Models:
 4. 再加 `SmartRouter.router_model / candidates`
 5. 最后再加 `Governance` 的 cascade / shadow / observability
 
+基础路由排查时先记住当前判断顺序：显式 `provider,model` 上游引用会直接使用；随后才是 `Router.longContext` 阈值、`Router.background`、`Router.think`、`Router.webSearch` 和 `Router.default`。这意味着长上下文可能先于 thinking / webSearch 命中；`Router.background` 目前依赖 Claude Code 请求模型以 `claude-3-5-haiku` 开头；最终定模后还会按模型 metadata 执行 context window guard，必要时切到 `Router.longContext`。可用 `ctr doctor --route-preview --route-text "你的请求"` 先预演，不会调用上游模型。
+
 这样排查问题最简单，也最符合当前文档和测试覆盖的主路径。
 
 ## 12. 参考文件
@@ -420,7 +424,8 @@ Models:
 - 主入口：`README.md`
 - 最小示例：`config/trigger.example.yaml`
 - 基础路由五槽位示例：`config/trigger.routing.yaml`
-- SmartRouter 常用规则示例：`config/trigger.smart-router.yaml`
+- SmartRouter 两模型起步示例：`config/trigger.smart-router.yaml`
+- SmartRouter 多候选高级示例：`config/trigger.smart-router.advanced.yaml`
 - 完整高级示例：`config/trigger.advanced.yaml`
 - 旧配置迁移：`docs/models-migration-guide.md`
 - 发布验证：`docs/releasing.md`

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

@@ -0,0 +1,38 @@
+# Release notes v1.12.0
+
+`v1.12.0` 定位为“流式传输韧性与远程中转稳定性修复版”。用户在 `v1.11.0` 上仍复现 `The socket connection was closed unexpectedly`、同模型经中转响应更慢和输出突然卡住，说明首轮修复只覆盖了默认全量缓冲和结构化 error hook 两个问题，还缺少上游中途断流、远程中转取消和跨 chunk 解码的防线。
+
+## 本次主线
+
+1. 上游流式中途断开不再硬断 socket。
+   - 问题：`v1.11.0` 默认透传流式 chunk 后，如果上游 body 在中途抛错，错误仍会冒泡到 ReadableStream controller，客户端可能继续看到 socket 异常。
+   - 修复：默认透传路径捕获上游 stream read error，保留已输出 chunk，并追加 `event: error` / `type: upstream_stream_error` 的可读 SSE 事件后关闭流。
+
+2. 远程中转在客户端断开时主动取消上游。
+   - 问题：`Runtime.remote_service` thin proxy 直接 `reply.send(response.body)`，没有把客户端连接关闭绑定到远端 fetch abort；客户端已经断开时，上游请求可能继续挂住并放大卡顿和资源占用。
+   - 修复：远程转发使用 `AbortController`，将 `reply.raw close` 绑定到上游 abort；远端 SSE 响应也进入同一套流式治理包装。
+
+3. SSE parser 修复多字节字符跨 chunk 解码。
+   - 问题：parser 每个 chunk 新建 `TextDecoder`，中文等多字节字符被网络拆开时可能产生替换字符或 JSON 解析失败。
+   - 修复：parser 持续复用同一个 `TextDecoder` 并在 flush 时收尾。
+
+## 发布边界
+
+- 本版本不新增 SmartRouter 协作模式，不改变远程客户端配置心智。
+- `v1.11.0` 仍保留为首轮止血版本；`v1.12.0` 是针对用户在 `v1.11.0` 上再次复现的二次修复版。
+- 远程中转的非 SSE 响应仍保持原始 body 透传，不注入 SSE error event。
+
+## 验证
+
+本版本收口前至少需要通过：
+
+```bash
+npm run release:verify
+```
+
+本轮新增和复核的 targeted 看护：
+
+- `src/governance/stream-response-governance.test.ts`
+- `src/utils/SSEParser.transform.test.ts`
+- `src/index-startup.test.ts`
+- `src/deploy-assets.test.ts`

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

@@ -0,0 +1,49 @@
+# Release notes v1.13.0
+
+`v1.13.0` 定位为“核心路由用户体感与看护补强版”。这个版本不继续扩展低频能力，而是回到普通用户每天最容易感知的基础路由与 SmartRouter：请求会走哪个模型、为什么这么走、是否会增加首包等待、错误是否可读，以及发布前能不能稳定拦住慢、卡、错路由回归。
+
+## 本次主线
+
+1. 路由预演入口。
+   - 新增 `ctr doctor --route-preview`，支持 `--route-text`、`--route-model`、`--route-thinking`、`--route-web-search` 和 `--route-tokens`。
+   - 预演不调用上游模型，也不调用 SmartRouter LLM，因此不会消耗额度；它会解释基础路由槽位、SmartRouter rule/semantic 预测、候选 LLM 选模的 pending 状态和额外等待风险。
+
+2. 基础路由触发解释收口。
+   - README、配置指南和 setup next steps 已统一基础路由顺序：显式上游模型 -> `longContext` -> `background` -> `think` -> `webSearch` -> `default`。
+   - 文档明确显式 `provider,model` 会绕过基础槽位，`background` 当前只识别 Claude Code 的 `claude-3-5-haiku*` 后台请求，context window guard 仍可能 fallback 到 `Router.longContext`。
+
+3. SmartRouter 起步模板降心智成本。
+   - `config/trigger.smart-router.yaml` 改为两模型起步模板，只保留 `sonnet`、`reasoner`、`architecture` 和 `review`。
+   - 原高级组合迁移到 `config/trigger.smart-router.advanced.yaml`，承接 semantic/sticky/governance、本地 fast model 和多候选调优。
+
+4. SmartRouter 协作口径校准。
+   - README 和配置指南明确当前默认仍是单模型 `route_only`。
+   - `verify_only`、`compare_then_arbiter`、`cascade_on_evidence` 作为策略 contract、trace/UI 信号和后续演进边界存在，不默认并发调用额外模型。
+
+5. 核心路由用户体感专项门禁。
+   - 新增 `npm run test:route-ux`。
+   - 专项覆盖 route preview、doctor 可读输出、SmartRouter 规则/候选 packaged slice、首包即时输出、上游中途断流可读 SSE error、远程中转取消上游和结构化 API error。
+
+## 发布边界
+
+- 本版本不新增默认多模型并发执行，不改变 `v1.10.0` 的协作 contract 能力边界。
+- 本版本不替代 `v1.12.0` 的传输韧性修复；上游中途断流、远程中转取消和 SSE parser 可靠性继续作为回归底线。
+- `ctr doctor --route-preview` 是确定性预演工具，不等价于真实 SmartRouter LLM 最终选择；当配置了 `router_model + candidates` 时，它会明确提示运行时仍需等待 SmartRouter 选择。
+
+## 验证
+
+本版本收口前至少需要通过：
+
+```bash
+npm run test:route-ux
+npm run release:verify
+```
+
+本轮新增和复核的 targeted 看护：
+
+- `src/router/route-preview.test.ts`
+- `src/doctor/index.test.ts`
+- `src/governance/stream-response-governance.test.ts`
+- `src/index-startup.test.ts`
+- `src/e2e/cli-e2e.test.ts` SmartRouter packaged slices
+- `src/deploy-assets.test.ts`

package/docs/releasing.md

@@ -7,7 +7,7 @@
 - `Release Check`：在 PR、`master` push 和手动触发时执行发布前检查
 - `Publish Package`：在版本 tag、GitHub Release 或手动触发时执行正式发布
 
-本次 `v1.11.0` minor release 的优先级是基础路由流式稳定性与 socket 错误修复。发布检查需要优先保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及 `/v1/messages` 流式即时透传、SSE 跨 chunk 解析、结构化 API error 返回和 v1.10.0 SmartRouter 协作能力不回退。
+本次 `v1.13.0` minor release 的优先级是核心路由用户体感与看护补强。发布检查需要优先保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及 route preview 可读解释、基础路由触发顺序、SmartRouter 起步模板、协作模式真实口径、`/v1/messages` 流式即时透传、上游中途断流的可读 SSE error、远程中转客户端断开取消上游、结构化 API error 返回和 v1.10.0 SmartRouter 协作 contract 不回退。
 
 ## 一次性准备
 
@@ -26,14 +26,22 @@
 
 1. 更新版本号
    - `vX.Y.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
-   - 本次 `v1.11.0` 的发布边界以 `docs/release-notes-v1.11.0.md` 为准：主打基础路由流式稳定性、socket 错误修复和 SSE parser 可靠性，不新增 SmartRouter 协作模式或远程客户端配置心智。
+   - 本次 `v1.13.0` 的发布边界以 `docs/release-notes-v1.13.0.md` 为准：主打路由预演、基础路由触发解释、SmartRouter 起步模板收口、协作口径校准和核心路由用户体感专项门禁，不新增默认多模型并发执行。
 2. 本地先执行发布包验证：
 
 ```bash
 npm run release:verify
 ```
 
-v1.11.0 期间建议在正式 `release:verify` 前额外跑一次流式稳定专项：
+v1.13.0 期间建议在正式 `release:verify` 前额外跑一次核心路由用户体感专项：
+
+```bash
+npm run test:route-ux
+```
+
+这条专项把 route preview、doctor 可读输出、基础路由触发解释、SmartRouter 规则/候选选模、首包即时输出、上游中途断流可读 SSE error、远程中转取消上游和结构化 API error 串成同一个发布前门禁。它关注用户能直接感知的“选了谁、为什么、是否变慢、断流时是否可读、远程中转是否能停住”，不是只检查内部函数返回。
+
+v1.12.0 期间建议在正式 `release:verify` 前额外跑一次流式稳定专项：
 
 ```bash
 npm test -- --run src/governance/stream-response-governance.test.ts src/utils/SSEParser.transform.test.ts src/index-startup.test.ts
@@ -81,7 +89,7 @@ npm run test:e2e:acceptance
 - 目标端口被非本服务占用时的安全提示与“无额外文件修改”边界
 - 残留 / 失效 PID 文件的安全清理
 - `release:stage` 生成的 `.release-stage\ctr-release-home.cmd` wrapper 是否真的指向隔离 `.release-home`
-- v1.11.0 基础路由流式稳定性发布承诺的 stream governance 即时透传、SSE parser 跨 chunk、结构化 API error 返回，以及 v1.10.0 routing advisor / SmartRouter collaboration 不回退检查
+- v1.12.0 流式传输韧性发布承诺的 stream governance 即时透传、上游中途断流可读 SSE error、远程中转客户端断开取消上游、SSE parser 跨 chunk / 多字节解析、结构化 API error 返回，以及 v1.10.0 routing advisor / SmartRouter collaboration 不回退检查
 
 只有这一步通过后，才继续正式发布，避免“发布后才发现包内容、CLI 启动或 setup 主流程有问题”。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterwangze/claude-trigger-router",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Intelligent trigger-based router for Claude Code with automatic task type detection and model routing",
   "bin": {
     "ctr": "dist/cli.js"
@@ -27,6 +27,7 @@
     "dev": "tsx watch src/cli.ts",
     "start": "node dist/cli.js start",
     "test": "vitest --exclude src/e2e/**",
+    "test:route-ux": "vitest --run src/router/route-preview.test.ts src/doctor/index.test.ts src/governance/stream-response-governance.test.ts src/index-startup.test.ts src/e2e/cli-e2e.test.ts -t \"route preview|previews route decisions|router slot summary|emits streamed chunks|readable SSE error|remote forwarding|structured 502|upstream error payloads|SmartRouter rules route|SmartRouter selects\"",
     "test:ui": "vitest --run src/ui/workbench.dom.test.ts",
     "test:e2e:cli": "vitest --run src/e2e/cli-e2e.test.ts",
     "test:e2e:cli:entry": "vitest --run src/e2e/cli-e2e.test.ts -t \"init --force generates|doctor can repair|start/status/stop work|code reuses|ui prints|setup can create a fresh config|setup can create a remote-service client config|setup can create a server deployment profile\"",