mslxdff 0.1.174 → 0.1.176

package/src/routes/AGENTS.md

@@ -1,37 +0,0 @@
-# src/routes — 转发链契约（改 relay / 流式 / 用量前必读）
-
-> 从 `AGENTS.md` 下沉（2026-09-29 分层，就近生效）。改完跑：`node --test --test-concurrency=1 test/stream-*.test.js test/relay-*.test.js test/usage-*.test.js` + `npm run docs:check`。
-
-## 时间量测的两条口径（ADR-0039，最易被改错）
-
-- **保护闸门的零点 = `relay()` 入口的 `t0`**（首帧超时 / stall / MAX_STREAM / keepalive 四类）。**禁止**把上报锚点接进闸门判定，否则上游排队时间会吃掉超时预算、误杀正在出字的慢模型。
-- **上报时长（usage 行）的零点 = 本次上游尝试起点**（`serial-trial` 的 `tUp`，经 `attemptStartMs` 交进 relay）；relay 入口算 `preflightMs = t0 − 锚点` 并随**全部 4 个 return 点**带出，`relay-pipeline` 落行时相加。锚点缺失/负值一律 0。
-- 报表口径与 state 口径**彻底分离**：`recordModelStats`（→ `-status`/`-model stats` 的 EMA）仍吃转发入口相对值，勿"顺手统一"。
-- 首字与总耗时同加一个常数 → `总 − 首字` 恒等 → 速度读数不变（已锁为单测）。
-- usage 行**只增字段**演进（`src/usage/record.js` 拥有行形状）；旧行缺字段 = 未知，不得当 0。
-- 模型日志里 `relay-first-chunk ttfMs=` 是**转发入口相对值**（故意与报表不同源），排查时别混。
-
-## relay 的行为契约（既有测试锁死）
-
-- **超时是显式字段 `timedOut`**，`status` 数值只是 HTTP 语义展示，不得再拿 status 当"是否可 failover"的信号。
-- **注释帧（`: keepalive`）不算首块**：不解除闸门、不触发超时救回，但照常透传；能否安全 failover 看 `detail.wrotePayload`（=是否已**提交**模型产出，见下条留口）。
-- 闸门到点后上游仍吐出真实数据 → **撤销超时判定照常转发**（cancel 是异步的，竞态窗口内已到达的数据是纯收益），记 `detail.recoveries`。
-- 任一闸门到点且未写真实数据 → 回退候选；唯一/末位候选无 failover 去向 → 闸门放宽到 `MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS`（默认 120s，0=不限），防误杀慢模型。
-- **空转 200 判据单一真相** = `stream-scan.js:isEmptyTurnDetail`（`chatShaped===true` 且 `chars===0 && toolCalls===0` 且 `finish_reason ∉ {tool_calls, function_call}`）；relay 侧「要不要封口」与 pipeline 5a0「要不要重拉」都必须用它，两处各写一份必然错拍。判空 → 转 failover，不记 auto 冷却（空转≠模型坏）。错误包络暂扣 `holdableChunk` 与非 chat 形状放行同在 `stream-scan.js`（**不在 stream.js**）。
-- **空轮留口（ADR-0043）**：模型产出（正文/工具/**思考**）出现前，空 delta 帧与 `[DONE]` 一律暂扣不写（`stream-hold.js:createRevocablePrefix`）；流结束仍零产出且未断下游 → **不 `res.end()`**，返回 `heldOpen:true` 交回重拉/换候选，正文续写同一条连接。三条铁律：① 异形/解析失败帧必须立即透传（`isTrivialFrame` 白名单式），透传契约不得为救空轮让路；② `[DONE]` 是终点，错误帧要排在它之前（tail 槽）且全程只允许一个；③ 重入同一条连接时 headers 可能已 flush → `statusCode`/`setHeader` 一律门控，收场经 `endHeldFailure`/`endEmptyTurnStream`/`helpers.json` 的 `writableEnded`+`headersSent` 守卫保证**恰好一次**，禁止把 JSON 体混进 `text/event-stream`。
-- 断下游即掐上游：relay 自持 `reader`（`for-await` 会锁 ReadableStream 使 `body.cancel()` 必 reject），`reader.cancel()` 才真掐得断。
-
-## 组/组员与宽带中继（`src/routes/groups*.js`、`peers.js`、`relay-queue.js`）
-
-- 慢模型不掐当前流：首块 25s 内到即视为可用、后续无限等；stall 15s 仅作质量分，耗时 >20s 降权；`MSLXDFF_HEDGE_DELAY_MS=1000` 时 1s 并发组员赛跑，赢家 `x-mslxdff-via`；指定模型 429 时按延迟 EMA 择优切最快模型。
-- `SLOW_TOTAL_MS=20s` 标 slow 进 5 分钟冷却（普通 60s）；上游重试 `1次×100ms`；`MSLXDFF_STREAM_TIMEOUT_MS=25s`（**仅首块未到且未写出任何字节时**才 failover；`0`=显式关闭首块超时，给重思考模型用）；`MAX_STREAM_MS=120s`。
-- 宽带 `relay://` 成员走 `GET /v1/groups/relay/stream` SSE 单长连 25s ping 直推（`pushToStream`），`MSLXDFF_BROADBAND_STREAM=0` 回退 1s poll，`MSLXDFF_BROADBAND_PING_MS=25000`/`_STALE_MS=90000` 可配（空闲 -96%）；用户明确反对 1s 轮询的空轮询。
-- 组命令语义：`-group list` 序号按 state 成员顺序（过滤 leader）固定渲染，`-group remove <seq>` 用同一顺序踢人（仅组长）；组长 `-leavegroup` 提示改用 `-delgroup`，`-delgroup` 在组员节点报错并提示该组由谁领导。
-- 模型可观测面：事件用**黑名单** `TRACE_DENY`（默认全可见，只排噪声与敏感面）；决定类事件只渲染 `DECISION_FIELDS` 登记过的标量，**"加日志"≠"倒数据"**，payload/正文一律不落；回显取头单一入口 `upstreamEcho(res)`。
-
-## Responses 端点（`routes/responses-route.js` + `responses/translate.js`，ADR-0012）
-
-- 复用 ChatPipeline 全链路，只做形状翻译；stateless（`previous_response_id` 不支持）；**思考档位已透传**：`reasoning.effort` → `reasoning_effort`（change fix-thinking-effort-passthrough / ADR-0053）。
-- Codex Rust 严格解码三特例（缺一整轮作废）：① 对 codex 调用者（UA/originator `codex_*` 或 `?client_version=`）`GET /v1/models` 追加顶层 `models: []`（**必须空**，填真目录会覆盖其内置 agent prompt）；② completed 的 usage 转 Responses 口径（`input_tokens/output_tokens` + details）；③ done 事件 `text` 带累积全文。
-- `-setto chatgpt`（`src/sync-codex.js`）写三端共用 `~/.codex/config.toml`（`wire_api="responses"` 显式、鉴权绝对路径 `node + -showtoken`，换模型需重跑 setto / `codex exec -m` / 手改 `model=`，单键覆盖无需剪枝）；排障 `MSLXDFF_RESPONSES_DEBUG=1` 看 `daemon.log [responses]` 四段 + Codex 侧 `~/.codex/logs_2.sqlite`（`Request completed ... status=`）与 `thread_history_1.sqlite`（正文）。
-- `@ai-sdk/openai` 只是客户端包，替代不了服务端翻译层；Qwen 上游走 `/v1/messages`（Anthropic 协议），接 Codex 要多一跳（未做）。