# 插件管理、实验性插件与升级

[首页](README.md) · [日常操作](operations.md)

操作入口为“更多 → 主机插件”，操作目标始终是当前主机确认的 profile。市场页面使用主机的官方 `pluginMarket` 索引；列表或搜索结果不是安全、兼容性或安装成功的背书。

## KB-PLUGIN-01：已安装插件没显示、实验性插件找不到

**先看：** 当前连接主机/profile、名称与状态筛选，以及“内置插件”页；旧版可能把主机提供的实验性条目归在内置列表。

**当前源码行为：** 官方实验性条目在“已安装 → 实验性插件（数量）”中，默认收起。展开后显示，刷新/筛选保留展开状态，重新进入插件页恢复收起。这个改动在本库基线中尚未公开发布；用户当前旧包不一定有此行为。

**判断：** “已安装”“配置启用”“运行中”分别来自依赖/配置与运行快照。实验性、主机提供或核心包不等于 Remote 可管理的第三方依赖。

**验收：** 正确 profile 的条目可找到，名称/状态吻合；主机维护的包保持只读，不因显示出来就获得卸载、更新或启停权限。

## KB-PLUGIN-02：插件中心只读，无法启停或更新

**先看：** 是否能确认 profile、对应 DSH CLI/桌面 carrier、实际运行时；条目是否核心包、主机提供或 Remote 本身。

**判断：** 无法验证管理入口时只读是保护行为。`@deepseek-ai/*` 核心包和非 profile 依赖不能按普通第三方包管理；Remote 自身只提供明确确认的精确版本更新。

**下一步：** 在主机官方管理入口确认版本与安装完整性。不要为了显示开关而强行设置 managed，也不要退回 PATH 中另一个全局 CLI。

**验收：** 管理目标可验证，正常第三方条目有恰当动作；受保护条目仍由主机维护。配置启停完成后通常还需重启 DSH，不能称为热生效。

**适配诊断（当前未发布源码）：** 卡片区分配置、运行状态、待重启和实际读取证据。运行中但尚未打开页面时显示“接口待读取验证”；只有用户主动读取成功才显示成功。接口不兼容、缺失、认证拒绝、失败或超时应分别处理。证据仅关联当前主机/令牌/版本，不代表所有数据和所有会话都可读取；列表本身不查询余额、技能正文或任务快照。

## KB-PLUGIN-03：更新卡住、任务锁或 pnpm 发布时间限制

**先看：** 操作记录中的目标包/版本、阶段、最后输出、错误与任务归属。阶段包括预检、备份、快照、CLI、核验和完成；关闭客户端不取消主机任务。

| 证据 | 意味着什么 | 下一步 |
| --- | --- | --- |
| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | 发布时间策略阻止；可能是锁文件中另一个包 | 指明实际阻塞包、精确版本和规则；不要自动清锁或降低全局策略 |
| Windows `EPERM` rename | 文件占用/权限等，需要查操作对象与实例 | 保留备份和日志；不能宣称自动回滚，不能盲目重试安装 |
| 快照路径越界 | 快照安全检查失败，不等于下载失败 | 核对链接是否属于同 profile 的 local-plugins；不放开外部路径边界 |
| worker/CLI 仍活着 | 任务可能仍执行或静默等待 | 不删任务锁，不杀所有 node |
| 身份/权限查询失败 | 不知道是否有活进程 | 保留锁，记录权限限制；不能当作进程已退出 |

**恢复：** 自动死任务回收会核对已知进程；旧锁人工恢复仍要确认没有安装进程。还原是单独的、需要用户授权的动作，会核验指纹/版本，避免覆盖失败后的新修改。

**验收：** 任务进入明确终态，实际包版本与配置核验一致，必要时重启并读回运行版本。CLI 退出 0 或 HTTP 200 不单独证明更新成功。

## KB-PLUGIN-04：安装、精确更新与还原的操作顺序

1. 确认主机/profile、插件包名、精确版本与当前任务为空闲；读取插件要求和兼容状态。
2. 发起预检，查看将修改的依赖、发布时间限制与恢复范围；用户确认后才执行写操作。
3. 记录任务 ID，等待终态，读取实际安装版本和待重启状态。失联时先查原任务，不重新创建安装。
4. 如失败，保存错误阶段；需要恢复时审阅“恢复更新前状态”的内容与校验结果，再执行。
5. 更新 Remote 本体后，先确认安装任务完成，再重启 DSH 加载新插件。新插件会检查网关版本/上游，并通过已有令牌认证关闭旧网关、拉起新网关；随后读回运行版本与连接状态，不凭升级文件推断旧进程已获得修复。

**旧网关升级卡住：** 早期 0.7.x 的精简探活只有 `liveness.pid`。旧插件可能将它误判为未运行，随后只报告端口占用；当前工作区已兼容，尚未公开发布。不要仅因此要求用户更换端口。令牌不匹配时应保留旧服务、报告认证问题；Windows 旧进程占用包目录则按主机维护流程处理。已做 Windows 隔离宿主/网关/换包/恢复模拟及本地 registry 的真实 pnpm 自更新验证；这不代替报告者 macOS 或真实 Desktop ASAR 验收。详细记录位于源码仓库 `docs/remote-self-update-verification.md`。

普通用户优先使用管理页流程。`pnpm remove/add` 本地 tgz 替换、特殊安装脚本或额外凭据配置只在已授权的主机维护中处理；不要把命令模板直接作用于用户真实 profile。

## KB-PLUGIN-05：任务看板、费用或团队数据显示不完整

**任务看板：** 当前未发布源码只适配 `@linxin666/dsh-client-ui-task-board` 的只读 `taskBoard.snapshot()`、schema 6。先确认插件已启用且运行，再在其卡片打开看板并选已注册工作区。只展示该工作区的任务；未绑定、其他工作区、隐藏任务不展示，归档需勾选。最多 200 条，活跃与最近任务优先。服务或数据格式不兼容时不自行读取账本文件。

**执行与验收：** 看板列是任务状态，最近执行是执行记录，验收是另一个结果，三者不能互相替代。外部报告和不属于主机登记工作区的执行会话不提供跳转。计划时间使用规则/主机时区；没有下次时间保持未知。

**费用：** 自定义渠道余额和网关额度遵守主机启用/隐藏开关。不同币种和积分不能相加；未知、失败、缓存数据不等于余额为零。部分账户失败时仍可显示其他有效账户；保留供应商查询时间，不把界面刷新时间当作供应商刷新。设置与凭据仍由费用插件拥有。

**团队：** 分别查看计划审查、交付阻断和可展开警告。只有插件同时确认可交付且交付检查通过，才称可交付。等待审查反馈不能当作执行卡死，警告也不能直接当作验收失败。

**验收：** 对应主机/工作区/币种/时间和状态一致，切换工作区后不残留旧数据，刷新失败明确保留旧结果，返回插件列表能查看适配诊断。详细源码/模拟证据位于仓库 `docs/plugin-adaptation-2026-10-23.md`；这些功能尚未公开分发。

## KB-PLUGIN-06：Windows 上 DSH 更新失败 / 被插件网关占用

**先看：** 安装是否真的执行过（安装目录当天是否有写入）、`resources\app.asar` 与卸载登记项版本是否更新，以及安装目录内的 `DeepSeek Harness.exe` 是否仍被进程占用。更新前 DSH 会退出，但 Remote 插件的常驻网关按设计继续运行。本条目依据 2026-10-24 在 Windows 10 + DSH Desktop 0.2.1-rc.3 上的实际事件核对，插件为修复前版本。

| 证据 | 意味着什么 | 下一步 |
| --- | --- | --- |
| DSH 已退出时，对 `<DSH 安装目录>\DeepSeek Harness.exe` 做 `r+` 打开仍报 `EBUSY`/`EPERM` | 仍有进程以该 exe 运行，Windows 无法替换；旧插件网关常用 `process.execPath` 启动 | 查网关进程与解释器路径，核对归属后停止或由新插件接管 |
| 安装器或更新流程提示占用/失败，Restart Manager 点名同一 exe 或 `gateway.cjs` | 插件网关持有安装目录内 exe，NSIS 原地替换被阻塞 | 不要反复重试安装；先解除占用 |
| Prefetch 有安装器记录、`%TEMP%` 有 `nsr*.tmp`，但安装目录当天 0 个文件更新 | 安装器运行过但未写入，不能当作下载或校验失败 | 按占用处理，再重试更新 |
| 卸载登记项 `DisplayVersion` 与 `resources\app.asar` 修改时间仍是旧值 | 新版本没有落盘 | 解除占用并重试后，再核对这两项 |

**0.8.1 起的行为：** 插件按 `DSH_REMOTE_NODE` → PATH `node` → 内置运行时副本 → `process.execPath` 的顺序选择网关解释器；旧插件需升级后才能获得。所选来源与告警显示在插件面板版本号旁，跳过原因写入 `~/.dsh-remote/plugin-gateway.log`。

外部解释器通过版本检测但启动失败时，仍会先尝试内置副本再回退宿主。路径按真实位置检查，目录联接不能把安装目录内的 exe 伪装成外部候选。面板只显示当前网关 PID 对应的实际解释器；旧网关无法报告时显示「网关解释器待确认」，停止再启动后确认。重启桌面插件后，可认证迁移同版本遗留网关；已尝试并回退的实例不会被反复重启。

**判断：** 反直觉的是，更新时 DSH 本体已经关闭，所以「DSH 还在运行」通常不是占用源；遗留的插件网关才是常见阻塞者。Windows 不允许覆盖正在运行的 exe，而 NSIS 更新器会替换整个安装目录；Linux/macOS 的运行中可执行文件可以替换，不受影响。

**下一步：** 升级到含网关解释器修复的插件版本；重启 DSH 或从插件面板停止/启动网关，让旧网关被认证关闭并拉起新网关；确认网关解释器不在安装目录内，再重试内置更新。旧版插件遗留的网关可在插件面板停止。进程核对命令与选择顺序见仓库 `docs/troubleshooting.md` 的「Windows：DSH 更新点了没反应 / 提示安装更新失败」；`DSH_REMOTE_NODE` 等配置见仓库 `docs/configuration.md` 的「网关解释器」。

**验收：** 卸载登记项版本与 `resources\app.asar` 已更新，安装目录有实际写入；网关继续运行且 `ExecutablePath` 为 PATH node 或 `~/.dsh-remote/runtime/node-<版本>.exe`，不在安装目录内；插件面板不再显示「网关解释器位于 DSH 安装目录内，DSH 更新可能失败」告警。仍显示告警说明当前回退到安装目录内 exe，需按配置参考改用合格 Node。

依据：仓库 `packages/plugin/plugin-center.mjs`、`plugin-transaction.mjs`、`task-board.mjs`、`insights.mjs`、`index.mjs`、`public/plugin-center.js`、`public/task-board.js`，以及 `docs/plugin-center.md`、`docs/plugin-update-transaction.md`。