@jsonstudio/rcc 0.89.1562 → 0.89.1803

package/docs/CLOCK.md

@@ -0,0 +1,94 @@
+# `clock`（Time + Alarm）概览
+
+本项目的 `clock` 是 llmswitch-core 的 ServerTool，用于给模型/MCP提供两类能力：
+
+1. **获取时间**：可通过工具调用 `clock(action="get")` 获取机器可解析的当前时间（UTC + 本地时间）与 NTP 校时状态。
+2. **设置闹钟/提醒**：可通过工具调用 `clock(action="schedule")` 写入持久化的 session 级任务；到点后在后续请求中注入提醒文本，提示模型进行工具调用。
+
+更详细的设计/语义说明见：`docs/SERVERTOOL_CLOCK_DESIGN.md`。
+
+## 1) 时间从哪里来？（System + NTP）
+
+`clock` 的“当前时间”以 `nowMs` 为基准：
+
+- **系统时间**：`Date.now()`（毫秒）
+- **NTP 校时**（可选）：后台通过 SNTP（UDP/123）向 NTP 服务器获取偏移量 `ntpOffsetMs`，并用 `nowMs = Date.now() + ntpOffsetMs` 作为“校正后的当前时间”
+
+默认 NTP server 列表（可通过环境变量覆盖）：
+
+- `time.google.com`
+- `time.cloudflare.com`
+- `pool.ntp.org`
+
+相关环境变量：
+
+- `ROUTECODEX_CLOCK_NTP=0|false|off`：禁用 NTP
+- `ROUTECODEX_CLOCK_NTP_SERVERS=host1,host2,...`：自定义 NTP servers
+- `ROUTECODEX_CLOCK_NTP_STALE_AFTER_MS=<ms>`：NTP 状态多久后视为 `stale`（默认 6h）
+
+NTP 状态持久化路径（落在运行时 session 根目录下）：
+
+- `$ROUTECODEX_SESSION_DIR/clock/ntp-state.json`
+
+## 2) 时间输出格式（Time Tag）
+
+当 `clock` 功能启用后，Hub Pipeline 会在每次请求的 messages 末尾追加一条 **`role=user`** 的时间标签（Time Tag），格式如下：
+
+```
+[Time/Date]: utc=`2026-02-02T21:22:38.229Z` local=`2026-02-02 13:22:38.229 -08:00` tz=`America/Los_Angeles` nowMs=`1770038558229` ntpOffsetMs=`-12`
+```
+
+字段含义：
+
+- `utc`：ISO8601 UTC 时间
+- `local`：本地时间字符串（含毫秒 + 时区偏移）
+- `tz`：服务端 `Intl.DateTimeFormat().resolvedOptions().timeZone`
+- `nowMs`：校正后的毫秒时间戳
+- `ntpOffsetMs`：当前使用的 NTP 偏移（毫秒）
+
+注意：
+
+- `Time Tag` 是“提示信息”，不改变系统消息。
+- 内部 servertool followup hops（`serverToolFollowup=true`）会跳过注入，避免死循环/噪声。
+
+## 3) 闹钟/提醒如何工作？（Schedule → Persist → Inject）
+
+### 3.1 `clock` 工具动作
+
+工具名固定为 `clock`，通过 `action` 区分：
+
+- `get`：获取当前时间与 NTP 状态（无需 sessionId）
+- `schedule`：创建提醒任务（需要 sessionId）
+- `list`：列出任务（需要 sessionId）
+- `cancel`：取消指定任务（需要 sessionId）
+- `clear`：清空全部任务（需要 sessionId）
+
+### 3.2 `schedule` 入参（核心字段）
+
+`schedule` 使用 `items` 数组，每项包含：
+
+- `dueAt`：ISO8601（含时区），例如 `2026-01-21T20:30:00-08:00`
+- `task`：提醒文本（建议写清楚“要调用哪个工具、做什么”）
+- `tool`：可选建议工具名（提示用，不强制）
+- `arguments`：可选建议工具参数（JSON 字符串；不用时传 `"{}"`）
+
+### 3.3 持久化位置
+
+每个 session 的任务持久化在：
+
+- `$ROUTECODEX_SESSION_DIR/clock/<sessionId>.json`（`sessionId` 会做安全字符清洗）
+
+### 3.4 触发窗口与“避免同请求死循环”
+
+- 触发窗口：当 `now >= dueAt - dueWindowMs` 视为“到点需要提醒”（默认 60s）
+- 为避免“在同一次 HTTP 请求链里 schedule 后立刻触发”导致死循环：
+  - 若 `schedule` 的 `dueAt` 已经落在触发窗口（`dueAt <= now + dueWindowMs`），系统会为任务写入 `notBeforeRequestId=<当前请求 requestId>`
+  - 在同一请求链（例如 `requestId` 或 `requestId:clock_followup`）内不会投递该任务；必须等到下一次独立请求才会投递
+
+## 4) MCP 如何获取时间/设置闹钟？
+
+两种方式：
+
+1. **主动工具调用**：MCP/模型调用 `clock(action="get")` 或 `clock(action="schedule")`
+2. **被动注入**：每次请求都会看到 `Time Tag`；到点的提醒会被注入为 `role=user` 的提示文本（建议进行工具调用）
+

package/docs/DAEMON_CONTROL_PLANE.md

@@ -0,0 +1,34 @@
+# Daemon Control Plane (single WebUI entry)
+
+## Goal
+WebUI connects to **one** RouteCodex server port and can:
+- discover all local servers
+- broadcast restart
+- manage quota (disable / recover / reset / refresh)
+- fetch a unified snapshot (servers + quota + routing hits)
+
+## Endpoints (daemon-admin, localhost-only, password-auth)
+### `GET /daemon/control/snapshot`
+Returns:
+- discovered local servers (ports + pids + version + ready)
+- quota snapshot (provider states + antigravity raw snapshot)
+- `virtualRouterConfig` (current runtime config snapshot)
+- `policy` + `policyHash` (best-effort read of routing policy from `configPath` on disk; `policy` is a stable, serializable subset of the user config)
+- `antigravityAliasLeases` (best-effort read of `~/.routecodex/state/antigravity-alias-leases.json` when present; used for session lease/binding observability)
+- `llmsStats` (llmswitch-core stats center snapshot; includes routing hits)
+
+### `POST /daemon/control/mutate`
+Body: `{ action: string, ... }`
+
+Supported actions:
+- `servers.restart` (broadcast): sends `SIGUSR2` to other servers; self uses runtime reload when available
+- `quota.refresh`
+- `quota.disable` `{ providerKey, mode: "cooldown"|"blacklist", durationMs }`
+- `quota.recover` `{ providerKey }`
+- `quota.reset` `{ providerKey }`
+- `routing.policy.set` `{ policy }` (writes policy into config file and triggers best-effort broadcast restart)
+- `runtime.restart` (reload config from disk for current server)
+
+## Discovery
+- Uses `~/.routecodex/sessions/*_<port>` + env ports (`ROUTECODEX_PORT/RCC_PORT`) + dev default `5555`.
+- Probes `/health` and filters `server=routecodex`.

package/docs/OAUTH.md

@@ -0,0 +1,172 @@
+# OAuth Guide（认证与刷新）
+
+本页是 RouteCodex / RCC 的 **OAuth 统一说明**：如何认证、如何刷新、以及常见踩坑（尤其是 “我都授权了但服务器不拿 token”）。
+
+> 说明：文中用 `${bin}` 表示 CLI 命令名：release 包是 `rcc`，dev 包是 `routecodex`。
+
+## 1) Token 文件与 `tokenFile` 写法
+
+### Token 存放位置
+
+默认目录：`~/.routecodex/auth/`
+
+常见命名：
+- `qwen-oauth-<seq>-<alias>.json`
+- `antigravity-oauth-<seq>-<alias>.json`
+- `gemini-cli-oauth-<seq>-<alias>.json`
+- `iflow-oauth-<seq>-<alias>.json`
+
+### `tokenFile` 支持两种写法
+
+1) **显式路径**（通用，最稳）：
+
+```jsonc
+"auth": { "type": "qwen-oauth", "tokenFile": "~/.routecodex/auth/qwen-oauth-1-default.json" }
+```
+
+2) **alias（仅文件名，不含路径）**：
+
+```jsonc
+"auth": { "type": "qwen-oauth", "tokenFile": "default" }
+```
+
+当前推荐 Qwen 用 alias：`default`。
+
+- 如果存在 `~/.routecodex/auth/qwen-oauth-1-default.json`，会优先使用它（固定文件名，避免“我刚 reauth 但 server 读的是另一个 seq”的坑）
+- 否则会回退到 `~/.routecodex/auth/qwen-oauth-*-default.json` 中 seq 最新的那份
+
+## 2) 认证（授权登录）
+
+### 2.1 手动认证（通用）
+
+```bash
+${bin} oauth --force qwen-oauth-1-default.json
+```
+
+- `selector` 支持：token 文件 basename、全路径、或 provider id（例如 `qwen` / `iflow` / `antigravity`）
+- `--force`：强制重新授权（一定会走浏览器/portal）
+- 不带 `--force`：如果 token 仍然有效，会直接跳过（避免“每次都让我重新认证”）
+- 如果你希望看到可见窗口（避免 headless 误以为“没弹出来”），加 `--headful`（等价于 `ROUTECODEX_CAMOUFOX_DEV_MODE=1`）
+- 若你的 `oauthBrowser=camoufox`，Qwen 在 `authorize` 页面需要点一次 Confirm；`oauth` 默认会启用 `qwen` auto（等价于 `oauth qwen-auto ...`）
+
+### 2.2 Camoufox 自动化（推荐：Qwen / Gemini / Antigravity / iFlow）
+
+这些命令会用 Camoufox（固定指纹 + profile）帮你自动完成关键点击。
+
+```bash
+${bin} oauth qwen-auto qwen-oauth-1-default.json
+${bin} oauth gemini-auto gemini-cli-oauth-1-youralias.json
+${bin} oauth antigravity-auto antigravity-oauth-1-youralias.json
+${bin} oauth iflow-auto iflow-oauth-1-youralias.json
+```
+
+Qwen 的自动化会在授权页自动点击：
+
+`button.qwen-confirm-btn`（Confirm）
+
+> 如果 auto 失败，会自动退到 headed 模式让你手动完成（Qwen 不走 localhost callback，因此不会再“等不到回调一直卡住”）。
+
+WebUI（daemon-admin）里点 “Authorize OAuth” 时也会强制走 Camoufox；若未安装，会返回错误 `camoufox_missing` 并提示安装命令。
+
+当 token 被标记为 `verify required`（Google 风控校验）时，daemon-admin 会提供 `open` 链接，点击后会用 Camoufox 打开验证 URL（固定 profile + 指纹），不要再用系统浏览器。
+
+CLI `oauth <selector>` 若发现 quota-manager 已将该 alias 标记为 `verify required`，也会打印明确警告与验证 URL（即使 token 文件仍显示 valid）。
+
+同时 CLI 会提供“一步打开”：
+
+- 在 TTY 下会询问是否立刻用 Camoufox 打开验证 URL（默认 **Y**，open-only，不等 callback）
+- 若你希望不提示直接打开：设置 `ROUTECODEX_OAUTH_AUTO_OPEN_VERIFY=1`（或 `RCC_OAUTH_AUTO_OPEN_VERIFY=1`），或在命令上加 `--headful`
+- 若你只想打印 URL：回答 `n`
+
+> 注：quota-manager 状态文件默认读取 `${ROUTECODEX_HOME:-$HOME}/.routecodex/quota/quota-manager.json`（便于测试/沙盒环境重定向）。
+
+Portal 健康检查（`/health`）默认会等待 **300s**（网络慢时避免过早 timeout），可用环境变量调整：
+
+- `ROUTECODEX_OAUTH_PORTAL_READY_TIMEOUT_MS`（总等待）
+- `ROUTECODEX_OAUTH_PORTAL_READY_REQUEST_TIMEOUT_MS`（单次请求）
+- `ROUTECODEX_OAUTH_PORTAL_READY_POLL_MS`（轮询间隔）
+
+Camoufox 自动化（Google / Antigravity / Qwen）相关等待也有独立超时（默认 **300s**，避免网络慢/跳转慢导致误判）：
+
+- `ROUTECODEX_CAMOUFOX_GEMINI_TIMEOUT_MS`（Gemini / Antigravity account/confirm/callback 总等待）
+- `ROUTECODEX_CAMOUFOX_PORTAL_BUTTON_TIMEOUT_MS`（token portal `Continue` 按钮等待）
+- `ROUTECODEX_CAMOUFOX_PORTAL_POPUP_TIMEOUT_MS`（portal 点击后 popup 或同页跳转等待）
+- `ROUTECODEX_CAMOUFOX_PAGE_LOAD_TIMEOUT_MS`（portal 后 OAuth 页 `domcontentloaded` 等待）
+
+> Antigravity/Gemini 的确认按钮点击不依赖文案（locale/font 变化），按容器 selector 点击 primary action。
+
+## 3) 刷新（refresh）是怎么工作的？
+
+### 3.1 后台刷新（默认：静默，不弹窗）
+
+RouteCodex 运行时会启动 token-daemon 做 **后台刷新**（默认提前刷新窗口：到期前 **30 分钟**；可用 `ROUTECODEX_TOKEN_REFRESH_AHEAD_MIN` 覆盖）。
+
+默认情况下后台会先尝试 **静默 refresh**（`openBrowser=false`）。对以下 provider：
+
+- `antigravity`
+- `qwen`
+- `iflow`
+
+当静默 refresh 失败且需要交互式修复时，会尝试用 Camoufox 做 **auto OAuth**（headless），并在 auto 失败时退到 headed 让你手动完成。
+
+为避免“无限认证 / 无限弹窗”，如果连续 **3 次**都等不到用户完成（例如 device-code 超时 / callback 超时），token-daemon 会对该 token **自动暂停**后续后台认证，直到 token 文件被你手动更新（例如执行一次 `${bin} oauth --force ...` 成功写回文件）。
+
+> 需要交互式修复时，使用上面的 `${bin} oauth ...` 显式触发。
+
+### 3.3 403 账户验证（Antigravity / Gemini）
+
+如果上游返回 `HTTP 403` 且包含以下关键字之一：
+
+- `verify your account`
+- `validation_required`
+- `accounts.google.com/signin/continue`
+
+说明账号需要在浏览器里完成验证/风控解除（不是简单的 token 过期）。此时 RouteCodex 会尝试自动拉起 Camoufox 交互式 OAuth/验证流程。
+
+- 对于这类 “Google verify” 403，后台非阻塞 repair 会优先 **直接打开验证 URL**（Camoufox open-only，不等 localhost callback），让路由立即 failover，同时用户可以在 Camoufox 里完成验证。
+
+为避免“无限弹窗/无限认证”，同一个 token（provider + tokenFile）在该类 403 下会有 **30 分钟冷却**（可用环境变量覆盖）：
+
+- `ROUTECODEX_OAUTH_GOOGLE_VERIFY_COOLDOWN_MS`（默认 `1800000`）
+
+另外，所有 **交互式 OAuth repair**（例如持续 401/403 导致的自动 reauth）也有统一冷却，避免在网络抖动或上游风控期内“疯狂弹窗/疯狂认证”：
+
+- `ROUTECODEX_OAUTH_INTERACTIVE_COOLDOWN_MS`（默认 `1800000`）
+
+### 3.2 显式刷新/重登（你主动触发）
+
+- 刷新（有效就跳过）：`${bin} oauth <selector>`
+- 强制重登：`${bin} oauth --force <selector>`
+
+验证 token 状态：
+
+```bash
+${bin} oauth validate all
+```
+
+> `oauth validate ...` 只做读取/校验，不会拉起浏览器。
+
+## 4) 常见问题（非常重要）
+
+### “我都授权了，但服务器不拿 token / 还是 401/403”
+
+按顺序排查：
+
+1) **你的配置里有没有这个 provider**
+   - 例如 Qwen：`virtualrouter.providers.qwen` 必须存在，否则 token 永远不会被使用
+
+2) **`auth.type` 与 `tokenFile` 是否对得上**
+   - Qwen：`"type": "qwen-oauth"` + `tokenFile: "default"`（或写全路径）
+   - 认证生成的文件是否真的在 `~/.routecodex/auth/` 下
+
+3) **token 文件内容是否具备可用字段**
+   - 至少需要 `access_token`（部分 provider 还会有 `api_key`）
+
+4) **你是不是在后台刷新时期待它弹窗**
+   - 默认后台不会弹；需要交互请用 `${bin} oauth --force ...` 或 `${bin} oauth qwen-auto ...`
+
+## 5) 相关文档入口
+
+- 内置 Provider 配置：`docs/PROVIDERS_BUILTIN.md`
+- Provider 类型：`docs/PROVIDER_TYPES.md`
+- Antigravity 指纹/养号：`docs/providers/antigravity-fingerprint-ua-warmup.md`

package/docs/PROVIDERS_BUILTIN.md

@@ -29,9 +29,11 @@
 ### 2) OAuth（tokenFile）
 
 ```jsonc
-"auth": { "type": "qwen-oauth", "tokenFile": "~/.routecodex/auth/qwen-oauth.json" }
+"auth": { "type": "qwen-oauth", "tokenFile": "default" }
 ```
 
+> OAuth 详细说明（认证 / 刷新 / auto）：`docs/OAUTH.md`
+
 ### 3) Cookie（cookieFile）
 
 ```jsonc
@@ -76,8 +78,8 @@
 ### Qwen（OAuth）
 
 - 样本：`configsamples/provider/qwen/config.v1.json`
-- 关键点：`auth.type: "qwen-oauth"` + `auth.tokenFile` 指向你的 token 文件；`compatibilityProfile: "chat:qwen"`
-- 你需要：先完成一次 OAuth 登录生成 tokenFile（或按你自己的路径修改 tokenFile）
+- 关键点：`auth.type: "qwen-oauth"` + `auth.tokenFile: "default"`（或写全路径）；`compatibilityProfile: "chat:qwen"`
+- 你需要：先完成一次 OAuth 登录生成 tokenFile（详见 `docs/OAUTH.md`）
 
 ### iFlow（OAuth）
 

package/docs/PROVIDER_TYPES.md

@@ -24,7 +24,10 @@
   "id": "openai",
   "type": "openai",
   "baseURL": "https://api.openai.com/v1",
-  "auth": { "type": "apikey", "apiKey": "YOUR_API_KEY_HERE" }
+  // 推荐：用环境变量引用，config 可共享/可进 repo
+  "auth": { "type": "apikey", "apiKey": "${OPENAI_API_KEY}" }
+  // 兼容：也支持直接明文写入（不推荐）
+  // "auth": { "type": "apikey", "apiKey": "sk-..." }
 }
 ```
 
@@ -38,7 +41,7 @@
   "type": "openai",
   "baseURL": "https://portal.qwen.ai/v1",
   "compatibilityProfile": "chat:qwen",
-  "auth": { "type": "qwen-oauth", "tokenFile": "~/.routecodex/auth/qwen-oauth.json" }
+  "auth": { "type": "qwen-oauth", "tokenFile": "default" }
 }
 ```
 
@@ -49,7 +52,6 @@
   "id": "tab",
   "type": "responses",
   "baseURL": "https://api.tabcode.cc/openai",
-  "auth": { "type": "apikey", "apiKey": "YOUR_API_KEY_HERE" }
+  "auth": { "type": "apikey", "apiKey": "${TAB_API_KEY}" }
 }
 ```
-

package/docs/QUOTA_MANAGER_V3.md

@@ -0,0 +1,54 @@
+# Quota Manager V3 (Core-Owned)
+
+## Goal
+Make **quota / cooldown / blacklist / auth-verify gating** a *single source of truth* and stop producing router-local cooldown state.
+
+- Routing path remains: `HTTP server → llmswitch-core Hub Pipeline → Provider V2 → upstream`.
+- VirtualRouter **consumes** quota view only; it must not invent cooldown/health decisions in host/server/provider layers.
+
+## Where it lives
+- **llmswitch-core**: `sharedmodule/llmswitch-core/src/quota/*`
+  - `QuotaManager` state machine + persistence contract (`QuotaStore`)
+  - Outputs `ProviderQuotaView` (consumed by VirtualRouter selection)
+- **routecodex host**: `src/manager/modules/quota/antigravity-quota-manager.ts`
+  - Implements `QuotaStore` (I/O only)
+  - Subscribes to `providerErrorCenter` + `providerSuccessCenter` and forwards events into core `QuotaManager`
+  - Feeds Antigravity external quota snapshot into `QuotaManager.updateProviderPoolState(...)`
+
+## Inputs
+1) Provider errors (from Provider V2 → `emitProviderError(...)`)
+2) Provider successes (from HTTP server → `providerSuccessCenter.emit(...)`)
+3) External quota snapshots (Antigravity quota API refresh)
+4) Static metadata per providerKey (authType / priorityTier / apikeyDailyResetTime)
+
+## Outputs
+- `quotaView(providerKey) -> ProviderQuotaViewEntry`
+  - `inPool`, `cooldownUntil`, `blacklistUntil`
+  - `selectionPenalty`, `lastErrorAtMs`, `consecutiveErrorCount`
+
+## Key semantics
+- **HTTP 402** (apikey daily cost limit): blacklist until `resetAt` (prefer upstream `resetAt`, else use `apikeyDailyResetTime`, default `12:00` local).
+- **Antigravity OAuth auth verification required**: blacklist the whole `antigravity.<alias>.*` group with `authIssue=google_account_verification`.
+- **Antigravity thought-signature missing**: cooldown Gemini series keys under `antigravity.<alias>.*` to avoid request storms.
+
+## Config
+You can set the default daily reset time used for **HTTP 402 without upstream `resetAt`**:
+
+```json
+{
+  "virtualrouter": {
+    "quota": {
+      "apikeyDailyResetTime": "16:00Z"
+    }
+  }
+}
+```
+
+- Format:
+  - `"HH:MM"` = local time (server timezone)
+  - `"HH:MMZ"` = UTC time
+- Default: `"12:00"` (local)
+
+## Persistence
+- Core `QuotaManager` persists via host `QuotaStore` at `~/.routecodex/quota/quota-manager.json`.
+- Legacy fallback migration reads `~/.routecodex/quota/provider-quota.json` when the new snapshot is missing.

package/docs/ROUTING_POLICY_SCHEMA.md

@@ -0,0 +1,47 @@
+# Routing Policy Schema (Control Plane)
+
+## Goal
+Provide a **serializable** routing policy snapshot for WebUI, and a single write path that updates the user config on disk and triggers a controlled restart.
+
+This policy is **not** a separate runtime config. It is a stable subset of the user config that maps to llmswitch-core Virtual Router inputs.
+
+## Read: `GET /daemon/control/snapshot`
+The response includes:
+- `routing.policy` (nullable)
+- `routing.policyHash` (nullable; `sha256(stableStringify(policy))`)
+
+The policy is read best-effort from the current server `configPath` on disk.
+
+## Write: `POST /daemon/control/mutate`
+Action:
+- `routing.policy.set` `{ policy }`
+
+Behavior:
+- Writes the policy fields into `virtualrouter.*` in the config file.
+- Reloads the current server runtime from disk (best-effort) without cutting the HTTP response.
+- Sends `SIGUSR2` to other local servers (best-effort) so they restart and pick up the new config.
+
+## Policy object (V1)
+Canonical snapshot shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "virtualrouter": {
+    "routing": { "default": ["provider.model"] },
+    "loadBalancing": { "strategy": "round-robin" },
+    "classifier": {},
+    "health": {},
+    "contextRouting": {},
+    "webSearch": {},
+    "execCommandGuard": {},
+    "clock": {}
+  }
+}
+```
+
+Notes:
+- `virtualrouter.routing` is required; other fields are optional.
+- For compatibility, `routing.policy.set` also accepts a flattened input shape (`{ routing, loadBalancing, ... }`) and will normalize it into the canonical form.
+- The control plane does **not** interpret or validate routing semantics; llmswitch-core remains the single source of truth for routing behavior.
+

package/docs/ROUTING_POLICY_UI.md

@@ -0,0 +1,11 @@
+# Routing Policy UI (planned)
+
+This repo already has a CRUD editor under the daemon-admin “Runtime Routing Pool” tab.
+
+The next step (not implemented yet) is a unified **policy editor** in the control plane that:
+- edits `virtualrouter.routing` tiers (targets/mode/priority) and `virtualrouter.loadBalancing` (strategy/healthWeighted/contextWeighted/aliasSelection)
+- writes to the user config file and triggers a controlled restart (`config-driven` rule)
+
+This doc exists to reserve the contract and avoid ad-hoc runtime patching.
+
+See `docs/ROUTING_POLICY_SCHEMA.md` for the control-plane schema and the `/daemon/control/*` contract.

package/docs/SERVERTOOL_CLOCK_DESIGN.md

@@ -1,15 +1,16 @@
-# ServerTool: `clock`（定时提醒）详细设计（Draft）
+# ServerTool: `clock`（Time + Alarm）详细设计（Draft）
 
-> 目标：在不引入“旁路”执行路径的前提下，为每个 session 提供可持久化的定时提醒能力，并在后续请求中把提醒注入到模型上下文里。
-> 本文是**详细设计**，不包含实现。
+> 目标：在不引入“旁路”执行路径的前提下，为每个 session 提供可持久化的 **定时提醒（Alarm）**，并提供可机器读取的 **当前时间（Time）** 能力给 MCP/模型使用。
+> 本文是**详细设计**，用于约束行为与契约（实现细节以源码为准）。
 
 ## 0. 背景与约束
 
 - 单执行路径：所有模型调用仍必须走 `HTTP server → llmswitch-core Hub Pipeline → Provider V2 → upstream`。
 - llmswitch-core 拥有工具语义与路由：Host/Provider 不得自行修复 tool calls、重写参数或决定路由，只能注入依赖与 IO。
 - Provider 层只做 transport（auth/http/retry/compat），不得理解 payload 语义。
-- 时钟任务必须 **serverId + sessionId** 作用域隔离，避免跨 server 串读（stopMessage 的坑不能再踩）。
-- “过期删除”与“过期也算触发”必须统一：保留期（retention）设为 **20 分钟**（`retentionMs = 20 * 60 * 1000`）。
+- `clock` 的存储根目录由运行时环境变量 `ROUTECODEX_SESSION_DIR` 提供；所有持久化均落在该目录下。
+- “过期删除”与“过期也算触发”必须统一：保留期（retention）默认 **20 分钟**（`retentionMs = 20 * 60 * 1000`）。
+- 所有 “注入（messages/tools）/工具 schema/工具配对” 必须在 llmswitch-core 内完成；Host/Provider 不得做补丁式修复。
 
 ## 1. 需求澄清（本设计采纳的语义）
 
@@ -20,7 +21,7 @@
 
 ### 1.2 调度与触发窗口
 
-- 模型通过调用 `clock` 工具创建任务，形成 `{dueAt, task}` 列表，写入 daemon（持久化）。
+- 模型通过调用 `clock` 工具创建任务，形成 `{dueAt, task, tool?, arguments?}` 列表，写入持久化（按 session 作用域）。
 - 每次请求到来时（对该请求的 session）检查任务是否“到达触发阈值”：
   - 触发窗口定义为：`now >= dueAt - 60s` 即视为到达（“差一分钟到也算，过期也算”）。
   - 过期任务并不立即删除；仅当 `now > dueAt + retentionMs` 才删除。
@@ -30,10 +31,16 @@
 **重要现实约束：没有客户端请求就无法把提醒推送给客户端**（系统当前没有反向推送通道）。
 
 - 本设计的默认投递语义：提醒以 `"[scheduled task:\"...\"]"` 的形式**注入到下一次该 session 的请求**中。
-- “finish_reason=stop 且时间没到就 hold 等待”会把 HTTP 变成长连接并引发代理/超时/资源占用等风险；但在当前需求中**明确要求 hold 且不限制时间**：
-  - 当响应 `finish_reason=stop` 且存在未到达触发窗口的最近任务 `nextDueAtMs`，server 可以保持连接，直到 `now >= nextDueAtMs - 60s` 再继续执行注入/续轮。
-  - 若客户端在 hold 期间断开：server 无法把“同一条响应”推送回客户端；此时任务保持在 daemon 持久化中，**在下一次同 session 的请求到来时**（只要未超过 20 分钟 retention）依然会被判定为 due 并注入提醒。
-  - 若需要“用户完全离线仍能收到提醒”，必须补齐客户端侧机制（例如：客户端定期发起心跳/拉取请求，或新增事件订阅/长轮询 endpoint）。单纯 server 侧 fake 请求给模型不会自动出现在既有客户端 UI 上。
+- 本设计的 best-effort：在 stop/length 场景下允许“短暂 hold + followup”，以便在触发窗口到达时立刻续轮注入提醒（减少“必须等下一次请求”的延迟）。
+  - 默认 **stream/SSE** 与 **非流式（JSON）** 都允许 hold（长轮询/阻塞返回），但必须满足 `holdMaxMs` 上限（默认 60000ms），客户端可随时断开连接取消等待。
+  - 如需关闭非流式 hold（改回“仅下一次请求注入”语义），可在 `virtualrouter.clock` 中设置：
+    - `holdNonStreaming=false`
+    - `holdMaxMs=<ms>`（仍用于限制单次 hold 最长等待）
+
+另外，为避免“同一 HTTP 请求内的二跳/三跳 followup”导致的死循环：
+
+- 当 `schedule` 的目标时间已经落入触发窗口（`dueAt <= now + dueWindowMs`）时，会给任务写入 `notBeforeRequestId=<当前请求 requestId>`。
+- 注入提醒时会把 `notBeforeRequestId` 视为“请求链前缀屏蔽”，即 `requestId === notBeforeRequestId` 或 `requestId` 以 `notBeforeRequestId + ":"` 开头（例如 `:clock_followup`）时，都不会在该请求链内投递提醒。
 
 ### 1.4 与 `stopMessage` 的优先级与交互（必须）
 
@@ -53,6 +60,7 @@
 
 - 工具名：`clock`
 - action：
+  - `get`：获取当前时间（UTC + local）与 NTP 校时状态（机器可解析；同时作为“clock 激活”信号）
   - `schedule`：创建/覆盖任务
   - `list`：列出本 session 未过期任务
   - `cancel`：取消指定任务
@@ -68,7 +76,7 @@
 {
   "type": "object",
   "properties": {
-    "action": { "type": "string", "enum": ["schedule", "list", "cancel", "clear"] },
+    "action": { "type": "string", "enum": ["get", "schedule", "list", "cancel", "clear"] },
     "items": {
       "type": "array",
       "items": {
@@ -87,24 +95,28 @@
             "description": "可选：建议要调用的工具名（仅用于提示，不做强制执行）。"
           },
           "arguments": {
-            "type": "object",
-            "description": "可选：建议工具参数（仅用于提示）。",
-            "additionalProperties": true
+            "type": "string",
+            "description": "可选：建议工具参数（仅用于提示）。JSON string（例如 \"{}\"），避免 strict schema 下的任意 object 结构。",
+            "default": "{}"
           }
         },
-        "required": ["dueAt", "task"]
+        "required": ["dueAt", "task", "tool", "arguments"]
       }
     },
     "taskId": { "type": "string", "description": "cancel 时使用" }
   },
-  "required": ["action"]
+  "required": ["action", "items", "taskId"]
 }
 ```
 
+> 说明：当前实现采用 `strict: true` 的函数工具 schema（对齐 OpenAI Responses 的严格校验），因此 `required` 需要覆盖 `properties` 的全部字段；
+> 对不适用的 action，可使用空数组/空字符串占位（例如 `get` 使用 `items=[]`、`taskId=""`）。
+
 ### 2.3 工具返回（建议）
 
 `clock` 工具返回必须可机器解析，便于模型后续自查：
 
+- `get`：返回 `{ ok, action:"get", active:true, nowMs, utc, local, timezone, ntp:{...} }`
 - `schedule`：返回 `{ ok, scheduled: [{ taskId, dueAt, task }] }`
 - `list`：返回 `{ ok, items: [{ taskId, dueAt, task, deliveredAt? }] }`
 - `cancel`：返回 `{ ok, removed: taskId }`
@@ -117,7 +129,6 @@
 ```ts
 type ClockTask = {
   taskId: string;          // uuid
-  serverId: string;        // 当前 server 实例稳定标识（用于路径隔离）
   sessionId: string;
   dueAtMs: number;         // 毫秒时间戳
   createdAtMs: number;
@@ -127,6 +138,7 @@ type ClockTask = {
   arguments?: Record<string, unknown>;
   deliveredAtMs?: number;  // 成功“注入到某次请求并 commit”后写入
   deliveryCount: number;   // 注入/投递计数（至少 1 次）
+  notBeforeRequestId?: string; // 防死循环：窗口内设置的任务，本 requestId 不允许触发注入
 };
 ```
 
@@ -135,7 +147,6 @@ type ClockTask = {
 ```ts
 type ClockSessionState = {
   version: 1;
-  serverId: string;
   sessionId: string;
   tasks: ClockTask[];
   updatedAtMs: number;
@@ -146,10 +157,9 @@ type ClockSessionState = {
 
 ### 4.1 存储位置
 
-- 统一放在 server-scoped session dir 下，避免跨 server 串读：
-  - 根目录：`~/.routecodex/sessions/<serverId>/`
-- Clock 子目录建议：
-  - `~/.routecodex/sessions/<serverId>/clock/<sessionId>.json`
+- 统一放在 `ROUTECODEX_SESSION_DIR` 下：
+  - 闹钟任务：`$ROUTECODEX_SESSION_DIR/clock/<sessionId>.json`
+  - NTP 校时状态（server-wide）：`$ROUTECODEX_SESSION_DIR/clock/ntp-state.json`
 
 ### 4.2 加载/写入策略
 
@@ -164,10 +174,16 @@ type ClockSessionState = {
 
 在 Hub Pipeline 的 canonicalization 完成后、路由/上游调用前执行注入（属于 llmswitch-core 的职责）。
 
-注入格式（最小实现）：
+注入包括两部分：
+
+1) Time tag（每次请求）：
+   - 在 messages 末尾追加一条新的 `role:user`，内容为 markdown time tag（inline code）：
+     - `[Time/Date]: utc=\`...\` local=\`...\` tz=\`...\` nowMs=\`...\` ntpOffsetMs=\`...\``
+   - 设计意图：避免引入额外 tool-call 语义，减少模型把“时间注入”当作必须响应/执行的工具回合，从而分散注意力或打断会话结构。
 
-- 在请求末尾追加一段系统文本（或 user 文本，二选一，建议 system）：
-  - `"[scheduled task:\"<task>\" tool=<tool?> args=<json?> dueAt=<iso>]"`（字符串格式固定，方便可观测）
+2) Alarm due reminders（仅当本次有到期任务）：
+   - 在请求末尾追加一条 `role:user` 提醒文本，包含到期任务列表，并明确提示：
+     - “你可以调用 tools 完成这些任务；如果 tools 不全，系统会补齐标准工具列表。”
 
 ### 5.2 触发判定
 
@@ -226,6 +242,21 @@ daemon 启动时扫描 `~/.routecodex/sessions/<serverId>/clock/`：
 - 写盘失败：工具错误（fail fast）
 - 同一 session 大量任务：上限策略可后续再加；本设计先不设硬上限（但要有 O(n) 扫描的性能告警/日志）
 
+## 10. NTP 校时（Time 校验与偏移）
+
+- `clock` 在启用后会进行 best-effort NTP 校时（SNTP/UDP 123）：
+  - 维护 `ntpOffsetMs`，用于计算 `correctedNowMs = Date.now() + ntpOffsetMs`。
+  - 失败不阻断请求/不影响闹钟功能；仅更新 `ntp.status=error` 与 `lastError`。
+- 校时状态持久化到 `$ROUTECODEX_SESSION_DIR/clock/ntp-state.json`，用于进程重启恢复。
+
+## 11. 防死循环规则（窗口内设置不在当前请求激发）
+
+当 `schedule` 设置的 `dueAt` 已经落入触发窗口（例如 `dueAt <= now + dueWindowMs`）时：
+
+- 本次请求不注入/不激发提醒（防止同 requestId / followup 路径产生逻辑死循环）。
+- 任务仍会被持久化保存，但写入 `notBeforeRequestId=<currentRequestId>` 作为 guard。
+- 下一次请求（requestId 不同）到来时，会立即满足注入条件并注入一次，然后正常 commit 为 delivered。
+
 ## 9. 与“fake 请求/hold”相关的实验结论（必须先对齐现实）
 
 - 单纯由 server 主动发起一条“fake /v1/responses 请求”，其响应只会返回给**发起该 HTTP 请求的客户端连接**。