@jsonstudio/rcc 0.90.876 → 0.90.1270

package/docs/chat-process-continuation-state-contract.md

@@ -0,0 +1,196 @@
+# Chat Process Continuation / State Contract
+
+## 索引概要
+- L1-L8 `purpose`：定义 chat process 统一 continuation/state 语义真源。
+- L10-L28 `ssot`：唯一真源与边界。
+- L30-L78 `schema`：统一语义 schema。
+- L80-L112 `stage-ownership`：req/resp/inbound/outbound/router 各自职责。
+- L114-L154 `migration`：Responses 专属字段向统一语义迁移表。
+- L156-L183 `acceptance`：四协议矩阵验收口径。
+
+## 目标
+
+按 Jason 的要求，把所有协议的 continuation/state/tool-loop/response continuity 统一收口到 **chat process request + response**。
+
+### 唯一真源
+
+统一语义真源定义为：
+
+- `ChatEnvelope.semantics.continuation`
+- `ChatEnvelope.semantics.audit.protocolMapping`
+
+### 边界规则
+
+1. **inbound** 只做 `format_parse + semantic lift`，不得持有协议语义真源。
+2. **req chat process** 是 request continuity/state 的唯一读写点。
+3. **resp chat process** 是 response continuity/state 的唯一恢复点。
+4. **outbound** 只做协议映射和显式 audit，不得新增协议专属状态机。
+5. **router** 只能消费统一 continuation semantics，不得继续直接读取 `responsesResume` / `previous_response_id` 等协议私有键。
+6. **host/provider** 可保留 transport/store 实现，但对 hub 暴露的只能是统一 continuation semantics，不得把协议私有状态继续向下游泄漏。
+
+---
+
+## 统一语义 Schema
+
+## `chat.semantics.continuation`
+
+```ts
+{
+  chainId?: string
+  previousTurnId?: string
+  resumeFrom?: {
+    protocol?: string
+    requestId?: string
+    responseId?: string
+    previousResponseId?: string
+    turnId?: string
+  }
+  stickyScope?: 'request_chain' | 'session' | 'conversation' | 'request'
+  stateOrigin?: 'openai-responses' | 'openai-chat' | 'anthropic-messages' | 'gemini-chat' | 'servertool-followup' | 'tool-loop' | 'unknown'
+  restored?: boolean
+  toolContinuation?: {
+    mode?: 'required_action' | 'submit_tool_outputs' | 'tool_calls' | 'tool_outputs' | 'servertool_followup'
+    pendingToolCallIds?: string[]
+    submittedToolCallIds?: string[]
+    resumeOutputs?: JsonValue[]
+  }
+  protocolHints?: JsonObject
+}
+```
+
+### 语义要求
+
+- `chainId`
+  - 跨协议 continuation 的统一链路主键。
+  - 目标：替代 Responses 特判 `previousRequestId -> stickyKey`。
+- `previousTurnId`
+  - 上一轮在 chat process 统一视角下的 turn 标识。
+  - 不等同于某个协议专属 `response_id`。
+- `resumeFrom`
+  - 保存“从哪里恢复”的协议锚点。
+  - 允许保留协议原始锚点，但只能作为 continuation 子字段，不得散落 metadata。
+- `stickyScope`
+  - router continuity 的统一口径。
+  - 后续 router 只能读这个字段，而不是协议特判。
+- `restored`
+  - 表示本轮请求/响应是否由历史 continuation 恢复而来。
+- `toolContinuation`
+  - 表示当前 continuation 是否属于 tool loop / followup。
+  - `resumeOutputs` 是统一工具结果面，不再要求协议侧各自保存一套恢复结构。
+- `protocolHints`
+  - 仅保留协议侧需要的最小恢复提示。
+  - 不能成为协议语义第二真源。
+
+## `chat.semantics.audit.protocolMapping`
+
+```ts
+{
+  protocolMapping?: {
+    preserved?: Array<{ field, disposition, reason, sourceProtocol?, targetProtocol?, source? }>
+    lossy?: Array<{ ... }>
+    dropped?: Array<{ ... }>
+    unsupported?: Array<{ ... }>
+  }
+}
+```
+
+### 语义要求
+
+- 所有协议转换导致的保留 / 有损 / 丢弃 / 不支持，都要进入统一 audit 面。
+- 不允许再只有 Anthropic/Gemini 记录 dropped/lossy，而 OpenAI Chat / Responses 没痕迹。
+- audit 是 **映射结果**，不是状态真源；只能由 inbound/outbound mapper 写入。
+
+---
+
+## Stage Ownership
+
+## Request Path
+
+### inbound
+- 允许：
+  - parse client protocol
+  - lift protocol fields -> `semantics.continuation`
+  - 记录 mapping audit
+- 禁止：
+  - 保存协议私有 continuation 状态为 router 真源
+  - 继续把 `responsesResume` 等散落在 metadata 中供下游读取
+
+### chat_process.req
+- 唯一职责：
+  - continuation/state/tool-loop 统一承接
+  - route continuity 所需的统一字段装配
+  - request side 保真恢复
+
+## Response Path
+
+### chat_process.resp
+- 唯一职责：
+  - 从 provider/compat/inbound 结果恢复统一 response continuity semantics
+  - 将 required_action / tool_outputs / previous response continuity 统一到 chat 语义面
+
+### outbound
+- 允许：
+  - 从统一语义恢复协议字段
+  - 对无法等价恢复的字段写 audit
+- 禁止：
+  - 再持有协议专属 continuation/state 真源
+  - 再新增 host/provider 侧语义补丁
+
+## Router
+
+- 只能读取：
+  - `semantics.continuation.chainId`
+  - `semantics.continuation.stickyScope`
+  - `semantics.continuation.resumeFrom`
+- 禁止直接读取：
+  - `metadata.responsesResume`
+  - `previous_response_id`
+  - protocol-specific sticky 特判字段
+
+---
+
+## Responses → 统一语义迁移表
+
+| 当前字段 | 目标字段 | 说明 |
+|---|---|---|
+| `metadata.responsesResume.previousRequestId` | `semantics.continuation.chainId` | Router continuity 统一主键 |
+| `metadata.responsesResume.restoredFromResponseId` | `semantics.continuation.resumeFrom.responseId` | 恢复锚点 |
+| `previous_response_id` | `semantics.continuation.resumeFrom.previousResponseId` | 保留协议锚点，但不再作全局真源 |
+| `responsesResume` | `semantics.continuation + semantics.responses.resume` | 前者是跨协议统一层；后者保留协议专属补充 |
+| `tool_outputs` / submit payload | `semantics.continuation.toolContinuation.resumeOutputs` + `chat.toolOutputs` | 统一工具结果面 |
+| Responses sticky request-chain 特判 | `semantics.continuation.stickyScope='request_chain'` | 清掉 router 特判 |
+
+### 迁移原则
+
+1. `semantics.responses.*` 继续保留，但只作为 **Responses 协议专属补充**。
+2. 跨协议共享能力必须优先进入 `semantics.continuation`。
+3. 任何模块若继续直接读取 `responsesResume` 作为全局 continuation 真源，视为架构违规。
+
+---
+
+## 四协议矩阵验收口径
+
+覆盖：
+
+- `openai-responses`
+- `openai-chat`
+- `anthropic-messages`
+- `gemini-chat`
+
+每个方向至少验证：
+
+1. **Request Continuation**
+   - continuation fields 是否进入 `semantics.continuation`
+2. **Response Continuation**
+   - response continuity / tool required_action 是否能回到统一语义面
+3. **Route Continuity**
+   - sticky key 是否来自统一 continuation，而不是协议特判
+4. **Mapping Audit**
+   - preserved / lossy / dropped / unsupported 是否完整显式记录
+
+### 通过标准
+
+- chat process req/resp 两侧都能观察到统一 continuation semantics。
+- inbound/outbound 不再承担协议语义真源。
+- 无 audit 的协议降级视为失败。
+- 非 Responses 协议即使不能 1:1 恢复协议私有字段，也必须明确标记为 `lossy` / `dropped` / `unsupported`，不能静默塌缩。

package/docs/chat-semantic-expansion-plan.md

@@ -2,6 +2,8 @@
 
 > 目标：让 llmswitch-core 中的 Chat Process / Standardized 桥承接四种协议的语义，不再依赖 metadata 透传 “raw payload”，并按顺序分阶段完成。
 
+> continuation/state 统一真源见：`docs/chat-process-continuation-state-contract.md`
+
 > 术语约定：本文中的 “chat process” 指代码层面的 `chat_process` 阶段（工具治理/路由/协议重建的必经处理段）。
 
 ### 阶段 0：现状确认

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

@@ -61,11 +61,11 @@
 ```jsonc
 [
   {
-    "id": "iflow-oauth-1-186",
+    "id": "glm-oauth-1-186",
     "kind": "oauth",
     "providerFamily": "gemini",
-    "alias": "iflow-186",
-    "tokenFile": "~/.rcc/auth/iflow-oauth-1-186.json",
+    "alias": "glm-186",
+    "tokenFile": "~/.rcc/auth/glm-oauth-1-186.json",
     "projectId": "my-project",
     "expiresAt": 1736500000000,
     "expiresInSec": 3600,
@@ -86,11 +86,11 @@
 
 ```jsonc
 {
-  "id": "iflow-oauth-1-186",
+  "id": "glm-oauth-1-186",
   "kind": "oauth",
   "providerFamily": "gemini",
-  "alias": "iflow-186",
-  "tokenFile": "~/.rcc/auth/iflow-oauth-1-186.json",
+  "alias": "glm-186",
+  "tokenFile": "~/.rcc/auth/glm-oauth-1-186.json",
   "projectId": "my-project",
   "expiresAt": 1736500000000,
   "expiresInSec": 3600,
@@ -112,7 +112,7 @@
 ```jsonc
 {
   "ok": true,
-  "id": "iflow-oauth-1-186",
+  "id": "glm-oauth-1-186",
   "status": "valid", // valid | invalid | error
   "checkedAt": 1736500100000,
   "message": "Token accepted by upstream."
@@ -131,7 +131,7 @@
 ```jsonc
 {
   "ok": true,
-  "id": "iflow-oauth-1-186",
+  "id": "glm-oauth-1-186",
   "status": "refreshed",
   "expiresAt": 1736503600000
 }
@@ -228,7 +228,7 @@
     "protocol": "gemini-chat",
     "series": "gemini-pro",
     "enabled": true,
-    "boundCredentialId": "iflow-oauth-1-186",
+    "boundCredentialId": "glm-oauth-1-186",
     "health": {
       "status": "ok",
       "lastErrorAt": null,

package/docs/design/provider-failure-policy-ssot.md

@@ -0,0 +1,215 @@
+# Provider Failure Policy SSOT 设计
+
+## 索引概要
+- L1-L8 `purpose`：本设计文档的目标与适用范围。
+- L10-L31 `single-cognition`：唯一认知理念（什么是唯一真源、什么是第二中心）。
+- L33-L58 `current-audit`：当前已确认的分裂实现与风险。
+- L60-L101 `target-architecture`：目标架构与唯一职责分配。
+- L103-L131 `execution-rules`：执行期硬规则（retry/backoff/health/direct return）。
+- L133-L170 `migration-plan`：分阶段迁移计划。
+- L172-L189 `acceptance`：验收信号。
+
+## 目的
+本设计用于收口 **provider 执行期错误处理 / retry / reroute / backoff / health 影响** 的唯一真源。
+
+适用范围：
+- `request-executor`
+- `provider-error-classifier`
+- `provider-error-reporter`
+- `provider-traffic-governor`
+- `Virtual Router policy` 消费链
+
+不适用范围：
+- 业务 payload 语义转换
+- tool harvest / chat-process 语义
+- 非 provider 执行期的 CLI / HTTP 外层错误映射
+
+## 唯一认知理念
+
+### 1. 一份事实只能有一个 owner
+对于 provider 执行期错误，以下事实只能各有一个真源：
+- 这是不是 **recoverable**
+- 这是否 **affectsHealth**
+- 这次应该 **direct return / same-provider backoff / explicit reroute**
+- 这次 backoff 的 **scope / key / duration**
+
+如果这些事实分别由 `request-executor`、`provider runtime`、`error reporter`、`router` 各自推一次，系统就一定漂移。
+
+### 2. emit 不是 policy
+`emitProviderError(...)`、event bus、registry、center 这类模块只负责 **传输事件**，不负责定义 retry/reroute/backoff/fail 语义。
+
+谁负责做 policy，谁才是真源；
+只做 `emit/forward/normalize` 的层，不能再偷偷夹带第二份判断。
+
+### 3. orchestrator 不能自带第二大脑
+`RequestExecutor` 允许负责：
+- 执行 sleep / wait / retry loop
+- 调 provider
+- 记录 telemetry
+
+但不允许再独立决定：
+- recoverable / unrecoverable
+- affectsHealth
+- should exclude current provider
+- should reroute
+
+否则它就不是 orchestration shell，而是第二个 policy center。
+
+### 4. recoverable 与 unrecoverable 是第一分叉，不是附属字段
+全局先问：**错误是否可恢复**。
+
+然后再决定：
+- unrecoverable → 直接返回
+- recoverable → 阻塞 + 指数 backoff
+
+禁止先做“切 provider 试试”，再回头补 recoverable 判定。
+
+### 5. health 是 policy 投影，不是 transport 猜测
+provider health 只能来源于统一 policy 计算结果。
+provider transport / converter / reporter 不得再根据自己看到的局部信息直接推导 health 影响。
+
+## 当前审计结论
+已确认当前仍存在多处第二中心：
+
+1. **错误分类双真源**
+- `src/server/runtime/http-server/request-executor.ts`
+- `src/providers/core/runtime/provider-error-classifier.ts`
+
+2. **retry/backoff 决策双真源**
+- `src/server/runtime/http-server/executor-provider.ts`
+- `src/server/runtime/http-server/request-executor.ts`
+
+3. **health 影响双真源**
+- `request-executor.ts -> isHealthNeutralProviderError(...)`
+- `provider-error-classifier.ts -> affectsHealth`
+- `provider-error-reporter.ts` 还有默认兜底口径
+
+4. **等待/阻塞分裂**
+- recoverable backoff gate
+- provider transport backoff gate
+- provider traffic governor concurrency wait
+
+其中流量并发闸门可独立存在，但“错误后的阻塞等待策略”必须统一由 failure policy 产出，而不是多个调用点各自算。
+
+## 目标架构
+
+```text
+provider/runtime/send/convert error
+  -> ProviderFailurePolicy.classify(error, stage, context)
+  -> ProviderFailurePolicy.decide(classification, route context, retry context)
+  -> decision {
+       recoverability,
+       affectsHealth,
+       action,
+       backoff
+     }
+  ->
+     A. RequestExecutor 执行 decision（wait / retry / direct return）
+     B. ProviderErrorReporter 仅上报 decision 结果
+     C. Virtual Router 仅消费 decision-affecting event / policy projection
+```
+
+### 单一模块职责
+新增唯一策略块：`ProviderFailurePolicy`
+
+它是唯一允许回答以下问题的地方：
+1. `classification`: `special_400 | recoverable | unrecoverable`
+2. `affectsHealth`: `true | false`
+3. `action`:
+   - `direct_return`
+   - `retry_same_provider`
+   - `reroute_explicit_alternative`
+4. `backoff`:
+   - `none`
+   - `attempt`
+   - `recoverable`
+   - `provider`
+   - 带 `key/base/max/ms`
+
+### 各层改造后职责
+
+| 层 | 允许做什么 | 禁止做什么 |
+| --- | --- | --- |
+| `ProviderFailurePolicy` | classify / decide / backoff-plan / health-impact | 执行真实 sleep / 发请求 |
+| `RequestExecutor` | 调 policy，执行 wait/retry loop，打日志 | 另写一份 classification / exclusion / health 逻辑 |
+| `provider-error-classifier` | 删除或降为 thin adapter | 自己独立决定 recoverable/health |
+| `provider-error-reporter` | 只转发已决定的 recoverable/affectsHealth/details | 自己补默认 policy |
+| `Virtual Router policy consumer` | 消费统一事件，更新健康/冷却投影 | 反向猜 host/provider 本应如何 retry |
+
+## 执行期硬规则
+
+### Rule 1: 不可恢复错误
+- 直接返回 HTTP 错误
+- 不 retry
+- 不 reroute
+- 不高频重放
+
+### Rule 2: 可恢复错误
+- 只能 **block + 指数 backoff**
+- 默认 `retry_same_provider`
+- 不能先 exclude 当前 provider 再制造 `PROVIDER_NOT_AVAILABLE`
+
+### Rule 3: reroute 不是默认恢复手段
+只有在 **policy 明确证明存在显式替代候选** 且属于允许 reroute 的语义时，才允许 `reroute_explicit_alternative`。
+
+没有证据，就不能把 reroute 当“试试看”。
+
+### Rule 4: recoverable 默认 health-neutral
+只要是 recoverable provider 执行期错误，默认不毒化 provider health。
+
+### Rule 5: reporter 不得二次脑补
+`emitProviderError(...)` 的输入必须已经带上明确的：
+- `recoverable`
+- `affectsHealth`
+- `classification`
+- `stage`
+
+reporter 只能透传，不得 fallback 成另一套语义。
+
+## 迁移计划
+
+### Phase A：审计定稿
+- 盘点所有 recoverable / affectsHealth / shouldRetry / exclude / backoff 实现点
+- 标记 active path / compat shell / dead residue
+- 文档化迁移边界
+
+### Phase B：抽单一策略块
+- 新建 `ProviderFailurePolicy`
+- 收入口：
+  - classification
+  - health impact
+  - retry action
+  - backoff plan
+- 为策略块补单测
+
+### Phase C：Host 执行器去脑化
+- `request-executor.ts` 改成只：
+  - 调 policy
+  - 执行 decision
+  - 记录 telemetry
+- 删除本地重复 helper
+
+### Phase D：Provider runtime 去脑化
+- `provider-error-classifier.ts` 降级或删除
+- `base-provider.ts` / `responses-provider.ts` 不再自产 recoverable/health 语义
+- provider 层仅上报 transport/context 原始事实
+
+### Phase E：Reporter 去默认语义
+- `provider-error-reporter.ts` 不再自己推断 `affectsHealth=true`
+- 缺少明确 policy 字段时直接视为调用方 bug，而不是帮忙兜底
+
+### Phase F：回归与在线验证
+- TypeScript 编译
+- request-executor / error-reporting / traffic governor 定向回归
+- 构建、安装、重启、真实请求验证
+
+## 验收信号
+1. 仓内只剩一个地方能定义 recoverability。
+2. 仓内只剩一个地方能定义 affectsHealth。
+3. `request-executor` 不再保留独立 exclusion/backoff/health 判定 helper。
+4. `provider-error-reporter` 不再含 policy fallback 语义。
+5. 429 / `fetch failed` / `SQLITE_BUSY` / 5xx 不再触发 storm / `PROVIDER_NOT_AVAILABLE` 连锁。
+6. 在线日志里 recoverable 错误统一表现为：
+   - `switch=retry_same_provider`
+   - `decision=recoverable_backoff_same_provider` 或 `provider_backoff_same_provider`
+   - 无匿名风暴式 sibling 冲击。

package/docs/design/reasoning-stop-lifecycle.md

@@ -0,0 +1,90 @@
+# Reasoning Stop / Stopless Lifecycle
+
+## 1. Scope
+
+本文定义 `reasoning.stop` / `stopless:on` / `stopless:endless` 的真实需求与唯一停止条件。
+
+目标：
+
+1. `stopless` 只影响“模型准备停止时”的自检与续轮。
+2. `reasoning.stop` 是停止前的结构化闸门，不是普通业务工具。
+3. `endless` 语义必须与实现一致，禁止出现“文档允许、代码禁止”或“提示词允许、validator 拦截”的矛盾。
+
+## 2. 指令语义
+
+### 2.1 `<**stopless:on**>`
+
+- 默认继续执行，不要直接 stop。
+- 停止前必须先调用 `reasoning.stop` 做结构化自检。
+- 允许停止的情况：
+  1. **任务已完成**；
+  2. **已穷尽可行尝试且遇到不可抗阻塞**。
+
+### 2.2 `<**stopless:endless**>`
+
+- 比 `on` 更强调“只要还有 next_step 就继续执行”。
+- 但 **不是绝对禁止停止**。
+- 允许停止的情况同样只有两类：
+  1. **任务已完成**；
+  2. **已穷尽可行尝试且遇到不可抗阻塞**。
+
+> 结论：`endless` 的真实需求是“默认强制继续”，不是“永不停止”。
+
+## 3. Canonical stop conditions
+
+### 3.1 完成态停止
+
+当且仅当：
+
+- `is_completed = true`
+- `completion_evidence` 非空
+
+才允许按“已完成”停止。
+
+### 3.2 不可抗阻塞停止
+
+当且仅当以下条件同时满足，才允许按“不可抗阻塞”停止：
+
+- `is_completed = false`
+- `next_step` 为空
+- `attempts_exhausted = true`
+- `cannot_complete_reason` 非空
+- `blocking_evidence` 非空
+
+如果还需要用户参与，则再额外要求：
+
+- `user_input_required = true`
+- `user_question` 非空
+
+## 4. 非法停止
+
+以下情况都不应直接 finalize stop：
+
+1. 还有 `next_step`
+2. 只有“做不到”的口头描述，没有 `blocking_evidence`
+3. 没写 `attempts_exhausted=true`
+4. 标记了 `user_input_required=true`，但没有 `user_question`
+
+这些情况应继续执行，或回到 guard 提示模型补齐结构化信息。
+
+## 5. Runtime anchors
+
+- request-side tool injection:
+  - `sharedmodule/llmswitch-core/src/conversion/hub/pipeline/hub-pipeline-chat-process-request-utils.ts`
+- stop payload normalization:
+  - `sharedmodule/llmswitch-core/src/servertool/handlers/reasoning-stop.ts`
+- stop/finalize/continue guard:
+  - `sharedmodule/llmswitch-core/src/servertool/handlers/reasoning-stop-guard.ts`
+- sticky state:
+  - `sharedmodule/llmswitch-core/src/servertool/handlers/reasoning-stop-state.ts`
+
+## 6. Verification checklist
+
+最少需要覆盖：
+
+1. `stopless:on` 完成态可停止
+2. `stopless:on` 不可抗阻塞可停止
+3. `stopless:endless` 完成态可停止
+4. `stopless:endless` 不可抗阻塞可停止
+5. 有 `next_step` 时两种模式都必须继续
+6. `reasoning.stop` schema / validator / finalize 三处语义一致