@peterwangze/claude-trigger-router 1.10.0 → 1.12.0

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

@@ -0,0 +1,36 @@
+# Release notes v1.11.0
+
+`v1.11.0` 定位为“基础路由流式稳定性与 socket 错误修复版”。这个版本不扩展新的路由能力，专门回看 `v1.5.0` 之后的入口、runtime pipeline、流式治理、远程客户端和 SmartRouter 协作改动，优先修复用户反馈的两个 P0/P1 可用性问题。
+
+## 修复重点
+
+1. 基础路由流式输出恢复即时透传。
+   - 问题：`v1.8.0` 引入流式 response governance 后，`governStreamingResponse` 会先完整收集上游 SSE，再一次性输出。长回复或普通 Claude Code 会话中，客户端长时间收不到增量 token，容易表现为输出中断。
+   - 修复：默认 `stream_guard` 未开启时改为边转发原始 chunk、边旁路收集文本和 usage 用于 trace / output guardrail；只有显式开启 `Governance.cascade.stream_guard` 时才保留 buffer-and-retry。
+
+2. API error 不再被转换成 socket-level hook error。
+   - 问题：运行时 `onSend` 看到 `{ error: ... }` payload 时会把它作为 Fastify hook error 传出，客户端可能看到 `The socket connection was closed unexpectedly`，而不是稳定的结构化 API 错误。
+   - 修复：保留上游结构化错误 payload 返回；model pool fallback 尝试失败后也返回 payload，不再把普通 API error 当成传输层异常。
+
+3. SSE parser 修复跨 chunk 状态丢失。
+   - 问题：`SSEParserTransform` 的当前事件对象只存在于单次 parse 调用里；当上游把 `event:`、`data:`、空行拆成多个网络 chunk 时，事件状态可能丢失。
+   - 修复：parser 现在跨 chunk 保留当前事件，并能 flush 没有尾随空行的最终事件，降低 agent/tool stream 和 stream guard 场景的偶发中断风险。
+
+## 看护
+
+- `src/governance/stream-response-governance.test.ts` 新增“上游未关闭前就能读到首个 chunk”的回归测试。
+- `src/utils/SSEParser.transform.test.ts` 新增 SSE 跨 chunk 和无尾随空行 flush 测试。
+- `src/index-startup.test.ts` 新增上游 API error payload 不触发 socket-level hook error 的测试。
+
+## 发布边界
+
+本版本是稳定性修复版，不新增 SmartRouter 协作模式、不改变 v1.10.0 的 routing advisor / budget / collaboration contract，也不改变远程客户端推荐配置。发布前需要重点验证：
+
+```bash
+npm run build
+npm test -- --run
+npm test -- --run --coverage
+npm run test:e2e:cli:entry
+```
+
+若要做正式发布，仍以 `npm run release:verify` 作为最终门禁。

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/releasing.md

@@ -7,7 +7,7 @@
 - `Release Check`：在 PR、`master` push 和手动触发时执行发布前检查
 - `Publish Package`：在版本 tag、GitHub Release 或手动触发时执行正式发布
 
-本次 `v1.10.0` minor release 的优先级是智能路由自适应与多模型协同增强。发布检查需要同时保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及 outcome-driven routing feedback、模型能力画像、confidence/latency budget、多模型协作模式、SmartRouter trace metadata 和 `/ui` 协作证据入口。
+本次 `v1.12.0` minor release 的优先级是流式传输韧性与远程中转稳定性修复。发布检查需要优先保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及 `/v1/messages` 流式即时透传、上游中途断流的可读 SSE error、远程中转客户端断开取消上游、SSE 多字节跨 chunk 解析、结构化 API error 返回和 v1.10.0 SmartRouter 协作能力不回退。
 
 ## 一次性准备
 
@@ -26,16 +26,17 @@
 
 1. 更新版本号
    - `vX.Y.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
-   - 本次 `v1.10.0` 的发布边界以 `docs/release-notes-v1.10.0.md` 为准：主打 SmartRouter 自适应反馈和最小多模型协作 contract，不宣称完整自动化多 agent 编排、全量任务拆解执行器、跨请求在线学习系统或完整云端模型调度平台。
+   - 本次 `v1.12.0` 的发布边界以 `docs/release-notes-v1.12.0.md` 为准：主打流式传输韧性、远程中转取消上游、上游中途断流可读错误和 SSE parser 可靠性，不新增 SmartRouter 协作模式或远程客户端配置心智。
 2. 本地先执行发布包验证：
 
 ```bash
 npm run release:verify
 ```
 
-v1.10.0 期间建议在正式 `release:verify` 前额外跑一次智能路由协作专项：
+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
 npm test -- --run --coverage
 npm run test:ui
 npm run test:e2e:cli:entry
@@ -80,7 +81,7 @@ npm run test:e2e:acceptance
 - 目标端口被非本服务占用时的安全提示与“无额外文件修改”边界
 - 残留 / 失效 PID 文件的安全清理
 - `release:stage` 生成的 `.release-stage\ctr-release-home.cmd` wrapper 是否真的指向隔离 `.release-home`
-- v1.10.0 智能路由自适应与多模型协同发布承诺的 routing advisor、SmartRouter budget/collaboration guard、server routing-advisor API、trace metadata、`/ui` route decision evidence 和文档资产检查
+- 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.10.0",
+  "version": "1.12.0",
   "description": "Intelligent trigger-based router for Claude Code with automatic task type detection and model routing",
   "bin": {
     "ctr": "dist/cli.js"