@mzzsfy/dsh-llm-pi-gateway 0.2.6 → 0.3.0

package/README.md

@@ -1,17 +1,63 @@
 # @mzzsfy/dsh-llm-pi-gateway
 
-DeepSeek Harness pi-ai 透传网关插件:官方 `dsh-llm-pi-ai` 的零感知增强替换——为 newapi 等网关路由提供全协议会话标记(渠道亲和性)、compat 全控、metadata 模板透传与静态 headers,实现会话粘性负载,最大化上游 prompt cache 命中。
+把 DSH 会话的 sessionId 注入发往 newapi 等 LLM 网关的每个请求,供网关做请求亲和性(粘性会话路由):同一会话的请求稳定落到同一上游渠道,上游 prompt cache 命中是这种路由方式的结果。形态上是官方 `dsh-llm-pi-ai` 的零感知增强替换(装上即接管、卸载即还原),compat 全控、metadata 模板透传与静态 headers 兜底一并提供。
+
+## sessionId 注入通道
+
+核心能力:每条路由的每个上游请求自动携带会话标识,网关按任一载体做粘性键即可实现请求亲和性:
+
+| 通道 | 载体 | 值 | 生效条件 |
+| --- | --- | --- | --- |
+| 请求体标记 | anthropic-messages 写 `metadata.user_id`(同 Claude Code);openai-completions / openai-responses 写顶层 `prompt_cache_key`(同 Codex,无 `prompt_cache_retention` 副作用) | sessionId 单向派生的稳定标记 `dsh:<sha256 前 40 位>`,前缀可配 | 默认开启,每路由可关(`sessionMarker.enabled`);不受 `cacheRetention` 影响 |
+| 亲和头 | 按协议与 `sessionAffinityFormat`,精确映射见下 | 裸 sessionId 原样 | sessionId 在场且 `cacheRetention` ≠ `none`;anthropic-messages / openai-completions 另需 compat `sendSessionAffinityHeaders: true`,openai-responses 无需 compat |
+| metadata 模板 | anthropic `metadata` 任意键透传(openai 系路由声明 metadata 无效果) | 字符串值渲染 `{sessionId}` / `{marker}` 占位符 | 依赖标记通道:非 user_id 键经标记 onPayload 合入请求体,`sessionMarker.enabled=false` 时仅 user_id 键经 pi-ai 原生转发,其余键不上 wire;模板 `user_id` 键标记开启时恒被派生标记覆盖 |
+| 静态 headers | 任意网关约定的自定义头 | 固定值 | 声明即生效;与亲和头同名时静态头后写覆盖;请避开 attribution 保留头名 |
+
+亲和头精确映射(头集合随协议与 `sessionAffinityFormat` 不同,网关粘性键须按所选形态勾选):
+
+| 协议 | 头集合 |
+| --- | --- |
+| anthropic-messages | `x-session-affinity` |
+| openai-completions | format `openai`:`session_id` + `x-client-request-id` + `x-session-affinity`;format `openai-nosession`:`x-client-request-id` + `x-session-affinity`;format `openrouter`:`x-session-id` |
+| openai-responses | format `openai`:`session_id` + `x-client-request-id`;format `openai-nosession`:`x-client-request-id`;format `openrouter`:`x-session-id` |
+
+format 未声明时由 pi-ai 自动检测:provider 名为 `openrouter`(精确匹配)或 baseUrl 含 `openrouter.ai` 判为 `openrouter`,否则 `openai`——newapi 类路由未声明即按 `openai` 头集合发射。
+
+- 标记经 pi-ai `onPayload`(请求体发出前最后一步)直写,不依赖 baseURL / retention 条件,上游原生发射的同名键以本包值覆盖;路由按显式 api 直注,形状判别仅为 api 缺失时的兜底,未知形状不注入。
+- 亲和头由 pi-ai 按路由 compat 与 `cacheRetention` 门控:`cacheRetention: none` 抑制全部亲和头(亲和头不再携带会话 id,请求体通道不受影响);`sessionAffinityFormat` 仅 openai 系 compat 名单内合法,取值 `openai` / `openai-nosession` / `openrouter`,声明其他值不报错但产生残缺头集合。
+- sessionId 缺省契约:标记关闭且模板不引用 `{sessionId}` 的路由允许请求缺省 sessionId(官方 wire 契约同构);接管路由标记默认开启,sessionId 因此默认必填。
+- 粘性生效前提:网关侧按对应键做亲和路由,粘性键勾选上述载体之一(`metadata.user_id` / `prompt_cache_key` / `x-session-affinity` / `x-client-request-id` / `session_id` / `x-session-id`,按路由协议与 format 取其一);本包只保证标识发出,网关行为不在边界内。
 
 ## 零感知接管(0.2.0 起)
 
 **装上即生效,用户无感**:插件通过 bundle patch 禁用官方 `dsh-llm-pi-ai` 行,并以**官方包自己的 Config schema** 接管 `llm-pi-ai:` 设置节——
 
 - 现有官方配置**原样保留、原样生效**,路由名不变:`agent-default-model`、quota 面板、Models 页面、历史会话全部无缝继续
-- 接管的路由自动获得会话标记(粘性默认开启),其余行为与官方逐项对表(见下节)
+- 接管的路由自动获得 sessionId 注入(请求体标记默认开启;亲和头 anthropic-messages / openai-completions 经 compat 开启,openai-responses 默认开启),其余行为与官方逐项对表(见下节)
 - `llm-pi-gateway:` 节仍可用:独立声明路由,或与官方节同名时整体覆盖(增强)
 - **卸载即还原**:patch 随 bundle 移除,官方插件恢复,同一份配置继续由官方服务
 - 防御:若 patch 失效(宿主升级等)官方插件仍在,本包接管官方节失败时降级为只服务 `llm-pi-gateway:` 节并记日志(命名空间注册冲突与一般失败区分文案),不阻塞启动;官方包本体不可用时同样降级并告警
 
+### 禁用与还原
+
+宿主注册面(adapter/directory/discovery/settings 命名空间)全部排他,官方插件与本包无法共存,因此**官方行的禁用由本包 bundle patch 静态声明,不随本包行被禁用而失效**。
+
+**dsh-market 开关 / 单行禁用(普通用户)**:直接在 dsh-market 点禁用,或只写一行 `- id: llm-pi-gateway` + `disabled: true`。bundle patch 会同时插入一个哨兵行(`llm-pi-gateway/guard`,market 的行写入对其 id 拒绝,不会被连带禁用):两行同禁的窗口期(点禁用后到下次重启)内,哨兵动态挂载官方插件恢复服务,所有模型继续可用;重启后本包 patch 随 bundle 移出(market 对本包按 disable-carrier 处理),官方插件原生接管,哨兵自动退场。重新点启用则哨兵先卸载,本包无缝接管回来。market 路径每次开关会对哨兵行记一条「行 id 含特殊字符,不支持写入补丁层」警告,属预期噪音。手写单行禁用(不移出 bundles)时,哨兵的自愈在每次重启后重新生效,死态窗口由哨兵长期兜底。
+
+**补丁层两行禁用(高级用户,不重启即时生效)**:
+
+```yaml
+- id: llm-pi-gateway
+  disabled: true
+- id: llm-pi-ai
+  disabled: false
+```
+
+- 官方行复活让位守卫:上述两行写入后热重载时,本包在官方插件重新注册前自停让位,官方无缝接管,不出现注册冲突拖垮 patch 应用;反之删掉这两行恢复接管时,本包等官方插件退场落定后再接管
+- 完全卸载本包(`dsh plugin remove`)无需任何 patch 改动,patch 随 bundle 移除,官方行自动恢复
+- 两节 provider 同名重叠时的归属:官方在场(让位态)下官方插件先注册,本包自有节若声明了与官方节同名的 provider,整组路由注册被宿主排他检查拒绝,本包节路由(含不重叠的)整体不服务,仅日志披露——让位态请避免两节同名,或接受官方节优先
+- 官方行 `disabled` 写为 `!!js` 表达式且求值出错时,本包按未禁用让位(官方节归官方,不制造注册冲突);若官方行实际未启用,会出现双空闲(provider 路由无人服务),需修正表达式或改静态布尔
+
 ## 官方兼容
 
 需要 dsh 本体 0.1.2 及以上:激活时动态探测 dsh-llm 的 `resolveImageAttachmentAccess` / `offloadedImageText`(0.1.2 引入),缺失即打日志禁用插件,不注册 adapter 与 settings 节,不影响宿主启动与其他插件。
@@ -61,13 +107,10 @@ DeepSeek Harness pi-ai 透传网关插件:官方 `dsh-llm-pi-ai` 的零感知增
 | 模型发现 | `INVALID_CREDENTIAL` | 发现请求凭据被上游拒绝 |
 | 模型发现 | `ABORTED` | 发现请求被调用方中止 |
 
-## 功能
+## 其他功能
 
 - **图片输入(多模态,官方管线同构)**:请求含图片且模型声明 `input: [text, image]` 时,经 attachments 服务读出为 base64 块(handle 文本 + `image` 块),预算策略 `maxRequestImageBytes` / `requestImagePixelBudget` / `requestImageMaxBytes` 与官方同款(缺省 20MiB / 4Mi 像素 / 1MiB);非 user 角色图片、模型无 image 能力、attachments 服务缺失均按官方语义 `UNSUPPORTED_CONTENT`;纯文本路径零开销。
-- **全协议会话标记(默认开启,每路由可关)**:请求体自动携带由 sessionId 单向派生的稳定标记(`dsh:<sha256 前 40 位>`,前缀可配)——anthropic-messages 写 `metadata.user_id`(同 Claude Code),openai-completions / openai-responses 写顶层 `prompt_cache_key`(同 Codex,无 `prompt_cache_retention` 副作用);未知协议形状不注入。经 pi-ai `onPayload`(请求体发出前最后一步)直写,不依赖 baseURL / retention 条件,上游原生发射时以本包标记覆盖。
-- **compat 全控**:官方包 withhold 的粘性等字段全部开放(`sendSessionAffinityHeaders`、`sessionAffinityFormat`、`supportsDeveloperRole` 等),字段名按 pi-ai 0.84.4 各协议 compat 类型校验,值为 null 拒绝;模型级 compat 覆盖路由级。
-- **metadata 模板透传**:字符串值支持 `{sessionId}` / `{marker}` 占位符;标记注入与模板独立,模板 `user_id` 键被标记覆盖,其余键照常透传。
-- **静态 headers**:任意网关约定的兜底通道(请避开 attribution 保留头名)。
+- **compat 全控**:官方包(0.1.2-rc.1)withhold 的字段全部开放(`supportsDeveloperRole` 等;`sendSessionAffinityHeaders` / `sessionAffinityFormat` 即上表亲和头通道),字段名按 pi-ai 0.84.4 各协议 compat 类型校验,值为 null 拒绝;模型级 compat 覆盖路由级。
 - **多模型路由**:一条路由声明多个模型,按请求 model 字段分发,未命中返回 `UNKNOWN_MODEL`。
 
 ## 配置(settings.yaml 命名空间 `llm-pi-gateway`)
@@ -75,30 +118,28 @@ DeepSeek Harness pi-ai 透传网关插件:官方 `dsh-llm-pi-ai` 的零感知增
 ```yaml
 llm-pi-gateway:
   providers:
-    new-api:                        # 路由名 = LLM provider 名
-      displayName: New API          # 可选,配置面/选择器显示名
+    new-api-claude:                 # 路由名 = LLM provider 名
+      displayName: New API Claude   # 可选,配置面/选择器显示名
       api: anthropic-messages       # 或 openai-completions / openai-responses
       baseURL: https://newapi.example.com
       apiKeyEnv: NEW_API_API_KEY    # 凭据引用(credentials 服务或环境变量)
       reasoning: high               # 可选,路由级默认档位(模型需支持)
-      sessionMarker:                # 会话标记,默认开启
+      sessionMarker:                # 会话标记(请求体通道),默认开启
         enabled: true
         prefix: dsh                 # 派生标记前缀
-      metadata:                     # anthropic metadata 模板(可选)
-        user_id: '{"gateway":"newapi","session":"{sessionId}"}'
-      compat:                       # 路由级 compat 覆盖,无 withhold
-        sendSessionAffinityHeaders: true
-        sessionAffinityFormat: openai   # 仅 openai 系协议生效
+      metadata:                     # anthropic metadata 模板(可选);user_id 键由标记占用,勿在此声明
+        gateway: newapi
+        session: '{sessionId}'
+      compat:                       # 路由级 compat 覆盖,无 withhold;字段按协议名单校验
+        sendSessionAffinityHeaders: true   # 亲和头通道(anthropic 即 x-session-affinity)
       headers:                      # 静态自定义头(粘性兜底通道)
         x-gateway-group: pool-a
-      cacheRetention: short         # 可选:none / short / long
+      cacheRetention: short         # 可选:none / short / long(none 会抑制亲和头)
       defaultContextWindow: 262144  # 可选,模型未声明时的兜底
       retryPolicy:                  # 可选,注册捕获,进 runtime 重试
         mode: normal
         maxRetries: 2
       models:
-        - id: auto
-          contextWindow: 200000
         - id: claude-sonnet
           name: Claude Sonnet
           input: [text, image]
@@ -108,20 +149,23 @@ llm-pi-gateway:
           reasoningEfforts:
             off:
             low: low
+            high: high
             max: ultra
           compat:
             sendSessionAffinityHeaders: true
+    new-api-gpt:                    # openai 系协议示例(sessionAffinityFormat 仅在此类协议合法)
+      api: openai-responses         # 或 openai-completions
+      baseURL: https://newapi.example.com/v1
+      apiKeyEnv: NEW_API_API_KEY
+      compat:
+        sessionAffinityFormat: openai   # openai / openai-nosession / openrouter,头集合见注入通道表
+      models:
         - id: gpt-4o
-          compat:
-            sendSessionAffinityHeaders: true
-            sessionAffinityFormat: openai   # openai 三头 / openrouter 单头 x-session-id
 ```
 
-配置修改**即时生效**(无需重启);解析失败时保留上一份好配置。纯 host 端,无 GUI。
+路由与模型的全量可配键以本包 settings schema 为准,示例未穷举。
 
-## 粘性生效前提
-
-网关侧需按对应键路由:newapi 粘性键勾选 `metadata.user_id` / `x-session-affinity` / `x-session-id` / `prompt_cache_key` 之一。本包只保证标识发出,网关行为不在边界内。
+配置修改**即时生效**(无需重启);解析失败时保留上一份好配置。纯 host 端,无 GUI。
 
 ## 安装
 
@@ -129,16 +173,16 @@ llm-pi-gateway:
 dsh plugin --profile web add @mzzsfy/dsh-llm-pi-gateway
 ```
 
-重启 dsh 生效。**无需任何配置改动**:官方 `llm-pi-ai:` 节原样接管(官方 schema 消费),路由名不变,粘性自动开启。`llm-pi-gateway:` 节仅用于增强覆盖(同名整体优先)或独立路由。
+重启 dsh 生效。**无需任何配置改动**:官方 `llm-pi-ai:` 节原样接管(官方 schema 消费),路由名不变,sessionId 注入自动开启(请求体标记)。`llm-pi-gateway:` 节仅用于增强覆盖(同名整体优先)或独立路由。
 
 卸载插件 = 官方原样接管回来,同一份配置继续工作。
 
 ## 已知取舍
 
-- 事件流适配与 pi-ai 数据结构耦合,pi-ai 协议 payload 形状大改时标记器判别需跟随;未知形状不注入保证不误伤。
+- 事件流适配与 pi-ai 数据结构耦合;路由按显式 api 直注标记,形状判别仅为 api 缺失的兜底路径,未知形状不注入。
 - 无流空闲超时看门狗(官方 0.1.2-rc.1 经 `streamIdleTimeoutMs` 300 秒兜底;实现需进程内动态 import dsh-timeout,宿主可达性待实测后补齐,当前纯披露);pi-ai 依赖下界较官方收紧(官方 0.1.2-rc.1 为 ^0.84.2,本包因 compat 名单取材 0.84.4 抬至 ^0.84.4),官方升级范围时本包需跟随。
-- sessionMarker.enabled=false 不拦截 metadata 模板的静态 user_id 键透传(该键来自模板而非标记器,不含会话派生标识)。
-- `sessionId` 缺省契约:会话标记关闭且模板不引用 `{sessionId}` 的路由允许缺失(官方 wire 契约同构,缺省即省略该键);接管路由会话标记**默认开启**,sessionId 因此默认必填——官方节路由无法声明关闭该键,依赖 sessionId 的零感知承诺仅对显式关闭标记或模板不引用的路由兑现。
+- sessionMarker.enabled=false 不拦截 metadata 模板的静态 user_id 键透传(该键来自模板而非标记器,不含会话派生标识);模板其余键经标记 onPayload 合入,标记关闭时不上 wire。标记关闭时 openai 系的原生 `prompt_cache_key` 随之不再被覆盖,pi-ai 原生行为仍在:openai-responses 在 retention ≠ none(未配置默认 short)时携带截断裸 sessionId;openai-completions 在 baseUrl 含 api.openai.com、或 retention 为 long 且 compat 允许时同——依赖派生标记隐藏内部会话 id 的场景此时应改用其他载体做粘性键。
+- `sessionId` 缺省契约:会话标记关闭且模板不引用 `{sessionId}` 的路由允许缺失(官方 wire 契约同构,缺省即省略该键);接管路由会话标记**默认开启**,sessionId 因此默认必填——sessionId 缺省承诺仅对显式关闭标记且模板不引用 `{sessionId}` 的路由兑现。
 - 上游错误以文本分类(pi-ai 把捕获错误展平为 message 字符串),quota/超窗判定用官方同款判定器,其余分支与官方同序同构。
 - 本包未复用 dsh-llm 类(插件依赖以副本安装,class 身份不通;错误以 own `code` / `failure` 数据属性被 harness 错误边界识别),官方公共导出仅消费纯函数与 schema 对象。
 - `reasoningEfforts` → `thinkingLevelMap` 解析为平行实现(官方未导出该函数),以对表测试锚定语义。

package/cordis.patch.yml

@@ -7,10 +7,32 @@
 # marking; the `llm-pi-gateway` section stays available for standalone or
 # enhanced routes. Uninstalling this bundle removes the patch, the official
 # row re-enables, and the official plugin serves the same profiles again.
-# Escape hatch: a later patch layer (profile cordis.patch.yml or --patch
-# overlay) can re-enable the official row, in which case this plugin logs a
-# takeover failure and serves only its own section (same-name routes would
-# collide, so the official plugin keeps those it declares).
+#
+# Dead-state self-heal: the second inserted row (`llm-pi-gateway/guard`) is
+# a sentinel. While BOTH the gateway row and the official row are disabled
+# (e.g. the dsh-market toggle disables the gateway row instantly while its
+# bundle removal only lands on the next boot), the sentinel dynamically
+# mounts the official plugin so models keep working. When the gateway row
+# comes back, the sentinel unmounts first and the gateway takes over with
+# zero registration conflicts. The sentinel id contains a "/", which the
+# dsh-market row writer refuses to persist, so the sentinel survives the
+# market toggle and is the only live self-heal executor in that window.
+#
+# Escape hatch: bundle patches load unconditionally while the bundle stays
+# listed, so disabling the gateway row ALONE would leave the official row
+# disabled — the sentinel covers that window, and a restart removes this
+# bundle's patch entirely (market uninstall or carrier toggle), restoring
+# the official plugin natively. To hand control back WITHOUT restarting,
+# also re-enable the official row:
+#
+#   - id: llm-pi-gateway
+#     disabled: true
+#   - id: llm-pi-ai
+#     disabled: false
+#
+# The gateway yields on its own before the official plugin re-registers
+# (revival guard), and re-takes-over only after the official plugin has
+# exited, so the switch over is live-reload safe in both directions.
 
 - id: llm-pi-ai
   disabled: true
@@ -18,3 +40,5 @@
 - insert:
     - id: llm-pi-gateway
       name: '@mzzsfy/dsh-llm-pi-gateway'
+    - id: llm-pi-gateway/guard
+      name: '@mzzsfy/dsh-llm-pi-gateway/guard'

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@mzzsfy/dsh-llm-pi-gateway",
-  "description": "NewAPI 等 LLM 网关接入:跨协议会话粘性标记,提升网关侧 prompt 缓存命中,compat 全开放",
-  "version": "0.2.6",
+  "description": "NewAPI 等 LLM 网关接入:向每个上游请求注入会话 sessionId(请求体派生标记 + 亲和头裸 sessionId),供网关做请求亲和性粘性路由,compat 全开放",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./guard": "./src/guard.js",
     "./package.json": "./package.json"
   },
   "dsh": {
@@ -37,6 +38,7 @@
     "@deepseek-ai/dsh-llm-pi-ai": ">=0.1.2-rc.1"
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
     "@deepseek-ai/schemastery": "3.18.2",
     "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
     "@deepseek-ai/dsh-settings": "0.1.2-rc.1",

package/src/apply-state.mjs

@@ -0,0 +1,25 @@
+// gateway 主行 apply 生命周期旗标:guard 据此识别"行活着但功能性未接管"
+// (旧宿主缺必备导出,apply 干净早退的假活形态)。经 globalThis 符号键承载,
+// 防同包多实例模块图读不到状态。
+
+const KEY = Symbol.for('@mzzsfy/dsh-llm-pi-gateway.applyState')
+
+// apply 开始清除旧态:运行中不可判,guard 保守不代挂
+export function beginGatewayApply() {
+  delete globalThis[KEY]
+}
+
+// apply 走到服务注册完成:本行有效接管
+export function endGatewayApplyActive() {
+  globalThis[KEY] = 'active'
+}
+
+// apply 因宿主能力缺失干净早退:行活着但不提供任何服务
+export function endGatewayApplyInactive() {
+  globalThis[KEY] = 'inactive'
+}
+
+/** @returns {'active'|'inactive'|undefined} undefined = 未运行/运行中/中途崩溃 */
+export function gatewayApplyState() {
+  return globalThis[KEY]
+}

package/src/guard.js

@@ -0,0 +1,344 @@
+// llm-pi-gateway guard 哨兵行:死态自愈,守服务不抢权。
+// 死态 = gateway 行功能性停摆(行被禁并停稳,或行活着但 apply 因宿主能力
+// 缺失干净早退)且官方行仍被 bundle patch 禁用并停稳——无任何插件服务
+// provider 路由,所有模型不可用。触发路径:dsh-market 对本包(禁用承载
+// 官方行的 disable-carrier)的 UI 开关写入即时生效的 user patch 行禁用,
+// 而其恢复机制(整包移出 bundles)只在下次 boot 生效,窗口内 composed
+// 自相矛盾;旧宿主(rc.2)则恒为假活形态。
+// 自愈手段:动态挂载官方插件模块(ctx.plugin),settings 节与模型注册全
+// 原生语义,挂 guard 子 context 随 guard fiber 卸载。gateway 行或官方行
+// 任一复活时先卸代挂再放行。guard 行 id 含 "/",dsh-market 的行写入对其
+// 拒绝,窗口内始终存活,是死态唯一的自愈执行者。
+//
+// 版本兼容(0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-alpha.1 实测):
+// - 行 id 解析:dsh 宿主把 profile 行树经 cordis:include 行挂载,嵌套
+//   分隔符是 ":",受控行的实际解析 id 带前缀(裸 id resolve 抛错)。
+// - guard 的 apply 与兄弟行同处一个 update 事务,首判可能早于兄弟行入树,
+//   PENDING 时必须延迟重试,不能当真/假值使用。
+// - 边沿事件时序因宿主版本而异(toggle 后的 in-process 重启、live 重载
+//   事务都会吞掉或推迟边沿),以低频轮询兜底,mount/unmount 均幂等,
+//   事件与轮询并发安全。
+
+import {
+  OFFICIAL_ENTRY_ID,
+  EXIT_POLL_INTERVAL_MS,
+  EXIT_POLL_ROUNDS,
+  ROW_ID_PREFIXES,
+} from './takeover.mjs'
+import { gatewayApplyState } from './apply-state.mjs'
+
+// 本包主行 id(cordis.patch.yml 的 insert 声明)
+const GATEWAY_ENTRY_ID = 'llm-pi-gateway'
+// guard 行 id:带 "/" 使 market 的 ROW_ID_RE 拒绝写入 user patch 层
+export const GUARD_FOR_GATEWAY_ID = 'llm-pi-gateway/guard'
+// 官方插件 settings 命名空间(官方源码常量同构)
+const OFFICIAL_SETTINGS_NS = 'llm-pi-ai'
+
+// 轮询兜底周期:边沿事件缺失/丢失时的状态跟随精度,幂等不抖动
+const SWEEP_INTERVAL_MS = 3000
+// boot 树就绪等待:兄弟行 update 事务完成的上限(超时按当前状态判定)
+const BOOT_SETTLE_ROUNDS = 50
+const BOOT_SETTLE_INTERVAL_MS = 100
+
+// 无法解析该 id:boot 早期兄弟行未入树,或行确实不存在;两者对"是否
+// 死态"都不可判定,调用方应稍后重试
+const PENDING = null
+
+// 解析按 ROW_ID_PREFIXES 候选顺序兜底;全部解析失败报 PENDING
+function resolveEntry(loader, id) {
+  for (const prefix of ROW_ID_PREFIXES) {
+    try {
+      const entry = loader?.resolve(prefix + id)
+      if (entry) return entry
+    } catch {
+      // 该候选空间无此 id,试下一候选
+    }
+  }
+  return PENDING
+}
+
+// 行有效禁用读宿主 Entry.disabled getter(!!js 求值 + 父链 + 宽化)。
+// 调用方保证 entry 非 undefined/PENDING;求值抛错按未禁用处理(保守向:
+// 少代挂,不多抢)
+function effectiveDisabled(entry) {
+  try {
+    return entry.disabled === true
+  } catch {
+    return false
+  }
+}
+
+// 行停稳 = fiber 已撤清(uid null 即 dispose 完成,注册已全部释放)
+function settled(entry) {
+  return entry.fiber?.uid == null
+}
+
+/**
+ * 死态判定:gateway 行功能性停摆(禁用停稳,或 apply 声明未接管),且官方
+ * 行禁用并已停稳。官方行未禁 = 官方自行服务。gateway apply 中途崩溃
+ * (旗标 undefined)不在判定内:自愈执行者不越权重启他人。
+ * 返回 PENDING 表示行尚无法解析(树未就绪或行不存在),调用方应稍后
+ * 重试——PENDING 不能当真值也不能当假值。
+ * @param {object|undefined} loader
+ * @returns {boolean|PENDING}
+ */
+export function detectDeadState(loader) {
+  const gateway = resolveEntry(loader, GATEWAY_ENTRY_ID)
+  const official = resolveEntry(loader, OFFICIAL_ENTRY_ID)
+  if (gateway === PENDING || official === PENDING) return PENDING
+  const gatewayOff = (effectiveDisabled(gateway) && settled(gateway))
+    || gatewayApplyState() === 'inactive'
+  if (!gatewayOff) return false
+  return effectiveDisabled(official) && settled(official)
+}
+
+// 树就绪判定:两个受控行都可解析(apply 跑在兄弟行 update 事务内时,
+// 解析会失败,此时不能做初始判定)
+function treeReady(loader) {
+  return detectDeadState(loader) !== PENDING
+}
+
+// 等待树就绪:guard apply 与兄弟行同事务,首判前必须等 gateway/official
+// 行完成创建。上限 BOOT_SETTLE_ROUNDS 次,超时按当前状态判定(树长期
+// 不就绪属宿主异常,持续轮询自会在就绪后接管)
+async function waitTreeReady(loader, delay) {
+  for (let round = 0; round < BOOT_SETTLE_ROUNDS; round += 1) {
+    if (treeReady(loader)) return true
+    await delay(BOOT_SETTLE_INTERVAL_MS)
+  }
+  return treeReady(loader)
+}
+
+// 官方包必须取自运行宿主本体树:guard 所在包经解析链裸 import 官方名会
+// 命中与本宿主版本脱钩的副本(如仓库根 symlink 指向最新版本体),其
+// apply 在旧宿主服务面上静默失能(注册空目录),代挂形同虚设。宿主入口
+// (process.argv[1] = bin.js)所在 node_modules 树与本宿主 llm/settings
+// 服务同源,经 createRequire 定位物理文件再动态 import。定位失败回退
+// 裸 import(单一本体安装的常规形态下两者一致)
+async function importOfficialFromHost() {
+  const resolved = await resolveFromHostTree('@deepseek-ai/dsh-llm-pi-ai')
+  if (resolved) {
+    const { pathToFileURL } = await import('node:url')
+    return import(pathToFileURL(resolved).href)
+  }
+  return import('@deepseek-ai/dsh-llm-pi-ai')
+}
+
+// 在宿主入口的依赖树内解析包的物理路径;宿主入口不可定位返回 null。
+// realpath 穿透 junction/pnpm 软链,落到宿主本体 .pnpm 实体,解析才能
+// 命中同宿主依赖树的包,而非外层链上的他版本副本
+async function resolveFromHostTree(packageName) {
+  try {
+    const { createRequire } = await import('node:module')
+    const { pathToFileURL } = await import('node:url')
+    const { realpath } = await import('node:fs/promises')
+    const entry = process.argv[1]
+    if (!entry) return null
+    const realEntry = await realpath(entry)
+    const require = createRequire(pathToFileURL(realEntry))
+    return await realpath(require.resolve(packageName))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 安装 guard:树就绪后判定初始死态,此后事件跟随 + 轮询兜底双通道跟随
+ * 死态/复活边沿——死态时代挂官方,任一行复活先卸代挂。全部状态挂 guard
+ * 自身 fiber,随其卸载自动清理。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{importOfficial?: () => Promise<object>, rowConfig?: () => Promise<object>, delay?: (ms: number) => Promise<void>}} hooks
+ *   测试注入桩;官方包默认取自宿主本体树,行配置默认读宿主 settings 文件,
+ *   缺失即干净禁用
+ */
+export async function installGuard(ctx, {
+  importOfficial = importOfficialFromHost,
+  rowConfig,
+  delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  let officialModule
+  try {
+    officialModule = await importOfficial()
+  } catch (error) {
+    ctx.logger.warn(`llm-pi-gateway/guard: 官方 dsh-llm-pi-ai 不可用,死态自愈停用: ${error?.message ?? error}`)
+    return undefined
+  }
+  let mounted = null
+  let mounting = null
+
+  // settings 服务可达性经注入 API 探测:guard 未声明 inject,直接读
+  // ctx.settings 在注入门控宿主上会抛错拖垮插件树。回调到达即服务就绪,
+  // 同时留下服务面供行配置读取
+  let settingsCtx = null
+  try {
+    ctx.inject(['settings'], (sctx) => { settingsCtx = sctx })
+  } catch {
+    // 注入 API 缺失,行配置退化为空,服务可达性视为未就绪
+  }
+
+  // 官方 ns 行内配置:官方 apply 的目录首注册先于其 settings 接线,行
+  // 配置为空会让部分宿主版本以空目录注册失败,且失败后再无补齐通道。
+  // settings 服务面读不到该节(官方行禁用时无人 register),只能读宿主
+  // 落盘文件;接线完成后仍由 settings 面接管(setSource 覆盖行配置)
+  async function officialRowConfig() {
+    try {
+      const settingsFile = await resolveFromHostTree('@deepseek-ai/dsh-home-paths')
+      const resolvedYaml = await resolveFromHostTree('yaml')
+      if (!resolvedYaml) return {}
+      const { readFile } = await import('node:fs/promises')
+      const { dirname, join } = await import('node:path')
+      const { pathToFileURL } = await import('node:url')
+      const { parse } = await import(pathToFileURL(resolvedYaml).href)
+      let home = null
+      if (settingsFile) {
+        try {
+          ;({ resolveDshHome: home } = await import(pathToFileURL(settingsFile).href))
+        } catch {
+          home = null
+        }
+      }
+      const filename = typeof home === 'function' ? join(home(), 'settings.yaml') : join(dirname(process.execPath), 'settings.yaml')
+      const document = parse(await readFile(filename, 'utf8'))
+      return document?.[OFFICIAL_SETTINGS_NS] ?? {}
+    } catch {
+      return {}
+    }
+  }
+
+  // 跨版本 compat 键差异:旧宿主的 wire protocol 不声明新键即拒整节,
+  // 行配置随之失效。拒绝信息机器可读,记录被拒键并在后续构造时剥离,
+  // 收敛后行配置即通过本宿主校验;仅影响代挂首注册,settings 接线后
+  // 以 settings 面为准
+  const refusedCompatKeys = new Set()
+  const REFUSED_COMPAT_RE = /sets compat "([^"]+)", which no wire protocol declares/g
+  function recordRefusedCompatKeys(message) {
+    for (const match of String(message ?? '').matchAll(REFUSED_COMPAT_RE)) {
+      refusedCompatKeys.add(match[1])
+    }
+  }
+  function stripRefusedCompatKeys(section) {
+    if (refusedCompatKeys.size === 0) return section
+    const providers = section?.providers
+    if (typeof providers !== 'object' || providers === null) return section
+    const cleaned = structuredClone(section)
+    for (const provider of Object.values(cleaned.providers)) {
+      for (const model of provider?.models ?? []) {
+        if (typeof model?.compat === 'object' && model.compat !== null) {
+          for (const key of refusedCompatKeys) delete model.compat[key]
+        }
+      }
+    }
+    return cleaned
+  }
+
+  const settingsReady = () => settingsCtx !== null
+
+  // 代挂官方插件:挂 guard 子 context,Config 校验与 settings 节全原生
+  // 语义;同一时刻至多一个代挂(mounting 去并发,mounted 去重入)
+  async function mountOfficial() {
+    if (mounted !== null || mounting !== null) return
+    mounting = (async () => {
+      try {
+        const section = await (rowConfig?.() ?? officialRowConfig())
+        const fiber = ctx.plugin(officialModule, stripRefusedCompatKeys(section))
+        await fiber
+        mounted = fiber
+        ctx.logger.warn('llm-pi-gateway/guard: 检测到 gateway 与官方行同时停用,已代挂官方插件恢复服务;重启后由宿主组合自然归位')
+      } catch (error) {
+        recordRefusedCompatKeys(error?.message)
+        ctx.logger.error(`llm-pi-gateway/guard: 代挂官方插件失败: ${error?.message ?? error}`)
+      } finally {
+        mounting = null
+      }
+    })()
+    await mounting
+  }
+
+  // 卸代挂:行复活的前置交接,必须完成后才放行其 apply。等待在途代挂
+  // 完成,防复活放行与代挂激活交错抢注册
+  async function unmountOfficial() {
+    if (mounting !== null) await mounting
+    if (mounted === null) return
+    const fiber = mounted
+    mounted = null
+    try {
+      await fiber.dispose()
+    } catch (error) {
+      ctx.logger.warn(`llm-pi-gateway/guard: 卸代挂失败(放行继续,接管方遇注册冲突会降级): ${error?.message ?? error}`)
+    }
+  }
+
+  const patchContextGuard = async (entry, next) => {
+    const id = entry?.options?.id
+    if (id !== GATEWAY_ENTRY_ID && id !== OFFICIAL_ENTRY_ID) return next()
+    if (entry.fiber?.uid != null) return next()
+    if (mounted === null && mounting === null) return next()
+    ctx.logger.warn(`llm-pi-gateway/guard: ${id} 行复活,卸代挂让位`)
+    try {
+      await unmountOfficial()
+    } finally {
+      return next()
+    }
+  }
+
+  // 禁用边沿:行退场事件后,等其注册撤清(fiber 消失)再判死态,防与
+  // 退场序列并发抢占官方注册。官方行退场(手动禁官方行)同样可能铸成
+  // 死态。fiber 在场的事件是配置更新/重启路径(非退场),快速返回:
+  // 宿主全部禁用/移除发射点都在 dispose 完成后
+  const partialDisposeGuard = async (entry) => {
+    const id = entry?.options?.id
+    if (id !== GATEWAY_ENTRY_ID && id !== OFFICIAL_ENTRY_ID) return
+    if (entry.fiber?.uid != null) return
+    for (let round = 0; round < EXIT_POLL_ROUNDS; round += 1) {
+      if (entry.fiber?.uid == null) break
+      await delay(EXIT_POLL_INTERVAL_MS)
+    }
+    if (detectDeadState(ctx.loader) === true && settingsReady()) await mountOfficial()
+  }
+
+  // 轮询兜底:边沿事件的时序因宿主版本而异(toggle 后的 in-process 重启、
+  // live 重载事务等都会吞掉或推迟边沿),周期性全量扫描保证死态→代挂、
+  // 复活→卸代挂的最终一致。与事件通道幂等并发:mount/unmount 各自去重,
+  // 双通道同时触发不会叠加。PENDING 轮跳过,下轮再扫。mount 前置条件:
+  // settings 服务已 provide——官方目录首注册需要 settings 现值作行配置,
+  // 且 boot 事务内 mount 会让官方插件的 settings 接线时序劣化
+  let sweeping = false
+  const sweep = async () => {
+    if (sweeping) return
+    sweeping = true
+    try {
+      const dead = detectDeadState(ctx.loader)
+      if (dead === true && settingsReady() && mounted === null && mounting === null) await mountOfficial()
+      else if (dead === false && (mounted !== null || mounting !== null)) await unmountOfficial()
+    } finally {
+      sweeping = false
+    }
+  }
+
+  ctx.on('loader/patch-context', patchContextGuard, { global: true })
+  ctx.on('loader/partial-dispose', partialDisposeGuard, { global: true })
+
+  // 初始判定前必须等树就绪:apply 与兄弟行同事务,首判早了会全部
+  // PENDING 而空转。settings 服务已注入即就地自愈;否则交由事件通道与
+  // sweep(同一门槛)兜底,官方目录首注册需要其现值
+  await waitTreeReady(ctx.loader, delay)
+  if (detectDeadState(ctx.loader) === true && settingsReady()) await mountOfficial()
+
+  // 兜底轮询:guard 行 fiber 存续期间持续扫描。guard entry 被宿主移除
+  // (随 bundle patch 退场)即整体退场;fiber dispose 后 sweep 空转无害
+  // (mounted 状态已无从变更)。unref 防定时器独占进程存活权;不能
+  // await ctx.fiber:apply 内 await 自身 fiber 会死锁
+  const timer = setInterval(() => { void sweep() }, SWEEP_INTERVAL_MS)
+  timer.unref?.()
+  return undefined
+}
+
+export const name = 'llm-pi-gateway/guard'
+
+/**
+ * guard 行入口:零配置,无服务依赖(loader 经 ctx 原型链可达)。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export async function apply(ctx) {
+  await installGuard(ctx)
+}