@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/cli-command-inventory.md

@@ -0,0 +1,76 @@
+# CLI Command Inventory & Contracts
+
+Source of truth: `src/cli.ts` (wiring) + command implementations in `src/cli/commands/*` and `src/commands/*`.
+
+## Inventory (from `src/cli.ts`)
+
+| Command | Where registered | Implementation | Side effects (non-exhaustive) | Exit behavior |
+|---|---|---|---|---|
+| `env` | `src/cli/register/basic-commands.ts` | `src/cli/commands/env.ts` | Reads config file (optional) | `ctx.exit(1)` on parse/config errors; otherwise returns |
+| `clean` | `src/cli/register/basic-commands.ts` | `src/cli/commands/clean.ts` | Deletes captures/logs via `fs.rmSync(recursive)` | Returns on success; on failure uses spinner/logger (no direct `ctx.exit` in this file) |
+| `examples` | `src/cli/register/basic-commands.ts` | `src/cli/commands/examples.ts` | Prints examples | Returns |
+| `port` | `src/cli/register/basic-commands.ts` | `src/cli/commands/port.ts` | Reads port listeners; may kill PIDs (`--kill`) | `ctx.exit(2)` on invalid port; `ctx.exit(1)` on failures |
+| `config` | `src/cli/register/status-config-commands.ts` | `src/cli/commands/config.ts` | Writes config file; reads existing config | Returns (no direct `ctx.exit` in this file) |
+| `status` | `src/cli/register/status-config-commands.ts` | `src/cli/commands/status.ts` | Network `fetch` to server status endpoint | Returns (no direct `ctx.exit` in this file) |
+| `start` | `src/cli/register/start-command.ts` | `src/cli/commands/start.ts` | Reads config; may write temp config + pid file; may `fetch` shutdown; may kill PIDs; spawns server (`node dist/index.js`) | Uses `ctx.exit(...)` for success/error paths |
+| `stop` | `src/cli/register/stop-command.ts` | `src/cli/commands/stop.ts` | Reads config (release); kill PIDs; optional token-daemon stop | `ctx.exit(1)` on config/stop failures; otherwise returns |
+| `restart` | `src/cli/register/restart-command.ts` | `src/cli/commands/restart.ts` | Reads config; kill PIDs; may `fetch` shutdown; spawns server; writes pid file | Uses `ctx.exit(...)` for success/error paths |
+| `code` | `src/cli/register/code-command.ts` | `src/cli/commands/code.ts` | Reads config for `apikey`; may `fetch /ready`; may spawn server; spawns `claude` | Uses `ctx.exit(...)` for success/error paths |
+| `provider-update` *(optional)* | `src/cli.ts` dynamic import | `src/commands/provider-update.ts` | Reads/writes provider config and lists; may call RouteCodex HTTP endpoint for probing | Uses `process.exit(1)` in multiple branches |
+| `camoufox-fp` *(optional)* | `src/cli.ts` dynamic import | `src/commands/camoufox-fp.ts` | Reads fingerprint JSON on disk | Sets `process.exitCode` on errors |
+| `camoufox-backfill` *(optional)* | `src/cli.ts` dynamic import | `src/commands/camoufox-backfill.ts` | Backfills fingerprints (disk IO) | Uses `process.exitCode` on errors (by pattern) |
+| `token-daemon` *(optional)* | `src/cli.ts` dynamic import | `src/commands/token-daemon.ts` | Spawns background daemon; reads/writes snapshots | Uses `process.exit(...)` / `process.exitCode` in command handlers |
+| `quota-status` *(optional)* | `src/cli.ts` dynamic import | `src/commands/quota-status.ts` | Reads quota snapshot file | Returns; throws on missing file |
+| `quota-daemon` *(optional)* | `src/cli.ts` dynamic import | `src/commands/quota-daemon.ts` | Reads replay NDJSON; writes `provider-quota.json` unless `--dry-run` | Returns; on failure throws/sets exit |
+| `oauth` *(optional)* | `src/cli.ts` dynamic import | `src/commands/oauth.ts` | Triggers OAuth flows (Camoufox/browser automation) | Returns; may set exit codes on failures (subcommands) |
+| `validate` *(optional)* | `src/cli.ts` dynamic import | `src/commands/validate.ts` | `fetch` health + API; may spawn `rcc start`; reads payload file | Calls `process.exit(1)` on failures |
+
+## Contracts (inputs/outputs) — extracted from `.option(...)`
+
+### `env` (`src/cli/commands/env.ts`)
+- Inputs: `--port`, `--host`, `--config`, `--json`; reads config file if present.
+- Output: prints shell exports (default) or JSON (`--json`).
+- Exit: `1` on invalid/missing config-derived port.
+
+### `clean` (`src/cli/commands/clean.ts`)
+- Inputs: `--yes`, `--what <targets>` (default `all`).
+- Output: spinner/log messages about deleted targets.
+- Exit: no explicit `ctx.exit` in this file (errors are handled inside action).
+
+### `port` (`src/cli/commands/port.ts`)
+- Inputs: `--port <port>` (default `5555`), `--kill`.
+- Output: diagnostics; when `--kill`, attempts to kill listeners.
+- Exit: `2` on invalid port; `1` on kill failure or unexpected errors.
+
+### `config` (`src/cli/commands/config.ts`)
+- Inputs: `--config <config>`, `--template <template>`, `--force`.
+- Output: writes/prints config info via logger/spinner.
+- Exit: no explicit `ctx.exit` in this file.
+
+### `status` (`src/cli/commands/status.ts`)
+- Inputs: `--json`.
+- Output: human-readable status or JSON.
+- Exit: no explicit `ctx.exit` in this file.
+
+### `start` (`src/cli/commands/start.ts`)
+- Inputs: `--config`, `--port`, `--quota-routing on|off`, `--log-level`, `--codex/--claude`, `--ua`, `--snap/--snap-off`, `--verbose-errors/--quiet-errors`, `--restart`, `--exclusive`.
+- Output: spinner/log lines; server process inherits stdio.
+- Exit: `0` on normal termination; `1` on validation/start/shutdown errors.
+
+### `stop` (`src/cli/commands/stop.ts`)
+- Inputs: none; release mode reads config file for port; dev mode uses default/env port.
+- Output: spinner/log lines about stop result.
+- Exit: `1` on configuration/stop errors.
+
+### `restart` (`src/cli/commands/restart.ts`)
+- Inputs: `--config`, `--log-level`, `--codex/--claude`.
+- Output: spinner/log lines; server process inherits stdio.
+- Exit: `0` on normal termination; `1` on validation/restart errors.
+
+### `code` (`src/cli/commands/code.ts`)
+- Inputs: `--port`, `--host` (default `0.0.0.0`), `--url`, `--config`, `--apikey`, `--claude-path`, `--cwd`, `--model`, `--profile`, `--ensure-server`.
+- Output: launches Claude Code (subprocess inherits stdio).
+- Exit: `0` when Claude exits cleanly; `1` on connection/start failures.
+
+### Optional command groups (`src/commands/*`)
+These are wired via `program.addCommand(...)` and still use `process.exit(...)`/`process.exitCode` in places. They are not yet migrated into the `ctx.exit`/testable registration pattern.

package/docs/codex-samples-replay.md

@@ -0,0 +1,50 @@
+# Codex Samples 回放
+
+`scripts/replay-codex-sample.mjs` 允许我们将 `~/.routecodex/codex-samples/**/*_client-request.json` 等样本重新发送到本地 RouteCodex，确保工具调用、SSE chunk 和最终 JSON 都被完整记录。
+
+## 使用步骤
+
+1. 启动 RouteCodex 主包（默认 `http://127.0.0.1:5555`）。
+2. 准备好想要回放的样本文件，例如：
+   `~/.routecodex/codex-samples/openai-responses/req_req-v2-1764415000213-z1sxtbhuo_client-request.json`
+3. 执行：
+
+```bash
+npm run replay:codex-sample -- \
+  --sample ~/.routecodex/codex-samples/openai-responses/req_req-v2-1764415000213-z1sxtbhuo_client-request.json \
+  --label first-run
+```
+
+可选参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--label` | 为本次运行命名（默认使用时间戳）。 |
+| `--base`  | RouteCodex 基地址，默认 `http://127.0.0.1:5555`。 |
+| `--key`   | API Key / Bearer Token，默认 `routecodex-test`。 |
+
+## 产出内容
+
+脚本会在样本所在目录下生成 `runs/<requestId>/<label>/`，包括：
+
+- `request.json`：发送给 RouteCodex 的 endpoint 与 body；
+- `response.meta.json`：状态码、响应头以及是否流式；
+- 若为流式：
+  - `response.sse.log`：完整的 SSE 文本（`event:`/`data:`）；
+  - `response.sse.ndjson`：逐帧 NDJSON，方便与黄金样本 diff；
+- 若为 JSON：
+  - `response.json`：RouteCodex 返回的 JSON payload；
+- 若发生错误，额外写入 `response.error.txt`。
+
+## 配合 proxy replay
+
+对于 responses SSE，可使用 `scripts/responses-sse-proxy.mjs --replay <capture>/response.sse.log` 将黄金样本作为上游输出，再结合本脚本回放客户端 payload，实现“同一份请求 + 同一份 SSE 流”在 RouteCodex 中的完整闭环。
+
+## 常见场景
+
+- **工具调用链路**：先回放 `/v1/responses` 样本捕获 `required_action`，再回放对应的 `/v1/responses.submit_tool_outputs` 样本；
+- **对比黄金样本**：和 `npm run verify:sse-loop -- --skip-chat --skip-anthropic --use-proxy-capture` 搭配，先复现请求，再检查 SSE 是否与黄金帧一致；
+- **调试快照**：`runs/` 输出可以直接归档到版本库/CI 工件，作为后续 Regression 的输入。
+
+通过上述流程，可以确保 codex samples 中的工具请求、工具返回以及最终响应数据均可被精准复现，并在磁盘上形成完备的 JSON/SSE 证据链。
+

package/docs/daemon-admin-api-design.md

@@ -0,0 +1,350 @@
+# Daemon / Token / Quota / Providers / Config V2 管理 API 设计
+
+> 目标：为 Daemon 管理 UI 和基于 Config V2 的 Provider 管理视图提供一组 **只读或低风险** 的 HTTP JSON API。  
+> 所有 API 均由 HTTP server 提供，数据来源于 ManagerDaemon、虚拟路由和 Config V2，禁止在此层做路由/工具语义决策。
+
+---
+
+## 1. 通用约定
+
+- 所有 API 均以 JSON 形式返回。
+- 错误返回格式对齐现有 HTTP server：
+  - HTTP 状态码 4xx/5xx。
+  - Body: `{ "error": { "message": string, "code"?: string, ... } }`
+- 仅暴露**非敏感字段**：
+  - 不返回 access_token / refresh_token / client_secret 等。
+  - 对 token 文件路径等敏感信息仅返回相对路径或掩码版本。
+
+---
+
+## 2. Daemon 状态 API
+
+### 2.1 `GET /daemon/status`
+
+> 展示当前 HTTP server 实例的 daemon/manager 状态，以及关键模块是否运行。
+
+- 响应示例：
+
+```jsonc
+{
+  "ok": true,
+  "serverId": "routecodex-dev-5555",
+  "version": "0.89.872",
+  "uptimeSec": 1234,
+  "manager": {
+    "active": true,
+    "modules": [
+      { "id": "token", "status": "leader", "details": { "intervalSec": 60 } },
+      { "id": "quota", "status": "running" },
+      { "id": "health", "status": "running" },
+      { "id": "routing", "status": "running", "stickyEnabled": true }
+    ]
+  }
+}
+```
+
+- 数据来源：
+  - `RouteCodexHttpServer`（serverId、版本、uptime）。
+  - `ManagerDaemon` + 各 `ManagerModule` 的只读状态。
+
+---
+
+## 3. Credentials 管理 API
+
+> 注意：所有 API 必须避免泄露敏感字段，只用于展示凭证状态和触发安全的 verify/refresh 操作。
+
+### 3.1 `GET /daemon/credentials`
+
+- 用途：列出 daemon 管理下已知的 credential 条目。
+- 响应示例：
+
+```jsonc
+[
+  {
+    "id": "iflow-oauth-1-186",
+    "kind": "oauth",
+    "providerFamily": "gemini",
+    "alias": "iflow-186",
+    "tokenFile": "~/.routecodex/auth/iflow-oauth-1-186.json",
+    "projectId": "my-project",
+    "expiresAt": 1736500000000,
+    "expiresInSec": 3600,
+    "status": "valid", // valid | expiring | expired | invalid
+    "lastError": null
+  }
+]
+```
+
+- 数据来源：
+  - Token 文件扫描器（现有 `scanProviderTokenFiles` 等）。
+  - `readTokenFile` + `evaluateTokenState`。
+
+### 3.2 `GET /daemon/credentials/:id`
+
+- 用途：查看单个 credential 的详细信息（仍然不包含密钥本体）。
+- 响应字段在列表基础上可增加：
+
+```jsonc
+{
+  "id": "iflow-oauth-1-186",
+  "kind": "oauth",
+  "providerFamily": "gemini",
+  "alias": "iflow-186",
+  "tokenFile": "~/.routecodex/auth/iflow-oauth-1-186.json",
+  "projectId": "my-project",
+  "expiresAt": 1736500000000,
+  "expiresInSec": 3600,
+  "status": "valid",
+  "lastError": null,
+  "issuer": "https://accounts.google.com",
+  "scopes": ["https://www.googleapis.com/auth/cloud-platform"],
+  "createdAt": 1736400000000,
+  "updatedAt": 1736499900000
+}
+```
+
+### 3.3 `POST /daemon/credentials/:id/verify`
+
+- 用途：触发一次“最佳努力”的远端验证（例如调用 userinfo 或简单的 API ping）。
+- 请求体：可为空 `{}`。
+- 响应示例：
+
+```jsonc
+{
+  "ok": true,
+  "id": "iflow-oauth-1-186",
+  "status": "valid", // valid | invalid | error
+  "checkedAt": 1736500100000,
+  "message": "Token accepted by upstream."
+}
+```
+
+- 行为约束：
+  - 仅在本地发起一次轻量级验证，不做重试风暴。
+  - 失败时只记录错误，不修改配置文件。
+
+### 3.4 `POST /daemon/credentials/:id/refresh`
+
+- 用途：在安全前提下触发一次刷新（如果支持 refresh_token）。
+- 响应示例：
+
+```jsonc
+{
+  "ok": true,
+  "id": "iflow-oauth-1-186",
+  "status": "refreshed",
+  "expiresAt": 1736503600000
+}
+```
+
+- 约束：
+  - 必须遵守现有 token-daemon 的刷新策略，不与后台自动刷新逻辑冲突。
+  - 若不支持手动刷新，应返回 `400` 或 `409` 并给出明确错误信息。
+
+---
+
+## 4. Quota & 429 冷却 API
+
+### 4.1 `GET /quota/summary`
+
+- 用途：展示所有受管配额（目前主要是 Antigravity）的摘要。
+- 响应示例：
+
+```jsonc
+{
+  "updatedAt": 1736500000000,
+  "records": [
+    {
+      "key": "antigravity://jasonqueque/gemini-3-pro-low",
+      "alias": "jasonqueque",
+      "modelId": "gemini-3-pro-low",
+      "remainingFraction": 0.42,
+      "resetAt": 1736503600000
+    }
+  ]
+}
+```
+
+- 数据来源：
+  - `QuotaManagerModule.getRawSnapshot()`。
+
+### 4.2 `GET /quota/runtime`
+
+- 用途：按 runtimeKey 或 providerKey 过滤配额状态。
+- 查询参数：
+  - `runtimeKey?: string`
+  - `providerKey?: string`
+- 响应示例：
+
+```jsonc
+{
+  "runtimeKey": "antigravity.jasonqueque",
+  "items": [
+    {
+      "providerKey": "antigravity.jasonqueque.gemini-3-pro-low",
+      "modelId": "gemini-3-pro-low",
+      "remainingFraction": 0.42,
+      "resetAt": 1736503600000
+    }
+  ]
+}
+```
+
+### 4.3 `GET /quota/cooldowns`
+
+- 用途：展示当前虚拟路由层面的 series cooldown 状态（与 429 相关）。
+- 响应示例（形态示意）：
+
+```jsonc
+[
+  {
+    "providerId": "antigravity.jasonqueque",
+    "providerKey": "antigravity.jasonqueque.gemini-3-pro-low",
+    "series": "gemini-pro",
+    "cooldownMs": 300000,
+    "until": 1736500200000
+  }
+]
+```
+
+- 数据来源：
+  - llmswitch-core virtual router 暴露的 cooldown 只读视图（或内部缓存）。
+
+---
+
+## 5. Providers 运行时视图 API
+
+### 5.1 `GET /providers/runtimes`
+
+- 用途：展示当前 virtual router 中实际存在的 provider runtimes 及其状态。
+- 响应示例：
+
+```jsonc
+[
+  {
+    "providerKey": "antigravity.jasonqueque.gemini-3-pro-low",
+    "runtimeKey": "antigravity.jasonqueque",
+    "family": "gemini",
+    "protocol": "gemini-chat",
+    "series": "gemini-pro",
+    "enabled": true,
+    "boundCredentialId": "iflow-oauth-1-186",
+    "health": {
+      "status": "ok",
+      "lastErrorAt": null,
+      "recent429Count": 2
+    }
+  }
+]
+```
+
+- 数据来源：
+  - `RouteCodexHttpServer` 中的 provider runtime 映射。
+  - Health/quota manager 模块。
+  - Credential 绑定信息从 Config 解析（不直接读取密钥）。
+
+---
+
+## 6. Config V2 Provider 视图 API
+
+> 与 `docs/provider-config-v2-ui-design.md` 对应，只读展示 Config V2 中声明的 provider 定义，并与 runtime/credentials 形成弱关联。
+
+### 6.1 `GET /config/providers/v2`
+
+- 用途：列出 Config V2 中声明的 provider 定义摘要。
+
+```jsonc
+[
+  {
+    "id": "antigravity.jasonqueque.gemini-3-pro-low",
+    "family": "gemini",
+    "protocol": "gemini-chat",
+    "runtimeKey": "antigravity.jasonqueque",
+    "route": "default",
+    "series": "gemini-pro",
+    "enabled": true,
+    "source": "virtualrouter.v2.json#providers[3]",
+    "defaultModels": ["gemini-3-pro-low"],
+    "credentialsRef": "antigravity-oauth-2-jasonqueque.json"
+  }
+]
+```
+
+### 6.2 `GET /config/providers/v2/:id`
+
+- 用途：查看单个 provider 的详细 Config V2 配置。
+- 在 6.1 的基础上，增加：
+
+```jsonc
+{
+  "id": "antigravity.jasonqueque.gemini-3-pro-low",
+  "family": "gemini",
+  "protocol": "gemini-chat",
+  "runtimeKey": "antigravity.jasonqueque",
+  "route": "default",
+  "series": "gemini-pro",
+  "enabled": true,
+  "source": "virtualrouter.v2.json#providers[3]",
+  "defaultModels": ["gemini-3-pro-low"],
+  "allowedModels": ["gemini-3-pro-low", "gemini-3-pro-high"],
+  "aliases": {
+    "thinking": "gemini-3-pro-high",
+    "low": "gemini-3-pro-low"
+  },
+  "credentialsRef": "antigravity-oauth-2-jasonqueque.json",
+  "quota": {
+    "perMinuteLimit": 60,
+    "perHourLimit": 2000
+  },
+  "flags": {
+    "beta": false,
+    "internalOnly": false
+  },
+  "notes": "Primary Gemini Pro provider for Antigravity runtime."
+}
+```
+
+### 6.3 `GET /config/providers/v2/:id/preview-route`
+
+- 用途：把该 provider 在虚拟路由中的路由规则用人类可读的方式展示出来。
+
+```jsonc
+{
+  "id": "antigravity.jasonqueque.gemini-3-pro-low",
+  "route": "default",
+  "series": "gemini-pro",
+  "description": [
+    "Matched when route=default and series=gemini-pro.",
+    "Primary for tools: tool-request-detected, last-tool-other.",
+    "Cooldown series: gemini-pro (300000 ms)."
+  ]
+}
+```
+
+- 数据来源：
+  - Virtual Router 的内部路由表，序列化为文本说明。
+
+---
+
+## 7. 安全与访问控制（设计约束）
+
+- 初期阶段，所有管理 API 仅对 `localhost` 暴露：
+  - 与现有 `/shutdown` 路由类似，限制 remoteAddress 为 127.0.0.1 / ::1。
+- 不在管理 API 中提供：
+  - 修改配置、强制切换路由、直接操作上游 provider 的危险动作。
+- 日志：
+  - 重要错误统一走 `RouteErrorHub`，标记 `scope: 'http' | 'daemon'`，但避免在日志中打印敏感字段。
+
+---
+
+## 8. 与任务规划的对应关系
+
+- 「文件结构落盘」：
+  - 对应 `docs/daemon-admin-module-structure.md` 中的模块/路径设计。
+- 「文档详细设计更新」：
+  - 对应本文件中对各 API 的输入/输出定义。
+- 后续实现步骤：
+  - 在 HTTP server 中新增 `daemon-admin-routes` 与各 handler。
+  - 在前端 UI 中按本 API 规范对接数据。
+  - 最终做一轮端到端集成测试（含 429 冷却/配额展示/credential 状态联动）。
+

package/docs/daemon-admin-module-structure.md

@@ -0,0 +1,169 @@
+# Daemon / Token 管理 & Provider Config V2 视图模块结构设计
+
+> 目标：在不破坏现有 HTTP server / Manager 架构的前提下，为 Daemon/Token 管理 UI 和基于 Config V2 的 Provider 管理视图定义清晰的**模块与文件结构**。本设计仅落盘结构与职责，不改动任何实现。
+
+---
+
+## 1. 总体架构与边界
+
+- **HTTP Server 仍然是唯一入口**
+  - 继续使用 `src/server/runtime/http-server/index.ts` + `routes.ts` 注册所有 HTTP 路径。
+  - 新的管理类 API（daemon/token/health/quota/providers/config-v2）作为一组「管理接口」，挂在 HTTP server 之下。
+
+- **ManagerDaemon 继续作为状态聚合点**
+  - 已有的 `src/manager` 模块负责：
+    - token 刷新（`TokenManagerModule`）
+    - health 持久化（`HealthManagerModule`）
+    - quota 追踪（`QuotaManagerModule`）
+    - routing 指令状态（`RoutingStateManagerModule`）
+  - 新的管理 API 只“读”这些模块暴露的状态或执行低风险动作（例如触发一次 verify），不直接操作 llmswitch-core 的内部路由逻辑。
+
+- **前端 UI 为独立模块**
+  - 静态设计页面保留在 `docs/daemon-admin-ui.html`。
+  - 真正运行时的管理 UI 视图将作为 HTTP server 提供的静态页面（后续实现阶段接入），前端通过一组只读 JSON API 获取数据。
+
+---
+
+## 2. 后端模块结构（HTTP Server 侧）
+
+### 2.1 入口与路由注册
+
+- 现状：
+  - HTTP server 在 `src/server/runtime/http-server/index.ts` 中构造 `RouteCodexHttpServer`。
+  - 路由在 `src/server/runtime/http-server/routes.ts` 中通过 `registerHttpRoutes` 注册。
+
+- 规划：
+  - 新增一个轻量的“管理 API 路由模块”：
+    - 文件：`src/server/runtime/http-server/daemon-admin-routes.ts`
+    - 导出函数：`registerDaemonAdminRoutes(options: DaemonAdminRouteOptions): void`
+    - 在 `routes.ts` 内部调用 `registerDaemonAdminRoutes(...)`，与现有 `/health`、`/config` 等路由并列。
+
+```ts
+// src/server/runtime/http-server/daemon-admin-routes.ts（示意）
+export interface DaemonAdminRouteOptions {
+  app: Application;
+  getManagerDaemon: () => ManagerDaemon | null;
+  getServerId: () => string;
+}
+
+export function registerDaemonAdminRoutes(options: DaemonAdminRouteOptions): void {
+  const { app } = options;
+  // 这里仅定义 path → handler 的绑定，具体 handler 抽到子模块。
+}
+```
+
+### 2.2 管理 API Handler 模块划分
+
+在 `src/server/runtime/http-server` 下增加一个子目录，专门存放管理类 handler：
+
+- 目录：`src/server/runtime/http-server/daemon-admin/`
+
+建议的文件划分：
+
+- `daemon-admin/status-handler.ts`
+  - 对应 API：`GET /daemon/status`
+  - 依赖：
+    - `ManagerDaemon`（读取当前是否为 leader、运行模块列表）
+    - `TokenManagerModule`（token Daemon 运行状态）
+    - `HealthManagerModule` / `QuotaManagerModule`（用于统计摘要）
+
+- `daemon-admin/credentials-handler.ts`
+  - 对应 API：
+    - `GET /daemon/credentials`
+    - `GET /daemon/credentials/:id`
+    - `POST /daemon/credentials/:id/verify`
+    - `POST /daemon/credentials/:id/refresh`
+  - 依赖：
+    - 现有 token 文件扫描、解析工具：
+      - `providers/auth/token-scanner` 系列
+      - `token-daemon/token-utils` 中的 `readTokenFile` / `evaluateTokenState`
+    - 必须避免返回敏感字段（access_token / refresh_token 等），只返回文件路径、issuer、project_id 等非敏感信息。
+
+- `daemon-admin/quota-handler.ts`
+  - 对应 API：
+    - `GET /quota/summary`
+    - `GET /quota/runtime`（按 runtimeKey / providerKey 过滤）
+    - `GET /quota/cooldowns`（暴露当前 429 冷却相关信息）
+  - 依赖：
+    - `QuotaManagerModule` 的 `getRawSnapshot()`。
+    - 虚拟路由 cooldown 状态（通过 llmswitch-core 暴露的只读接口，或已有的 series cooldown 统计）。
+
+- `daemon-admin/providers-runtime-handler.ts`
+  - 对应 API：`GET /providers/runtimes`
+  - 依赖：
+    - `RouteCodexHttpServer` 内部已维护的 `providerHandles` / `providerKeyToRuntimeKey` 映射。
+    - `HealthManagerModule` / `QuotaManagerModule` 的统计，用于补充 runtime 健康/配额状态。
+
+- `daemon-admin/config-providers-v2-handler.ts`
+  - 对应 API：
+    - `GET /config/providers/v2`
+    - `GET /config/providers/v2/:id`
+    - `GET /config/providers/v2/:id/preview-route`
+  - 依赖：
+    - 未来的 Config V2 loader / Virtual Router builder：
+      - provider 定义集合（id/family/protocol/runtimeKey/route/series/defaultModels/credentialsRef/flags）。
+    - 虚拟路由中的路由规则（用于 preview-route 的人类可读描述）。
+
+> 以上 handler 模块均保持「薄层」：只做数据组装与序列化，不直接参与路由决策或工具语义处理。
+
+### 2.3 与 ManagerDaemon 的绑定
+
+- `RouteCodexHttpServer` 构造时已经创建并启动了 `ManagerDaemon`：
+  - 在 `src/server/runtime/http-server/index.ts` 中：
+    - 创建 `ManagerDaemon`；
+    - 注册 `HealthManagerModule` / `RoutingStateManagerModule` / `TokenManagerModule` / `QuotaManagerModule`；
+    - 持有一个 `managerDaemon` 字段。
+
+- 新的 `registerDaemonAdminRoutes` 需要能够访问这个实例：
+  - 在 `RouteCodexHttpServer` 内暴露一个 `getManagerDaemon(): ManagerDaemon | null` 的只读方法。
+  - 调用 `registerHttpRoutes` 时，将此方法以闭包形式传递给 `registerDaemonAdminRoutes`，实现解耦：
+
+```ts
+// routes.ts（示意）
+registerDaemonAdminRoutes({
+  app,
+  getManagerDaemon: () => this.managerDaemon,
+  getServerId: () => this.config.server.serverId
+});
+```
+
+---
+
+## 3. 前端静态资源结构
+
+### 3.1 设计稿与运行时文件的关系
+
+- 设计稿：
+  - `docs/daemon-admin-ui.html` 保留为设计 Mock，展示完整的 UI 布局和交互。
+
+- 运行时静态页面（后续实现阶段）：
+  - 计划通过 HTTP server 暴露一个只读页面，例如：
+    - `GET /daemon/admin` → 返回一个内嵌或打包好的 HTML。
+  - 为了减少重复，推荐方案：
+    - 在构建流程中，将 `docs/daemon-admin-ui.html` 复制/压缩到构建输出目录（例如 `dist/daemon-admin/index.html`）。
+    - 在 HTTP server 中提供一个简单的静态文件响应（不在本次设计中实现具体逻辑）。
+
+### 3.2 前端脚本组织（后续）
+
+- 前端 JS/CSS 初期可以内联在单一 HTML 中（如当前 mock）。
+- 一旦接入真实 API，可将脚本拆分为：
+  - `daemon-admin.js`：负责 Tab 切换、调用 JSON API、渲染数据。
+  - 后续如有必要，再拆分子模块（例如 `credentials-panel.js`、`providers-panel.js`），但这不是当前阶段的目标。
+
+---
+
+## 4. 与现有路由的关系与约束
+
+- 所有新 API 都必须遵守现有 HTTP server 的约束：
+  - 不在管理 API 中直接调用 provider 上游或 llmswitch-core 的 Hub Pipeline。
+  - 错误处理统一走现有的 `reportRouteError` + `mapErrorToHttp` 逻辑（通过封装好的 helper）。
+  - 只暴露只读或低风险的动作，不提供重写配置、强制路由等高风险操作。
+
+- 管理 UI 相关路径建议统一在以下空间之内：
+  - `/daemon/*`：daemon 自身状态、tokens、credentials。
+  - `/quota/*`：配额快照与 429 冷却视图。
+  - `/providers/*`：runtime 级别的 provider 运行状态。
+  - `/config/providers/v2*`：Config V2 声明性配置视图。
+
+> 本文档仅定义结构与边界，实际实现将严格参考本结构，并在实现前再与现有代码和运行约束对齐。实现阶段需同时更新对应的 API 设计文档。
+