@peterwangze/claude-trigger-router 1.8.0 → 1.9.0

package/README.md

@@ -11,11 +11,54 @@ Claude Trigger Router 是给 Claude Code 用的本地路由代理。
 - 想在 Claude Code 外层增加配置校验、健康检查、治理观测和 UI 工作台
 - 想从 `claude-code-router` 迁移到更清晰的 `Models + Router` 配置心智
 
-## v1.8.0 发布定位
+## 5 分钟跑起来
+
+安装并确认命令可用：
+
+```bash
+npm install -g @peterwangze/claude-trigger-router
+ctr version
+ctr help
+```
+
+首次使用最推荐走交互式 setup：
+
+```bash
+ctr setup
+```
+
+`ctr setup` 会自动处理：
+
+- 复用已有 `~/.claude-trigger-router/config.yaml`
+- 探测并迁移旧 `claude-code-router` 配置
+- 在没有可用配置时询问“本地使用”、“连接远程服务”还是“部署为远程服务端”
+- 本地使用时创建最小可用配置
+- 连接远程服务时写入 `Runtime.remote_service`，不要求你先填写本地 provider/model
+- 部署为远程服务端时生成 server profile 和 bootstrap admin `APIKEY`，但不会自动启动服务
+- 本地使用时，引导填写默认模型 ID、接口地址、API Key 和模型名
+- 本地使用时，可选追加复杂任务模型，并生成 SmartRouter 起步模板
+- 保存配置后按角色输出下一步：本地路径提示 `ctr code` 和路由模板，远程客户端路径提示 `ctr doctor` / `ctr status` / 本地代理转发，服务端路径提示 `ctr doctor` / `ctr start --daemon`
 
-`v1.8.0` 是低侵入 agent/tool 增强与架构减压版。它把 agent/tool 能力压回现有路由代理和治理观测体系，先补 runtime pipeline、管理 API 权限 contract、UI fragment contract、route handoff summary、tool capability guardrail、输入/输出 guardrail 和 trace spans。
+本地日常使用路径：
 
-这个版本不把独立 agent 编排、任务队列、完整工具平台、完整 cloud 托管控制面或节点集群编排纳入发布承诺。完整发布边界见 [docs/release-notes-v1.8.0.md](docs/release-notes-v1.8.0.md)。
+```bash
+ctr status
+ctr doctor
+ctr code
+ctr ui
+```
+
+`ctr code` 会带着本地代理环境启动 Claude Code。之后你在 Claude Code 里的请求会经过本地 Trigger Router；`ctr ui` 用于查看当前服务、配置草稿、远程状态、compiled models 和治理摘要。
+
+如果 setup 选择的是“连接远程服务”，它会生成远程服务连接配置；先用 `ctr doctor` / `ctr status` 检查远端 ready 状态，再运行 `ctr code`，Claude Code 会继续连接本地 `ctr`，由本地 `ctr` 把模型调用转发到远端 CTR。直接把 Claude Code 指向远端服务仍然可用，但属于可选路径；这时使用 `ANTHROPIC_BASE_URL` 指向远端服务地址，并用 `ANTHROPIC_AUTH_TOKEN` 传服务维护者发放的 managed key。
+
+如果 setup 选择的是“部署为远程服务端”，setup 只生成配置，不会自动启动；请先编辑 `Models[].key` / `Models[].model`，再运行 `ctr doctor` 和 `ctr start --daemon`。服务端和远程客户端细节见下方“部署模式与边界”。
+
+## v1.9.0 发布定位
+
+`v1.9.0` 是用户入口与远程客户端一致性收口版。它把 README、setup、status/doctor、`ctr code`、`ctr ui` 和远程客户端手册统一到同一条主路径：本地日常用户先走 `ctr setup -> ctr status/doctor -> ctr code -> ctr ui`；远程客户端可以继续通过本地 `ctr code` 让本地 `ctr` 作为 thin proxy 转发模型调用到远端 CTR。
+
+这个版本不把独立 agent 编排、任务队列、完整工具平台、完整 cloud 托管控制面或节点集群编排纳入发布承诺；也不新增长期 key URL 或完整 UI auth 代理。完整发布边界见 [docs/release-notes-v1.9.0.md](docs/release-notes-v1.9.0.md)。
 
 ## 版本路线
 
@@ -27,6 +70,7 @@ Claude Trigger Router 是给 Claude Code 用的本地路由代理。
 - `v1.6.0`：多模型收益运营化，已补 benchmark history、人工校准 UI、核心路由场景任务集和评测/真实 trace 统一解释。
 - `v1.7.0`：服务化与模型池安全体验，已补服务端安全默认值、密钥轮换、主动 pool health、成本/速率元数据和更多调度策略。
 - `v1.8.0`：低侵入 agent/tool 增强与架构减压，已补 runtime pipeline、管理 API route contract、UI fragment contract、handoff summary、tool capability guardrail、输入/输出 guardrail 和 trace spans。
+- `v1.9.0`：用户入口与远程客户端一致性收口，已补远程客户端 proxy 文档、setup next steps、远程 Claude Code 鉴权变量、受保护 `/ui` admin 入口指导和 README 新用户路径前置。
 
 完整版本计划见 [docs/superpowers/plans/2026-05-07-core-routing-version-plan.md](docs/superpowers/plans/2026-05-07-core-routing-version-plan.md)。
 
@@ -41,7 +85,7 @@ Claude Trigger Router 是给 Claude Code 用的本地路由代理。
 - **路由评测**：`ctr eval --tasks` 查看固定任务契约，`ctr eval --input results.json` 离线评分，`ctr eval --run --models "sonnet;haiku"` 真实调用 CTR 做多模型 A/B；追加 `--judge-model` 后可调用一个 LLM 裁判模型给结果打分。
 - **doctor 诊断**：检查配置、服务可启动性、基础路由槽位、上下文窗口提示、鉴权安全状态、模型兼容策略和可选模型探测。
 - **UI 工作台**：`ctr ui` 打开本地页面，查看服务上下文、远程状态、鉴权安全状态、配置草稿、compiled models、capability warnings、治理 trace、metrics 和 Health 摘要。
-- **远程状态基础**：可配置 `Runtime.remote_service`，通过 `/api/remote-status` 查看远程服务健康、compiled model 摘要和治理告警摘要。默认用户不需要配置远程模式。
+- **远程客户端基础**：可配置 `Runtime.remote_service`，通过 `/api/remote-status` 查看远程服务健康、compiled model 摘要和治理告警摘要；在本地 `ctr code` 主路径中，本地 `ctr` 也可作为 thin proxy 把模型调用转发到远端 CTR。默认用户不需要配置远程模式。
 
 ## 部署模式与边界
 
@@ -51,7 +95,7 @@ Claude Trigger Router 是给 Claude Code 用的本地路由代理。
 - `server`：把 `ctr` 作为远程路由服务运行。它暴露 `/api/service-info`、`/api/remote-status`、`/api/registration`、`/ui` 等服务端状态和管理入口。
 - `cloud`：保留给托管/云端形态的配置语义；当前 npm 包仍按自托管进程运行，不包含托管控制面或集群编排。
 
-已落地的远程能力聚焦在“远程服务连接配置、状态查询和注册摘要”。它不会默认替代本地代理主路径，也不会自动启用尚未实现的集群、节点调度或托管控制面。
+已落地的远程能力聚焦在“远程服务连接配置、状态查询、注册摘要和本地 thin proxy 转发”。远程客户端配置下，Claude Code 仍连接本地 `ctr`，本地 `ctr` 会把 `/v1/messages` 与 `/v1/chat/completions` 转发到远端 CTR；这不会自动启用尚未实现的集群、节点调度或托管控制面。
 
 如果要把当前机器作为远程 `server` 暴露给其他客户端，先生成安全默认的服务端配置：
 
@@ -108,6 +152,7 @@ ctr start --daemon
 - `APIKEY` 定位为 bootstrap/admin key；服务端启动后用它调用 `POST /api/auth/keys` 生成给远程使用者的 managed key。
 - 远程日常 token 推荐同时授予 `client + read-only`：`client` 用于模型调用，`read-only` 用于 ready/status、compiled models 和 governance 观测接口。
 - `admin` key 才能访问 `/ui`、配置保存和 auth 管理。列表接口只返回 key 前后缀，secret 只在创建时返回一次。
+- 启用鉴权后，浏览器直接打开 `/ui` 不能自动携带 `Authorization` header；维护者应通过内网/本地隧道或 HTTPS 反向代理注入 `Authorization: Bearer <admin-key>` 后访问，不要把 admin key 放进 URL。API smoke 可以用 `curl -H "Authorization: Bearer $CTR_ADMIN_KEY" http://127.0.0.1:5678/api/service-info`。
 - `operator` key 用于日常运维写操作，例如重启、治理指标快照/定时快照、异常阈值和归档删除；它不能读取配置、保存配置或管理 auth key。
 - managed key 支持过期、撤销和 `quota.request_limit` / `quota.token_limit` / `quota.window_seconds`；窗口配额会持久化到本地状态文件，超限时 429 会返回 `quota.windowResetAt` 和 `Retry-After`。
 - `GET /api/service-info` 会返回脱敏的 `auth` / `security` 摘要和 quota 用量；`GET /api/auth/audit` 可用 admin key 查看最近鉴权允许/拒绝记录。
@@ -117,50 +162,6 @@ ctr start --daemon
 - `Registration.strategy` 支持 `priority`、`least-latency`、`round-robin`、`health-aware`、`cost-aware`，active endpoint 和 fallback candidate 使用同一排序口径。
 - 公网入口仍建议放在 HTTPS 反向代理之后；远程浏览器访问 UI 时建议使用本地隧道、内网访问，或由反向代理处理认证。
 
-## 安装
-
-```bash
-npm install -g @peterwangze/claude-trigger-router
-```
-
-安装后确认命令可用：
-
-```bash
-ctr version
-ctr help
-```
-
-## 5 分钟跑起来
-
-首次使用最推荐走交互式 setup：
-
-```bash
-ctr setup
-```
-
-`ctr setup` 会自动处理：
-
-- 复用已有 `~/.claude-trigger-router/config.yaml`
-- 探测并迁移旧 `claude-code-router` 配置
-- 在没有可用配置时询问“本地使用”、“连接远程服务”还是“部署为远程服务端”
-- 本地使用时创建最小可用配置
-- 连接远程服务时写入 `Runtime.remote_service`，不要求你先填写本地 provider/model
-- 部署为远程服务端时生成 server profile 和 bootstrap admin `APIKEY`，但不会自动启动服务
-- 本地使用时，引导填写默认模型 ID、接口地址、API Key 和模型名
-- 本地使用时，可选追加复杂任务模型，并生成 SmartRouter 起步模板
-- 保存配置后按角色输出下一步：本地路径提示 `ctr code` 和路由模板，远程客户端路径提示 `ctr status` / 远端 ready 检查，服务端路径提示 `ctr doctor` / `ctr start --daemon`
-
-本地使用路径完成后按这个顺序使用：
-
-```bash
-ctr status
-ctr code
-```
-
-`ctr code` 会带着本地代理环境启动 Claude Code。之后你在 Claude Code 里的请求会经过本地 Trigger Router。
-
-如果 setup 选择的是“连接远程服务”，当前主要用于生成远程服务连接配置并通过 `ctr status` 检查远端 ready 状态；日常直连远程服务时，请按服务维护者提供的 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 配置 Claude Code。首次日常使用仍建议先跑通本地 `Models + Router.default` 主路径。如果选择“部署为远程服务端”，setup 只生成配置，不会自动启动；请先编辑 `Models[].key` / `Models[].model`，再运行 `ctr doctor` 和 `ctr start --daemon`。
-
 ## 手动配置
 
 如果你更喜欢手动编辑，可以先生成模板：
@@ -531,7 +532,7 @@ GET /api/registration
 GET /api/auth/audit
 ```
 
-这条能力当前作为远程接入基础 contract 提供，用于服务发现、状态检查和注册摘要；它不表示已经自动把 Claude Code 请求转发到远端。首次使用仍建议从本地 `ctr setup -> ctr start -> ctr code` 开始。
+这条能力当前作为远程接入基础 contract 提供，用于服务发现、状态检查、注册摘要和本地 thin proxy 转发。启用 `Runtime.remote_service` 后，Claude Code 仍可通过本地 `ctr code` 进入，本地 `ctr` 会把模型请求转发到远端 CTR；直接连接远端服务只是可选高级路径。首次本地使用仍建议从 `ctr setup -> ctr start -> ctr code` 开始。
 
 ## 常用命令