# 架构与实现细节

> 这份文档回答"它是怎么做到的、为什么这么做"，面向要改代码或排查问题的人。
>
> - 安装、使用、常见问题 → [README.md](README.md)
> - 逐版改动与真机事故复盘（现场 → 根因 → 修法 → 断言） → [CHANGELOG.md](CHANGELOG.md)
> - 主题式改动清单与取舍 → [MODIFICATIONS.md](MODIFICATIONS.md)

---

## 1. 包的三半

| 半边 | 干什么 |
|---|---|
| `lib/index.js`（宿主） | 空逻辑 + 一次客户端产物静态核对（`lib/client.js` 与 `lib/client.picker.js` 分开报）。存在的唯一理由是让本包成为 cordis 树上的一行，否则 `dsh.client` 的 bundle 不会被扫进启动图 |
| `lib/client.js`（客户端·接线） | 不可见锚点（注册进 `conversation.input.right`，用来拿 `sessionId` 与 `ctx`）+ **DOM 桥** + 官方菜单那行的滑条（`react-dom` portal 注入官方那一行）+ 自建浮层的接线 |
| `lib/client.picker.js`（客户端·自建面板） | 按参考实现复刻的自建浮层：收起态按钮 / 两级面板 / 模型档位徽标 / 常驻滑条 / 档位弹层。它是**包内动态 chunk**（宿主的 `client.*.js` 规则），由 `require.async("./client.picker.js")` 取；取不到时只有它消失，官方菜单那条路照常 |

`lib/client.js` 是**手写的发布产物**（`require("react")` / `require("react-dom")` 走宿主模块表的平台种子词）；
自建浮层那一半有一步构建：源码 `lib/client.picker.src.js` → `npm run build` → 自注册 chunk `lib/client.picker.js`。

**chunk 必须自己注册**（真机踩过一次）：客户端模块表按包名建表，同步 `require("包名/子路径")` 会抛
"missed the module table"；包内 chunk 要用 `require.async("./client.picker.js")` 取，文件名必须匹配 `client.*.js`。
宿主对 chunk 的响应体**只做拼接、不包壳**，所以裸 ESM 的 `export` 会在脚本标签里直接语法错 ——
表现是"入口按钮根本不出现、控制台很安静"。第 32 节断言按真宿主的方式加载这个文件，防止再退回去。

---

## 2. 两套界面（A / B）与默认开关

默认只启用 B。两套 UI 同时挂在同一个输入区里会互相干扰（官方那一行里会多出一条滑条），
所以 `lib/client.js` 里的编译期开关二选一：

```js
ENABLE_OFFICIAL_MENU_SLIDER = false;   // true = 回到 A（改造官方菜单），同时关掉 B 的接管
```

### A. 官方菜单那一行（1.x 起，默认关闭）

直接改造官方模型菜单里的「推理等级」那一行 —— 那一行被加高上下内距、允许折行，滑条作为第二行铺满整行；
拖到最高档时整条轨道亮起紫色能量层。另外往官方菜单里加**三处只读注记**（都只 append，不改官方任何文字）：

```
点开官方模型菜单后：
┌──────────────────────────────────────────────┐
│ 模型             DeepSeek-V41-Flash › deepseek│  ← 归属标签（provider，一级页就能确认）
├──────────────────────────────────────────────┤
│ 推理等级                       Max ›  max    │  ← 数值文字跟着变色；右侧灰字是原始 API 取值
│ ●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    │  ← 插件注入的滑条（这一行因此被加高）
└──────────────────────────────────────────────┘

点「模型」进二级页（官方那一屏）：
  DeepSeek-V41-Flash  [4 档]
  gpt-6-astra         [8 档]
  gpt-6-luna          [7 档]
  gpt-6-spark         [5 档]
  gpt-4o              [不支持]
输入框工具行：**不加任何东西**（没有胶囊、没有浮层）
```

### B. 自建浮层（1.3.0 起；1.3.2 起**接管官方那颗模型席按钮**）

输入框右侧那颗 `模型名 · 档位名 ⌄` 就是它 —— **没有第二颗**（见第 3 节），
点开是**两级面板**（挂在 `conversation.input.overlay`，所以不会被 composer 卡片裁掉）：

```
收起态：  [ DeepSeek-V41-Flash · Max ⌄ ]

点开后：
┌──────────────────────┐
│ 模型                  │
│ DeepSeek      V41-Flash ›│   ← 一级页：provider 行 + 该 provider 当前选中的模型名
│ OpenAI                ›│
├──────────────────────┤        点 provider → 同一块面板**横向翻页**到二级：
│ 推理等级          Max ⌄│      ┌──────────────────────┐
│ ●━━━━━━━━━━━━━━━━━━━ │      │ ‹ DeepSeek           │
└──────────────────────┘      │ [搜索模型…          ] │
                              │ DeepSeek-V41-Flash ✓ │
                              │ DeepSeek-V41-Pro  4 档│
                              │ Plain Model    不支持 │
                              └──────────────────────┘
点档位名展开弹层：每行 = 档位名 + 原始 API 取值
  Off   off
  Low   low
  High  high   ✓
  Max   max
```

两页是**同步位移**的（`page1 0 → -100%` / `page2 +100% → 0`），所以边界全程贴合；
点模型**不关面板**、滑条立刻跟到新模型的档位（这是"自建面板"相对内置注入的关键好处：
内置注入借官方菜单的 DOM，官方菜单一关就跟着没了）。

面板的位置口径（1.3.4 定稿）：**右缘贴 composer 卡片右缘**、**底边贴触发器上方 8px**；
**滚动 / 窗口缩放只重定位、不关闭** —— 助手流式输出时聊天区会一直自动滚动，
早先"滚动即关闭"会把面板关掉。触发器被宿主 `hidden`（助手在跑时 composer 会藏起控件行）时保持原位。

面板材料（1.3.9 / 1.3.10）走官方菜单那一套令牌：

| 项 | 取值 |
|---|---|
| 模糊 | `backdrop-filter: var(--dsw-menu-backdrop-filter, blur(40px) saturate(150%))`（官方令牌定义在 `body` 上，自定义属性会继承） |
| 底色 | 官方色相 + 比官方**再透一档**：浅色 `rgba(248,249,250,.46)`、深色 `rgba(67,69,74,.40)`（官方填充令牌是 `.58` / `.45`） |
| 阴影 | `--dsw-elevation-stroke` + `--dsw-shadow-lv3` + 一层落地阴影；深色另给一套 |
| 推理等级卡片 | 半透明（浅色 `rgba(255,255,255,.55)`、深色 `.06`）——实心卡片会把毛玻璃整个抵消 |
| 滚动安全网 | 在**面板自己**那层（`.cxp-panel{overflow:auto}`）；定位壳 `.cxp-root` 必须 `overflow:visible`，否则会把面板的 `box-shadow` 裁成矩形 |

---

## 3. 接管官方模型席（1.3.2 起）

官方那颗席按钮注册在槽位 `conversation.input.model`，那是一个 **single 槽**，官方注册时没写 `priority`（= 0）。
single 槽**同优先级撞了会抛错**，换优先级就是"遮蔽"（最低者渲染）—— 所以本插件用 `priority: -1` 接管：

| 时序 | 行为 |
|---|---|
| 官方席先出现 | 直接接管（注册 `priority: -1` 的 occupant） |
| 工具行先出现 | 先挂在 `conversation.input.right`，官方席随后出现时撤掉那条再接管（两个回调同一批同步执行，看不到闪动） |
| 官方席始终没有 / 注册抛错 | 工具行那条就是最终落点 |

**最差也只是回到"两颗按钮"，绝不会两边都没有。** 另外接管意味着那份"报告"也归我们了：
官方菜单会显示"目录正在加载 / 没有可用 provider / 某个 provider 加载失败"，
这些状态现在画在自建面板里（含宿主**逐 provider** 的失败原文），并且高度算得下它们。

`locked` 是那个槽的 **owner prop**（官方席按钮就吃它）：接管之后这条语义跟着接过来，
输入区被锁住时我们那颗也不可点。紧凑态沿用官方的两个变量
（`--dsh-composer-model-text-display` / `--dsh-composer-model-icon-display`）。

---

## 4. DOM 桥依赖的官方锚点（全是**语义属性**，不是哈希 class）

| 锚点 | 官方产物里的形状 |
|---|---|
| 席：`button[aria-haspopup="menu"][aria-expanded="true"]` | `<button aria-haspopup="menu" aria-expanded={open} aria-controls={…}>` |
| 菜单：席的 `aria-controls` → `getElementById(…)` | 菜单 `id={…-menu}`，portal 到 body |
| 目标行：菜单里 `button[role="menuitem"]` 的**第 2 个** | 根面板恰好两行（模型 / 推理等级）；子面板用 `menuitemradio`，所以 `menuitem` 唯一标识根面板 |
| 模型行：`button[role="menuitemradio"][id$="-model-N"]` → `.optionCopy > .modelName` | 档位徽标按**行上的模型名**认（不用 id 里的序号：那是筛选后的位置） |
| 档位行：没有 id 的 `button[role="menuitemradio"]` | 原始 API 取值按文档顺序对上 `reasoning.efforts` |
| 根面板行：`.cellLabel` / `.cellValue` / `.cellChevron` | provider 归属标签追加在最后 |
| 滚动容器：`.scrollable`（字面量 class） | 翻页稳定化（`overflow-anchor:none` + 滚动清零） |
| 归属判定：从自己的锚点向上找 `[data-composer-card]` | composer 卡片带这个标记；打开的那颗席必须在**自己的** composer 里 |

**只改那一行**：写 4 个内联样式（`height:auto` / `flex-wrap:wrap` / `padding-block:10px`）+ append 一个容器；
关菜单或插件卸载时逐个还原。不碰官方 class、不改官方文字与 chevron。
**三处注记**（徽标 / 归属标签 / API 取值）同样只 append，不改官方任何文字，也不改它的 hover/focus 机制。

**fail-open**：任何一步认不出（没有 `aria-controls`、不是根面板、不是自己的 composer、
目录里没有档位、会话作用域没就绪）就**什么都不做** —— 官方菜单保持原样，绝不会因为本插件点不开。

官方菜单是"测量后固定定位"的，插件加高那一行后会派发一次 `resize`，
官方自己的 `place()` 会重新读 `offsetHeight` 并重新夹取位置。

---

## 5. 数据路径（只用官方公开面）

| 用途 | 接口 |
|---|---|
| 读档位 | `directoryFor(sessionId).store.getSnapshot()` → `groups[].models[].reasoning.efforts` |
| 读**能力索引**（徽标用） | 同一份快照：`groups[].models[].reasoning`（缺席 = 该模型不支持推理等级） |
| 写档位 | `directory.select({ provider, model, reasoningEffort })`（与官方菜单同一写入口） |
| 订阅 | `store.subscribe()` + `React.useSyncExternalStore` |

**能力清单是活数据，不是本地快照**：徽标上那个"几档"直接来自 `reasoning.efforts` 的长度；
本地只留一张 9 键的档位字典（`LV`）用来**校验**未知档位 id 与补显示名，以及一张 GPT 家族的兜底清单
（只在目录没列到某个模型、或那一行认不出名字时才用）。

---

## 6. 目录访问器（每会话一个，永不抛错）

`directoryFor(sessionId)` 在会话作用域/绑定尚未就绪时**按设计抛错**，目录实例也会被宿主重建
（换模型代、连接重置）。所以每个会话一个访问器，把这几件事都兜住：

- **解析失败就退避重试**（60ms 起，约 9 秒），之后由 1.5s 心跳兜底；实例换了就把订阅重挂到新 store 上。
- **两条会话 id 来路互为备份**：标准 kit 的 `sessionId` 优先、`inject` 拿到的 `binding.key` 兜底，
  坏的自动轮换到好的（`inject` 只回私有键 `__sessionKey`，**不能**回 `{sessionId}` —— 那会盖掉 kit 里正确的值）。
- **load 失败会自愈**：按退避重试；"就绪但空"（宿主 provider 还没注册完就返回了一个合法空目录，
  而且那个结果**会被缓存**）则主动借用官方 resolver 的 `catalog.refresh()` 刷一次 —— 8 秒冷却、最多 3 次。
- **`phase()` / `reason()` 给界面说人话**：`unresolved`（我们还没拿到）/ `no-session`（还没有会话）/
  `loading` / `empty`（宿主就绪但没列 provider）/ `ready` / `error`，失败时把**宿主原话**摆到面板上。
- **插件级 `inject` 必须声明 `remote` / `remote.session`**：Cordis 的服务访问跟着调用方 ctx 走，
  而 `directoryFor()` 给新 binding 建实例时要访问 `this.ctx.remote.session`。接管官方席之后我们是
  唯一的调用方（官方组件不再渲染，命中不了它建好的缓存），少了这两个声明就会抛
  `cannot get property "remote.session" without inject`，界面永久停在"会话目录未就绪"。

---

## 7. 色彩与粒子（**由位置连续驱动**，与档位数无关）

拖到哪，颜色与粒子就跟到哪。三个纯函数（都有断言）：

| 位置 `pct` | 颜色 `fillColorFor` | 能量 `energyFor` | 粒子数 `particleCountFor` | 速率 `speedFor` |
|---|---|---|---|---|
| 0（第一档） | 蓝 `#4d93f8` | 0 | 0 | 0.35× |
| 1/3（第二档） | 蓝（**第一档到第二档恒为蓝**） | 0 | 0 | 0.35× |
| 2/3（high） | 紫 `#9333ea` | 0.5 | 11 / 22 | **1×** |
| 1（max） | 深紫 `#4c1d95` | 1 | 22 / 22 | **2×** |

- **颜色**：填充层是 `linear-gradient(90deg, 蓝, 当前位置的颜色)` —— **左端恒为蓝、右端是当前位置的颜色**，
  所以 high 档自然呈现"左蓝右紫"，越往右右端越深。
- **能量层**（紫色星云 + 扫光）强度 = `energyFor`，它在第二档以前是 0 —— 所以左半段是**干净的蓝**；
  官方那一行的紫边透明度也跟着能量走（`0.16 + 0.34 × energy`）。
- **能量条只覆盖已填充那一段**：能量层宽度与填充层完全相同（都到旋钮圆心），
  档位右边没达到的部分只剩轨道底色。
- **Off 档在两个界面里都保持官方灰**（`isOffLevel` + `valueColorFor` 返回**空串** = 不写内联色）。
  档位是不是"关"按 **id 和 name 都认**（`off`/`none`/`关闭`/`无`，大小写与空格不敏感）。
- **档位数变了也是一条连续曲线**：能量只看**位置**，与"这是 4 档还是 8 档模型"无关。
  8 档模型下 `Max`（位置 6/7）已是后段的 **11/14 ≈ 0.786**；而"半能量"这个锚点仍是
  4 档模型的 high（位置 2/3）= 0.5。（参考实现给 8 档走 `(n-2)/(n-1)` 回退，本插件统一成一套。）
- **刻度点更小更淡**：`5px → 3px`；已达刻度 `rgba(255,255,255,.92) → .5`，未达刻度
  `color-mix(... 38% → 26%)` —— 改小改淡之后不再和星尘抢眼。
- **星空**（所有出现粒子的档位共用一套）：
  - **不消失**：外层是**整轨宽度**的轨道，自己连续 `translate3d(-100%)` 横穿；
    残影只在 0%/6% 与 94%/100% 淡出淡入 —— 那两端在可视区外。
  - **亮度随机、越亮越大**：每颗的亮度/大小系数由确定性伪随机给出，落在 **0.5 ~ 1**；
    圆点用 `opacity:var(--ces-b)` + `transform:scale(var(--ces-b))`。
  - **速度随位置变化**：横穿时长 = `STARFIELD_DURATION_MEAN × MAX_SPEED_FACTOR / speedFor(pct)`
    —— MAX 档 1.5s、high 档 3s、第二档附近约 8.6s。
  - **星星单独一层，不跟星云淡入**：星云层透明度 = 能量强度，high 档只有 0.5；
    星星若套在里面会被压到 0.25~0.5、在紫底上几乎看不见。所以星星放在独立层，
    透明度 = `starLayerOpacityFor`（high 档 **0.8**、MAX 档 **1.0**），"逐渐出现"交给**粒子数**表达。
  - **各星之间只差 ±8%**（`STARFIELD_DURATION_SPREAD`）：保留"有的稍快有的稍慢"的层次，
    又不会快星追上慢星排成一队。
  - **高度 = 随机排列的等距槽位，并与相位解耦**（8%~92% 用满轨道高度）：早期版本高度和相位取自
    同一个数，于是"越靠右的星越高"、22 颗排成一条斜线（相关系数实测 0.999）；现在是确定性随机排列，
    并自动挑一个盐值保证**相位相邻**的两颗至少差 28% 轨道高。相关系数实测 **−0.110**（断言 `|r| < 0.35`）。
  - **相位只跟 index 有关、跟"当前显示几颗"无关**（黄金比低差异序列，任意前缀都铺得开）：
    拖动改变粒子密度时不会改写已挂载动画的 `animation-delay`，进档那一下不会被整体重排。
  - **时长与相位内联写在元素上**（`animationDuration` / `animationDelay`），不走 CSS 变量；
    "减少动态效果"的放缓也顺势在 JS 里算（`REDUCED_MOTION_SLOWDOWN`）。
  - 伪随机是**确定性**的（不用 `Math.random`）：重渲染不跳变，且可离线断言。

**"聚集"的量化对照**（模拟真产物参数，轨道 300×28px，两星中心距离 <6px 记为粘住）：

| t=0.2s（刚进档） | t=0.4s | t=1s | t=2s | t=3s |
|---|---|---|---|---|
| 3 对 → **0 对** | 1 对 → **0 对** | 4 对 → 2 对 | 7 对 → 4 对 | 4 对 → **0 对** |

**长期行为（如实标注）**：只要每颗星时长不完全相同，相位就会缓慢互相错开，最终趋近随机分布。

| 每颗星时长浮动 | t=0.5s | t=1s | t=2s | t=5s |
|---|---|---|---|---|
| **±8%（当前）** | 1 | 7 | 9 | 17 |
| ±4% | 0 | 2 | 7 | 10 |
| ±2% | 0 | 0 | 2 | 11 |
| **0%（全同速）** | **0** | **0** | **0** | **0** |

想彻底永不聚集，把 `STARFIELD_DURATION_SPREAD` 设成 0（代价是所有星速度完全一致）。

- **官方那一行的数值文字也会跟着变色**（`valueColorFor`）：与能量同源，**蓝 → 靛 → 紫罗兰**。
  写的是内联 `color`（内联优先于官方样式表），关菜单时由桥还原；**文字内容一个字都不碰**。
  终点色 `#8b5cf6` 是照着对比度挑的：白底 **4.23:1**、深色底 **4.02:1**（测试里有对比度断言挡着）。
  先试过更亮的 `#c084fc`，浅色主题只有 2.6:1、发虚。
- **收起态的模型席按钮**同样着色：官方那一小段文字是**哈希 class**（前缀随构建变），所以按**文字**认
  —— 官方 trigger 里的文字就是档位的 `name`，与目录里读到的是同一份数据。传的是**全部档位名**而不是
  "当前那个"：档位刚切换、官方还没重渲染时文字还是旧的，只认当前名字会在那一瞬间掉色。
  席上显示的是**已生效**档位，所以拖动过程中它不跟着草稿跳，提交后才变。
- **`prefers-reduced-motion`**：**放缓而不是冻住** —— 收起扫光、粒子周期 ×2.6，
  并在滑条 `title` 里说明原因。
- **配色跟随主题**：轨道底色用 `--dsw-alias-border-l1`；浅色/深色都自动跟随。
  星尘是例外：**固定浅色**（`#eaf0ff`）—— 它永远飘在蓝→紫的填充层上，跟随主题令牌会在浅色下变成深色小点。
  旋钮同理固定白（`#fff`）。

---

## 8. 旋钮几何（顶头适配）

旋钮是**正圆，直径 = 轨道高度**（`TRACK_HEIGHT = KNOB_SIZE = 28px`），圆心只在 `[14px, 宽度 − 14px]` 之间移动：

```
left = calc(14px + pct × (100% − 28px))     ← 旋钮、填充终点、刻度共用这一个几何
```

所以 `pct=0` 时圆心落在左端圆角内、`pct=1` 时落在右端圆角内，圆**永远是完整的圆**
（早期圆心跑到两端之外，圆被 `overflow:hidden` 切掉右半边，看起来像圆角方块）。
指针映射用同一套内缩几何（`pctAt`），所以拖到最左/最右必定命中端点档位。

面板视口高度是**算式**而不是 DOM 测量（离线测试台没有布局引擎），所以行高常量（`SEC_H` / `ROW_H` /
`MODEL_H` / `EMPTY_H` / `FAILURE_H`…）**必须与 CSS 同步**，第 30 节有"算式与 CSS 实算一致"的断言盯着。

---

## 9. 稳健性清单（每一条都有断言）

- `directoryFor()` 在会话作用域就绪前抛错 → 退避重试 + 心跳自愈；档位数是**后到**的，
  桥会在档位数变化时主动重扫（DOM 不会因为 store 变化而产生 mutation）。
- 写入失败 / 超时（10s）→ 回滚到真实档位并显示原因，**不谎报成功**。
- 拖动写入有**同档位去重 + 在途合并 + 260ms 停顿去抖**：连续拖动期间 **0 次**写回，
  指针停住或松手才落地；落在当前档位时也是 0 次。
- 滑条吞掉自己的 pointer/click 事件（**不接管方向键**），不会误触官方那一行的 `onClick`。
- 组件卸载时清掉去抖定时器；桥卸载时还原那一行的样式并摘掉容器。
- **禁用态每帧重算**（不做增量 patch）：目录这一代给不出可读档位时，滑条灰掉且不吃指针，
  并把 `aria-disabled` 同步进无障碍树。
- **翻页那一帧把滚动位置清回 0**：官方换内容时的 `.focus()` 不带 `preventScroll`，加上给那一行加高
  触发的 scroll anchoring，本来会多出一次位移。菜单根与官方 `.scrollable` 都关掉 `overflow-anchor`，
  清除动作在 mutation 回调里同步做（早于绘制）。
- **面板不因滚动而消失**：滚动/缩放只重定位；触发器不可见时保持原位。
- **插件整包被宿主丢弃时**（`package.json` 带 BOM 那次的现场）：`rows: []`、界面毫无反应，
  插件管理器的插件详情页会给出 `Unexpected token ...` —— 所以第 44 节断言钉住"清单不能带 BOM"，
  同时钉住两个 `.ps1` **必须**带 BOM（PowerShell 5.1 的规则是反的）。

---

## 10. 测试台与断言策略

`test/harness.mjs` 里有一份**保状态**的 React 桩、够用的假 DOM（含 portal、MutationObserver、
多属性/class/子串选择器、滚动位置、focus 记录、`getBoundingClientRect`）、以及一个**假官方菜单**
（形状逐字对齐官方产物，含模型列表与档位列表两个二级页）。本机没有可离线使用的真 React
（`app.asar` 里不带），所以渲染层是桩件驱动的；**数据路径与 DOM 注入路径跑的都是真代码**。

假宿主还复刻了三条真内核的规矩，否则"接管官方模型席"这件事在离线根本测不出来：

1. 槽没被声明就不能注册（真内核原话：`slot "X" is not declared`）；
2. `inject` 是"**等**那个槽出现"，没声明就一直不回调（所以插件得自己有退路）；
3. **single 槽同优先级撞了会抛错**，换优先级就是"遮蔽"（最低者渲染）。

另外它还复刻了：`ModelDirectoryResolver.directoryFor()` 对无效会话 id 抛错、
**调用方 ctx 缺 `remote.session` 时抛真机那句原话**、以及"目录实例按 binding 缓存"的行为。

第 12 节断言会**直接读解包出来的官方产物**校验那些语义锚点还在（`aria-haspopup` / `aria-expanded` /
`aria-controls` / `role="menuitem"` / `role="menuitemradio"` + 官方文案 + `resize` 重测），
官方改版导致锚点漂移时会先炸测试，而不是静默失效。本机没有解包产物时该节自动跳过。

跑法：`npm test`（当前 **911** 项断言）。断言分布是**按主题**归并的手工表，见
[MODIFICATIONS.md](MODIFICATIONS.md)。