@jsonstudio/rcc 0.89.1205 → 0.89.1348

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 设计文档。
+