dsh-router-core 0.3.20 → 0.4.0

package/README.md

@@ -5,12 +5,15 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/dsh-router-core"><img src="https://img.shields.io/npm/v/dsh-router-core?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square" alt="MIT license"></a>
-  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本：0.1.5-rc.1+" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B-4d6bfe" /></a>
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="DSH 0.1.5" src="https://img.shields.io/badge/DSH-0.1.5-4d6bfe?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="DSH 0.1.7-alpha.2 支持" src="https://img.shields.io/badge/DSH-0.1.7--alpha.2-e400dd?style=flat-square" /></a>
+  <a href="#agent-team-支持"><img alt="Agent Team" src="https://img.shields.io/badge/Agent%20Team-%E2%9C%93-10b981?style=flat-square" /></a>
 </p>
 
 <p align="center">
   <a href="#快速安装">快速安装</a> ·
   <a href="#面板设置--路由">面板</a> ·
+  <a href="#agent-team-支持">Agent Team</a> ·
   <a href="#api-端点openai-兼容3080v1">API 端点</a> ·
   <a href="docs/suppliers.md">供应商开发</a> ·
   <a href="docs/ext.md">扩展开发</a>
@@ -21,6 +24,11 @@
 管理界面在**设置 → 路由**(官方设置页座位,不是自己开的页面)。装好即用,
 不用多开一个 9router、不用维护第二个端口、不用在网关和 DSH 之间搬配置。
 
+**原生支持 Agent Team / 多会话** —— 0.1.7 起每个 team 成员是独立会话,
+dsh-router 按**会话身份**亲和选号:同会话固定落同一个连接(前缀缓存只写一份),
+不同会话尽量铺开到不同连接;多会话共用同号时按会话隔离统计,**不会互相拖累**。
+详见 [Agent Team 支持](#agent-team-支持)。
+
 ![设置 → 路由 面板：概览（用量看板）、供应商、组合、端点与密钥](docs/screenshot.png)
 
 ## 快速安装
@@ -42,16 +50,17 @@ dsh plugin --profile web add dsh-router-core
 
 ## 它解决什么问题
 
-| 能力 | 说明 |
-|---|---|
-| 零额外进程 | 就是 DSH 插件,随 `dsh web` 启停,天然同源(`/router/api/*` 无 CORS、面板嵌在设置里)。 |
-| 扩展即插即拔 | 扩展插件(如 [`dsh-router-ext-rtk`](https://github.com/CARVIN94/dsh-router-ext-rtk))经 `router.ext` 注册,在 bash 执行前改写命令(如加 `rtk` 前缀压缩输出)。面板「扩展」页一键开关,带自检。 |
-| 供应商即插即拔 | 内置供应商随插件分发;更多供应商 = 装一个 DSH 插件(`dsh-router-*`)或放一个 js 文件到 `~/.dsh/profiles/web/suppliers/`。 |
-| 模型不内置 | 供应商只实现差异化能力,模型拉取与缓存由核心统一管,不写死、不过时。 |
-| 策略只写一次 | 组合回退、账号池(选号/冷却/禁用)、响应写入、凭证存储、积分持久化、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告成败,不自己遍历账号、不维护冷却表、不落盘积分——否则每个插件都会长出一份互相不一致的实现,而核心也就无从判断「该不该换号」。 |
-| 凭证单库 | `auths/credentials.sqlite`,供应商凭证不透明 blob,核心统一生命周期,干净可备份。 |
-| 组合即模型 | 建好的组合自动带出为 DSH 模型目录里的 `router` provider 选项,设置 → 模型直接选组合名即可。 |
-| 用量可观测 | 面板概览看板:周期切换、汇总卡、趋势折线、Top 榜、最近请求。 |
+| 能力           | 说明                                                                                                                                                                                                                                                         |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 零额外进程     | 就是 DSH 插件,随 `dsh web` 启停,天然同源(`/router/api/*` 无 CORS、面板嵌在设置里)。                                                                                                                                                                          |
+| 扩展即插即拔   | 扩展插件(如 [`dsh-router-ext-rtk`](https://github.com/CARVIN94/dsh-router-ext-rtk))经 `router.ext` 注册,在 bash 执行前改写命令(如加 `rtk` 前缀压缩输出)。面板「扩展」页一键开关,带自检。                                                                     |
+| 供应商即插即拔 | 内置供应商随插件分发;更多供应商 = 装一个 DSH 插件(`dsh-router-*`)或放一个 js 文件到 `~/.dsh/profiles/web/suppliers/`。                                                                                                                                       |
+| 模型不内置     | 供应商只实现差异化能力,模型拉取与缓存由核心统一管,不写死、不过时。                                                                                                                                                                                           |
+| 策略只写一次   | 组合回退、账号池(选号/冷却/禁用)、响应写入、凭证存储、积分持久化、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告成败,不自己遍历账号、不维护冷却表、不落盘积分——否则每个插件都会长出一份互相不一致的实现,而核心也就无从判断「该不该换号」。 |
+| 凭证单库       | `auths/credentials.sqlite`,供应商凭证不透明 blob,核心统一生命周期,干净可备份。                                                                                                                                                                               |
+| 组合即模型     | 建好的组合自动带出为 DSH 模型目录里的 `router` provider 选项,设置 → 模型直接选组合名即可。                                                                                                                                                                   |
+| 用量可观测     | 面板概览看板:周期切换、汇总卡、趋势折线、Top 榜、最近请求。                                                                                                                                                                                                  |
+| Team 友好      | 按**会话身份**亲和选号:同会话固定同一连接(前缀缓存只写一份),不同会话尽量铺开到不同连接;多会话共用同号时缓存质量**按会话隔离**统计,不会互相拖累。                                                                                                            |
 
 > 面板布局、组合 fallback、连接池/账号池、API key 管理都贴近
 > [9router](https://github.com/decolua/9router),但按 DSH「一切皆插件」的方式
@@ -59,6 +68,35 @@ dsh plugin --profile web add dsh-router-core
 >
 > 供应商开发与接入规范见 [`docs/suppliers.md`](docs/suppliers.md)
 > （契约 / 加载顺序 / 模型统一策略 / 内置供应商参考实现）。
+> 选号/亲和/team 的完整设计与实测见
+> [`docs/pool-sticky-block.md`](docs/pool-sticky-block.md)。
+
+## Agent Team 支持
+
+DSH 0.1.7 的**智能体团队**把任务拆给多个成员,**每个成员是独立会话**,一轮
+team 测试就是多个会话交错发请求。dsh-router 原生适配这个场景:
+
+- **真会话身份** —— 从宿主 `GenerateOptions.sessionId` 拿到权威会话 id
+  (adapter 转成内部头),不再靠猜。有 id 就按 id 亲和,精确、零撞车;
+  外部 OpenAI 客户端拿不到 id 时,回落前缀指纹兜底。
+- **会话亲和选号** —— 同一会话的连续请求**永远落回同一个连接**,前缀在该
+  连接缓存里只写一份,缓存命中率稳定在 ~98%;新会话按游标分发,天然均衡。
+- **fresh 会话优先铺开** —— 多个成员交替到达时,优先分配到**还没被别的会话
+  占用**的连接,各成员尽量独占一个连接;连接数不够时才回绕复用。
+- **按会话隔离的缓存统计** —— 多会话共用同号时,**各会话的缓存质量分开统计**,
+  不会因为别的会话"踩"了同一个号就把这个号误判成"缓存坏了"从而集体降权
+  (消除了 team 场景下的「降权串」)。
+- **底部命中指示** —— 输入框旁的「路由」徽章按**当前会话**显示最近一次命中
+  的连接/积分;点击展开卡片,点外部或 `Esc` 收起(与原生弹层一致)。
+
+> 天花板:**连接数 < 并发成员数**时,多出来的成员必然共用连接 → 前缀缓存互相
+> 驱逐,无法用选号手法消除(上游缓存空间是账号侧物理限制)。要彻底隔离只能
+> **加连接**或**限制 team 并发成员数 ≤ 连接数**。详见
+> [`docs/pool-sticky-block.md`](docs/pool-sticky-block.md) §11。
+>
+> 版本适配:「路由」徽章只在 **DSH ≥ 0.1.7** 出现(0.1.5 的对应座位渲染位置
+> 不同);0.1.5 与 0.1.7 的兼容差异(设置注册、tool 消息形态)统一按宿主版本号
+> 判定。
 
 ## 面板(设置 → 路由)
 
@@ -93,8 +131,7 @@ dsh plugin --profile web add dsh-router-core
   - **链接池** — 账号列表(冷却/禁用/健康数/积分),支持删除;
   - **加链接** — 按供应商能力弹出不同流程:URL 登录(生成链接 → 浏览器登录 → 回调)、
     API key 弹窗(填名字 + key)、轮询登录(登录后自动取凭证);
-  - **签到** — 供应商实现了签到的才显示(如 codebuddy:每日 100 积分,连续第 7 天
-    1000)。核心遍历所有链接逐个签,汇总「N/M 成功 · X 今日已签」;上游「今日已
+  - **签到** — 供应商实现了签到的才显示(如 codebuddy:每日 100 积分,连续第 7 天1000)。核心遍历所有链接逐个签,汇总「N/M 成功 · X 今日已签」;上游「今日已
     签到」按成功处理(幂等),账号额度或凭证失效会单独标出;
   - **刷新** — 刷所有链接的积分,并跑一次最简会话探测该供应商是否还有活着的链接
     (走真实对话路径 + 账号池回退,能分清是账号额度没了还是供应商真挂了);
@@ -131,24 +168,25 @@ curl -X POST http://localhost:3080/v1/chat/completions \
 
 ## 面板 API(`/router/api/*`,同源)
 
-| 端点 | 方法 | 说明 |
-|---|---|---|
-| `/health` | GET | 供应商列表(含来源/能力) |
-| `/status` | GET | 全部账号(含供应商 id) |
-| `/models` | GET | 合并模型列表(已过滤禁用) |
-| `/combos` | GET | 组合 fallback 链 |
-| `/keys` | GET/POST | 密钥列表(含完整 key)/ 创建 `{name}` → 返回明文一次 |
-| `/keys/toggle` | POST | `{id, isActive}` |
-| `/keys/delete` | POST | `{id}` |
-| `/settings` | GET/PATCH | `{requireApiKey}` |
-| `/ext` | GET/PATCH | 扩展插件列表 + 开关 `{id, enabled}`(见下) |
-| `/stats` | GET | 用量统计 `?period=today\|24h\|7d\|30d`(汇总 + Top 榜 + 最近请求 20 条) |
-| `/stats/chart` | GET | 趋势图数据 `?period=…`(today/24h = 24 小时桶,7d/30d = 天桶) |
-| `/stats/clear` | POST | 清空全部用量统计 |
-| `/suppliers/:id/login` | POST | 生成登录链接 |
-| `/suppliers/:id/login/callback` | POST | `{callbackUrl}` → 加账号 |
-| `/suppliers/:id/models` | GET | 模型 + 启用状态 |
-| `/suppliers/:id/models/toggle` | POST | `{id, enabled}` |
+| 端点                            | 方法      | 说明                                                                   |
+| ------------------------------- | --------- | ---------------------------------------------------------------------- |
+| `/health`                       | GET       | 供应商列表(含来源/能力)+ 宿主版本 `hostVersion` / 徽章支持位 `lastHitDock` |
+| `/last-hit`                     | GET       | 最近一次命中 `?session=<id>`(按会话取,缺省全局);供「路由」徽章 |
+| `/status`                       | GET       | 全部账号(含供应商 id)                                                  |
+| `/models`                       | GET       | 合并模型列表(已过滤禁用)                                               |
+| `/combos`                       | GET       | 组合 fallback 链                                                       |
+| `/keys`                         | GET/POST  | 密钥列表(含完整 key)/ 创建 `{name}` → 返回明文一次                     |
+| `/keys/toggle`                  | POST      | `{id, isActive}`                                                       |
+| `/keys/delete`                  | POST      | `{id}`                                                                 |
+| `/settings`                     | GET/PATCH | `{requireApiKey}`                                                      |
+| `/ext`                          | GET/PATCH | 扩展插件列表 + 开关 `{id, enabled}`(见下)                              |
+| `/stats`                        | GET       | 用量统计 `?period=today\|24h\|7d\|30d`(汇总 + Top 榜 + 最近请求 20 条) |
+| `/stats/chart`                  | GET       | 趋势图数据 `?period=…`(today/24h = 24 小时桶,7d/30d = 天桶)            |
+| `/stats/clear`                  | POST      | 清空全部用量统计                                                       |
+| `/suppliers/:id/login`          | POST      | 生成登录链接                                                           |
+| `/suppliers/:id/login/callback` | POST      | `{callbackUrl}` → 加账号                                               |
+| `/suppliers/:id/models`         | GET       | 模型 + 启用状态                                                        |
+| `/suppliers/:id/models/toggle`  | POST      | `{id, enabled}`                                                        |
 
 ## 扩展插件(`router.ext`)
 
@@ -186,11 +224,14 @@ curl -X POST http://localhost:3080/v1/chat/completions \
             ├─ StatsTab          概览:用量看板(周期按钮组 + 汇总卡 + 折线趋势 + Top 榜 + 最近请求)
        ├─ SupplierDetail    供应商详情:链接池 + 加链接 + 可用模型
        ├─ EndpointTab       端点 URL + requireApiKey + 密钥管理
+       └─ LastHitDock       「路由」徽章(composer.dock 座位,≥0.1.7;按会话显示最近命中)
        └─ fetch /router/api/*            (同源,无 CORS)
             └─ host 半(src/index.ts)
                  ├─ /v1/models + /v1/chat/completions   (OpenAI 兼容, KeysStore 鉴权)
                  │    └─ RouterAdapter(src/llm/adapter.ts)  OpenAI SSE → DSH StreamChunk
                  │         (usage 经 toTokenUsage 转 DSH 契约,见 docs/suppliers.md)
+                 │         (带 x-dsh-router-session 头:宿主 sessionId → 会话亲和)
+                 ├─ host-version(src/host-version.ts)  按宿主版本号适配 0.1.5 / 0.1.7
                  ├─ KeysStore(src/keys.ts)              密钥库 + requireApiKey
                  └─ Router(路由器) → suppliers[]
                       ├─ OpenCodeSupplier(lib/suppliers/opencode.js) 无账号直连(Zen 免费档,需 CLI 握手)
@@ -200,9 +241,9 @@ curl -X POST http://localhost:3080/v1/chat/completions \
 ```
 
 - **供应商抽象**:可插拔 js 模块只提供**差异化能力**(`status/listModels/getAlias/chatOnce`
-  + 可选登录/签到/加 key);**策略与通用能力**(组合回退、账号池选号/冷却/禁用、
-  连接池排序、模型启用/自定义、别名、凭证、响应写入)由核心统一管。
-  `chatOnce(uid, req)` 一次只服务一个账号,返回成功/失败 + 语义状态,换号由核心决定。
+  - 可选登录/签到/加 key);**策略与通用能力**(组合回退、账号池选号/冷却/禁用、
+    连接池排序、模型启用/自定义、别名、凭证、响应写入)由核心统一管。
+    `chatOnce(uid, req)` 一次只服务一个账号,返回成功/失败 + 语义状态,换号由核心决定。
 - **供应商加载**(三来源,见 [`docs/suppliers.md`](docs/suppliers.md)):
   1. 内置:`lib/suppliers/*.js`(随插件分发,如 opencode)
   2. 用户:`~/.dsh/profiles/web/suppliers/*.js`
@@ -227,6 +268,8 @@ curl -X POST http://localhost:3080/v1/chat/completions \
 
 ## 前提
 
+- **DSH 版本**:`0.1.5-rc.1` 及以上;插件内部按宿主版本号自动适配 0.1.5 / 0.1.7
+  差异(设置注册方式、tool 消息形态、底部徽章);「路由」徽章需 **≥ 0.1.7**;
 - 凭证由 dsh-router 核心统一管(SQLite 库 `<dataDir>/auths/credentials.sqlite`);
 - 供应商接入与开发见 [`docs/suppliers.md`](docs/suppliers.md);
 - 重启 DSH 后 `/v1/*` 即生效;面板管理账号、模型与密钥。

package/docs/pool-sticky-block.md

@@ -255,3 +255,161 @@ pick(round-robin):
 ponytail:会话标识目前靠前缀指纹推断,真要百分百准得等 DSH 在 `ChatRequest`
 透传会话 id(需改契约,不做);指纹对「首条消息就分叉」的客户端(极少见)
 会散得比会话更细,退化为均衡分发,无害。
+
+## 10. 统一模型:会话亲和选号(2026-09-23 落地,废除策略旋钮)
+
+### 10.0 结论先行:没有「策略」
+
+`fallback`(永远取健康池第一个)与 `round-robin`(轮转)**都是没有会话身份
+时代的产物**。有了会话亲和后,二者都错:
+
+- `fallback` 让**所有**会话挤同一个号 → team/多会话下必互踩(§2.1 实测 3.8%)。
+- `round-robin` 的"轮转"语义与亲和"同会话永不换号"直接冲突。
+
+**正确模型只有一条,无需旋钮:**
+
+```
+选号 = f(会话身份, 该 model 下的健康号集合)
+  1. 会话身份 → 亲和键;该键绑定的号仍健康 → 用它
+  2. 无绑定(新会话)→ 从健康池挑一个(避开降权号),记下绑定
+  3. 无身份(指纹算不出)→ 块轮询兜底(§2),这不是"策略",是无身份时的替身
+  4. 该 model 下全不健康 → 交给组合的降级链,换下一个 model(§10.2)
+
+  号数 ≥ 并发会话数 → 每个会话独占一个号,缓存空间互不驱逐
+  号数 < 并发会话数 → 必然有会话共用号 → 共用者互踩,不可消除(见 10.3 天花板)
+```
+
+### 10.1 关键认知边界:会话 id = 选号稳定性,不是缓存隔离
+
+**必须分清**,否则会做出错误期望:
+
+| 能力 | 会话 id 能带来吗 |
+|---|---|
+| 选号时认出"这是哪个会话",避免误绑 | ✅ 能 |
+| 保证同一会话永远绑同一个号(不漂移) | ✅ 能 |
+| **同一个号上,不同会话的缓存各占一块、互不驱逐** | ❌ **不能** |
+
+上游 prompt cache 是 `per-account × per-conversation` 命名空间,**同一个号
+上的缓存空间是共享的、会被互相驱逐的**。session id 只是"货物标签",帮上游
+知道哪批是哪批;**仓库满了照样扔货**,不会因为标签不同就给每批货独立仓位。
+
+证据:§2.1 实测那 3 个并发会话本就走不同的对话内容(等价于不同 id 语义),
+照样只命中 3.8% —— **驱逐是账号侧物理限制,不归 id 管**。
+
+> 所以「号不够就共用号 + 靠会话 id 分开缓存」**前半成立(选得准)、
+> 后半不成立(缓存仍互踩)**。
+
+### 10.2 组合 = 降级链(不是轮转)
+
+组合(一组模型)的语义统一为:**从第一个模型起顺序尝试,谁先服务成功就
+停**。原 `round-robin` 组合(换模型轮转)**删除** —— 因为换模型 = 换供应商
+= 整段前缀缓存作废,与亲和的价值直接冲突。
+
+```
+组合选模型: start = 0 恒定(删掉 rrCursors 游标与 strategy 字段)
+  对 combo.models[i] 依次:
+    chatWithModel(该模型的降级链) → 成功即停
+    瞬时故障 → 等 TRANSIENT_SETTLE_MS 再试下一个(§已有)
+  全失败 → 503 combo: all models unavailable
+```
+
+选号(§10.0)与选模型(本节)是**正交的两条轴**:前者在"单个 model 的账号池"
+内做亲和,后者在"多个 model"间做降级。二者的共同点:**都只按"身份 + 健康性"
+决策,不按"轮转"**。
+
+### 10.3 天花板(ponytail)
+
+1. **号数 < 并发会话数时必然互踩** —— 物理限制(缓存空间有限),只能
+   **加号**或**限制 team 并发成员数 ≤ 号数**,任何选号手法都消除不了。
+2. ~~**会话身份目前靠前缀指纹推断**~~ —— **2026-09-23 已落地真会话 id**(见 §11):
+   宿主 `GenerateOptions.sessionId` → adapter 转成 `x-dsh-router-session` 头 →
+   核心按会话亲和。指纹降为**无会话身份时的兜底**(外部 OpenAI 客户端)。
+3. **上游 TTL 仍未知**(§8):长会话若间隔超过 TTL,miss 是上游行为,
+   不误判成选号问题。
+
+### 10.4 废除的旧配置
+
+| 旧字段 | 处置 |
+|---|---|
+| `supplier-config.json` 的 `poolStrategy` | **静默忽略**:读盘不解析,写盘不产出;旧文件不报错,下次保存自动瘦身 |
+| `combos.json` 的 `strategy` | 同上 |
+| `GET/POST /suppliers/:id/pool/strategy` 路由 | 删除 |
+| 面板「连接池策略」「组合策略」下拉 | 删除(选项无意义则不该占位) |
+
+### 10.5 为什么这不是"回退/轮询"的合并,而是概念删除
+
+旧的两策略试图用**一个旋钮**回答两个不同的问题("要不要均衡" vs "要不要
+粘缓存"),而这两个问题在亲和下**同时被回答了**:亲和天然均衡(新会话按
+游标分发)+ 天然粘缓存(同会话固定号)。旋钮消失不是"合并了两个选项",
+是**承认这个问题本身提错了** —— 不存在"要不要均衡"的选择,只有"按身份
+选号"这一个正确答案。
+
+## 11. Agent Team 支持(2026-09-23 落地)
+
+DSH 0.1.7 的**智能体团队**(agent team)把一个任务拆给多个成员,**每个成员
+是一个独立会话**(TeamId = Lead 的 SessionId;成员各自独立 `sessionId`)。
+这正好把 §10 的"多并发会话"从理论变成日常 —— 一轮 team 测试就是 3 个会话
+交错发请求。本节记录为此做的三件事。
+
+### 11.1 真会话 id 通道(替代前缀指纹)
+
+宿主 `dsh-llm` 的 `GenerateOptions.sessionId` 是**权威会话身份**。链路:
+
+```
+dsh-llm GenerateOptions.sessionId
+  → RouterAdapter 发请求时带 `x-dsh-router-session: <sessionId>`
+  → 核心 /v1 读进 ChatRequest.session
+  → 选号: sessionFingerprint(session, messages) = session!=空 ? `sid:<session>` : 前缀指纹
+  → 落账: UsageRecord.session
+  → 面板: /router/api/last-hit?session=<id> 按当前会话取「最近命中」
+```
+
+要点:
+- **有会话 id 时以它为主键**("sid:xxx"),精确、零撞车;指纹只在**拿不到
+  会话 id 时**(外部 OpenAI 客户端)兜底。`sessionFingerprint` 就这一行分叉。
+- 会话 id 是**选号稳定性**凭证,**不是缓存隔离**承诺 —— 见 §10.1,别混淆。
+
+### 11.2 fresh 会话优先「铺开」到空闲号
+
+三个 fresh 成员交替到达时,若只按全局游标分发,会**回绕撞号**(实测:
+Lead 与 T1 撞同一个号,T2 独占)。改为**占用感知分配**(`allocSession`):
+
+```
+新会话分配:
+  1. 先算「本 model 下没有被其它会话绑定的空闲号」(freeUids)
+  2. 空闲号非空 → 从空闲号里按游标挑 → 各会话尽量独占一个号
+  3. 空闲号用尽 → 才回绕到已占用的号复用(复用无害,见 §11.3)
+```
+
+"占用"= 该 model 的亲和绑定表里,**其它**指纹当前指向的 uid;同一会话自己
+的旧绑定不算占用(它改绑不冲突)。号数 ≥ 会话数 → 每个会话独占;号数 <
+会话数 → 必然复用(物理限制,§10.3)。
+
+### 11.3 缓存质量样本按会话隔离(消除「降权串」)
+
+**症状**(实测):team 3 个会话全落到同一个号,且该号看起来"缓存坏了"。
+
+**根因**:`samples`(缓存质量样本)与 `demoted`(降权)的键原为
+`(supplier, model, uid)`,**没有会话维度**。多会话共用同号时,各自前缀在
+该号缓存里互相驱逐 → 命中率被**混在一起算** → 跌破阈值 → 误判"这个号缓存
+坏了" → 降权 → 所有会话被挤到剩余号 → 那个号又被同样机制打低 → **降权串**。
+
+**修法**:键改为 `(supplier, model, uid[, session])`(`sampleKey`)。有会话
+身份时**按会话隔离统计**,降权只反映「这个会话在这个号上真的反复不命中」,
+不因别的会话共用同号而被牵连。无会话身份(外部客户端走无指纹路径)保持
+`(model, uid)` 原语义。
+
+回归测试:`account-pool.test.ts` 的「多会话共用同号互踩 → 不误伤降权」——
+两会话各在该号服务 24 次、命中率 50%,旧逻辑立刻误降权,新逻辑不降;
+同时锁死"单会话自己真攒满 48 次全 miss 仍会被降权"(隔离 ≠ 免疫)。
+
+### 11.4 天花板(ponytail)
+
+- **隔离让降权更迟钝**:会话越分散,单个会话攒满样本越慢 → 降权触发越晚。
+  这是**想要的**(宁可慢也不要误伤)。要更快感知真坏号,调小 `BLOCK_MAX`
+  (当前 48)。
+- **号数 < 成员数仍互踩**:隔离只是**不误判**,不改变"缓存空间共享"这个
+  物理事实(§10.1/§10.3)。真要不互踩只能加号或减少并发成员。
+- **每会话一份样本 → 内存随会话数增长**:`samples` 按会话分叉,长跑多会话
+  场景条目变多。当前无上限(随进程存亡),量大时再加 LRU(对齐 `AFFINITY_MAX`
+  的做法)。