@peterwangze/claude-trigger-router 1.8.0 → 1.9.0

package/docs/cli-test-matrix.md

@@ -74,7 +74,7 @@
 - `ctr status` 在 server/cloud 模式下输出 role、listener、auth 摘要、维护入口和远程客户端连接说明；服务已 ready 时优先使用 live `/api/service-info`，PID 元数据缺失时也不能误报停止
 - `ctr setup` 在本地使用和连接远程服务两条 fresh 路径中输出统一角色说明，避免把 remote service、server deploy 和 managed key 混成同一条用户路径
 - `ctr setup` fresh 路径支持“部署为远程服务端”，生成 server profile / bootstrap admin `APIKEY` / `Runtime.mode: server`，并且不自动启动服务
-- `ctr setup` 保存后按角色输出状态反馈：本地路径说明本地代理已 start/reuse/reload/restart 并提示 `ctr code`，远程客户端路径只承诺 ready/status 检查和直连远端所需环境变量，服务端路径不启动服务
+- `ctr setup` 保存后按角色输出状态反馈：本地路径说明本地代理已 start/reuse/reload/restart 并提示 `ctr code`，远程客户端路径提示先用 `ctr doctor` / `ctr status` 检查本地代理与远端 ready，再运行本地 `ctr code` 由本地代理转发模型调用，直连远端所需环境变量只作为可选路径，服务端路径不启动服务
 - `ctr setup` 复用已有 `Runtime.mode: server/cloud` 配置时不能自动启动服务或进入 Claude Code，本地代理 next steps 只适用于 `Runtime.mode: local`
 
 ### UI / 服务状态

package/docs/configuration-guide.md

@@ -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` 只建议服务所有者使用。日常维护可以发放 managed `operator` key，用于重启、治理快照、定时快照、异常阈值和归档删除，但不能读写配置或管理 auth。公网部署建议放在 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` 不能自动携带 `Authorization` header，维护者应使用本地隧道、内网访问，或由反向代理在完成自身认证后注入 `Authorization: Bearer <admin-key>`，不要把 admin key 放进 URL。
 
 远程客户端配置是可选路径，不是默认路径。最小写法：
 
@@ -269,7 +269,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_AUTH_TOKEN`；服务端路径提示 `ctr doctor` 与 `ctr start --daemon`
 - 在当前配置损坏时 repair / rebuild
 
 当前对用户主流程已经补了打包态 E2E，覆盖：

package/docs/configuration-roles.md

@@ -32,11 +32,11 @@
 
 - 向服务维护者获取服务 base URL。
 - 获取同时带 `client` 和 `read-only` scope 的 managed key。
-- 使用 `Runtime.remote_service` 保存连接配置，并做 ready/status 检查。
-- 如果直接让 Claude Code 连接远程服务，把 `ANTHROPIC_BASE_URL` 设置为服务地址，把 `ANTHROPIC_API_KEY` 设置为 managed key。
+- 使用 `Runtime.remote_service` 保存连接配置，并做 ready/status 检查；日常可以继续运行本地 `ctr code`，由本地 `ctr` 把模型调用转发到远端服务。
+- 如果直接让 Claude Code 连接远程服务，把 `ANTHROPIC_BASE_URL` 设置为服务地址，把 `ANTHROPIC_AUTH_TOKEN` 设置为 managed key。
 
 详细客户端步骤见 `docs/remote-client-guide.md`。
 
 ## 当前边界
 
-`Runtime.remote_service` 当前是连接配置、ready/status 检查和注册摘要 contract。它还不表示本地 `ctr code` 会自动把所有请求转发到远程 router。首次日常使用仍建议优先走本地 `Models + Router.default` 路径，除非你已经有一个由维护者提供的远程服务。
+`Runtime.remote_service` 当前是连接配置、ready/status 检查、注册摘要和本地 thin proxy 转发 contract。当 `Runtime.mode: local` 且 `Runtime.remote_service.enabled` 时，本地 `ctr code` 仍启动 Claude Code 连接本地 `ctr`，模型请求会由本地 `ctr` 转发到远程 router。它不表示已经有集群节点调度或托管控制面；直接让 Claude Code 连接远端只是可选路径。

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

@@ -0,0 +1,33 @@
+# Release notes v1.9.0
+
+`v1.9.0` 定位为“用户入口与远程客户端一致性收口版”。这个版本不新增大型能力，重点是把已经落地的远程转发、setup 下一步、鉴权变量、受保护 UI 入口和 README 新用户路径统一到同一套用户心智。
+
+## 本次主线
+
+- 远程客户端 proxy 心智统一：README、configuration roles、configuration guide 和 remote client guide 均明确 `Runtime.mode: local` 且 `Runtime.remote_service.enabled` 时，本地 `ctr code` 可作为 thin proxy 转发 `/v1/messages` 与 `/v1/chat/completions` 到远端 CTR；直接连接远端只是可选路径。
+- setup remote-client next steps 收口：`ctr setup` 远程客户端路径现在提示先运行 `ctr doctor` / `ctr status` 检查远端 ready，再运行本地 `ctr code` 进入 Claude Code；setup 单测和 packaged CLI entry smoke 已同步。
+- 远程 Claude Code 鉴权口径统一：面向 Claude Code 推荐 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`；本地 `ctr code` 也注入 `ANTHROPIC_AUTH_TOKEN` 并清理 `ANTHROPIC_API_KEY`，原始 HTTP 客户端仍可用 `Authorization: Bearer` 或 `x-api-key`。
+- `/ui` admin 入口最小闭环：`ctr ui` 输出、README、configuration guide、server maintainer guide 和 UI Auth scope guide 均说明受保护 `/ui` 需要 admin key，并建议通过内网/本地隧道或反向代理注入 `Authorization: Bearer <admin-key>`，不要把 admin key 放进 URL。
+- README 新用户路径前置：`5 分钟跑起来` 已移动到项目介绍之后，直接给出 `ctr setup -> ctr status/doctor -> ctr code -> ctr ui` 主路径；版本定位、部署和维护者内容后移。
+
+## 发布边界
+
+- 本版本不声明完整 cloud 托管控制面、节点/集群编排或独立 agent 平台。
+- `/ui` 本轮完成可执行访问指导和 CLI 提示，不新增长期 key URL、一次性 token 或 loopback header proxy；后续若实现新的 UI auth 入口，必须补 server/auth/UI smoke。
+- 远程客户端仍是本地 thin proxy + 远端只读状态/注册摘要，不做服务发现或远端注册写回。
+
+## 验证
+
+本版本收口前至少需要通过：
+
+```bash
+npm run release:verify
+```
+
+本轮已为新增闭环补充 targeted 看护：
+
+- `src/setup/index.test.ts`
+- `npm run test:e2e:cli:entry`
+- `src/deploy-assets.test.ts`
+- `src/cli-run.test.ts`
+- `npm run test:ui`

package/docs/releasing.md

@@ -7,7 +7,7 @@
 - `Release Check`：在 PR、`master` push 和手动触发时执行发布前检查
 - `Publish Package`：在版本 tag、GitHub Release 或手动触发时执行正式发布
 
-本次 `v1.8.0` minor release 的优先级是低侵入 agent/tool 增强与架构减压。发布检查需要同时保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及 runtime pipeline、管理 API 权限矩阵、UI fragment contract、route handoff summary、tool capability guardrail、输入/输出 guardrail 和 trace spans。
+本次 `v1.9.0` minor release 的优先级是用户入口与远程客户端一致性收口。发布检查需要同时保护既有 `setup / start / status / code / doctor / ui` 入口主路径，以及远程客户端 thin proxy 文档、setup remote-client next steps、`ANTHROPIC_AUTH_TOKEN` 鉴权口径、受保护 `/ui` admin 入口指导和 README 新用户路径前置。
 
 ## 一次性准备
 
@@ -26,14 +26,14 @@
 
 1. 更新版本号
    - `vX.Y.0` 这类 minor release 还需要同步更新版本依赖用例、README 发布定位和对应 release notes。
-   - 本次 `v1.8.0` 的发布边界以 `docs/release-notes-v1.8.0.md` 为准：主打低侵入 agent/tool 增强与架构减压，不宣称独立 agent 编排、完整工具平台、完整云端托管控制面或节点集群编排。
+   - 本次 `v1.9.0` 的发布边界以 `docs/release-notes-v1.9.0.md` 为准：主打用户入口与远程客户端一致性收口，不宣称完整云端托管控制面、节点集群编排或完整 UI auth 代理。
 2. 本地先执行发布包验证：
 
 ```bash
 npm run release:verify
 ```
 
-v1.8.0 期间建议在正式 `release:verify` 前额外跑一次 agent/tool 与架构 contract 专项：
+v1.9.0 期间建议在正式 `release:verify` 前额外跑一次用户入口与远程客户端一致性专项：
 
 ```bash
 npm test -- --run --coverage
@@ -80,7 +80,7 @@ npm run test:e2e:acceptance
 - 目标端口被非本服务占用时的安全提示与“无额外文件修改”边界
 - 残留 / 失效 PID 文件的安全清理
 - `release:stage` 生成的 `.release-stage\ctr-release-home.cmd` wrapper 是否真的指向隔离 `.release-home`
-- v1.8.0 agent/tool 与架构减压发布承诺的 runtime pipeline、管理 API route contract、UI fragment anchors、route handoff summary、tool capability guardrail、输入/输出 guardrail 和 trace spans
+- v1.9.0 用户入口与远程客户端一致性发布承诺的 remote-client setup next steps、README quick start、remote Claude Code auth guidance、protected `/ui` admin guidance 和文档资产检查
 
 只有这一步通过后，才继续正式发布，避免“发布后才发现包内容、CLI 启动或 setup 主流程有问题”。
 

package/docs/remote-client-guide.md

@@ -62,6 +62,8 @@ You can still point Claude Code directly at the remote server when you do not wa
 
 ```bash
 export ANTHROPIC_BASE_URL="https://router.example.com"
-export ANTHROPIC_API_KEY="$CTR_REMOTE_AUTH_TOKEN"
+export ANTHROPIC_AUTH_TOKEN="$CTR_REMOTE_AUTH_TOKEN"
 claude
 ```
+
+For raw HTTP clients, the server accepts the managed key through either `Authorization: Bearer <token>` or `x-api-key: <token>`. For Claude Code, keep using `ANTHROPIC_AUTH_TOKEN`; local `ctr code` also injects this variable and clears `ANTHROPIC_API_KEY` so stale provider keys do not bypass the local proxy.

package/docs/server-maintainer-guide.md

@@ -96,4 +96,10 @@ ctr ui
 
 `ctr ui` opens the workbench. The maintainer area shows security status, auth scope guidance, quota usage, governance health and routing outcome summaries.
 
+When auth is enabled, `/ui` requires an admin key. A normal browser navigation cannot attach `Authorization: Bearer <admin-key>` by itself, so expose the UI through a private network, local tunnel or HTTPS reverse proxy that injects the admin header after its own authentication. Do not put an admin key in the URL. For a quick API smoke, use:
+
+```bash
+curl -H "Authorization: Bearer $CTR_ADMIN_KEY" http://127.0.0.1:5678/api/service-info
+```
+
 For model pools, use `GET /api/models/pool-health` for current health and `POST /api/models/pool-health/probe` for an operator-triggered lightweight reachability probe. The probe does not send a model request; it uses `HEAD` against enabled endpoints, records latency for reachable endpoints, and records failures into the existing cooldown/circuit breaker state.

package/package.json

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