dsh-paoding 0.3.5 → 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/installation.md

@@ -12,7 +12,7 @@
 
 - **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 家目录。
 - **路径事实**（生成管线内建常量，写死前先了解它们）：
 
 | 项 | 默认值 | 说明 |
@@ -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」的机制不同，安装器据此分双轨落点，宿主检测全自动、用户无感：
 
@@ -108,7 +108,7 @@ 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
@@ -120,7 +120,7 @@ dsh plugin --profile <name> update dsh-paoding
 
 **开发 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,7 +12,7 @@ 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 |
@@ -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:
 
@@ -108,7 +108,7 @@ 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
@@ -120,7 +120,7 @@ Manual equivalent: run the `dsh plugin update` command above yourself, restart,
 
 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.5",
+  "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/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 键控槽在左侧栏
@@ -530,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.5",
+  "version": "0.3.6",
   "private": true,
   "type": "module",
   "main": "index.mjs",

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,