dsh-paoding 0.3.4 → 0.3.6

package/README.md

@@ -17,9 +17,9 @@ dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理
 - **装了什么都能认出来**：MCP 服务器、本地插件、已装技能，安装与配置时全程检测；默认只装 dsh 基础工具，检测到的 host 工具在「庖丁配置」里按需勾选；停用哪个，重新应用后相关工具自动剔除。
 - **按工作区各有各的班底**：不同项目可以配不同的主/子 agent——「庖丁配置」里选定工作区单独配置，每个工作区生成自己的预设（`orchestrator-<目录名>`），新建会话时选对应预设即可，全局默认不受影响。
 - **图形界面配置**：不习惯改配置文件的话，点开左侧栏底部动作条（设置行上方）的「庖丁配置」入口，整页点选即可，「保存并应用」即时重生成预设——与首装自动化同一条生成管线。
-- **版本更新有提醒，面板一键升级**：面板会对比 npm registry（GitHub release 兜底）上的最新版本，发现新版就地提示并附上发布页链接；点「升级」就地执行 `dsh plugin update dsh-paoding`（profile 自动探测）换上新版，重启 DSH 后生效，编排预设会在重启时按新版自动重生成。开发检出的 link 形态无法就地升级，面板会提示切回 registry 版的办法；检测失败（比如断网）就静默跳过，不影响任何使用。
+- **版本更新有提醒，面板一键升级**：面板会对比 npm registry（npmmirror 镜像、GitHub release 依次兜底）上的最新版本，发现新版就地提示并附上发布页链接；点「升级」就地执行 `dsh plugin update dsh-paoding`（profile 自动探测）换上新版，重启 DSH 后生效，编排预设会在重启时按新版自动重生成。开发检出的 link 形态无法就地升级，面板会提示切回 registry 版的办法；检测失败时页头留一行「版本检测失败 · 重试」（完整原因与代理排查提示在悬浮提示里），不弹窗打扰。
 - **来去自由**：不改 DSH 一行源码；装完新会话即用，卸载即删目录。
-- **两代宿主都兼容**：DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 全支持——两代宿主发现预设的机制不同（目录扫描 vs patch 声明行），安装器自动检测宿主版本选对落点，宿主升级、降级后的首次保存/自愈自动迁移，全程无感。
+- **两代宿主都兼容**：DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1.7-rc.2 全支持——两代宿主发现预设的机制不同（目录扫描 vs patch 声明行），安装器自动检测宿主版本选对落点，宿主升级、降级后的首次保存/自愈自动迁移，全程无感。
 
 ## 插件截图
 
@@ -27,7 +27,7 @@ dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理
 
 ## 快速开始
 
-前置：**Node.js ≥ 18**、**pnpm** 与一台已装好的 DSH host（**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1** 全支持，预设落点自动适配两代宿主机制）。
+前置：**Node.js ≥ 18**、**pnpm** 与一台已装好的 DSH host（**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.2** 全支持，预设落点自动适配两代宿主机制）。
 
 **官方插件通道（唯一安装入口）**——不用克隆仓库，一条命令，装完重启即用：
 
@@ -80,7 +80,7 @@ dsh plugin --profile web add link:"$PWD/dsh-paoding"
 | 文档 | 内容 |
 |---|---|
 | [架构](docs/architecture.md) | 为什么这样设计——概述、成本账、角色与工具、对应 DSH 原生机制、Token 治理、已知边界。 |
-| [安装](docs/installation.md) | 官方插件通道一条命令安装、版本支持与预设落点双轨（DSH 0.1.5 – 0.1.7-rc.1）、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载、排查。 |
+| [安装](docs/installation.md) | 官方插件通道一条命令安装、版本支持与预设落点双轨（DSH 0.1.5 – 0.1.7-rc.2）、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载、排查。 |
 | [编排](docs/orchestration.md) | 编排总览、失败如何呈现与三层处理、one-shot vs continuable、上下文隔离。 |
 | [配置](docs/configuration.md) | 配置键全参考、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型、角色会话模式。 |
 

package/README_en.md

@@ -17,9 +17,9 @@ dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of
 - **Whatever you've installed, it's recognized**: MCP servers, local plugins, installed skills — detected throughout install and configuration; the default install carries only DSH base tools, and detected host tools are opted into per tool in **Paoding Config**; disable one, re-apply, and its tools drop out on their own.
 - **A different lineup per workspace**: each project can carry its own main/sub-agent setup — pick the workspace in 庖丁配置, configure it separately, and it gets its own preset (`orchestrator-<basename>`); choose that preset when starting a session. The global default stays untouched.
 - **A visual configurator**: prefer clicking to editing YAML? the 庖丁配置 (Paoding Config) entry in the sidebar bottom action bar (above the Settings row) covers everything; Save & Apply regenerates the preset on the spot — the same generation pipeline as first-install automation.
-- **Notified of new releases, one-click upgrade in the panel**: the panel compares your local version against the latest npm registry publish (GitHub release as fallback) and points to the release page when a newer one is out. The Upgrade button runs `dsh plugin update dsh-paoding` in place (profile auto-detected) to swap in the new version; a DSH restart applies it, and the orchestrator preset regenerates itself against the new version on startup. A dev checkout in link: form cannot be upgraded in place — the panel tells you how to switch back to the registry version. If the check fails (offline, rate-limited), it stays silent and nothing is interrupted.
+- **Notified of new releases, one-click upgrade in the panel**: the panel compares your local version against the latest npm registry publish (npmmirror and GitHub release as successive fallbacks) and points to the release page when a newer one is out. The Upgrade button runs `dsh plugin update dsh-paoding` in place (profile auto-detected) to swap in the new version; a DSH restart applies it, and the orchestrator preset regenerates itself against the new version on startup. A dev checkout in link: form cannot be upgraded in place — the panel tells you how to switch back to the registry version. If the check fails (offline, rate-limited), a subdued "version check failed · retry" row stays in the header (full causes and proxy hints in its tooltip) without popping anything up.
 - **Installs and uninstalls cleanly**: no DSH source changes; active in a new session right after install, gone when you delete one directory.
-- **Works on both host generations**: DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 are all supported — the two generations discover presets differently (directory scan vs patch declaration rows), and the installer picks the right landing automatically, then migrates on the first save/self-heal after a host upgrade or downgrade, all without user action.
+- **Works on both host generations**: DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1.7-rc.2 are all supported — the two generations discover presets differently (directory scan vs patch declaration rows), and the installer picks the right landing automatically, then migrates on the first save/self-heal after a host upgrade or downgrade, all without user action.
 
 ## Screenshots
 
@@ -27,7 +27,7 @@ dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of
 
 ## Quick Start
 
-Prerequisites: **Node.js ≥ 18**, **pnpm**, and a working DSH host (**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1**, all supported — the preset landing adapts to the host generation automatically).
+Prerequisites: **Node.js ≥ 18**, **pnpm**, and a working DSH host (**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.2**, all supported — the preset landing adapts to the host generation automatically).
 
 **The official plugin channel (the only install route)** — no clone needed; one command, then a restart:
 
@@ -80,7 +80,7 @@ All preferences live in `~/.dsh/dsh-paoding.config.yml`: role add/remove/tweak,
 | Document | Contents |
 |---|---|
 | [Architecture](docs/architecture_en.md) | Why it is designed this way — overview, the cost ledger, roles and tools, mapping to DSH's native mechanisms, token governance, known limits. |
-| [Installation](docs/installation_en.md) | The single official channel (`dsh plugin add`), version support and the dual preset landing (DSH 0.1.5 – 0.1.7-rc.1), first-install automation and the version marker, upgrading, dev-checkout install, host patch detection, the Paoding Config panel, uninstalling, troubleshooting. |
+| [Installation](docs/installation_en.md) | The single official channel (`dsh plugin add`), version support and the dual preset landing (DSH 0.1.5 – 0.1.7-rc.2), first-install automation and the version marker, upgrading, dev-checkout install, host patch detection, the Paoding Config panel, uninstalling, troubleshooting. |
 | [Orchestration](docs/orchestration_en.md) | Orchestration overview, how failures surface and the three recovery layers, one-shot vs continuable, context isolation. |
 | [Configuration](docs/configuration_en.md) | The full key reference, tuning built-in roles, main-agent tools and skills, custom roles, per-role models, per-role session modes. |
 

package/docs/architecture.md

@@ -269,7 +269,7 @@ grep inline cap 与对照同设计）后，根因锁定为：**默认压缩从
 触发），配合 retainRatio 默认保留约 16% 尾部（≈42K）+ 摘要 checkpoint，稳态平均回落到 ~80K 量级。
 压缩每次触发调用一次 LLM 摘要——复用前缀缓存，成本极低——因此触发频繁一点也几乎不额外花钱；
 0.45 是「省 token 与不频繁摘要」之间的平衡点。compaction-basic 另显式钉了 `maxTokens: 8192`：
-DSH 0.1.7 起宿主默认升到 65536，显式值让 0.1.5 – 0.1.7-rc.1 全系的摘要预算行为保持一致。
+DSH 0.1.7 起宿主默认升到 65536，显式值让 0.1.5 – 0.1.7-rc.2 全系的摘要预算行为保持一致。
 
 **参数与效果。**
 

package/docs/architecture_en.md

@@ -352,7 +352,7 @@ performs one LLM summarization call that reuses the prefix cache, so its cost is
 somewhat more often costs almost nothing extra; 0.45 is the balance point between saving tokens and not
 summarizing too frequently. compaction-basic also pins `maxTokens: 8192` explicitly: from DSH 0.1.7 the host
 default rises to 65536, and the explicit value keeps the summary-budget behavior identical across
-0.1.5 – 0.1.7-rc.1.
+0.1.5 – 0.1.7-rc.2.
 
 **Parameters and effect.**
 

package/docs/configuration.md

@@ -19,7 +19,7 @@ dsh-paoding 把「按角色分工的编排 preset」做成**配置驱动**：你
 | 场景 | 行为 |
 |---|---|
 | Web 面板（左侧栏「庖丁配置」入口） | **主路径**：打开面板会把既有配置加载为当前值，点「保存并应用」写入 preset 并把分配保存到配置文件（默认 `~/.dsh/dsh-paoding.config.yml`，以 `0o600` 权限写入）。手编过配置文件的话，先开面板再应用即可 |
-| 首装自动化 | 插件启动时发现 preset 缺失或版本标记不符，自动按配置文件应用一次（无配置则写基础模板）——日常无需手动触发 |
+| 首装自动化 | 插件启动时发现 preset 缺失、版本标记不符、或宿主预设轨道翻转（只升 dsh 不动插件），自动自愈一次：前者按配置文件重生成（无配置则写基础模板），轨道翻转只按磁盘产物补写缺失的声明行、不重生成内容——日常无需手动触发 |
 | 兜底 CLI（仅限克隆仓库的开发者） | `node tools/install.mjs --auto`：有配置文件则幂等应用，没有则写基础模板；`--dry-run` 只打印检测报告与将生成的 allow / persona 变化，不写任何文件（含配置文件），适合先预览再动手；`--config <file>` 用指定文件替代默认位置 |
 
 配置文件**存在但解析失败**是硬错误（直接报错退出）；**不存在**则视为无配置（写基础模板）。`profile`、`roles` 等顶层键的语义见下节。

package/docs/installation.md

@@ -12,14 +12,14 @@
 
 - **Node.js ≥ 18**。DSH host 与插件链路都跑在 Node 上；版本过低时 `dsh` 本身就起不来。可用 `node --version` 自查。
 - **pnpm 可用**。`dsh plugin` 是 pnpm 的透明转发器：插件包装进 profile 时由 pnpm 完成。缺失时安装命令会报 pnpm 相关错误，装好 pnpm（`npm i -g pnpm` 或 `corepack enable`）后重试。
-- **已安装 DSH host**（`dsh` 可用，含其 Web/agent 运行时；**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1** 全支持，安装器自动适配两代预设机制，详见第 2 节「版本支持与预设落点双轨」）。本插件不改 DSH 源码，只往 DSH 的 preset roster 写入编排预设、并把「庖丁配置」面板挂进 Web 左侧栏，因此先要有可用的 DSH 家目录。
+- **已安装 DSH host**（`dsh` 可用，含其 Web/agent 运行时；**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.2** 全支持，安装器自动适配两代预设机制，详见第 2 节「版本支持与预设落点双轨」）。本插件不改 DSH 源码，只往 DSH 的 preset roster 写入编排预设、并把「庖丁配置」面板挂进 Web 左侧栏，因此先要有可用的 DSH 家目录。
 - **路径事实**（生成管线内建常量，写死前先了解它们）：
 
 | 项 | 默认值 | 说明 |
 |---|---|---|
 | `$DSH_HOME` | `~/.dsh` | DSH 家目录（认环境变量 `DSH_HOME`，缺省 `$HOME/.dsh`）。host 层配置 `cordis.patch.yml`、`node_modules`、`profiles/<name>/cordis.patch.yml`、插件 profile 目录都在其下 |
 | preset roster 根目录 | `$DSH_HOME/.agent-presets/` | DSH ≤ 0.1.6 由 `dsh-agent-presets` 扫描此目录发现本地 authored presets；DSH ≥ 0.1.7 宿主不再扫目录，此目录退为预设文件存放处（见第 2 节「版本支持与预设落点双轨」） |
-| 本预设安装目标 | `$DSH_HOME/.agent-presets/orchestrator` | 生成产物：`agent.cordis.yml`（重写后的角色配置）、`preset.yml`、`restrict.mjs`、`.generator-version` 版本标记，是一个静态目录；按工作区配置生成的预设落同一父目录下的 `orchestrator-<slug>` |
+| 本预设安装目标 | `$DSH_HOME/.agent-presets/orchestrator` | 生成产物：`agent.cordis.yml`（重写后的角色配置）、`preset.yml`、`restrict.mjs`、`.generator-version` 版本与轨道标记，是一个静态目录；按工作区配置生成的预设落同一父目录下的 `orchestrator-<slug>` |
 | 声明行托管块（仅 DSH ≥ 0.1.7） | `$DSH_HOME/cordis.patch.yml` 内的托管块 | 以 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始、配套 end 标记收尾，块内 `- insert:` 写 `@deepseek-ai/dsh-agent-preset` 声明行；安装器自动维护，详见第 2 节 |
 | 配置文件 | `$DSH_HOME/dsh-paoding.config.yml` | 「庖丁配置」面板「保存并应用」写入的角色与工具分配（`0o600`，可手编）；首装自动化同样读写它 |
 
@@ -50,9 +50,9 @@ dsh plugin --profile web add dsh-paoding
 
 `--profile web` 决定插件装进哪个 profile：「庖丁配置」面板只在以该 profile 启动的 DSH Web 里出现。`web` 是 `dsh web` 的默认 profile，多数机器无需改动；多 profile 用户对每个需要的 profile 各执行一次 `dsh plugin add`。编排预设本体落在 `$DSH_HOME/.agent-presets/`，全机共享、不随 profile 走——DSH ≥ 0.1.7 的声明行写在 home 层 `$DSH_HOME/cordis.patch.yml`，同样与 profile 无关——在任何 profile 的面板里「保存并应用」，写的都是同一份预设。
 
-### 版本支持与预设落点双轨（DSH 0.1.5 – 0.1.7-rc.1）
+### 版本支持与预设落点双轨（DSH 0.1.5 – 0.1.7-rc.2）
 
-本插件兼容两代宿主：**DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 全部支持**，安装与使用流程完全一致。插件 0.3.4 起，package.json 显式声明 `peerDependencies: @deepseek-ai/dsh >= 0.1.5`——0.1.7 起宿主装插件前做兼容性预检，无声明等于默认放行，显式声明后按真实兼容面把关；0.1.5 / 0.1.6 不读这个字段，声明纯属元数据，不影响安装。
+本插件兼容两代宿主：**DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1.7-rc.2 全部支持**，安装与使用流程完全一致。插件 0.3.4 起，package.json 显式声明 `peerDependencies: @deepseek-ai/dsh >= 0.1.5`——0.1.7 起宿主装插件前做兼容性预检，无声明等于默认放行，显式声明后按真实兼容面把关；0.1.5 / 0.1.6 不读这个字段，声明纯属元数据，不影响安装。
 
 两代宿主发现「本地 authored preset」的机制不同，安装器据此分双轨落点，宿主检测全自动、用户无感：
 
@@ -80,11 +80,17 @@ dsh plugin --profile web add dsh-paoding
 
 插件启动时自动检测编排预设是否就位：`$DSH_HOME/.agent-presets/orchestrator` 目录缺失，或其中的 `.generator-version` 标记与插件包版本不符时，自动执行一次等价 `--auto` 的安装——`~/.dsh/dsh-paoding.config.yml` 已存在就按配置应用；没有就写基础模板（只含 DSH 自带的基础工具，见下）。它走的是与面板「保存并应用」同一条检测/生成管线（`collectState` / `generateAndInstall`）——同一管线，但启动自愈的检测是纯文件扫描、不带运行时检测事实，面板则带；host 上装有 bundle 形态插件时，两者的检测库存可能不同，产物随之略有差异。
 
-所以 **`dsh plugin add` + 重启 = 完整安装**：预设生成、配置模板落盘、面板可点，一步到位。自动生成失败不会拖垮插件启动——只在 DSH 日志里记一条告警，可到面板手动「保存并应用」补上。启动自愈同时负责双轨落点的维护与跨版本迁移——宿主在 0.1.6 与 0.1.7 之间升级、降级后，首次自愈会自动补写或撤下 `$DSH_HOME/cordis.patch.yml` 里的托管块（见上节「版本支持与预设落点双轨」）。
+所以 **`dsh plugin add` + 重启 = 完整安装**：预设生成、配置模板落盘、面板可点，一步到位。自动生成失败不会拖垮插件启动——只在 DSH 日志里记一条告警，可到面板手动「保存并应用」补上。启动自愈同时负责双轨落点的维护与跨版本迁移——宿主在 0.1.6 与 0.1.7 之间升级、降级后，首次自愈会自动补写或撤下 `$DSH_HOME/cordis.patch.yml` 里的托管块（见上节「版本支持与预设落点双轨」）。**只升级 dsh、不动插件**时同样如此：宿主轨道翻转后首次启动，自愈按磁盘上已有的预设产物补写缺失的声明行——preset 内容一字节不重生成，各工作区预设一并恢复。
 
 ### 版本标记与自动重生成
 
-`.generator-version` 标记（内容 = 生成器版本）由插件启动自愈在生成 preset 后写入。面板「保存并应用」与兜底 CLI 的生成走整目录重建、不写回标记——重建即移除旧标记，下次 DSH 启动自愈发现标记缺失会多补跑一次生成并重写标记（产物相同，只是多跑一轮）。版本不符触发重生成的语义不变：插件升级后标记与包版本不符，下次 DSH 启动自动按新版重生成，「升级后 preset 还是旧版产物」的漂移就此消除。标记只在缺失或版本不符时触发重生成，面板不监视配置文件改动；想立刻按当前配置重新生成，点面板「保存并应用」。
+`.generator-version` 标记由插件启动自愈在生成 preset 后写入，内容两行：**生成器版本 + 预设安装轨道**（旧版只写版本一行，读到时按「轨道未知」处理，恰是宿主升级后的迁移触发态）。三类触发：
+
+- **标记缺失 / 版本不符**（首装、插件升级）→ 整盘重生成。面板「保存并应用」与兜底 CLI 的生成走整目录重建、不写回标记——重建即移除旧标记，下次 DSH 启动自愈发现标记缺失会多补跑一次生成并重写标记（产物相同，只是多跑一轮）。插件升级后标记与包版本不符，下次 DSH 启动自动按新版重生成，「升级后 preset 还是旧版产物」的漂移就此消除。
+- **版本一致、轨道翻转**（只升 dsh 不动插件——升级最常见路径）→ 轻量迁移，不重生成内容：声明轨上按磁盘产物补写缺失的声明行（含各工作区预设），directory 轨上若有残留声明行则整盘重生成撤下（残留会让 0.1.6 profile 启动失败）。
+- **版本轨道都一致** → 对账声明行：缺行补行、目录已删的孤儿行撤行，齐则什么都不动。
+
+面板不监视配置文件改动；想立刻按当前配置重新生成，点面板「保存并应用」。
 
 ### 基础模板与工具勾选
 
@@ -102,19 +108,19 @@ dsh plugin --profile web add dsh-paoding
 
 ## 3. 升级
 
-**面板一键升级（推荐）**：面板自动对比 npm registry 上的最新版本（GitHub release 兜底），发现新版就地提示并附上发布页链接。点「升级」按钮，面板就地执行：
+**面板一键升级（推荐）**：面板自动对比 npm registry 上的最新版本（npmmirror 镜像、GitHub release 依次兜底），发现新版就地提示并附上发布页链接。点「升级」按钮，面板就地执行：
 
 ```bash
 dsh plugin --profile <name> update dsh-paoding
 ```
 
-（profile 自动探测，通常无需手填。）升级只换 profile 里的插件包本体，当前进程的代码不变；成功后提示**重启 DSH**，重启时 preset 按 `.generator-version` 标记自动按新版重生成。
+（profile 自动探测，通常无需手填。）升级只换 profile 里的插件包本体，当前进程的代码不变；成功后提示**重启 DSH**，重启时 preset 按 `.generator-version` 标记自动按新版重生成。只升级 dsh 本体（不动插件）同理：重启即触发轨道迁移自愈，无需重装或重新应用。
 
 手动升级等价：直接在终端跑上面这条 `dsh plugin update` 命令，同样重启生效。
 
 **开发 link 形态**（见第 4 节）版本比较照常（更新卡有新版照常提示），但无法就地升级——升级器要求包真实装在某个 profile 的 node_modules 下，link 直连仓库匹配不到；点「升级」会如实报这一点，并提示手动跑 `dsh plugin add dsh-paoding@latest` 切回 registry 版。
 
-检测失败（断网、限流）时静默跳过，不影响任何使用。
+检测失败（断网、限流、代理不可用）时页头会留一行弱化的「版本检测失败 · 重试」，完整原因（npm registry / npmmirror / GitHub 三路各自的错误，以及代理排查提示）在悬浮提示里，不弹窗打扰；检测成功且确无新版时不显示任何内容。常见误区：浏览器能打开 npm 页面不代表 DSH 进程检测也能通——DSH 遵循启动环境里的 `HTTPS_PROXY` / `HTTP_PROXY` 等代理变量，浏览器不走它们；若靠代理上网，请确认代理可用后重启 DSH 再试。
 
 ## 4. 开发自装（link: 形态）
 

package/docs/installation_en.md

@@ -12,14 +12,14 @@ Check the following before installing:
 
 - **Node.js ≥ 18**. The DSH host and the plugin chain both run on Node; with an older version `dsh` won't start in the first place. Check with `node --version`.
 - **pnpm available**. `dsh plugin` is a transparent pass-through to pnpm: installing a plugin package into a profile is done by pnpm. If pnpm is missing the install command fails with a pnpm error — install pnpm (`npm i -g pnpm` or `corepack enable`) and retry.
-- **A working DSH host** (the `dsh` command, including its Web/agent runtime; **@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1**, all supported — the installer adapts to the two preset mechanisms automatically; see §2 "Version support and the dual preset landing"). This plugin does not modify DSH source code; it only writes the orchestrator preset into DSH's preset roster and mounts the Paoding Config page into the Web sidebar, so a usable DSH home directory must exist first.
+- **A working DSH host** (the `dsh` command, including its Web/agent runtime; **@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.2**, all supported — the installer adapts to the two preset mechanisms automatically; see §2 "Version support and the dual preset landing"). This plugin does not modify DSH source code; it only writes the orchestrator preset into DSH's preset roster and mounts the Paoding Config page into the Web sidebar, so a usable DSH home directory must exist first.
 - **Path facts** (constants built into the generation pipeline; know them before customizing):
 
 | Item | Default | Description |
 |---|---|---|
 | `$DSH_HOME` | `~/.dsh` | The DSH home directory (the `DSH_HOME` environment variable is honored, defaulting to `$HOME/.dsh`). The home-layer `cordis.patch.yml`, `node_modules`, `profiles/<name>/cordis.patch.yml`, and plugin profile directories live under it |
 | preset roster root | `$DSH_HOME/.agent-presets/` | Under DSH ≤ 0.1.6, `dsh-agent-presets` scans this directory for locally authored presets; under DSH ≥ 0.1.7 the host no longer scans it and the directory is just where the preset files live (see §2 "Version support and the dual preset landing") |
-| Install target of this preset | `$DSH_HOME/.agent-presets/orchestrator` | The generated artifact: `agent.cordis.yml` (rewritten role config), `preset.yml`, `restrict.mjs`, and the `.generator-version` marker — a static directory; per-workspace presets land in sibling `orchestrator-<slug>` directories |
+| Install target of this preset | `$DSH_HOME/.agent-presets/orchestrator` | The generated artifact: `agent.cordis.yml` (rewritten role config), `preset.yml`, `restrict.mjs`, and the `.generator-version` version-and-track marker — a static directory; per-workspace presets land in sibling `orchestrator-<slug>` directories |
 | Declaration managed block (DSH ≥ 0.1.7 only) | a managed block inside `$DSH_HOME/cordis.patch.yml` | Opens with `# --- dsh-paoding presets (auto-generated; do not edit) ---` and closes with the matching end marker; the `- insert:` rows inside carry `@deepseek-ai/dsh-agent-preset` declarations, maintained by the installer — see §2 |
 | Config file | `$DSH_HOME/dsh-paoding.config.yml` | Role/tool assignments written by the Paoding Config panel's Save & Apply (`0o600`, hand-editable); first-install automation reads and writes it too |
 
@@ -50,9 +50,9 @@ The orchestrator preset needs no separate install — the plugin fills it in aut
 
 `--profile web` decides which profile the plugin is installed into: the Paoding Config page appears only in a DSH Web launched with that profile. `web` is the default profile of `dsh web`, so most machines need no change; multi-profile users run `dsh plugin add` once per profile they want it in. The orchestrator preset itself lives under `$DSH_HOME/.agent-presets/` and is shared machine-wide, independent of profiles — under DSH ≥ 0.1.7 the declaration rows go into the home-layer `$DSH_HOME/cordis.patch.yml`, equally profile-independent — Save & Apply from any profile's panel writes the same preset.
 
-### Version support and the dual preset landing (DSH 0.1.5 – 0.1.7-rc.1)
+### Version support and the dual preset landing (DSH 0.1.5 – 0.1.7-rc.2)
 
-The plugin supports two host generations: **DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 are all supported**, with an identical install and usage flow. As of plugin 0.3.4, package.json declares `peerDependencies: @deepseek-ai/dsh >= 0.1.5` explicitly — from 0.1.7 the host runs a plugin-compatibility precheck before installing: no declaration meant a default pass, an explicit one gets checked against the real compatibility surface; 0.1.5 / 0.1.6 never read the field, where the declaration is pure metadata and changes nothing about the install.
+The plugin supports two host generations: **DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1.7-rc.2 are all supported**, with an identical install and usage flow. As of plugin 0.3.4, package.json declares `peerDependencies: @deepseek-ai/dsh >= 0.1.5` explicitly — from 0.1.7 the host runs a plugin-compatibility precheck before installing: no declaration meant a default pass, an explicit one gets checked against the real compatibility surface; 0.1.5 / 0.1.6 never read the field, where the declaration is pure metadata and changes nothing about the install.
 
 The two generations discover "local authored presets" differently, so the installer maintains a dual landing, detecting the host automatically — nothing for the user to do:
 
@@ -80,11 +80,17 @@ Two cross-version behavior alignments happen the same automatic way, with no use
 
 At startup the plugin checks whether the orchestrator preset is in place: if the `$DSH_HOME/.agent-presets/orchestrator` directory is missing, or its `.generator-version` marker does not match the plugin package version, it automatically performs one install equivalent to `--auto` — applying `~/.dsh/dsh-paoding.config.yml` when it exists, writing the base template otherwise (DSH base tools only; see below). It runs the same detection/generation pipeline as the panel's Save & Apply (`collectState` / `generateAndInstall`) — the same pipeline, but the startup self-heal detects with a pure file scan and no runtime detection facts while the panel detects with them; when a bundle-form plugin is installed on the host, the two detection inventories may differ, and the outputs differ slightly with them.
 
-So **`dsh plugin add` + restart = a complete install**: preset generated, config template on disk, panel ready — all in one step. If the automatic generation fails it never takes the plugin down — a warning is logged, and you can apply manually from the panel. The startup self-heal also maintains the dual landing and the cross-version migration: after the host moves between 0.1.6 and 0.1.7, the first self-heal writes or removes the managed block in `$DSH_HOME/cordis.patch.yml` automatically (see "Version support and the dual preset landing" above).
+So **`dsh plugin add` + restart = a complete install**: preset generated, config template on disk, panel ready — all in one step. If the automatic generation fails it never takes the plugin down — a warning is logged, and you can apply manually from the panel. The startup self-heal also maintains the dual landing and the cross-version migration: after the host moves between 0.1.6 and 0.1.7, the first self-heal writes or removes the managed block in `$DSH_HOME/cordis.patch.yml` automatically (see "Version support and the dual preset landing" above). The same holds when **only dsh is upgraded and the plugin untouched**: after the host's preset system flips, the first startup backfills the missing declaration rows from the preset artifacts already on disk — no preset content is regenerated, and per-workspace presets are restored along with the base one.
 
 ### The version marker and auto-regeneration
 
-The `.generator-version` marker (its content = the generator version) is written by the plugin's startup self-heal after it generates the preset. The panel's Save & Apply (and the fallback CLI) do a full-directory rebuild and write no marker — the rebuild removes the old marker, so the next DSH start's self-heal finds it missing, runs one extra generation, and rewrites the marker (same output, just one extra round). The version-mismatch trigger is unchanged: after a plugin upgrade the marker no longer matches the package version, so the next DSH start regenerates the preset against the new version — the "upgraded the plugin but the preset is stale" drift is eliminated. The marker triggers regeneration only when missing or version-mismatched, and the panel does not watch the config file; to regenerate from the current config right away, hit Save & Apply.
+The `.generator-version` marker is written by the plugin's startup self-heal after it generates the preset. Its content is two lines: **the generator version and the preset system track** (older releases wrote only the version; such markers read back as "track unknown", which is exactly the migration trigger after a host upgrade). Three triggers:
+
+- **Marker missing or version-mismatched** (first install, plugin upgrade) → full regeneration. The panel's Save & Apply (and the fallback CLI) do a full-directory rebuild and write no marker — the rebuild removes the old marker, so the next DSH start's self-heal finds it missing, runs one extra generation, and rewrites the marker (same output, just one extra round). After a plugin upgrade the marker no longer matches the package version, so the next DSH start regenerates the preset against the new version — the "upgraded the plugin but the preset is stale" drift is eliminated.
+- **Version matching but the track flipped** (dsh upgraded, plugin untouched — the most common upgrade path) → lightweight migration with no content regeneration: on the declarative track, missing declaration rows are backfilled from the on-disk artifacts (per-workspace presets included); on the directory track, any leftover declaration rows force a full regeneration that strips them (leftovers would break 0.1.6 profile startup).
+- **Version and track both matching** → declaration-row reconciliation: missing rows are backfilled, orphan rows whose directories are gone are removed; if everything lines up, nothing is touched.
+
+The panel does not watch the config file; to regenerate from the current config right away, hit Save & Apply.
 
 ### Base template and tool opt-in
 
@@ -102,19 +108,19 @@ Once installed:
 
 ## 3. Upgrading
 
-**One-click upgrade in the panel (recommended)**: the panel compares your local version against the latest npm registry publish (GitHub release as fallback) and points to the release page when a newer one is out. Click the Upgrade button and the panel runs this in place:
+**One-click upgrade in the panel (recommended)**: the panel compares your local version against the latest npm registry publish (npmmirror and GitHub release as successive fallbacks) and points to the release page when a newer one is out. Click the Upgrade button and the panel runs this in place:
 
 ```bash
 dsh plugin --profile <name> update dsh-paoding
 ```
 
-(the profile is auto-detected; usually nothing to fill in). The upgrade only swaps the plugin package inside the profile — the running process's code is untouched; on success it asks you to **restart DSH**, and at restart the preset regenerates itself against the new version via the `.generator-version` marker.
+(the profile is auto-detected; usually nothing to fill in). The upgrade only swaps the plugin package inside the profile — the running process's code is untouched; on success it asks you to **restart DSH**, and at restart the preset regenerates itself against the new version via the `.generator-version` marker. Upgrading only the dsh host (plugin untouched) works the same way: the restart triggers the track-migration self-heal — no reinstall or manual re-apply needed.
 
 Manual equivalent: run the `dsh plugin update` command above yourself, restart, done.
 
 A **dev link: checkout** (see §4) still gets version checks (the update card appears when a newer version exists) but cannot be upgraded in place — the upgrader requires the package to really live under a profile's node_modules, which a link straight into the repo never matches. Hitting Upgrade reports exactly that and suggests running `dsh plugin add dsh-paoding@latest` to switch back to the registry version.
 
-If the check fails (offline, rate-limited), it stays silent and nothing is interrupted.
+If the check fails (offline, rate-limited, proxy down), a subdued "version check failed · retry" row stays in the panel header with the full causes (per-source errors across npm registry / npmmirror / GitHub, plus proxy troubleshooting hints) in its tooltip; a successful check with no new version shows nothing. Common pitfall: being able to open the npm page in a browser does not mean the DSH process can reach it — DSH honors HTTPS_PROXY / HTTP_PROXY from its launch environment while browsers do not. If you rely on a proxy, make sure it is up and restart DSH before retrying.
 
 ## 4. Dev-checkout install (link: form)
 

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#4D6BFE"/>
+  <g transform="rotate(-45 32 32)">
+    <rect x="14" y="11" width="32" height="22" rx="3" fill="#FFFFFF"/>
+    <circle cx="41" cy="16.5" r="2" fill="#4D6BFE"/>
+    <rect x="44" y="17" width="13" height="10" rx="4" fill="#FFFFFF" opacity="0.85"/>
+  </g>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Paoding",
+    "description": "Orchestrator-mode installer: host-aware role tool filtering plus a visual settings panel in DSH Web."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "庖丁",
+    "description": "编排模式安装器：host 感知的角色工具过滤，外加 DSH Web 里的可视化设置面板。"
+  }
+}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "dsh-paoding",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "庖丁 — DSH (DeepSeek Harness) 编排模式安装器：host 感知的角色工具过滤 + Web 设置页可视化配置器",
   "type": "module",
   "license": "MIT",
+  "icon": "./icon.svg",
   "files": [
     "bin/",
     "tools/",
@@ -11,6 +12,8 @@
     "plugins/",
     "!plugins/paoding-config-ui/src",
     "docs/",
+    "locale/",
+    "icon.svg",
     "README.md",
     "README_en.md",
     "LICENSE",
@@ -43,7 +46,8 @@
   "exports": {
     ".": "./plugins/paoding-config-ui/index.mjs",
     "./client": "./plugins/paoding-config-ui/lib/client.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
   },
   "dsh": {
     "client": {

package/plugins/paoding-config-ui/api-core.mjs

@@ -12,6 +12,14 @@ import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'n
 import { readFile } from 'node:fs/promises'
 import { assignSlugs, collectState, generateAndInstall, presetIdOf } from '../../tools/install.mjs'
 import { autoAssignments } from '../../tools/lib/alloc.mjs'
+import {
+  backfillHomePatchRows,
+  detectPresetSystem,
+  formatGeneratorMarker,
+  listOrchestratorPresetIds,
+  parseGeneratorMarker,
+  readHomePatchRows,
+} from '../../tools/lib/preset-system.mjs'
 
 export function resolveDshHome() {
   return process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
@@ -142,10 +150,11 @@ export function installAssignments(state, assignments, { dryRun = false, saveCon
 // ── 首装 / 升级后 preset 自动重生成 ─────────────────────────────────────────
 //
 // 唯一官方安装通道是插件通道（dsh plugin add dsh-paoding），包不再携带 CLI：
-// preset 的落盘改由插件启动时自愈——目录缺失（首装）或由旧版生成器产出（升级
-// 换包）时，按 install --auto 语义重生成一次。对账基准是 preset 目录里的
-// .generator-version 标记文件（内容 = 生成器版本）：插件包版本变 → 标记不符 →
-// 下次启动自动重生成，一举解决「升级后 preset 还是旧版产物」的漂移问题。
+// preset 的落盘改由插件启动时自愈。对账基准是 preset 目录里的 .generator-version
+// 标记文件（v2 起内容 = 生成器版本 + 预设安装轨道两行）：插件包版本变、或宿主
+// 轨道翻转（只升 dsh 不动插件——升级最常见路径，旧标记只记版本时同样解析为
+// 轨道不符）→ 下次启动自动自愈，一举解决「升级后 preset 还是旧版产物」与
+// 「升 dsh 后 preset 静默消失」两类漂移。
 
 // 生成器版本（标记对账基准）：插件包根 package.json 读一次即缓存。读失败兜底
 // '0.0.0'——最坏后果只是每次启动多重生成一次 preset，不会装坏任何东西。
@@ -165,23 +174,30 @@ export function pluginVersion() {
 const PRESET_ENSURE_ABORTED = '插件已卸载（dispose），本次 preset 生成中止'
 
 /**
- * 首装 / 升级后自动重生成 orchestrator preset（等价 install --auto 语义）。
+ * 首装 / 升级后自动安装 orchestrator preset（等价 install --auto 语义）。
  *
- * 判定：preset 目录缺失，或 .generator-version 标记缺失 / 版本与 generatorVersion
- * 不符 → 执行一次自动安装：局部 collectState()（不带运行时事实的纯文件扫描，
- * 首装触发点在插件启动、宿主服务未必就绪，且与 CLI --auto 语义对齐；预设安装
- * 轨道由 collectState 内部按 dsh --version / 文件探测兜底，state.presetSystem
- * 随 state 一并进 generateAndInstall 双轨收尾；不走 refreshState()——那会拿
- * 无事实的扫描覆盖路由层的共享缓存）后按既有配置合成 assignments（无配置写
- * 基础模板），经 generateAndInstall 落盘，最后写标记文件。
+ * 判定（满足其一即动盘）：
+ *   - preset 目录 / 标记缺失，或标记版本与 generatorVersion 不符 → 整盘重生成；
+ *   - 版本一致但标记轨道与当前宿主轨道不符（只升 dsh 不动插件 / 旧格式标记）→
+ *     轻量迁移：声明轨上按磁盘产物补写缺失声明行（内容字节不动，不重生成），
+ *     directory 轨上落回整盘重生成（残留声明行会让 0.1.6 profile 启动失败，
+ *     撤块自愈由其 directory 分支完成）；
+ *   - 版本轨道都一致 → 对账声明行（缺行补行、孤儿行撤行），齐则跳过。
+ * 局部 collectState() 不带运行时事实（首装触发点在插件启动、宿主服务未必就绪，
+ * 且与 CLI --auto 语义对齐；预设安装轨道由 collectState 内部按 argv 宿主版本 /
+ * dsh --version / 文件探测兜底，state.presetSystem 随 state 一并进
+ * generateAndInstall 双轨收尾；不走 refreshState()——那会拿无事实的扫描覆盖
+ * 路由层的共享缓存）后按既有配置合成 assignments（无配置写基础模板），经
+ * generateAndInstall 落盘，最后写标记文件（版本 + 轨道）。
  * shouldAbort 在各 await 点后检查：插件 dispose 后在途的生成不再继续写盘。
  * 可脱离 ctx 独立调用（单测友好），任何异常自捕、绝不抛出。
  *
  * @param {{dshHome?: string, generatorVersion?: string, shouldAbort?: () => boolean}} opts
  *   缺省取 resolveDshHome() 与 pluginVersion()；shouldAbort 返回 true 时中止
  *   （按 reason 返回，不算 error）。
- * @returns {Promise<{installed: boolean, reason?: string, error?: string}>}
- *   installed=true 表示本次实际重生成；false 时带 reason（无需重生成 / 已中止）
+ * @returns {Promise<{installed: boolean, backfilled?: string[], reason?: string, error?: string}>}
+ *   installed=true 表示本次实际重生成；backfilled 非空表示本次补写了哪些
+ *   preset 的声明行（内容未重生成）；两者皆否时带 reason（无需动盘 / 已中止）
  *   或 error（生成失败，调用方只记日志）。
  */
 export async function ensurePresetInstalled({ dshHome = resolveDshHome(), generatorVersion = pluginVersion(), shouldAbort = null } = {}) {
@@ -190,10 +206,35 @@ export async function ensurePresetInstalled({ dshHome = resolveDshHome(), genera
     const markerFile = path.join(presetDir, '.generator-version')
     let marker = null
     try {
-      marker = (await readFile(markerFile, 'utf8')).trim()
+      marker = parseGeneratorMarker(await readFile(markerFile, 'utf8'))
     } catch { /* 目录或标记缺失：按未生成处理 */ }
-    if (marker === generatorVersion) {
-      return { installed: false, reason: 'preset 已由当前版本生成器产出，无需重生成' }
+
+    if (marker !== null && marker.version === generatorVersion) {
+      // 版本一致：内容无需重生成，但宿主轨道可能已随 dsh 升降级翻转（只升 dsh
+      // 不动插件是升级常态），声明行也可能被外部动过——这里做轻量对账。
+      const system = await detectPresetSystem({ dshHome })
+      if (shouldAbort?.()) return { installed: false, reason: PRESET_ENSURE_ABORTED }
+      const presetIds = listOrchestratorPresetIds(dshHome)
+      if (system === 'declarative') {
+        const backfilled = backfillHomePatchRows(dshHome, presetIds)
+        if (marker.track === 'declarative' && backfilled.length === 0) {
+          return { installed: false, reason: 'preset 已由当前版本生成器产出，无需重生成' }
+        }
+        writeFileSync(markerFile, formatGeneratorMarker(generatorVersion, 'declarative'), 'utf8')
+        return backfilled.length > 0
+          ? { installed: false, backfilled, reason: `宿主已切换声明行轨，补写 ${backfilled.length} 条预设声明行（preset 内容未重生成）` }
+          : { installed: false, reason: '预设安装轨道标记已更新为声明行轨（内容无需重生成）' }
+      }
+      // directory 轨：声明行残留会让 0.1.6 profile 启动失败——有残留走整盘
+      // 重生成（directory 分支撤块自愈）；行清白时只升级标记格式，不动内容。
+      if (readHomePatchRows(dshHome).length === 0) {
+        if (marker.track === 'directory') {
+          return { installed: false, reason: 'preset 已由当前版本生成器产出，无需重生成' }
+        }
+        writeFileSync(markerFile, formatGeneratorMarker(generatorVersion, 'directory'), 'utf8')
+        return { installed: false, reason: '预设安装轨道标记已升级为带轨道格式（内容无需重生成）' }
+      }
+      // 声明行残留 + directory 宿主：落到下方整盘重生成
     }
 
     if (shouldAbort?.()) return { installed: false, reason: PRESET_ENSURE_ABORTED }
@@ -220,9 +261,14 @@ export async function ensurePresetInstalled({ dshHome = resolveDshHome(), genera
     // 标记最后写：generateAndInstall 会整目录重建（rmSync），先写必被删。
     if (shouldAbort?.()) return { installed: false, reason: PRESET_ENSURE_ABORTED }
     mkdirSync(presetDir, { recursive: true })
-    writeFileSync(markerFile, `${generatorVersion}\n`, 'utf8')
+    const track = result.presetSystem === 'declarative' ? 'declarative' : 'directory'
+    writeFileSync(markerFile, formatGeneratorMarker(generatorVersion, track), 'utf8')
+    // 声明轨上整盘重生成只重建本 preset 的行：其余工作区 preset 目录若在而
+    // 声明行缺（轨道翻转后首次触发本路径），一并补齐。
+    const backfilled = track === 'declarative' ? backfillHomePatchRows(dshHome, listOrchestratorPresetIds(dshHome)) : []
     return {
       installed: true,
+      ...(backfilled.length > 0 ? { backfilled } : {}),
       reason: state.existing
         ? 'preset 缺失或由旧版生成器产出，已按现有配置重新生成'
         : 'preset 缺失或由旧版生成器产出，已写入基础模板',

package/plugins/paoding-config-ui/index.mjs

@@ -6,8 +6,9 @@
  *     upgrade/preview/apply/rescan + client.css 静态样式），经
  *     ./api-core.mjs 复用 tools/install.mjs 的检测与生成管线；workspaces 直连
  *     宿主 workspaceRegistry 服务（list / create，幂等）；version
- *     复用 tools/lib/version.mjs 的版本检测（npm registry 优先、GitHub release
- *     兜底）；upgrade 经 tools/lib/upgrade.mjs spawn `dsh plugin update` 完成
+ *     复用 tools/lib/version.mjs 的版本检测（npm registry 优先，npmmirror
+ *     镜像、GitHub release 依次兜底）；upgrade 经 tools/lib/upgrade.mjs
+ *     spawn `dsh plugin update` 完成
  *     一键升级。首装 / 升级后 preset 自动重生成（ensurePresetInstalled，等价
  *     install --auto 语义）在路由注册完成后异步触发，不阻塞启动。
  *   - Client 侧：lib/client.js 经宿主 sidebar.footer.action 键控槽在左侧栏
@@ -175,12 +176,16 @@ function triggerPresetEnsure(ctx, isDisposed) {
         ctx.logger?.info?.(
           `paoding-config-ui: orchestrator preset 已重生成（generator v${generatorVersion}，${r.reason}）`,
         )
+      } else if (Array.isArray(r.backfilled) && r.backfilled.length > 0) {
+        // 轨道迁移 / 声明行对账补写（preset 内容未重生成）：值得留一行轨迹，
+        // 方便「升级 dsh 后主子代理消失」这类问题定位。
+        ctx.logger?.info?.(`paoding-config-ui: ${r.reason ?? '预设声明行已补写'}（${r.backfilled.join('、')}）`)
       } else if (r.error) {
         // 失败复位防抖闩：下次 activate（热重载 / 重注册）可重试
         presetEnsureStarted = false
         ctx.logger?.warn?.(`paoding-config-ui: preset 自动生成失败（可在侧栏底部「庖丁配置」入口手动应用）: ${r.error}`)
       }
-      // 版本一致的常规跳过不打日志：每次启动都刷一行纯噪音。
+      // 版本轨道一致的常规跳过 / 纯标记格式升级不打日志：每次启动都刷一行纯噪音。
     })
     .catch((err) => {
       presetEnsureStarted = false
@@ -526,7 +531,7 @@ export function apply(ctx) {
         }
 
         if (route === 'version' && req.method === 'GET') {
-          // 版本提示：npm registry 优先、GitHub release 兜底（tools/lib/version.mjs，
+          // 版本提示：npm registry 优先，npmmirror / GitHub 依次兜底（version.mjs，
           // 带 1 小时内存缓存，命中不发外网请求）。绝不 5xx——检测失败也回
           // 200 + error 字段，面板据此静默降级（不打扰使用）。timeoutMs 3000：
           // 检测只是锦上添花，不值得让面板等更久。layout 告知客户端挂载形态

package/plugins/paoding-config-ui/lib/base.css

@@ -149,6 +149,34 @@
 
 .omd-upgradeBtn:focus-visible { outline: 2px solid var(--dsw-alias-border-l4); outline-offset: 1px; }
 
+/* 版本检测失败行（弱化）：比更新警示卡低一档的存在感——三级文字色小字
+   ⚠ + 重试小 pill，常态（检测成功且无新版）不渲染。完整失败原因（三路源
+   各自错误与代理排查提示）收在行上的 title 悬浮提示，不占版面。 */
+.omd-versionFail { gap: 4px; }
+
+.omd-retryBtn {
+  flex: none;
+  padding: 1px 10px;
+  border: 1px solid var(--dsw-alias-border-l3);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font: inherit;
+  font-size: 11px;
+  line-height: 16px;
+  cursor: pointer;
+  transition: color 0.12s ease, border-color 0.12s ease;
+}
+
+.omd-retryBtn:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+  border-color: var(--dsw-alias-border-l4);
+}
+
+.omd-retryBtn:disabled { opacity: 0.6; cursor: default; }
+
+.omd-retryBtn:focus-visible { outline: 2px solid var(--dsw-alias-border-l4); outline-offset: 1px; }
+
 /* 升级进行中的补充说明（分钟级操作，管理预期）。 */
 .omd-upgradeHint {
   flex: none;

package/plugins/paoding-config-ui/lib/client.js

@@ -236,8 +236,8 @@ window.__ModuleLoader__.load({
     // 版本提示（渲染在页头标题旁，由 PageShell 持有）：常态版本号不进正文；
     // updateAvailable 时这里渲染醒目提示卡：releaseUrl 新标签页打开 release 页、
     // 「升级」按钮走 onUpgrade（一键 dsh plugin update 自升级），并保留当前版本号。
-    // latest 为 null（含检测失败 error 的情况）一律不显示新版部分——检测失败
-    // 时服务端也只回 200 + error 字段，这里整行静默。
+    // latest 为 null 一律不显示新版部分；检测失败（error 非空）改渲染弱化失败行
+    // （⚠ 版本检测失败 · 重试，完整原因在 title 悬浮提示），不再整行静默。
     // opts（可省）：busy/busyOp 复用面板级互斥（任何操作进行中都禁用升级，
     // 升级进行中也反过来禁用其他按钮），onUpgrade 为点击回调。
     // ── 服务端 API 助手（PageShell 与 ConfigPanel 共用）──────────────────────
@@ -325,9 +325,28 @@ window.__ModuleLoader__.load({
     // 渲染并持有升级动作，面板正文不再重复版本信息；当前版本号就在旁边的
     // pd-versionTag 上，卡内不再赘述「（当前 vX）」。note / error 为升级
     // 反馈行（成功提示 / 失败原因，含子进程输出尾部），也收在卡内。
+    // 检测失败（v.error 非空且无新版信息）不再全静默：弱化小字「版本检测
+    // 失败 · 重试」——否则「没新版」与「没测出来」无从区分（真实事故：用户
+    // 端 0.3.2 对 0.3.5 迟迟看不到升级卡，只能靠作者远程猜）。检测成功且确
+    // 无新版仍静默（常态不打扰）。完整失败原因（三路源各自错误 + 代理提示）
+    // 收在 title 悬浮提示里，不占版面。
     function versionRowOf(v, opts) {
       if (!v || typeof v.current !== "string" || !v.current) return null;
-      if (!(v.updateAvailable && v.latest)) return null;
+      if (!(v.updateAvailable && v.latest)) {
+        if (typeof v.error !== "string" || !v.error) return null;
+        var retryBusy = !!(opts && opts.retryBusy);
+        return h("span", { className: "omd-versionRow omd-versionFail", title: v.error },
+          h("span", { className: "omd-versionIcon" }, "⚠"),
+          h("span", { className: "omd-versionText" }, "版本检测失败"),
+          typeof (opts && opts.onRetry) === "function"
+            ? h("button", {
+                type: "button",
+                className: "omd-retryBtn",
+                disabled: retryBusy,
+                onClick: opts.onRetry,
+              }, retryBusy ? "检测中…" : "重试")
+            : null);
+      }
       var busy = !!opts && !!opts.busy;
       var note = (opts && opts.note) || "";
       var error = (opts && opts.error) || "";
@@ -3042,11 +3061,26 @@ window.__ModuleLoader__.load({
       var _ub = useState(false), upgBusy = _ub[0], setUpgBusy = _ub[1];
       var _un = useState(""), upgNote = _un[0], setUpgNote = _un[1];
       var _ue = useState(""), upgErr = _ue[0], setUpgErr = _ue[1];
+      // 版本检测重试进行中（页头失败行的「重试」按钮禁用态）：与升级三态分开，
+      // 检测失败重试不该锁升级（升级预检在服务端另做一次，不依赖这份 verInfo）。
+      var _vb = useState(false), verRetryBusy = _vb[0], setVerRetryBusy = _vb[1];
 
       // 一键升级逻辑在共享的 runUpgradeFlow（页头更新卡统一走这一份）。
       function doUpgrade() {
         runUpgradeFlow(verInfo, setVerInfo, setUpgBusy, setUpgNote, setUpgErr);
       }
+
+      // 检测失败重试：直接再拉一次 /api/paoding/version（服务端失败结果不进
+      // 缓存，重试即真实检测；成功则 error 随新响应自然清空）。仍失败维持
+      // 原提示——失败行常驻，重试按钮永远可用。
+      function doRetryVersion() {
+        setVerRetryBusy(true);
+        paodingApi("version").then(function (d) {
+          if (d && typeof d.current === "string" && d.current) setVerInfo(d);
+        }).catch(function () { /* 仍不通：维持失败行，不额外打扰 */ }).finally(function () {
+          setVerRetryBusy(false);
+        });
+      }
       useEffect(function () {
         var onKey = function (e) {
           if (e && e.key === "Escape" && typeof onClose === "function") onClose();
@@ -3064,7 +3098,7 @@ window.__ModuleLoader__.load({
                 verInfo && typeof verInfo.current === "string" && verInfo.current
                   ? h("span", { className: "pd-versionTag" }, versionTagOf(verInfo.current))
                   : null),
-              versionRowOf(verInfo, { busy: upgBusy, onUpgrade: doUpgrade, note: upgNote, error: upgErr })),
+              versionRowOf(verInfo, { busy: upgBusy, onUpgrade: doUpgrade, note: upgNote, error: upgErr, onRetry: doRetryVersion, retryBusy: verRetryBusy })),
             h("p", { className: "pd-pageSubtitle" },
               "为主 agent 与子 agent 编排工具、技能与角色，预览并应用生成的 agent.cordis.yml。")),
           h("button", {

package/plugins/paoding-config-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paoding-config-ui",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "private": true,
   "type": "module",
   "main": "index.mjs",

package/tools/lib/preset-system.mjs

@@ -5,9 +5,10 @@
  * name: '@deepseek-ai/dsh-agent-preset' 的行（config = { id 必填, name?,
  * description?, order?, plugins[] 必填 }，宿主 agent-preset-registry 挂载
  * plugins 子树；行 name 相对声明行 baseUrl 解析，绝对 file: URL 直接采用）。
- * 本模块为双轨化提供三件事：
+ * 本模块为双轨化提供四件事：
  *   1) 轨道探测 detectPresetSystem：运行时探测（Web 插件对宿主服务的实时反射，
- *      最权威）> `dsh --version` 版本号 > $DSH_HOME 单数包存在性 > 默认
+ *      最权威）> 进程 argv 宿主版本（插件进程内零开销，反映正在运行的宿主而非
+ *      PATH 上的 dsh）> `dsh --version` 版本号 > $DSH_HOME 单数包存在性 > 默认
  *      directory（安全侧：声明行误落 0.1.6 会炸 profile 启动，目录轨误落
  *      0.1.7 只是预设不显示）；
  *   2) 声明行构造 buildPresetRowText：把生成的 agent.cordis.yml 全文内联成
@@ -17,11 +18,16 @@
  *      readHomePatchRows：对 $DSH_HOME/cordis.patch.yml 的 MANAGED 标记块做
  *      行级增删查，块外用户内容一字节不动；托管块损坏（缺结束标记）时拒绝
  *      写盘并明确报错，与仓库「配置不可信时拒绝落盘」口径一致。
- * 零运行时依赖（node:child_process / node:fs / node:path）；被 state 引用。
+ *   4) 轨道迁移对账 backfillHomePatchRows / listOrchestratorPresetIds /
+ *      parseGeneratorMarker / formatGeneratorMarker：宿主只升 dsh 不动插件时
+ *      （标记版本一致、轨道翻转——升级最常见路径），按磁盘产物补写缺失声明行
+ *      而不整盘重生成；生成器标记记「版本 + 轨道」两行，任一不符即触发自愈。
+ * 零运行时依赖（node:child_process / node:fs / node:path / node:url）；被 state 引用。
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { warn } from './util.mjs'
 
 /** 托管块起始标记：其后到结束标记之间是本工具自动生成的声明行，用户勿改。 */
@@ -62,14 +68,22 @@ export function isDeclarativeTriple(triple) {
 /**
  * 探测当前宿主的预设安装轨道，返回 'declarative' | 'directory'。逐级降级：
  *   1) runtimeSystem 直通：Web 插件运行时对宿主服务的实时探测结果最权威；
- *   2) `dsh --version`（timeout 10s；spawn 失败 / 超时 / 输出不可解析一律吞掉
+ *   2) 进程 argv 宿主版本：插件与宿主同进程时零开销、且反映正在运行的宿主
+ *      （PATH 上的 dsh 可能已换代而旧进程还在跑，此时以 argv 为准才不会把
+ *      声明行提前写出去）；CLI / 测试进程不是 dsh，返回 null 落到下一级；
+ *   3) `dsh --version`（timeout 10s；spawn 失败 / 超时 / 输出不可解析一律吞掉
  *      落到下一级）；
- *   3) 文件探测：单数包 @deepseek-ai/dsh-agent-preset 是 0.1.7 的声明行宿主
+ *   4) 文件探测：单数包 @deepseek-ai/dsh-agent-preset 是 0.1.7 的声明行宿主
  *      组件，在即声明轨（复数包时代没有它）；
- *   4) 默认 directory —— 安全侧兜底（理由见模块头注释）。
+ *   5) 默认 directory —— 安全侧兜底（理由见模块头注释）。
  */
 export async function detectPresetSystem({ dshHome, runtimeSystem = null } = {}) {
   if (runtimeSystem === 'declarative' || runtimeSystem === 'directory') return runtimeSystem
+  const argvVersion = hostVersionFromArgv()
+  if (argvVersion !== null) {
+    const triple = parseVersionTriple(argvVersion)
+    if (triple !== null) return isDeclarativeTriple(triple) ? 'declarative' : 'directory'
+  }
   const versionText = dshVersionText()
   if (versionText !== null) {
     const triple = parseVersionTriple(versionText)
@@ -79,6 +93,32 @@ export async function detectPresetSystem({ dshHome, runtimeSystem = null } = {})
   return 'directory'
 }
 
+/**
+ * 从当前进程 argv[1] 推断正在运行的宿主版本：沿脚本所在目录向上找最近的
+ * package.json，name 是 @deepseek-ai/dsh 即取其 version。插件跑在宿主进程里，
+ * 这比 PATH 上的 `dsh --version` 又快又准（无需子进程）；找不到（CLI / 测试 /
+ * 任意非 dsh 进程）返回 null。找到的第一个 package.json 不是 dsh 即止——
+ * 向上穿越无关包目录没有意义。
+ */
+function hostVersionFromArgv() {
+  try {
+    const entry = process.argv[1]
+    if (typeof entry !== 'string' || entry === '') return null
+    let dir = path.dirname(path.resolve(entry))
+    for (let i = 0; i < 6 && dir !== path.dirname(dir); i++) {
+      const pkgPath = path.join(dir, 'package.json')
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        return pkg?.name === '@deepseek-ai/dsh' ? String(pkg.version ?? '') : null
+      }
+      dir = path.dirname(dir)
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
 /** `dsh --version` 取裸版本号文本；任何失败（ENOENT / 超时 / 非零退出）返回 null。 */
 function dshVersionText() {
   try {
@@ -388,3 +428,130 @@ export function readHomePatchRows(dshHome) {
     return []
   }
 }
+
+// ── 轨道迁移对账（宿主升降级自愈）────────────────────────────────────────────
+//
+// 只升 dsh 不动插件是升级的最常见路径：标记版本照旧吻合、自愈不会触发，但
+// .agent-presets/ 目录轨产物在 0.1.7 下已经无人扫描——preset 静默消失。这一节
+// 的原语补上这条缝：标记从「只记版本」升级为「版本 + 轨道」两行，轨道翻转即
+// 触发自愈；且声明轨上的自愈可以只补 home patch 声明行（磁盘产物原样保留、
+// 字节不动），不必整盘重生成。
+
+/** 编排类 preset 目录名（orchestrator / orchestrator-<slug>）的形状过滤。 */
+const ORCHESTRATOR_PRESET_ID_RE = /^orchestrator(-[a-z0-9-]+)?$/
+
+/**
+ * 列出 $DSH_HOME/.agent-presets/ 下的编排类 preset 目录名（含基础 orchestrator
+ * 与各工作区专属 orchestrator-<slug>），按名排序。目录不存在 / 不可读一律返回
+ * 空列表。非编排类目录（liangshen 之类自制 preset）不在此列——迁移对账只认
+ * 本工具生成的产物形状。
+ */
+export function listOrchestratorPresetIds(dshHome) {
+  try {
+    return readdirSync(path.join(dshHome, '.agent-presets'))
+      .filter((name) => ORCHESTRATOR_PRESET_ID_RE.test(name))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 读任意 preset 目录下 preset.yml 的显示元数据（name / description / order），
+ * 与 generateAndInstall 写 preset.yml / 声明行 config 的取值口径同源：顶层
+ * name / order 单行标量 + description 多行纯量（续行按 YAML 折叠语义以空格
+ * 拼接成单值）。读不到 / 解析不出时返回空元数据——声明行的 name /
+ * description / order 都是宿主可选键，缺省不致命。
+ */
+export function readPresetDirMeta(dir) {
+  try {
+    const text = readFileSync(path.join(dir, 'preset.yml'), 'utf8')
+    const lines = text.split(/\r?\n/)
+    const firstMatch = (re) => {
+      for (const line of lines) {
+        const m = re.exec(line)
+        if (m) return m
+      }
+      return null
+    }
+    const name = firstMatch(/^name:[ \t]*(.+?)[ \t]*$/)?.[1] ?? null
+    const orderRaw = firstMatch(/^order:[ \t]*(\d+)[ \t]*$/)
+    const order = orderRaw ? Number(orderRaw[1]) : null
+    let description = null
+    const di = lines.findIndex((l) => /^description:/.test(l))
+    if (di !== -1) {
+      const parts = [lines[di].slice('description:'.length).trim()]
+      for (let i = di + 1; i < lines.length; i++) {
+        const line = lines[i]
+        if (line.trim() === '' || !/^[ \t]/.test(line)) break // 续行尽 / 撞上下一个顶层键
+        parts.push(line.trim())
+      }
+      description = parts.filter((p) => p !== '').join(' ') || null
+    }
+    return { name, description, order }
+  } catch {
+    return { name: null, description: null, order: null }
+  }
+}
+
+/**
+ * 把磁盘上已有的编排类 preset 目录补写进 home patch 托管块（缺行才补，已有行
+ * 原样不动）；行在、目录没了的撤行——目录与行同生同灭。产物不全（缺
+ * agent.cordis.yml / restrict.mjs）的目录跳过并 warn，不拖垮其余补写。
+ * 返回实际补写成功的 presetId 列表（既没补也没撤时为空数组）。
+ */
+export function backfillHomePatchRows(dshHome, presetIds) {
+  const rowsOnDisk = readHomePatchRows(dshHome)
+  const wanted = new Set((Array.isArray(presetIds) ? presetIds : []).filter((id) => ORCHESTRATOR_PRESET_ID_RE.test(id)))
+  const rows = []
+  const backfilled = []
+  for (const presetId of wanted) {
+    if (rowsOnDisk.some((r) => r.presetId === presetId)) continue
+    const dir = path.join(dshHome, '.agent-presets', presetId)
+    try {
+      const agentYmlText = readFileSync(path.join(dir, 'agent.cordis.yml'), 'utf8')
+      const restrictFile = path.join(dir, 'restrict.mjs')
+      if (!existsSync(restrictFile)) throw new Error('restrict.mjs 缺失')
+      const meta = readPresetDirMeta(dir)
+      rows.push(
+        buildPresetRowText({
+          presetId,
+          name: meta.name,
+          description: meta.description,
+          order: meta.order,
+          agentYmlText,
+          restrictFileUrl: pathToFileURL(restrictFile).href,
+        }),
+      )
+      backfilled.push(presetId)
+    } catch (err) {
+      warn(`声明行补写跳过 ${presetId}（产物不全，可整盘重生成修复）: ${err?.message ?? err}`)
+    }
+  }
+  if (rows.length > 0) upsertHomePatchRows(dshHome, rows)
+  // 反向对账：托管块里有行、磁盘上已无对应目录的（用户手删目录等），行同步撤下
+  const orphanRowIds = rowsOnDisk.filter((r) => r.presetId !== null && !wanted.has(r.presetId)).map((r) => r.rowId)
+  if (orphanRowIds.length > 0) stripHomePatchRows(dshHome, orphanRowIds)
+  return backfilled
+}
+
+/**
+ * 解析 .generator-version 标记文本为 { version, track }。v2 格式两行：首行
+ * 生成器版本、次行预设安装轨道（declarative / directory）；旧格式（单行版本，
+ * 0.3.4 及以前）解析出 track: null —— 恰是「宿主轨道已翻转但产物版本未动」的
+ * 迁移触发态。空文本 / 全空白返回 null（按未生成处理）。
+ */
+export function parseGeneratorMarker(text) {
+  const lines = String(text ?? '')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l !== '')
+  if (lines.length === 0) return null
+  const track = lines[1] === 'declarative' || lines[1] === 'directory' ? lines[1] : null
+  return { version: lines[0], track }
+}
+
+/** 生成 .generator-version 标记文本（版本 + 轨道两行，v2 格式）。 */
+export function formatGeneratorMarker(version, presetSystem) {
+  return `${version}\n${presetSystem}\n`
+}

package/tools/lib/state.mjs

@@ -16,7 +16,6 @@ import {
   copyFileSync,
   existsSync,
   mkdirSync,
-  readdirSync,
   readFileSync,
   rmSync,
   statSync,
@@ -50,8 +49,10 @@ import { smartDefaults } from './alloc.mjs'
 import {
   buildPresetRowText,
   detectPresetSystem,
+  listOrchestratorPresetIds,
   presetRowId,
   readHomePatchRows,
+  readPresetDirMeta,
   stripHomePatchRows,
   upsertHomePatchRows,
 } from './preset-system.mjs'
@@ -236,14 +237,7 @@ export async function collectState({ dshHome, configFile, profile = null, patche
   // 无读权限等）一律降级为空列表，绝不影响检测结果本体；generateAndInstall
   // 成功落盘后以它为对账清单做孤儿工作区 preset 回收。两轨的产物目录同名同
   // 位置（.agent-presets/<presetId>/），这一扫描天然覆盖两轨的 installed 判定。
-  let installedPresets = []
-  try {
-    installedPresets = readdirSync(path.join(dshHome, '.agent-presets'))
-      .filter((name) => /^orchestrator(-[a-z0-9-]+)?$/.test(name))
-      .sort()
-  } catch {
-    installedPresets = []
-  }
+  const installedPresets = listOrchestratorPresetIds(dshHome)
 
   return {
     dshHome,
@@ -283,43 +277,13 @@ export async function collectState({ dshHome, configFile, profile = null, patche
 }
 
 /**
- * SRC preset.yml 显示元数据提取（name / description / order）：声明行轨把这些
- * 值写进 home patch 声明行的 config，取值口径与目录轨写 preset.yml 完全同源
+ * SRC preset.yml 显示元数据（name / description / order）：声明行轨把这些值
+ * 写进 home patch 声明行的 config，取值口径与目录轨写 preset.yml 完全同源
  * （name 可被 main_agent_display_name / 工作区派生名覆盖，见 generateAndInstall
- * 调用处）。preset.yml 是仓库内受控格式：顶层 name / order 单行标量 +
- * description 多行纯量（续行按 YAML 折叠语义以空格拼接成单值，落声明行时由
- * JSON.stringify 转义）。读不到 / 解析不出时返回空元数据——声明行的
- * name / description / order 都是宿主可选键，缺省不致命。
+ * 调用处）。解析实现已沉到 preset-system.readPresetDirMeta（迁移对账同源复用）。
  */
 function readPresetMeta() {
-  try {
-    const text = readFileSync(path.join(SRC_DIR, 'preset.yml'), 'utf8')
-    const lines = text.split(/\r?\n/)
-    const firstMatch = (re) => {
-      for (const line of lines) {
-        const m = re.exec(line)
-        if (m) return m
-      }
-      return null
-    }
-    const name = firstMatch(/^name:[ \t]*(.+?)[ \t]*$/)?.[1] ?? null
-    const orderRaw = firstMatch(/^order:[ \t]*(\d+)[ \t]*$/)
-    const order = orderRaw ? Number(orderRaw[1]) : null
-    let description = null
-    const di = lines.findIndex((l) => /^description:/.test(l))
-    if (di !== -1) {
-      const parts = [lines[di].slice('description:'.length).trim()]
-      for (let i = di + 1; i < lines.length; i++) {
-        const line = lines[i]
-        if (line.trim() === '' || !/^[ \t]/.test(line)) break // 续行尽 / 撞上下一个顶层键
-        parts.push(line.trim())
-      }
-      description = parts.filter((p) => p !== '').join(' ') || null
-    }
-    return { name, description, order }
-  } catch {
-    return { name: null, description: null, order: null }
-  }
+  return readPresetDirMeta(SRC_DIR)
 }
 
 /**

package/tools/lib/upgrade.mjs

@@ -10,7 +10,9 @@
  * 开发 link: 直连形态的真实路径在仓库里、匹配不到，如实报「无法就地升级」。
  *
  * 零依赖纯 Node（>=18）：目标版本复用 version.mjs 的 fetchLatestFromRegistry
- * （npm registry 优先），子进程、时钟全部可注入便于单测。升级后不做磁盘后验
+ * / fetchLatestFromMirror（官方源失败再走 npmmirror 镜像——点「升级」的用户
+ * 网络本来就在出状况，多一路快路能实打实救回一次升级），子进程、时钟全部
+ * 可注入便于单测。升级后不做磁盘后验
  * ——本进程代码不随升级变化，无从对账；成功与否以 dsh 子进程退出码为准，
  * 新版本在重启 DSH 后生效（preset 由新包的启动自愈钩子自动重生成）。
  *
@@ -22,7 +24,7 @@ import os from 'node:os'
 import { spawn } from 'node:child_process'
 import { realpath } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
-import { currentVersion, compareVersions, fetchLatestFromRegistry } from './version.mjs'
+import { currentVersion, compareVersions, fetchLatestFromMirror, fetchLatestFromRegistry } from './version.mjs'
 
 // 子进程输出上限：合并 stdout+stderr 后只保留最后 ~8KB（安装进度刷屏无排障
 // 价值，报错结论都在尾部）；累积过程中超过 1MB 就先截一版，防止异常刷爆内存。
@@ -124,13 +126,17 @@ async function doRunUpgrade({ profile, fetchImpl, spawnImpl, timeoutMs, now }) {
   const elapsedMs = () =>
     Math.max(0, (typeof now === 'function' ? now() : typeof now === 'number' ? now : Date.now()) - startedAt)
 
-  // ① 版本预检：拿不到 registry latest 就不做半截升级（宁可不动现有安装）。
-  //    registry 超时给 10s：面板静默检测用 3s 够了，这里是用户显式点了「升级」、
-  //    本来就要等，多花几秒换一次成功率是划算的；仍超时就如实报失败。
+  // ① 版本预检：拿不到 latest 就不做半截升级（宁可不动现有安装）。官方源
+  //    失败再试 npmmirror 镜像。超时给 10s：面板静默检测用 3s 够了，这里是
+  //    用户显式点了「升级」、本来就要等，多花几秒换一次成功率是划算的；
+  //    仍超时就如实报失败。
   const { version: current } = await currentVersion()
   const reg = await fetchLatestFromRegistry({ fetchImpl, timeoutMs: 10000 })
-  if (!reg.ok) return { ok: false, error: `无法确定最新版本：${reg.error}` }
-  const target = reg.latest // 形如 v0.2.3
+  const manifest = reg.ok ? reg : await fetchLatestFromMirror({ fetchImpl, timeoutMs: 10000 })
+  if (!manifest.ok) {
+    return { ok: false, error: `无法确定最新版本：官方源 ${reg.error}；镜像 ${manifest.error}` }
+  }
+  const target = manifest.latest // 形如 v0.2.3
   if (compareVersions(target, current) <= 0) return { ok: true, upToDate: true, current }
   const targetVersion = target.replace(/^v/, '')
 

package/tools/lib/version.mjs

@@ -1,8 +1,10 @@
 /**
  * 版本提示 —— 检测线上是否有比本地更新的版本（Web 面板 + CLI 共用）。
  *
- * 检测源两级：npm registry 的 dist-tags/latest 优先（无认证无限流，发布即
- * 可见，不像 GitHub release 需要另行打 tag），GitHub releases/latest 兜底。
+ * 检测源三级：npm registry 的 dist-tags/latest 优先（无认证无限流，发布即
+ * 可见，不像 GitHub release 需要另行打 tag）；失败再试 npmmirror 镜像（数据
+ * 同步自 npm registry，官方源超时 / 被墙时国内几秒内可达，分钟级同步延迟对
+ * 「有没有新版」这个判断无伤大雅）；最后 GitHub releases/latest 兜底。
  *
  * 零依赖纯 Node（>=18）：不引 cordis / npm 依赖，fetch 可注入（缺省用
  * globalThis.fetch），超时用 AbortSignal.timeout()。所有失败路径都不抛错，
@@ -22,6 +24,9 @@ const RELEASE_API = 'https://api.github.com/repos/lifangjin/dsh-paoding/releases
 const RELEASE_PAGE = 'https://github.com/lifangjin/dsh-paoding/releases/latest'
 // npm registry 的 latest 元数据端点（等价 dist-tags.latest，无认证无限流）。
 const REGISTRY_LATEST = 'https://registry.npmjs.org/dsh-paoding/latest'
+// npmmirror 镜像的同名端点：manifest 形状与官方源一致（顶层 version 即
+// latest），同步自 npm registry，官方源不可达时的国内快路。
+const MIRROR_LATEST = 'https://registry.npmmirror.com/dsh-paoding/latest'
 
 // 读不到 package.json 时的版本兜底。当前版本不可知（source: 'fallback'）时
 // updateAvailable 恒 false —— 拿「0.0.0 恒小于任何真实版本」去比较，反而必然
@@ -141,65 +146,87 @@ export async function fetchLatestRelease({ fetchImpl, timeoutMs = 3000 } = {}) {
 }
 
 /**
- * 请求 npm registry 的 latest 元数据（版本检测的首选源，runUpgrade 也复用）。
- * 任何失败（网络 / 超时 / 解析 / 形状不对）都不抛出，返回 { ok: false, error }；
- * 成功返回 { ok: true, latest: 'vX.Y.Z', releaseUrl, source: 'npm' }（registry
- * 的 version 不带 v 前缀，这里统一补齐，与 GitHub tag 的显示口径一致）。
+ * 请求一个 npm 系 manifest 端点（官方源与 npmmirror 镜像共用同一形状：完整
+ * manifest，顶层 version 即 latest）。任何失败（网络 / 超时 / 解析 / 形状不对）
+ * 都不抛出，返回 { ok: false, error }；成功返回 { ok: true, latest: 'vX.Y.Z',
+ * releaseUrl, source }（端点的 version 不带 v 前缀，这里统一补齐，与 GitHub
+ * tag 的显示口径一致）。
  */
-export async function fetchLatestFromRegistry({ fetchImpl, timeoutMs = 3000 } = {}) {
+async function fetchLatestManifest(url, label, source, { fetchImpl, timeoutMs = 3000 } = {}) {
   const doFetch = typeof fetchImpl === 'function' ? fetchImpl : globalThis.fetch
   if (typeof doFetch !== 'function') return { ok: false, error: 'fetch 不可用（当前运行时无 fetch 实现）' }
   try {
-    const res = await doFetch(REGISTRY_LATEST, {
+    const res = await doFetch(url, {
       headers: { accept: 'application/vnd.npm+json' },
       signal: AbortSignal.timeout(timeoutMs),
     })
-    if (!res.ok) return { ok: false, error: `npm registry HTTP ${res.status}` }
+    if (!res.ok) return { ok: false, error: `${label} HTTP ${res.status}` }
     let data = null
     try {
       data = await res.json()
     } catch (err) {
-      return { ok: false, error: `npm registry 响应解析失败: ${err?.message ?? err}` }
+      return { ok: false, error: `${label} 响应解析失败: ${err?.message ?? err}` }
     }
     // /<name>/latest 返回该版本的完整 manifest，顶层 version 即 latest 版本号；
-    // CDN 缓存抖动可能回形状不对的正文，按失败处理走 GitHub 兜底。
+    // CDN 缓存抖动可能回形状不对的正文，按失败处理走下一级检测源。
     const ver = typeof data?.version === 'string' && data.version !== '' ? data.version : null
-    if (!ver) return { ok: false, error: 'npm registry 响应缺少 version' }
-    return { ok: true, latest: `v${ver}`, releaseUrl: RELEASE_PAGE, source: 'npm' }
+    if (!ver) return { ok: false, error: `${label} 响应缺少 version` }
+    return { ok: true, latest: `v${ver}`, releaseUrl: RELEASE_PAGE, source }
   } catch (err) {
     return { ok: false, error: String(err?.message ?? err) }
   }
 }
 
+/**
+ * 请求 npm registry（官方源）的 latest 元数据——版本检测首选源，runUpgrade
+ * 的目标版本解析也复用。
+ */
+export async function fetchLatestFromRegistry(opts) {
+  return await fetchLatestManifest(REGISTRY_LATEST, 'npm registry', 'npm', opts)
+}
+
+/**
+ * 请求 npmmirror 镜像的 latest 元数据——官方源不可达（超时 / 被墙 / 代理
+ * 黑洞）时的国内快路：manifest 形状与官方源一致，同步延迟分钟级，对「有
+ * 没有新版」这个判断无伤大雅。
+ */
+export async function fetchLatestFromMirror(opts) {
+  return await fetchLatestManifest(MIRROR_LATEST, 'npmmirror', 'mirror', opts)
+}
+
 /**
  * 组合结果（面板路由与 CLI 收尾共用）：带 1 小时内存缓存，过期才重新请求；
  * 请求失败时若上次成功结果在 lastGood 窗口（7 天，见 LASTGOOD_TTL_MS）内则
  * 原样复用（stale-if-error），否则返回带 error 的降级结果（latest 置 null、
  * updateAvailable 恒 false——调用方静默）。当前版本不可知（FALLBACK_VERSION
  * 兜底）时 updateAvailable 恒 false：0.0.0 对任何 latest 都「更小」，比较必
- * 误报新版，升级提示整体抑制。检测源 npm registry 优先，失败再试 GitHub
- * release；双败才算本次检测失败，error 里带上两级的失败原因便于排障。成功
- * 结果的 source 字段记录命中源。
+ * 误报新版，升级提示整体抑制。检测源三级：npm registry 优先，失败再试
+ * npmmirror 镜像，最后 GitHub release；三路皆败才算本次检测失败，error 里
+ * 带上各路失败原因与代理排查提示便于排障。成功结果的 source 字段记录命中源。
  * @param {{fetchImpl?: Function, timeoutMs?: number, now?: Function|number}} opts
  *   now 可注入函数或时间戳（测试用）；缺省 Date.now()。
  * @returns {Promise<{current: string, latest: string|null, updateAvailable: boolean,
  *           releaseUrl: string|null, checkedAt: string, error: string|null,
- *           source: 'npm'|'github'|null}>}
+ *           source: 'npm'|'mirror'|'github'|null}>}
  */
 export async function getVersionInfo({ fetchImpl, timeoutMs = 3000, now } = {}) {
   const nowMs = typeof now === 'function' ? now() : typeof now === 'number' ? now : Date.now()
   if (cache.info && nowMs - cache.at < CACHE_TTL_MS) return cache.info
   const { version: current, source: currentSource } = await currentVersion()
-  // ① npm registry 优先；② 失败时 GitHub releases/latest 兜底。
-  const reg = await fetchLatestFromRegistry({ fetchImpl, timeoutMs })
-  let hit = null
-  let githubErr = null
-  if (reg.ok) {
-    hit = reg
-  } else {
+  // 三级链：① npm registry（官方源）；② npmmirror 镜像（官方源不可达时的
+  // 国内快路）；③ GitHub releases/latest（镜像也挂时的独立数据源）。
+  const failures = []
+  let hit = await fetchLatestFromRegistry({ fetchImpl, timeoutMs })
+  if (!hit.ok) {
+    failures.push(hit.error)
+    hit = await fetchLatestFromMirror({ fetchImpl, timeoutMs })
+  }
+  if (!hit.ok) {
+    failures.push(hit.error)
     const rel = await fetchLatestRelease({ fetchImpl, timeoutMs })
-    if (rel.ok) hit = { ok: true, latest: rel.tag, releaseUrl: rel.url, source: 'github' }
-    else githubErr = rel.error
+    hit = rel.ok
+      ? { ok: true, latest: rel.tag, releaseUrl: rel.url, source: 'github' }
+      : { ok: false, error: rel.error }
   }
   if (hit && hit.ok) {
     const info = {
@@ -216,10 +243,11 @@ export async function getVersionInfo({ fetchImpl, timeoutMs = 3000, now } = {})
     cache = { at: nowMs, info }
     return info
   }
-  // 双失败：优先复用 lastGood 窗口（7 天）内的上次成功结果；超窗才给降级结果
-  // （不写缓存）。error 把 registry 与 GitHub 两级原因都带上（谁挂了一目了然）；
-  // 走到这里 githubErr 必有值（能进兜底说明 registry 已失败），无需再兜底文案。
-  const combined = `${reg.error}；GitHub 兜底也失败: ${githubErr}`
+  // 三路皆败：优先复用 lastGood 窗口（7 天）内的上次成功结果；超窗才给降级
+  // 结果（不写缓存）。error 把各路原因都带上（谁挂了一目了然），并附代理排查
+  // 提示——最常见的「浏览器能上网、DSH 进程检测失败」是启动环境的代理变量
+  // 指向了不可用的代理（DSH 遵循 HTTPS_PROXY 等变量，浏览器不走它们）。
+  const combined = `三路检测均失败（npm registry: ${failures[0]}；npmmirror: ${failures[1]}；GitHub: ${hit.error}）。若本机经代理访问外网，请确认代理可用后重启 DSH 再试——DSH 进程遵循 HTTPS_PROXY / HTTP_PROXY 环境变量，浏览器不走它们，两者连通性可能不同`
   if (cache.info && nowMs - cache.at < LASTGOOD_TTL_MS) return cache.info
   return {
     current,