@peterwangze/claude-trigger-router 1.3.0 → 1.5.0

package/docs/cli-test-matrix.md

@@ -14,6 +14,9 @@
 - `src/e2e/cli-acceptance.test.ts`
   - 关注更贴近真实人工验证的 shell / wrapper / staged 包路径
   - 重点校验 Windows 终端输出、wrapper、daemon 生命周期、release stage 验收链路
+- `src/ui/workbench.dom.test.ts`
+  - 关注 `/ui` 工作台真实 DOM 脚本执行和基础交互
+  - 重点校验配置载入、compiled preview、保存失败 validation issue 和 Health action 过滤
 
 ## 2. 当前自动覆盖范围
 
@@ -77,6 +80,8 @@
 ### UI / 服务状态
 
 - `/ui` 首屏展示服务 ready、端口、模型数、`Router.default`、`Runtime.mode`、listener、远程状态和 Registration 摘要
+- `POST /api/config` 保存前复用 validation issue contract；已有配置备份失败时必须拒绝写入，避免 UI save 静默覆盖用户配置
+- `POST /api/config` 保存 `Runtime` / `Registration` / `Auth` 等已配置分支时不能静默丢弃，尤其要保留 managed key 记录且不暴露一次性 secret
 - 维护者工作台展示 role / listener / remote client connection guide，和 `/api/service-info` 的 listener / clientConnection contract 对齐
 - 维护者工作台展示 Governance trace、metrics、Health 摘要、异常阈值、快照和归档入口
 - Compiled Models 区展示 `Registration.models` 编译出的 model pools、active endpoint、priority endpoint 列表和 upstream warning，覆盖同模型多源池化的编译期契约
@@ -84,6 +89,7 @@
 - `GET /api/governance/health` 返回维护者健康摘要、关键指标、模型切换 signals、routing outcome、异常列表和建议 action
 - Health action 可联动 trace 过滤：cascade action 对应 `cascadeTriggered=true`，shadow action 对应 `shadowChecked=true`
 - UI HTML 渲染测试覆盖 `/api/governance/health` 数据源、Health 状态占位、routing outcome 指标、分组 outcome 面板和健康摘要说明入口
+- UI DOM smoke 执行 `renderWorkbenchHtml()` 生成的内联脚本，覆盖载入当前配置、compiled models 预览、保存失败 validation issue 展示和 Health action trace 过滤，防止字符串级 HTML 断言漏掉脚本拼接或 DOM 绑定错误
 
 ### setup 主要选择路径
 
@@ -128,6 +134,7 @@
 - 主命令不会异常退出
 - 命令只修改允许的隔离文件
 - setup 与路由主流程可走通
+- 单个子命令超时时，harness 会清理子进程树并输出 stdout/stderr 摘要，便于定位卡点
 
 ### `cli-acceptance`
 
@@ -137,13 +144,38 @@
 - `release:stage` 产物本身可作为手工验收入口使用
 - staged 包路径会直接 smoke `/ui` 和 `/api/governance/health`，避免维护者工作台只在源码测试中可用
 
-## 4. 当前发布门禁
+## 4. v1.5 入口稳定专项门禁
+
+v1.5.0 期间新增或修改功能前，先确认这些入口契约不退化：
+
+- `setup`：覆盖 fresh setup、复用已有配置、legacy migration、repair、rebuild、远程客户端和服务端部署三类角色；不能误启动、误覆盖或把 next steps 指向错误角色。
+- `start/status/stop/restart`：覆盖前台、后台、alternate port、端口被非本服务占用、stale PID、服务已运行和配置错误；失败信息必须给出清晰下一步。
+- `code`：只在服务 ready 时进入 Claude Code；本地/远程代理环境变量必须正确注入；服务未运行或 Claude CLI 缺失时必须明确失败。
+- `doctor/setup/ui save`：复用同一 validation issue contract；写入前保留备份，不能静默丢弃 `Runtime` / `Registration` / `Auth` 等已配置分支。
+- `/ui`：现阶段保留 HTML / API smoke，并新增 `npm run test:ui` 的 jsdom DOM smoke；后续真实浏览器 smoke 继续覆盖基础路由解释、键鼠流程和维护者 Health 展示。
+- coverage：入口看护范围从早期 `src/trigger/**/*.ts` 扩展到 setup、config、models、protocols、governance、server、auth、doctor、cli 主链。
+
+专项验证建议加跑：
+
+```bash
+npm test -- --run --coverage
+npm run test:ui
+npm run test:e2e:cli:entry
+npm run test:e2e:cli
+npm run test:e2e:acceptance
+```
+
+这组检查不是替代 `release:verify`，而是在 v1.5.0 期间提前暴露入口主路径、UI 交互和 coverage 口径漂移。`test:ui` 是源码侧 `/ui` DOM smoke；`test:e2e:cli:entry` 是较短的入口 smoke，覆盖 init、doctor、start/status/stop、setup fresh、setup remote client、setup server deployment、code 和 ui；完整 `test:e2e:cli` 仍保留为发布门禁，当前在 Windows 本地约 3-4 分钟。
+
+## 5. 当前发布门禁
 
 发布前建议至少通过：
 
 ```bash
 npm run build
 npm test -- --run
+npm run test:ui
+npm run test:e2e:cli:entry
 npm run test:e2e:cli
 npm run test:e2e:acceptance
 npm run release:verify
@@ -155,7 +187,7 @@ npm run release:verify
 - `release:verify` 已包含 `test:e2e:acceptance`
 - `test:e2e:acceptance` 已包含 release-stage wrapper 的 `/ui` HTML 与治理健康 API smoke
 
-## 5. 仍建议保留的人工验收重点
+## 6. 仍建议保留的人工验收重点
 
 自动化已经尽量接近真实路径，但发布前仍建议人工快速确认：
 
@@ -166,7 +198,7 @@ npm run release:verify
 - 新增配置模板和 README 的指引是否和实现一致
 - server 部署入口生成的 bootstrap key 是否只用于维护者管理，远程客户端是否改用 managed `client + read-only` key
 
-## 6. 后续增补原则
+## 7. 后续增补原则
 
 后续新增用户可见命令、选项、setup 分支或发布脚本行为时，优先补到这 3 层之一：
 

package/docs/configuration-guide.md

@@ -213,6 +213,8 @@ SmartRouter:
       description: "复杂推理"
 ```
 
+如果想直接从常用规则起步，可以复制 `config/trigger.smart-router.yaml`。模板已经覆盖 `coding`、`review`、`architecture`、`long_context`、`fast_reply` 五类高频任务，并把每条规则引用的模型都写在 `Models[]` 中，便于 `ctr doctor` 和 `/ui` 做一致校验。
+
 默认情况下，`SmartRouter` 会启用语义增强和 sticky 稳定性修正，但不会自动启用 `sticky.alignment` 上下文摘要注入。Claude Code 会在每次请求里携带已有会话上下文；只有在你明确需要跨模型切换交接摘要，并接受额外一次 summarizer 调用带来的首包等待时，才建议显式开启：
 
 ```yaml
@@ -410,6 +412,8 @@ Models:
 
 - 主入口：`README.md`
 - 最小示例：`config/trigger.example.yaml`
+- 基础路由五槽位示例：`config/trigger.routing.yaml`
+- SmartRouter 常用规则示例：`config/trigger.smart-router.yaml`
 - 完整高级示例：`config/trigger.advanced.yaml`
 - 旧配置迁移：`docs/models-migration-guide.md`
 - 发布验证：`docs/releasing.md`

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

@@ -0,0 +1,40 @@
+# v1.4.0 Release Notes
+
+`v1.4.0` 定位为“SmartRouter 常用体验版”。这个版本把 CTR 的智能路由从“有能力但需要理解内部机制”推进到“能复制模板、能配置候选、能看懂为什么选模、能发现切换割裂，并能按配置路径调优”。
+
+## 本次发布主线
+
+- SmartRouter 规则模板：新增 `config/trigger.smart-router.yaml`，覆盖 coding、review、architecture、long_context、fast_reply 等高频任务。
+- SmartRouter 配置解释：`/api/models/compiled` 和草稿 preview 返回归一化 explanation，`/ui` 展示规则顺序、候选模型、router_model、semantic/sticky 开关和 fallback。
+- 候选模型向导：`/ui` Candidate guide 检查 fast / balanced / deep / long-context 候选覆盖，并支持把建议模型加入 `SmartRouter.candidates` 草稿。
+- 路由决策可解释性：governance trace 记录 route source、rule、confidence、选中模型和 fallback reason，`/ui` 展示最近请求的可读 route decision。
+- 切换体感治理：switch continuity summary 把 initial/final model、sticky、alignment、cascade 和 route source 合成为 stable / aligned / watch / critical 状态。
+- 配置路径级调优建议：health routing tuning 将 context window、switch without alignment、switch cascade risk 和 slow route group 转成 `configSuggestions`，指向 `Router.longContext`、`SmartRouter.sticky.alignment`、`SmartRouter.rules`、`SmartRouter.candidates` 等可操作建议。
+
+## 发布边界
+
+本版本聚焦本地 SmartRouter 常用体验，不把 CTR 宣称为完整 benchmark 运营平台或完整 server/cloud 托管平台。以下事项进入后续版本，但不作为 `v1.4.0` 发布承诺：
+
+- benchmark 历史看板。
+- 人工校准 UI 表单。
+- 固定任务集按核心路由场景重排。
+- `ctr eval` 与真实 trace 的统一收益解释口径。
+- 服务端安全默认策略、密钥轮换手册、主动 pool health、成本/速率元数据和更多调度策略。
+
+对用户的建议口径是：`v1.4.0` 已经适合把 SmartRouter 用作日常多模型组合入口；如果要证明长期质量/速度收益，仍应结合 `ctr eval`、真实 trace 和后续 v1.5.0 的运营化能力。
+
+## 发布前必跑
+
+```bash
+npm run release:verify
+npm run release:stage
+```
+
+正式发布前确认：
+
+- `package.json` 与 `package-lock.json` 版本均为 `1.4.0`
+- `ctr version` 输出 `Version: 1.4.0`
+- `v1.4.0` tag 与包版本一致
+- npm registry 中不存在 `@peterwangze/claude-trigger-router@1.4.0`
+- npm trusted publisher 指向 `peterwangze/claude-trigger-router` 的 `publish.yml`
+- GitHub publish workflow 使用 Node 24 / npm 11.5.1+

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

@@ -0,0 +1,39 @@
+# v1.5.0 Release Notes
+
+`v1.5.0` 定位为“入口基础功能稳定与易用性巩固版”。这个版本不继续扩展 benchmark、服务化或模型池策略，而是先把新用户和日常用户每天会碰到的入口主路径做稳。
+
+## 本次发布主线
+
+- 入口门禁稳定化：新增 `npm run test:e2e:cli:entry` 作为较短 packaged CLI smoke，覆盖 init、doctor、start/status/stop、setup fresh、setup remote client、setup server deployment、code 和 ui。
+- packaged E2E 可诊断性：E2E harness 在单命令 timeout 时会清理子进程树，并输出 cwd、stdout、stderr 摘要，避免发布前只看到超时和残留进程。
+- 配置保存安全线：setup、doctor、UI save 和 server save 继续复用 validation issue contract；配置写入前必须先备份，备份失败不继续写入。
+- 远程/服务端 setup 角色路径：packaged E2E 覆盖 remote client setup 保存 `Runtime.remote_service` 且不进入 provider/model 填写；server deployment setup 生成 `Runtime.mode: server` / bootstrap `APIKEY` 且不自动启动服务。
+- UI 基础交互看护：新增 `npm run test:ui` 与 jsdom DOM smoke，覆盖 `/ui` 载入当前配置、compiled models 预览、保存失败 validation issue 展示和 Health action trace 过滤。
+- UI 首轮工程化拆分：`workbench-document.ts` 承接 HTML 文档骨架和内联脚本抽取，UI smoke 增加脚本语法检查，防止字符串拼接错误绕过 HTML 字符串断言。
+
+## 发布边界
+
+本版本聚焦入口稳定，不把 CTR 宣称为完整 benchmark 运营平台、完整 server/cloud 托管平台或 agent 平台。以下事项进入后续版本，但不作为 `v1.5.0` 发布承诺：
+
+- benchmark 历史看板和人工校准 UI 表单。
+- `ctr eval` 与真实 trace 的长期收益运营闭环。
+- 服务端默认安全运营、密钥轮换手册、主动 pool health、成本/速率元数据和更多调度策略。
+- 更深入的 UI CSS/JS/渲染片段拆分、真实浏览器截图和键鼠流程 smoke。
+
+对用户的建议口径是：`v1.5.0` 适合把 CTR 作为日常 Claude Code 路由代理入口使用；遇到问题时优先依赖 `ctr doctor`、`ctr status`、`ctr ui` 和发布前 packaged smoke 所覆盖的主路径。
+
+## 发布前必跑
+
+```bash
+npm run release:verify
+npm run release:stage
+```
+
+正式发布前确认：
+
+- `package.json` 与 `package-lock.json` 版本均为 `1.5.0`
+- `ctr version` 输出 `Version: 1.5.0`
+- `v1.5.0` tag 与包版本一致
+- npm registry 中不存在 `@peterwangze/claude-trigger-router@1.5.0`
+- npm trusted publisher 指向 `peterwangze/claude-trigger-router` 的 `publish.yml`
+- GitHub publish workflow 使用 Node 24 / npm 11.5.1+

package/docs/releasing.md

@@ -7,6 +7,8 @@
 - `Release Check`：在 PR、`master` push 和手动触发时执行发布前检查
 - `Publish Package`：在版本 tag、GitHub Release 或手动触发时执行正式发布
 
+本次 `v1.5.0` minor release 的优先级是入口基础功能稳定与易用性巩固。继续扩展 benchmark、服务化、模型池或 agent/tool 前，发布检查需要先保护 `setup / start / status / code / doctor / ui`、配置保存/修复/迁移、打包后真实用户流和 UI 基础交互看护。
+
 ## 一次性准备
 
 1. 在 npm 包 `@peterwangze/claude-trigger-router` 的包设置中添加 trusted publisher
@@ -23,18 +25,32 @@
 推荐主流程：
 
 1. 更新版本号
-   - `v1.3.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
-   - 本次 `v1.3.0` 的发布边界以 `docs/release-notes-v1.3.0.md` 为准：主打基础路由常用体验，不宣称完整 SmartRouter 产品化版本或完整云端平台。
+   - `vX.Y.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
+   - 本次 `v1.5.0` 的发布边界以 `docs/release-notes-v1.5.0.md` 为准：主打入口基础功能稳定与易用性巩固，不宣称完整 benchmark 运营平台或完整云端平台。
 2. 本地先执行发布包验证：
 
 ```bash
 npm run release:verify
 ```
 
+v1.5.0 期间建议在正式 `release:verify` 前额外跑一次入口稳定专项：
+
+```bash
+npm test -- --run --coverage
+npm run test:ui
+npm run test:e2e:cli:entry
+npm run test:e2e:cli
+npm run test:e2e:acceptance
+```
+
+其中 coverage 口径已经从早期 `src/trigger/**/*.ts` 扩展到 setup、config、models、protocols、governance、server、auth、doctor、cli 主链；`test:ui` 是源码侧 `/ui` DOM smoke，用于保护配置载入、compiled preview、保存失败提示和 Health action 这类基础交互；`test:e2e:cli:entry` 是较短的打包后入口 smoke，用于先保护 init、doctor、start/status/stop、setup fresh、setup remote client、setup server deployment、code 和 ui；后续新增入口功能时，先补对应看护再扩展低频能力。
+
 这一步会依次执行：
 
 - `npm run build`
 - `npm test -- --run`
+- `npm run test:ui`
+- `npm run test:e2e:cli:entry`
 - `npm run test:e2e:cli`
 - `npm run test:e2e:acceptance`
 - `npm pack --dry-run`
@@ -44,7 +60,8 @@ npm run release:verify
 
 其中两层打包后验证分别承担不同职责：
 
-- `npm run test:e2e:cli`：覆盖打包后 CLI 的主要命令、选择路径与文件副作用边界
+- `npm run test:e2e:cli:entry`：覆盖打包后 CLI 的入口 smoke，优先保护 init、doctor、start/status/stop、setup fresh、setup remote client、setup server deployment、code 和 ui
+- `npm run test:e2e:cli`：覆盖打包后 CLI 的主要命令、选择路径与文件副作用边界；当前 Windows 本地完整运行约 3-4 分钟
 - `npm run test:e2e:acceptance`：通过真实 shell / 全局 wrapper / 隔离 HOME 做更贴近人工验收的主路径看护
 
 当前已经覆盖：
@@ -63,6 +80,7 @@ npm run release:verify
 - 目标端口被非本服务占用时的安全提示与“无额外文件修改”边界
 - 残留 / 失效 PID 文件的安全清理
 - `release:stage` 生成的 `.release-stage\ctr-release-home.cmd` wrapper 是否真的指向隔离 `.release-home`
+- v1.5.0 入口稳定发布承诺的 packaged entry smoke、UI DOM smoke、配置保存安全线、remote client setup 和 server deployment setup
 
 只有这一步通过后，才继续正式发布，避免“发布后才发现包内容、CLI 启动或 setup 主流程有问题”。
 
@@ -209,6 +227,7 @@ git push origin v1.0.1
    - `npm ci`
    - `npm run build`
    - `npm test -- --run`
+   - `npm run test:e2e:cli:entry`
    - `npm run test:e2e:cli`
    - npm trusted publishing 版本门禁
    - `npm publish --access public`
@@ -260,14 +279,17 @@ docs/cli-test-matrix.md
 - `npm run test:e2e:cli`
 - 当前 `package.json.version` 是否已经发布到 npm
 - 如果 `package.json` 已改动，版本号是否真的发生变化
+- 当前提交是否已经带有匹配的 `vX.Y.Z` release tag
 
 它会在这些情况下直接失败：
 
 - `package.json` 改了，但版本号没有变化
-- `package.json` 改了，而且目标版本已经存在于 npm
+- `package.json` 改了，而且目标版本已经存在于 npm，但当前提交没有匹配的 `vX.Y.Z` tag
 
 这样可以把常见发布问题提前暴露在 PR 或合入 `master` 之前。
 
+如果 `master` push 和 `vX.Y.Z` tag push 几乎同时发生，tag 触发的 `Publish Package` 可能先把版本发布到 npm。`Release Check` 会识别当前提交是否正好带有匹配 tag；如果是，它会把“npm 已存在”视为已完成发布提交，而不是误判为版本冲突。
+
 ## 本地兜底发布
 
 如果需要手动发布，仍可在本地执行：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterwangze/claude-trigger-router",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Intelligent trigger-based router for Claude Code with automatic task type detection and model routing",
   "bin": {
     "ctr": "dist/cli.js"
@@ -27,7 +27,9 @@
     "dev": "tsx watch src/cli.ts",
     "start": "node dist/cli.js start",
     "test": "vitest --exclude src/e2e/**",
+    "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\"",
     "test:e2e:acceptance": "vitest --run src/e2e/cli-acceptance.test.ts",
     "verify:package": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/verify-package.ps1",
     "install:local-release": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/install-local-release.ps1",
@@ -54,19 +56,22 @@
     "@fastify/static": "^8.2.0",
     "@musistudio/llms": "^1.0.31",
     "dotenv": "^16.4.7",
-    "json5": "^2.2.3",
     "js-yaml": "^4.1.0",
+    "json5": "^2.2.3",
+    "lru-cache": "^10.0.0",
     "openurl": "^1.1.1",
     "rotating-file-stream": "^3.2.7",
     "tiktoken": "^1.0.21",
-    "uuid": "^11.1.0",
-    "lru-cache": "^10.0.0"
+    "uuid": "^11.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^28.0.3",
     "@types/node": "^24.0.15",
+    "@vitest/coverage-v8": "^1.6.1",
     "esbuild": "^0.25.1",
     "fastify": "^5.4.0",
+    "jsdom": "^29.1.1",
     "shx": "^0.4.0",
     "tsx": "^4.7.0",
     "typescript": "^5.8.2",