@luolingp/request-doctor 0.0.0-stage → 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-request-doctor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# request-doctor · 请求急救员
+
+一个 DSH 插件：自动修好客户端这边造成的请求失败，并让版本对不上的插件能装上、能跑。
+
+## 它解决什么问题
+
+### 请求莫名失败
+
+网络抖一下、服务端超时、模型返回空、上下文太长——这些都不是你操作的问题，但默认会让一次对话直接断掉。
+
+插件判断这属于「本机这边能挽回」的失败后自动重试，间隔逐次拉长，不会把对方打得更糟。
+
+**不重试**：欠费、限流、服务端故障、内容审核拦截、图片超限。这些重试没有意义。
+
+**不重放**：会改动东西的操作（执行命令、写文件、发消息）。只重放只读的（读文件、搜索、抓网页、看页面）。
+
+### 版本对不上的插件
+
+DSH 升级后，旧插件可能只认 `0.2.1-rc.2`，而你现在是 `0.2.1-rc.3`。默认结果是插件用不了，甚至装不上。
+
+插件不会去关掉这个检查，而是**给那个插件搭一个它期望的旧环境**，跟 Windows 的「以兼容模式运行」是一个意思——不是忽略问题，是提供它需要的环境。
+
+分两种情况：
+
+**当前实现还够用**：在插件目录里放一层很薄的转发包，声明旧版本号，调用转到当前实现。不复制代码，开销极小。
+
+**当前实现缺了插件要的东西**：把插件当初对着写的那份**真实旧版本**从仓库取回来装进去。跑的是它认识的那份代码，不是一个缺胳膊少腿的替身。
+
+取回的版本缓存在 profile 下的 `.request-doctor-cache/`，同一个版本只下载一次。
+
+**旧版本里也没有**：如实报告不兼容。不伪造、不放占位——放一个「调用时才报错」的假货，只是把崩溃推迟到运行期，那是骗自己。
+
+### 装不上的插件
+
+分两种情况，命令只有一个：
+
+```
+/doctor install <插件目录，或者包名>
+```
+
+**本地目录**：先把环境备好，再正常安装，管理器的版本检查就会按它自己的规则通过。
+
+**注册表里的包**（`dsh-ssh-ops`、`@scope/name@1.2.3` 这类）：管理器的安装路径是「pnpm 装完再检查」。远程包的字节在检查之前就落地了，没法提前改好 manifest，所以它对不兼容的包永远装不上。
+
+这种情况由插件自己把 pnpm 该做的事做一遍：取包、取依赖、对齐声明、建兼容环境、登记为 bundle、重载。装完会打印位置、环境状态、依赖和重载结果。
+
+## 覆盖范围
+
+扫描的是**所有**不兼容的插件，不是一个。来源包括：Loader 拒绝的包、已启用但没被拒绝的、已禁用但装着的、安装时环境还欠着的，以及加载失败后不在插件清单里、只能靠扫目录发现的。
+
+## 建完会核对，不是建完就算
+
+环境建好之后，会逐条确认插件要的每个符号是否真能拿到，再决定算不算修好。
+
+这一条是必要的：垫片少写一个导出，插件在加载那一刻就会崩，而修复流程会以为一切正常。核对通不过就记为未修复，不谎报成功。
+
+检查脚本也接上了核对：垫片存在但内容不对的插件会被重新适配，不会当作已经修好放着。
+
+## 路由冲突只报告
+
+两个插件可能声明同一个 LLM provider id。插件会提示你，但**不会**替你停用任何一个——那是你的插件，由你决定。
+
+## 运行开销
+
+稳态下几乎不耗资源。
+
+- 源码和 manifest 按文件签名缓存，没变就不重解析
+- 后台扫描健康时逐步退避到 30 分钟一次
+- 内容没变就不写盘，不触发文件监听
+- 长会话里那些记账用的结构都有上限
+- 定时器全部 `unref`，不拖住进程退出
+
+## 安装
+
+仓库根目录就是包本身：没有构建步骤，没有运行时依赖，`npm pack` 出来 33 个文件，装进去就能用。
+
+### 从可视化界面安装
+
+打开「插件」页，选安装，填本仓库地址或本地目录。装完立即生效，不用重启。
+
+仓库里带 `dsh.bundle.patch`，DSH 会据此把插件挂进组合；版本检查对得上，不会出现在「不兼容」列表里。
+
+### 用命令安装
+
+```
+/doctor install <仓库本地路径或包名>
+```
+
+本地目录和注册表里的包都走这一条。
+
+### 手动放进 profile
+
+1. 把本仓库内容复制到 `<profile>/node_modules/request-doctor/`
+2. 在 `<profile>/package.json` 的 `dependencies` 里加上 `"request-doctor": "link:<本目录>"`
+3. 在 `<profile>/cordis.patch.yml` 里插入：
+
+```yaml
+- insert:
+    - id: request-doctor
+      name: 'request-doctor'
+```
+
+1. 重启 DSH
+
+### 装完自检
+
+```
+/doctor
+```
+
+会打印已修复的数量、最近几次修复的记录，以及最近一轮版本审计的结论。任何一项为 0 都正常——没坏东西可修的时候它不动作。
+
+## 配置
+
+都放在 `cordis.patch.yml` 的 `config` 下，全部可选。
+
+| 配置项 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `autoRepair` | boolean | `true` | 总开关 |
+| `autoVersionRepair` | boolean | `true` | 是否自动处理版本不匹配 |
+| `maxRetries` | number | `12` | 单步模型请求最多修几次 |
+| `maxToolRetries` | number | `2` | 单次工具调用最多重放几次 |
+| `maxVersionRepairs` | number | `64` | 单轮扫描最多适配几个插件，`0` 表示不限 |
+| `maxAuthRetries` | number | `2` | 鉴权类失败最多重试几次，额度单独且更小 |
+| `maxRepeatedToolCalls` | number | `3` | 同名同参调用超过几次后不再重放 |
+| `initialDelayMs` | number | `400` | 首次退避基准 |
+| `maxDelayMs` | number | `20000` | 退避上限 |
+| `jitterRatio` | number | `0.25` | 退避抖动比例 |
+| `retryableToolPattern` | string | 见下 | 允许重放的工具名正则 |
+| `recordRetryEvents` | boolean | `true` | 是否写入会话重试记录 |
+
+默认只读工具白名单：
+
+```
+^(read|read_image|glob|grep|web_fetch|web_search|cordis_inspect_.*|browser_(list_tabs|snapshot|get_text|wait|scroll)|db_(query|preview|describe_table|list_tables))$
+```
+
+## 使用
+
+```
+/doctor
+```
+
+看各类修复计数和最近发生的事。
+
+```
+/doctor install <目录路径或包名>
+```
+
+本地插件先备好环境再让你正常安装；注册表里的包则直接装上。已经装着的包会就地修复，不会重装一遍。
+
+```
+/doctor allow <包名@版本>
+```
+
+只授权、不安装。给那些想继续在插件面板里点安装的人用：先放行这个版本，再在界面上装，装完声明对齐和兼容环境会自动补上。
+
+## 插件面板里的「不兼容安装」
+
+打开「插件」，标签栏里会多一个「不兼容安装」。里面列出当前被 DSH 版本检查拒掉的插件，每行一个按钮；顶上还有一个输入框，可以直接填 `包名@版本`。
+
+点按钮做的事和 `/doctor install` 一样：先按管理器的规则授权这个版本，再让它自己装，装完声明对齐和兼容环境由后台扫描补上。点完不会立刻变绿，等几秒。
+
+界面是随插件一起加的客户端模块。**新装的插件要先刷新一次页面**，浏览器才会加载它——插件热替换只覆盖已经载入过的客户端模块。
+
+页面渲染出错时不会留一片空白，而是把那句错显示出来。看到「这个页面渲染出错」就是那条信息本身在告诉你原因。
+
+## 还原
+
+被适配过的插件目录里有 `package.json.request-doctor-original`，是改动前的备份。
+
+要恢复原状：删掉插件目录下的 `node_modules`（如果只有本插件为它建过），用备份覆盖 `package.json`，再删掉 `.request-doctor-compat.json`。
+
+兼容环境只包含标记里记下的那些包，删除时也只删那些——插件自带的依赖不会被误删。
+
+## 已知边界
+
+- 兼容环境只能保证「插件要用的东西还在」。插件内部若有别的假设已经变了，仍可能表现异常，需要作者更新。
+- 第三方依赖不在检查范围，那是插件自己的事。
+- 安装前预置只支持本地目录。注册表包的字节还没落盘，提前看一眼是不可能的，这种情况会明确告诉你。
+
+## License
+
+MIT

package/client.js

@@ -0,0 +1,174 @@
+// 插件面板里的「不兼容安装」页。
+//
+// 管理器把版本检查放在安装流程里，对不上的包直接拒掉，然后原样回滚。它自己留了版本
+// 豁免这个出口，但只有命令行或它自己的弹窗能走。这里把它做成一个页面：列出当前被拒的
+// 插件，一键授权并安装，装完交给后台扫描去对齐声明、建兼容环境。
+//
+// 界面和 Host 之间走同源 HTTP，不碰 typert 的 remote 门面。动态加载的客户端模块拿不到
+// 那个服务（它的上下文里没有），而 fetch 只要同源就行。Host 侧对应
+// /doctor/incompatible 与 /doctor/install 两条路由。
+window.__ModuleLoader__.load({
+  id: '@luolingp/request-doctor',
+  factory: (require) => {
+    const React = require('react')
+    const h = React.createElement
+    const inject = ['slots']
+
+    // 界面文案。语言服务不再参与：动态模块拿不到它，标签还曾经因此显示成键名。
+    const TEXT = {
+      tabLabel: '不兼容安装',
+      intro: '下面是被当前 DSH 版本拒装的插件。装它们只需要一步：先按管理器的规则授权这个版本，再让它自己装。装完之后，声明对齐和兼容环境会自动补上。',
+      placeholder: '包名@版本，例如 dsh-ssh-ops@0.4.0',
+      install: '授权并安装',
+      requires: '要求运行在',
+      none: '当前没有被拒装的插件。可以在上面直接填包名安装，或点「重新扫描」重算一遍。',
+      working: '正在处理',
+      done: '已装好，兼容环境会在后台补上',
+      failed: '没能装上',
+      rescan: '重新扫描',
+      offline: '连不上 Host 侧的安装路由，可以改用命令：',
+    }
+
+    const style = {
+      column: { display: 'flex', flexDirection: 'column', gap: 14, width: '100%', minWidth: 0 },
+      title: { margin: 0, fontSize: '0.95em', fontWeight: 600 },
+      text: { margin: 0, fontSize: '0.9em', lineHeight: 1.6, opacity: 0.8 },
+      hush: { margin: 0, fontSize: '0.9em', opacity: 0.7 },
+      mono: { margin: 0, fontSize: '0.85em', opacity: 0.75, fontFamily: 'monospace' },
+      line: { display: 'flex', gap: 8, alignItems: 'center' },
+      field: {
+        flex: 1, padding: '6px 10px', borderRadius: 8, font: 'inherit',
+        border: '1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.4))',
+        background: 'var(--dsw-alias-bg-l1, transparent)', color: 'inherit',
+      },
+      press: {
+        padding: '6px 14px', borderRadius: 8, cursor: 'pointer', font: 'inherit',
+        border: '1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.4))',
+        background: 'var(--dsw-alias-bg-l2, transparent)', color: 'inherit',
+      },
+      card: {
+        display: 'flex', flexDirection: 'column', gap: 8, padding: '10px 12px', borderRadius: 10,
+        border: '1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.3))',
+      },
+    }
+
+    // 统一走同源路由：取回 JSON，失败就把原因抛出去，由调用方决定怎么显示。
+    async function requestJson(path, init) {
+      const response = await fetch(path, init)
+      return response.json()
+    }
+
+    // 读一次被拒插件清单。Host 侧已经把不可用的行筛掉了。
+    async function loadRows() {
+      const data = await requestJson('/doctor/incompatible', { headers: { accept: 'application/json' } })
+      if (data.ok !== true) throw new Error(data.reason || 'host declined')
+      return data.rows || []
+    }
+
+    // 装一个包。授权、重试、声明对齐都在 Host 侧完成，这里只拿结果。
+    async function postInstall(spec) {
+      const data = await requestJson('/doctor/install', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ spec }),
+      })
+      return { ok: data.ok === true, reason: data.text || '' }
+    }
+
+    // 让 Host 立刻重算一轮审计，不用等下一次定时扫描。
+    async function postRescan() {
+      const data = await requestJson('/doctor/rescan')
+      return { ok: data.ok === true, reason: data.reason || '' }
+    }
+
+    function IncompatiblePanel() {
+      const [rows, setRows] = React.useState([])
+      const [spec, setSpec] = React.useState('')
+      const [busy, setBusy] = React.useState(false)
+      const [note, setNote] = React.useState('')
+
+      const refresh = React.useCallback(async () => {
+        try {
+          setRows(await loadRows())
+        } catch (error) {
+          // 路由不通就把可用的替代办法说出来，不留空白。
+          setNote(`${TEXT.offline} /doctor install <包名>（${String((error && error.message) || error)}）`)
+        }
+      }, [])
+
+      React.useEffect(() => { refresh() }, [refresh])
+
+      // 两个入口共用同一段收尾：跑、报结果、刷新列表。
+      async function run(label, task) {
+        setBusy(true)
+        setNote(`${TEXT.working} ${label}`)
+        try {
+          const outcome = await task()
+          setNote(outcome.ok ? `${TEXT.done}：${label}` : `${TEXT.failed}：${outcome.reason}`)
+          await refresh()
+        } catch (error) {
+          setNote(`${TEXT.failed}：${String(error)}`)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const submit = () => {
+        const trimmed = spec.trim()
+        if (trimmed === '') return
+        run(trimmed, () => postInstall(trimmed))
+      }
+
+      const children = []
+      children.push(h('p', { key: 'title', style: style.title }, TEXT.tabLabel))
+      children.push(h('p', { key: 'intro', style: style.text }, TEXT.intro))
+      children.push(h('div', { key: 'entry', style: style.line },
+        h('input', {
+          value: spec, style: style.field, placeholder: TEXT.placeholder,
+          onChange: (event) => setSpec(event.target.value),
+        }),
+        h('button', {
+          type: 'button', style: style.press, disabled: busy, onClick: submit,
+        }, TEXT.install),
+        h('button', {
+          type: 'button', style: style.press, disabled: busy,
+          onClick: () => run(TEXT.rescan, postRescan),
+          style: { ...style.press, opacity: 0.8 },
+        }, TEXT.rescan)))
+
+      if (rows.length === 0) {
+        children.push(h('p', { key: 'none', style: style.hush }, TEXT.none))
+      } else {
+        children.push(h('div', { key: 'rows', style: style.column }, rows.map((row) => h('div', {
+          key: `${row.name}@${row.version}`, style: style.card,
+        },
+        h('div', { style: style.title }, `${row.name}@${row.version}`),
+        h('div', { style: style.hush }, `${TEXT.requires} ${row.runtimeVersion || '?'}`),
+        h('button', {
+          type: 'button', style: style.press, disabled: busy,
+          onClick: () => run(`${row.name}@${row.version}`, () => postInstall(`${row.name}@${row.version}`)),
+        }, TEXT.install)))))
+      }
+
+      // Host 的返回是多行文本（安装结果、位置、兼容环境），按原样保留换行。
+      if (note !== '') children.push(h('p', { key: 'note', style: { ...style.hush, whiteSpace: 'pre-wrap' } }, note))
+      return h('div', { style: style.column }, ...children)
+    }
+
+    function apply(ctx) {
+      if (typeof ctx.slots?.inject !== 'function') return
+      const cells = [
+        ['plugins.tab', 'requestDoctorIncompatible', 5, TEXT.tabLabel, IncompatiblePanel],
+        ['settings.plugins.tab', 'requestDoctorSettingsTab', 20, TEXT.tabLabel, IncompatiblePanel],
+      ]
+      for (const [slot, id, order, label, Component] of cells) {
+        ctx.slots.inject(slot, () => ctx.slots.register({ name: slot, id, order, label }, Component))
+      }
+    }
+
+    const module = { exports: {} }
+    module.exports.apply = apply
+    module.exports.inject = inject
+    return module.exports
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+- insert:
+    - id: @luolingp/request-doctor
+      name: '@luolingp/request-doctor'
+      config:
+        autoRepair: true
+        autoVersionRepair: true
+        recordRetryEvents: true
+        maxRetries: 12
+        maxToolRetries: 2
+        maxVersionRepairs: 64
+        maxAuthRetries: 2
+        maxRepeatedToolCalls: 3
+        initialDelayMs: 400
+        maxDelayMs: 20000
+        jitterRatio: 0.25
+        retryableToolPattern: '^(read|read_image|glob|grep|web_fetch|web_search|cordis_inspect_.*|browser_(list_tabs|snapshot|get_text|wait|scroll)|db_(query|preview|describe_table|list_tables))$'

package/docs/00-/346/226/207/346/241/243/347/264/242/345/274/225.md

@@ -0,0 +1,26 @@
+# 文档索引
+
+| 编号 | 文档 | 对应标准条款 | 读者 |
+| --- | --- | --- | --- |
+| 01 | [软件需求规格说明](01-软件需求规格说明.md) | 6.1 | 开发者、验收方 |
+| 02 | [软件设计说明](02-软件设计说明.md) | 6.2 | 开发者、维护者 |
+| 03 | [软件测试报告](03-软件测试报告.md) | 6.6 | 验收方、维护者 |
+| 04 | [安装部署说明](04-安装部署说明.md) | 6.7 | 使用者、运维 |
+| 05 | [用户手册](05-用户手册.md) | 6.5 | 使用者 |
+| 06 | [软件质量度量报告](06-软件质量度量报告.md) | GB/T 45717-2025 | 验收方 |
+| — | [质量度量机器可读结果](quality-report.json) | — | 自动化门禁 |
+
+顶层文件：
+
+| 文件 | 说明 |
+| --- | --- |
+| `README.md` | 产品概述与快速上手 |
+| `LICENSE` | 许可协议 |
+
+---
+
+## 文档维护规则
+
+1. 需求变更先改《软件需求规格说明》，再改设计与测试报告。
+2. 任何度量项变化后重新生成《软件质量度量报告》与 `quality-report.json`。
+3. 新增模块必须在《软件设计说明》第 2.2 节登记。

package/docs/01-/350/275/257/344/273/266/351/234/200/346/261/202/350/247/204/346/240/274/350/257/264/346/230/216.md

@@ -0,0 +1,192 @@
+# 软件需求规格说明
+
+**产品名称**：request-doctor（请求急救员）
+**产品标识**：request-doctor
+**版本**：0.11.0
+
+---
+
+## 1 引言
+
+### 1.1 标识
+
+本文档适用于 request-doctor 插件。该插件以 npm 包形式发布，模块名 `request-doctor`，运行于 DeepSeek Harness（以下简称 DSH）宿主进程内，属于 Host 端插件，无客户端一半。
+
+### 1.2 系统概述
+
+DSH 是一个以 Cordis 插件框架组织的智能体运行时。插件通过组合包（bundle）安装进某个 profile，由 Loader 在启动时组合。系统存在两类对用户可见的失败：
+
+1. **请求失败**：模型请求、工具调用、浏览器载体请求在传输层、承载层或超时层失败，本身可重试，但运行时默认不重试或重试策略不足以覆盖。
+2. **版本不匹配**：已安装插件声明的 DSH 依赖范围与当前运行时版本不符，导致插件被 Loader 拒绝组合，或安装时被管理器拒绝。
+
+本插件对这两类失败自动处置，无需人工介入。
+
+### 1.3 文档概述
+
+本文档规定功能需求、外部接口需求、性能需求、设计约束、软件质量特性与验收准则。安全与隐私需求见第 5 章。
+
+---
+
+## 2 引用文件
+
+| 编号 | 名称 | 说明 |
+| --- | --- | --- |
+| GB/T 8567-2006 | 计算机软件文档编制规范 | 本文档及配套文档的编制依据 |
+| GB/T 45717-2025 | 信息技术 软件测量 软件质量测量 自动化的源代码质量测度 | 源代码质量度量依据 |
+| GB/T 8566-2007 | 信息技术 软件生存周期过程 | 验证与确认过程依据 |
+| GB/T 25000.51-2016 | 系统与软件质量要求和评价（SQuaRE） | 质量特性分类参考 |
+
+---
+
+## 3 需求
+
+### 3.1 所需状态和方式
+
+插件在 DSH 宿主进程内以单例方式运行，生命周期由 Cordis 上下文管理。插件被禁用或卸载时，所有定时器、进行中的重试、监听器必须一并释放，不得残留。
+
+### 3.2 功能需求
+
+#### FR-1 模型请求自动修复
+
+当 `agent/request-error` 事件触发时：
+
+- FR-1.1 必须在**所有下游监听器放弃重试之后**才接管，避免与 provider 自有重试策略形成双重重试链。
+- FR-1.2 必须区分"客户端原因"与"服务端原因"，仅修复前者。
+- FR-1.3 客户端原因必须覆盖下列形态，并归入对应的处置策略：
+
+| 形态 | 归类 | 处置 |
+| --- | --- | --- |
+| 传输中断、流式断连、socket 重置 | `transport` | 退避重试 |
+| SSE 长连接超时、事件流被截断 | `stream` | 退避重试 |
+| 超时 | `timeout` | 退避重试 |
+| 空响应 | `empty` | 退避重试 |
+| 上下文累加超限、裁剪策略失效 | `overflow` | 先压缩再重试 |
+| 压缩后仍超限、压缩自身打转 | `compaction-loop` | 先修历史，再重试 |
+| 会话历史损坏、规则文件解析失败、配置 JSON 解析失败 | `history` | 先修历史，再重试 |
+| Wire API 版本不匹配 | `protocol` | 有限重试 |
+| 角色字段不被接受、客户端追加独有参数、tool_call 格式不符 | `protocol` | 有限重试 |
+| 模型 ID 写死、模型能力判断错、模型列表缓存过期 | `model` | 先刷新模型目录，再重试 |
+| Header 构造错误、OAuth 会话过期、本地缓存 token 失效、不自动刷新 | `auth` | 先刷新凭据，再重试 |
+| 多 Key 轮换挑到失效项、Provider 侧缓存了旧凭据 | `auth` | 先刷新凭据，再重试 |
+| MCP 子服务独立鉴权失败 | `auth` | 先刷新凭据，再重试 |
+| MCP 会话关闭、握手失败、子服务未起 | `mcp` | 退避重试 |
+| `PI_AI_ERROR` | `provider-error` | 退避重试 |
+| 端口占用、句柄耗尽、内存不足、子进程崩溃、本地中转服务崩溃 | `local-env` | 退避重试 |
+| 权限不足、路径不存在、磁盘写满、沙箱拦截 | `local-blocked` | **不重试** |
+| TLS 证书校验失败、自签名、证书过期 | `tls` | **不重试** |
+| 配额耗尽、欠费、限流、内容审核、图片超限 | `quota` / `policy` / `image` | **不处置** |
+
+- FR-1.4 服务端原因不得处置，包括：配额耗尽、账号欠费、限流、上游 5xx、内容审核拦截、图片超限。
+- FR-1.5 重试必须采用有界指数退避，带抖动，且受单步预算约束。
+- FR-1.6 上下文超限时，必须先尝试压缩与工具结果裁剪，再重试。
+- FR-1.7 适配器缺失时，必须先触发版本修复，修复无效则不重试。
+- FR-1.7a 凭据失效**不得**走版本修复：重装插件不会让过期 token 变新。应先请求本机凭据层刷新，再重试。
+- FR-1.8 重试过程必须以既有的 `llm/retry` / `llm/retry-started` 会话事件记录，**不得新增会话事件类型**。
+- FR-1.9 同一处失败（按轮次、步骤、provider、类别定位）同时只允许一个重试在飞，避免并发重试叠加。
+- FR-1.10 压缩或修历史连续两轮未见进展时，必须停止重试并留下记录，不得无限循环。
+- FR-1.11 鉴权类失败的重试额度必须独立于普通重试额度，取值更小。
+- FR-1.12 不可重试类（证书、权限、路径、磁盘）必须直接放弃，不得进入退避。
+
+#### FR-2 工具调用自动修复
+
+当 `tools/execute` 事件触发且结果为瞬时失败时：
+
+- FR-2.1 仅允许重放**只读类**工具，白名单可配置。
+- FR-2.2 有副作用的工具（命令执行、写文件、发送消息等）一律不得重放。
+- FR-2.3 重放次数受 `maxToolRetries` 约束。
+- FR-2.4 同名同参的调用连续出现次数受 `maxRepeatedToolCalls` 约束；超过后**不得再重放**，避免把宿主侧失效的循环检测放大成重放风暴。
+
+#### FR-3 浏览器载体自动修复
+
+当 `connection/request` 事件在响应头发出前失败，且属于瞬时传输错误时：
+
+- FR-3.1 必须替换为 `503` 并附 `retry-after`，使前端自身恢复逻辑可以重发。
+- FR-3.2 响应头已发出或响应体已结束时，必须原样抛出原错误，不得写出残缺响应。
+
+#### FR-4 版本不匹配自动修复
+
+- FR-4.1 必须发现**全部**不兼容插件，而非只处理首个。
+- FR-4.2 发现来源必须覆盖：Loader 拒绝的包、已启用但未被拒绝的包、已禁用但已安装的包、安装时被延迟处理的包。
+- FR-4.3 修复前必须审计：该插件所导入的每个 `@deepseek-ai/*` 符号在现行运行时中是否仍然存在。
+- FR-4.4 审计通过者才可修复；审计未通过者只报告，不修改。
+- FR-4.5 修复方式为**兼容环境**：在插件目录内建立嵌套 `node_modules`，其中每个被重定位的包是一个声明旧版本号的垫片，转发到现行实现。
+- FR-4.6 修复必须同时对齐插件自身 manifest 中的 DSH 依赖声明，因为 Loader 在组合前读取该文件。
+- FR-4.7 **不得绕过版本检查**：修复后的声明必须真实满足当前运行时。
+- FR-4.8 现行运行时不存在的符号**不得伪造**。必须为插件安装它期望的那份真实旧版本；旧版本也没有时如实报缺。
+- FR-4.13 兼容环境装入真实旧版本后重载失败、且失败原因是缺少导出时，必须判定为「需要重启」，向用户给出明确提示，**不得**记为环境失败。
+- FR-4.12 **不得使用占位实现**。缺符号只有两种出路：装真实旧版本，或如实拒绝。
+- FR-4.9 环境建成后必须**逐条核对**插件所需符号是否真能提供；核对不通过不得计为已修复。
+- FR-4.10 核对无法进行时（目标文件不可读）不得判为失败，应单独记录为未核对。
+- FR-4.11 扫描须识别「垫片存在但内容不对」的情况并重新适配。
+
+#### FR-5 不兼容插件安装支持
+
+- FR-5.1 必须提供在安装前预置兼容环境的手段，使管理器的版本检查按其自身规则通过。
+- FR-5.2 安装失败或被取消时，必须完整回滚到候选目录原状。
+- FR-5.3 仅支持本地目录；注册表包字节尚未落盘，必须明确报告为不支持，不得静默失败。
+
+#### FR-6 状态与诊断
+
+- FR-6.1 必须提供 `/doctor` 命令，输出各类修复计数与最近事件。
+- FR-6.2 `/doctor install <路径>` 执行安装前预置。
+- FR-6.3 诊断快照可选写入文件，写入不得阻塞事件循环。
+
+### 3.3 性能需求
+
+- PR-1 稳态下后台扫描的 CPU 与 I/O 开销必须可忽略，采用退避策略。
+- PR-2 已适配插件必须从后续扫描的审计集合中自然退出，不得反复审计。
+- PR-3 任何长期存活的数据结构必须有界。
+- PR-4 定时器必须不阻止进程退出。
+
+### 3.4 设计约束
+
+- DR-1 不得依赖 `node_modules` 之外的第三方包；插件须在无额外依赖的 profile 中运行。
+- DR-2 不得调用 `setBundleEnabled` / `removeBundle` 操作本插件扫描范围之外的插件。
+- DR-3 路由冲突只报告，不处置——归属用户决定。
+- DR-4 不得新增会话事件类型，避免未知事件被读取方拒绝。
+- DR-5 源码质量须满足 GB/T 45717-2025 度量限值，见《软件质量度量报告》。
+
+### 3.5 属性
+
+- AR-1 平台：Windows / macOS / Linux，Node.js ≥ 20。
+- AR-2 运行时：DSH 0.2.x。
+- AR-3 并发：同一 profile 内单实例；修复过程以互斥标志防止重入。
+
+---
+
+## 4 合格性规定
+
+| 需求 | 验证方法 | 证据 |
+| --- | --- | --- |
+| FR-1.1 ~ FR-1.8 | 自动化测试 | `test/plugin.test.mjs`、`test/classify.test.mjs` |
+| FR-2.1 ~ FR-2.3 | 自动化测试 | `test/plugin.test.mjs` |
+| FR-3.1 ~ FR-3.2 | 自动化测试 | `test/plugin.test.mjs` |
+| FR-4.1 ~ FR-4.8 | 自动化测试 + 实机验证 | `test/compat*.test.mjs`、`RELEASE_CHECKLIST.md` |
+| FR-4.9 ~ FR-4.11 | 自动化测试 | `test/env-verify.test.mjs`、`test/verify-roundtrip.test.mjs` |
+| FR-4.12 不用占位 | 自动化测试 | `test/compat-env.test.mjs`（装真实旧版本 / 旧版本也没有则拒绝）、`test/dry-run.test.mjs` |
+| FR-5.1 ~ FR-5.3 | 自动化测试 + 实机验证 | `test/install-support.test.mjs` |
+| FR-6.1 ~ FR-6.3 | 代码审查 + 实机验证 | `index.js`、`lib/diagnostics.js` |
+| PR-1 ~ PR-4 | 代码审查 + 度量 | `lib/stat-cache.js`、`lib/timers.js`、《软件质量度量报告》 |
+| DR-1 ~ DR-5 | 代码审查 | 依赖清单、事件清单 |
+
+---
+
+## 5 安全与隐私
+
+- SR-1 插件不读取、不传输任何凭据内容；仅判断凭据相关错误码。
+- SR-2 插件不外发任何数据；全部处理在本地进程内完成。
+- SR-3 修改插件目录前必须备份原 manifest，备份文件名为 `package.json.request-doctor-original`。
+- SR-4 删除兼容环境时只删除本插件创建的包，不得删除插件自带的依赖。
+- SR-5 诊断快照默认不写文件；启用后内容限于计数、事件类别与配置项，不含请求体。
+
+---
+
+## 6 注释
+
+- 6.1 术语
+  - **兼容环境**：插件目录内嵌套的 `node_modules`，含声明旧版本号的垫片包。
+  - **垫片（shim）**：只做 `export *` 转发的最小包。
+  - **审计**：判定插件所需符号在现行运行时是否存在的过程。
+  - **退避**：重试间隔按指数增长并加抖动。
+- 6.2 待定事项
+  - 安装前预置目前需显式调用 `/doctor install`；拦截 `install_bundle` 工具调用可进一步自动化，但会改变既有工具行为，需单独确认。