@peterwangze/claude-trigger-router 1.13.0 → 1.14.0

package/docs/configuration-guide.md

@@ -27,6 +27,8 @@ ctr setup
 
 默认部署模式是 `Runtime.mode: local`，也就是本机运行本地代理服务。只有当你明确要连接已经存在的远程 Trigger Router 服务时，才需要配置 `Runtime.remote_service`。
 
+新配置统一只写 `id/api/key/interface/model/thinking/metadata`。旧 `Providers` 结构和 `api_base_url/api_key/protocol` 字段只作为历史配置兼容读取；setup、doctor、UI 保存和配置写回都应回到这套推荐字段。
+
 最小可用示例：
 
 ```yaml
@@ -405,6 +407,8 @@ Models:
 
 多模型上下文大小差异明显时，建议同时配置小窗口模型和长上下文模型的上下文 metadata，并设置 `Router.longContext`。如果所有候选模型都放不下，运行时会在发往上游前返回明确的 context window 错误，避免让小模型隐性截断或质量劣化。如果你不确定，不建议一开始就配太多 capability hint，先让模型跑通主路径。
 
+capability warning 在 CLI、doctor、setup、保存 API 和 `/ui` 中共用同一套语义：`thinking_ignored` 是 warning，需要移除 `thinking` 或确认模型真实支持 reasoning；`tools_text_fallback` / `images_text_fallback` / `context_window_hint_missing` / `safe_input_hint_missing` 是 info，表示可接受的降级或缺少容量提示，但会给出同一条修复 action。
+
 ## 11. 建议的配置演进顺序
 
 最稳的顺序是：
@@ -417,6 +421,8 @@ Models:
 
 基础路由排查时先记住当前判断顺序：显式 `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 "你的请求"` 先预演，不会调用上游模型。
 
+要逐个验证槽位，可以在 route preview 中加参数：`--route-thinking` 验证 `Router.think`，`--route-web-search` 验证 `Router.webSearch`，`--route-tokens 120000` 验证 `Router.longContext`，`--route-model claude-3-5-haiku` 验证 `Router.background`。基础路由可从 `config/trigger.routing.yaml` 复制，SmartRouter 起步建议先用 `config/trigger.smart-router.yaml`，再按需升级到 `config/trigger.smart-router.advanced.yaml`。
+
 这样排查问题最简单，也最符合当前文档和测试覆盖的主路径。
 
 ## 12. 参考文件

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

@@ -0,0 +1,51 @@
+# Release notes v1.14.0
+
+`v1.14.0` 定位为“配置产品化最终收口版”。这个版本不扩展新的路由策略，而是把用户每天会接触的配置入口收敛到同一套字段、同一套槽位解释、同一套 capability warning action 和同一套保存/预览 contract。
+
+## 本次主线
+
+1. `Models` 字段心智统一。
+   - 新配置统一推荐 `Models[].id/api/key/interface/model/thinking/metadata`。
+   - `api_base_url/api_key/protocol` 继续兼容读取，但 doctor 修复、UI 保存和配置写回会回到推荐字段。
+   - README、配置指南、setup 问答、doctor 和 `/ui` 字段说明已统一口径。
+
+2. 路由槽位配置产品化。
+   - setup 完成提示给出 `config/trigger.routing.yaml`、SmartRouter 起步/高级模板和逐槽位 route preview 参数。
+   - doctor 槽位体检输出基础路由顺序和验证命令。
+   - route preview 固定展示判断顺序：显式上游模型 -> `longContext` -> `background` -> `think` -> `webSearch` -> `default`。
+
+3. capability warning action 一致。
+   - `thinking_ignored` 保持 warning，并给出移除 `thinking` 或确认 reasoning 能力的 action。
+   - `tools_text_fallback`、`images_text_fallback`、`context_window_hint_missing`、`safe_input_hint_missing` 保持 info，并在 CLI、doctor、setup、保存 API 和 `/ui` 中复用同一条 action。
+   - context metadata 提示只在配置了 `Router.longContext`、确实需要容量比较和 fallback 时出现，避免打扰最小可用配置。
+
+4. 配置保存与预览一致性看护。
+   - `POST /api/config` 成功和失败都返回 `capabilityWarnings` 与统一 `issueReport`。
+   - 保存成功返回 canonical `normalizedConfig`，`/ui` 会刷新草稿并保留保存响应中的 warning/action。
+   - 保存写回继续输出推荐字段，不把旧别名重新写进 `Models[]`。
+
+## 发布边界
+
+- 本版本不改变基础路由和 SmartRouter 的运行时选择顺序。
+- 本版本不新增默认多模型并发执行。
+- 本版本不替代 v1.12.0/v1.13.0 的流式稳定性和核心路由用户体感门禁；这些继续作为回归底线。
+
+## 验证
+
+本版本收口前至少需要通过：
+
+```bash
+npx vitest --run src/doctor/index.test.ts src/setup/index.test.ts src/setup/setup.test.ts src/server.test.ts src/ui/workbench.dom.test.ts src/router/route-preview.test.ts src/deploy-assets.test.ts src/utils/validation-contract.test.ts
+npm run release:verify
+```
+
+本轮新增和复核的 targeted 看护：
+
+- `src/doctor/index.test.ts`
+- `src/setup/index.test.ts`
+- `src/setup/setup.test.ts`
+- `src/server.test.ts`
+- `src/ui/workbench.dom.test.ts`
+- `src/router/route-preview.test.ts`
+- `src/deploy-assets.test.ts`
+- `src/utils/validation-contract.test.ts`

package/docs/releasing.md

@@ -7,7 +7,7 @@
 - `Release Check`：在 PR、`master` push 和手动触发时执行发布前检查
 - `Publish Package`：在版本 tag、GitHub Release 或手动触发时执行正式发布
 
-本次 `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 不回退。
+本次 `v1.14.0` minor release 的优先级是配置产品化最终收口。发布检查需要优先保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及 `Models[].id/api/key/interface/model/thinking/metadata` 字段心智、doctor 修复写回、路由槽位诊断、capability warning action、UI 保存/预览 warning contract、配置写回 canonical 字段、route preview 可读解释、`/v1/messages` 流式即时透传、上游中途断流的可读 SSE error、远程中转客户端断开取消上游和结构化 API error 返回不回退。
 
 ## 一次性准备
 
@@ -26,20 +26,20 @@
 
 1. 更新版本号
    - `vX.Y.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
-   - 本次 `v1.13.0` 的发布边界以 `docs/release-notes-v1.13.0.md` 为准：主打路由预演、基础路由触发解释、SmartRouter 起步模板收口、协作口径校准和核心路由用户体感专项门禁，不新增默认多模型并发执行。
+   - 本次 `v1.14.0` 的发布边界以 `docs/release-notes-v1.14.0.md` 为准：主打 Models 字段心智统一、路由槽位配置产品化、capability warning action 一致和配置保存/预览 contract 收口。
 2. 本地先执行发布包验证：
 
 ```bash
 npm run release:verify
 ```
 
-v1.13.0 期间建议在正式 `release:verify` 前额外跑一次核心路由用户体感专项：
+v1.14.0 期间建议在正式 `release:verify` 前额外跑一次配置产品化专项：
 
 ```bash
-npm run test:route-ux
+npx vitest --run src/doctor/index.test.ts src/setup/index.test.ts src/setup/setup.test.ts src/server.test.ts src/ui/workbench.dom.test.ts src/router/route-preview.test.ts src/deploy-assets.test.ts src/utils/validation-contract.test.ts
 ```
 
-这条专项把 route preview、doctor 可读输出、基础路由触发解释、SmartRouter 规则/候选选模、首包即时输出、上游中途断流可读 SSE error、远程中转取消上游和结构化 API error 串成同一个发布前门禁。它关注用户能直接感知的“选了谁、为什么、是否变慢、断流时是否可读、远程中转是否能停住”，不是只检查内部函数返回。
+这条专项把 doctor 修复写回、setup 字段提示、server 保存/预览、UI 草稿保存、route preview、文档资产和 validation issue contract 串成同一个发布前门禁。它关注用户能直接感知的“该填哪些字段、哪个槽位生效、warning 怎么修、保存后看到的配置是否一致”，不是只检查内部函数返回。
 
 v1.12.0 期间建议在正式 `release:verify` 前额外跑一次流式稳定专项：
 

package/package.json

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