dsh-plugin-admin 0.3.1 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@ dsh web UI 插件：在浏览器设置弹窗（侧边栏底部“设置”）中
   - 列表展示当前 profile 下的全部 bundle 层（名称、版本，以及**内置 / 包安装 / 本地安装**标记；本地安装的插件额外显示其源路径，依据 profile 依赖清单中的 `link:` / `file:` / 绝对路径 spec 判定）；
   - **名称模糊搜索**：列表上方搜索框支持按插件名 / 版本号 / 本地路径模糊过滤（大小写不敏感子串匹配），可叠加「全部 / 扩展插件 / 系统内置」筛选胶囊，无结果时给出专属空状态提示；
   - 支持扩展插件一键卸载（带有优雅的行内二次确认）；
-  - **远程更新检测（自动）**：打开「插件管理」Tab 即自动按 profile 实际使用的 npm registry（`npm_config_registry` → 项目/用户 `.npmrc` → 官方源）查询每个 **registry 安装**的插件（跳过内置与本地路径安装）的 `latest` 版本，与本地版本比对——有新版时卡片显示琥珀色「⬆ 有新版本 vX.Y.Z」徽标并出现一键「⬆ 更新」按钮（`npm install <name>@latest`）；工具栏「⬆ 检查更新」可强制手动刷新；查询带超时与 5 分钟缓存（host 侧缓存，**缓存命中时按当前安装版本重算 `updateAvailable`**，重启 dsh 后首次打开自动重查），网络失败按条目提示而非报错；**「有新版本」提醒会保存下来（浏览器 localStorage 持久化）**——关闭再进入管理中心、甚至重启 dsh 后依然显示（含本次检查网络失败时），**只有点「更新」真正升级、或后续检查确认已是最新版本后，提醒才自动消除并同步清掉持久化记录**；
+  - **远程更新检测（自动）**：打开「插件管理」Tab 即自动按 profile 实际使用的 npm registry（`npm_config_registry` → 项目/用户 `.npmrc` → 官方源）查询每个 **registry 安装**的插件（跳过内置与本地路径安装）的 `latest` 版本，与本地版本比对——有新版时卡片显示琥珀色「⬆ 有新版本 vX.Y.Z」徽标并出现一键「⬆ 更新」按钮（`npm install <name>@latest`）；工具栏「⬆ 检查更新」是唯一的手动重查入口，**强制绕过 5 分钟缓存直接重查 registry 并刷新缓存内容**（自动检查走缓存，手动检查才是真查）；查询带超时与 5 分钟缓存（host 侧缓存，**缓存命中时按当前安装版本重算 `updateAvailable`**，重启 dsh 后首次打开自动重查），网络失败按条目提示而非报错；**「有新版本」提醒会保存下来（浏览器 localStorage 持久化）**——关闭再进入管理中心、甚至重启 dsh 后依然显示（含本次检查网络失败时），**只有点「更新」真正升级、或后续检查确认已是最新版本后，提醒才自动消除并同步清掉持久化记录；更新其中一个插件不会影响其余插件的提醒；升级完成后的自动复核同样**强制绕过缓存**重新查询，registry 在 TTL 窗口内刚发布更新的情况下也不会把刚升完级的插件误标回「有新版本」，检查与升级并发交错时，检查刚发现的提醒也不会被升级提交用旧快照覆盖（合并一律基于当前 state 的函数式更新，持久化由统一的镜像 effect 收口）；
   - 安装/卸载在 host 侧编排 profile 目录下的 pnpm 并自动同步 `package.json` 的 `dsh.profile.bundles` 清单（变更在重启 dsh 后生效）。
 - **💬 会话管理**：
   - **标题与内容摘要**：自动解析会话标题（`session/title` 或首条用户提问）并渲染首条消息的文本摘要气泡预览（带折行省略与多行保护）；
@@ -15,7 +15,8 @@ dsh web UI 插件：在浏览器设置弹窗（侧边栏底部“设置”）中
   - **状态呼吸灯与徽标**：绿色呼吸光晕（**会话在线**，悬停提示说明"在线 = 仍挂载于 dsh host 内存，非正在运行"）、琥珀色标签（**已归档**）、灰色默认点（**已结束**）；
   - **多维快捷搜索与筛选**：输入框支持同时模糊匹配标题、对话摘要、工作目录或 Session ID；支持按状态胶囊筛选（全部、在线、已归档、已结束）；
   - **会话清理与恢复**：支持会话永久物理删除（行内二次防误触确认，彻底清理磁盘日志、工作区记账与归档集合）；**在线会话不再需要重启 dsh**——「关停并删除」通过插件在 host 侧透明捕获的 `AgentHandle` 走 dsh 官方 dispose 链（停止 agent 运行、等待静止、注销 agent、从内存 SessionStore 移除并触发 `session/disposed`，持久化层随即 flush 缓冲事件并释放写路径），然后才删除日志，因此日志不会在下次 flush 复活；支持已归档会话一键取消归档，侧边栏即时联动刷新。
-- **🔌 MCP 配置**：管理中心中的独立 Tab——列出 profile 的 `cordis.patch.yml` 中所有 `@deepseek-ai/dsh-mcp-client` 实例，支持添加（stdio 子进程 / streamable-http）、编辑与移除，配置写回后重启 dsh 生效；新增**连通性检测**（🔌 测试）——host 侧按条目配置发起一次真实的 MCP 握手（`initialize` → `notifications/initialized` → `tools/list`），stdio 走新行分隔 JSON-RPC 子进程（Windows 下与 real 插件同样经 `cmd.exe` 解析 `.cmd` shim，超时强杀进程树、捕获 stderr 尾部便于诊断），streamable-http 走 `initialize` POST（兼容 SSE / 纯 JSON 响应）；成功后行内显示服务器标识、**工具数量与工具名列表**，失败给出可诊断错误（命令不存在 / 连接被拒 / 超时等）；若 `command` 写成整行调用（如 `npx -y fetcher-mcp`），探测会自动拆分执行并给出**警告**提示需拆分为 `command` + `args`（否则 dsh 启动该 MCP 服务器会失败）；结果经 typert 边界 JSON 安全清洗，绝无 `undefined` 字段。
+  - **🔌 MCP 配置**：管理中心中的独立 Tab——列出 profile 的 `cordis.patch.yml` 中所有 `@deepseek-ai/dsh-mcp-client` 实例，支持添加（stdio 子进程 / streamable-http）、编辑与移除，配置写回后重启 dsh 生效；新增**连通性检测**（🔌 测试）——host 侧按条目配置发起一次真实的 MCP 握手（`initialize` → `notifications/initialized` → `tools/list`），stdio 走新行分隔 JSON-RPC 子进程（Windows 下与 real 插件同样经 `cmd.exe` 解析 `.cmd` shim，超时强杀进程树、捕获 stderr 尾部便于诊断），streamable-http 走 `initialize` POST（兼容 SSE / 纯 JSON 响应）；成功后行内显示服务器标识、**工具数量与工具名列表**，失败给出可诊断错误（命令不存在 / 连接被拒 / 超时等）；若 `command` 写成整行调用（如 `npx -y fetcher-mcp`），探测会自动拆分执行并给出**警告**提示需拆分为 `command` + `args`（否则 dsh 启动该 MCP 服务器会失败）；结果经 typert 边界 JSON 安全清洗，绝无 `undefined` 字段；
+  - **测试结果的缓存边界**：只有**成功**的探测结果持久化到 localStorage（重开面板/重启后恢复上次状态并标注「缓存于」时刻）；**失败（❌ 不通）只在当前会话内显示、不落盘**——瞬时故障不会变成跨会话的过期 ❌，旧版本遗留的失败记录会在载入时自动清除；新增表单中手输与既有条目相同的 id 会被**直接拒绝并提示换名**——host 的 upsert 按 id 原位覆盖，不拦截就是静默毁掉该条目的既有配置。
 - **侧边栏右键菜单（会话 & 工作区）**：
   - **会话行右键**：在原生菜单末尾追加**复制会话 ID**与**删除会话**（危险操作）；删除按标题**精确匹配**解析目标，存在同名会话时拒绝执行并引导到管理中心按 ID 删除，且菜单项需**4 秒内两次点击**确认；删除复用 `sessionAdmin` 的安全语义——在线会话走 `closeSession`（先 dispose 捕获的 agent handle 再删日志，不再要求重启），非在线会话走 `deleteSession`，均定向 detach。
   - **工作区行右键**：新增**在资源管理器打开**——调用 `fsAdmin.reveal` 在系统文件管理器中定位该工作区目录（Windows `explorer /select`、macOS `open -R`、Linux `xdg-open`）。
@@ -27,7 +28,7 @@ dsh web UI 插件：在浏览器设置弹窗（侧边栏底部“设置”）中
 - **Host 端（`lib/index.js`，零 dsh 依赖）**：
   - 注入 `['typert', 'workspaceRegistry', 'sessionPersistence']`；
   - 提供并注册四个 RPC 命名空间：
-    - `pluginAdmin`（`list` / `install` / `remove` / `checkUpdates`）：异步 `spawn` pnpm（Windows 走 shell 解析 .cmd shim，5 分钟超时且**进程树强杀**（`taskkill /T /F`，避免超时后残留 pnpm/node 子进程继续写盘），Promise 尾链串行化防并发），镜像 CLI `reconcileBundles` 同步清单，清单写回为**原子写**（临时文件 + rename，崩溃不截断 profile 的 package.json）；安装/卸载参数经**字符白名单**校验（`assertPnpmOperand`），从根上排除 `&` `|` `>` `<` `%` 引号等 cmd 元字符注入向量；`install` / `remove` 返回真实 pnpm 输出尾部（`output` 字段），前端作为提示气泡的悬浮诊断信息展示；`checkUpdates` 对 registry 安装的 bundle 并发查询 npm registry 的 `latest`（registry 解析：`npm_config_registry` env → 项目/用户 `.npmrc` → 官方源；有界并发 4 路、8s 超时、5 分钟缓存），返回 `updateAvailable` / `latest` / `error`，本地路径与内置插件跳过；
+    - `pluginAdmin`（`list` / `install` / `remove` / `checkUpdates`）：异步 `spawn` pnpm（Windows 走 shell 解析 .cmd shim，5 分钟超时且**进程树强杀**（`taskkill /T /F`，避免超时后残留 pnpm/node 子进程继续写盘），Promise 尾链串行化防并发），镜像 CLI `reconcileBundles` 同步清单，清单写回为**原子写**（临时文件 + rename，崩溃不截断 profile 的 package.json）；安装/卸载参数经**字符白名单**校验（`assertPnpmOperand`），从根上排除 `&` `|` `>` `<` `%` 引号等 cmd 元字符注入向量；`install` / `remove` 返回真实 pnpm 输出尾部（`output` 字段），前端作为提示气泡的悬浮诊断信息展示；`checkUpdates` 对 registry 安装的 bundle 并发查询 npm registry 的 `latest`（registry 解析：`npm_config_registry` env → 项目/用户 `.npmrc` → 官方源；有界并发 4 路、8s 超时、5 分钟缓存；`force` 参数为 true 时**绕过缓存强制重查并刷新缓存内容**），返回 `updateAvailable` / `latest` / `error`，本地路径与内置插件跳过；
     - `sessionAdmin` (`list` / `archive` / `unarchive` / `deleteSession` / `closeSession`)：直接对接 `workspaceRegistry` 与 `sessionPersistence`，提供安全幂等的持久化日志清理与归档状态流转；`list` 采用**修订号驱动的摘要缓存**（`listSnapshots` 的 revision token，未变化会话不重读事件日志）与**有界并发**（最多 4 路并行 inspect），并设单会话事件扫描上限兜底；`archive` 校验会话真实存在，拒绝向归档集写入垃圾 id；对 registry 软私有写路径（`requireState` / `setState` / `enqueueOperation`）在 `apply()` 挂载时即做**兼容性探测**，dsh 版本变更会明确报出缺失成员，而不是首次归档时才静默失败。`closeSession` 使**在线会话免重启删除**成为可能：`installAgentHandleCapture` 在挂载时透明包装公开的 `ctx.agents.create` / `resume`（原样调用并返回，仅把返回的 `AgentHandle` 按 session id 存入插件私有 Map），删除在线会话时先 `handle.dispose()` 走 dsh 官方 teardown 链（停止 loop → 等待静止 → 注销 agent → 从 SessionStore 移除 → 触发 `session/disposed` → 持久化层 `retire()` flush 缓冲事件并释放写路径），再删日志——日志不会被下次 flush 复活；未被捕获 handle 的在线会话（如插件挂载前已创建）会明确报错并引导重启，绝不误删。
     - `fsAdmin` (`reveal`)：跨平台在系统文件管理器中定位一个绝对路径（Windows `explorer /select`、macOS `open -R`、Linux `xdg-open`），供工作区右键菜单「在资源管理器打开」使用；
     - `mcpAdmin` (`list` / `upsert` / `remove` / `test`)：管理 profile 的 `cordis.patch.yml` 中的 MCP 客户端实例（`@deepseek-ai/dsh-mcp-client`）。基于行级 YAML 块编辑（零依赖）：识别顶层 `- id:` 块并仅改动 `name` 为 MCP 客户端插件的条目，`upsert` 按 id 原位替换或追加，`remove` 整块删除，写回走**原子写**；校验 id / serverName / transport / command / url，拒绝畸形输入；文件变更与插件安装共用同一**串行操作队列**（读-改-写不交错）。`test` 按条目 id 发起**连通性探测**：stdio 子进程（newline JSON-RPC，`initialize` → `initialized` → `tools/list`，超时 `taskkill /T /F` 强杀进程树，捕获 stderr 尾部）或 streamable-http（`fetch` POST `initialize`，兼容 SSE 与纯 JSON，超时 AbortController），返回服务器标识 / 工具数量 / 耗时，或失败原因（命令不存在、连接拒绝、超时等），全程不抛异常。
@@ -87,8 +88,8 @@ node scripts/host-check.mjs
 7. 会话删除二次确认交互；
 8. **侧边栏菜单注入**：验证会话菜单追加「复制会话 ID / 删除会话」，删除项为**两次点击确认**（首击改写标签、二击才触发 RPC）且对**同名会话拒绝删除**；工作区菜单追加「在资源管理器打开」；
 9. **MCP 配置面板渲染与保存流**：独立 MCP 设置页展示服务器列表、添加/编辑/移除入口与空状态；打开添加表单填写 id / serverName / command 后保存，断言 `mcpAdmin/upsert` 收到正确载荷、表单关闭且新服务器入列；**连通性测试按钮**（🔌 测试）触发 `mcpAdmin/test` 并在行内渲染 ✅ 连通（含服务器名与工具数量）。
-10. `verify-mcp-cache.mjs`：MCP 连通性测试缓存的 localStorage 往返（预置缓存渲染 / 新探测持久化 + 重挂载恢复 / 配置保存失效缓存）；
-11. `verify-update-reminders.mjs`：插件**更新提醒持久化**（保存下来、更新完删除提醒）——① 已保存的提醒在重开面板且本次检查网络失败时依然渲染且不被抹除；② 检查确认已是最新版本 → 徽标与 localStorage 记录同时清除；③ 点击卡片「⬆ 更新」→ 安装后提醒立即消失（含回调确认后仍不复活）；④ 某个插件查询出错时不丢失已有提醒。
+10. `verify-mcp-cache.mjs`：MCP 连通性测试缓存的 localStorage 往返（预置缓存渲染 / 新探测持久化 + 重挂载恢复 / 配置保存失效缓存 / **失败探测 `{ok:false}` 只存于会话不落盘、重挂载不复活 ❌**）；
+11. `verify-update-reminders.mjs`：插件**更新提醒持久化**（保存下来、更新完删除提醒）——① 已保存的提醒在重开面板且本次检查网络失败时依然渲染且不被抹除；② 检查确认已是最新版本 → 徽标与 localStorage 记录同时清除；③ 点击卡片「⬆ 更新」→ 安装后提醒立即消失（含回调确认后仍不复活）；④ 某个插件查询出错时不丢失已有提醒；⑤ 同时有两个过时插件时**只更新其中一个**，另一个的提醒在重挂载（刷新）后依然保留、localStorage 也只留未更新那条；⑥ **首开即全量查询失败**时逐条渲染「⚠ 更新检查失败」标签并给出失败计数，绝不显示「全部为最新版本」——瞬时错误不写入 localStorage，下一次成功检查自动消退（混合轮次只对确实验证过的条目说「其余均为最新版本」）；⑦ 自动检查在飞期间点击「⬆ 更新」，检查刚发现的其他插件提醒**不会被升级提交用旧快照覆盖**（deferred 桩脚本化交错：先放行检查、再放行安装，中间断言提醒与 localStorage 均在；旧实现在此处会丢失提醒且跳过升级后的强制复核）。
 
 Host 侧自检（`scripts/host-check.mjs`）覆盖下列契约：
 1. `sessionAdmin.deleteSession` 的**定向 detach 契约**：删除会话只允许触碰实际记账该会话的那一个工作区，绝不允许批量遍历（dsh 的 `detachSession` 写入带剪枝语义——记录中所有不在 registry 内存头索引里的会话会被永久剥离；批量调用在索引不完整时会把无关工作区的记账整体清空，表现为所有会话落入"未分组"）；
@@ -100,7 +101,8 @@ Host 侧自检（`scripts/host-check.mjs`）覆盖下列契约：
 6. **mcpAdmin 配置往返**：对临时 profile 的 `cordis.patch.yml` 做 list / upsert（新增、原位更新）/ remove，验证条目 id、serverName 与最终文件内容正确且仍是合法 YAML；同时校验畸形输入（非法 id / transport / 缺 command）被拒绝；`fsAdmin.reveal` 校验路径参数；
 7. **mcpAdmin 写操作串行化**：并发 `upsert` 经与插件安装共享的操作队列后全部落盘，读-改-写不交错；
 8. **mcpAdmin.test 连通性探测**：对真实 stdio MCP 服务器（newline JSON-RPC 握手）与 streamable-http 服务器（`initialize` POST）分别断言 `ok:true` 且携带 serverInfo / toolCount；对不存在的命令（`not found`）、静默子进程（超时）、死 HTTP 端点（连接失败）断言 `ok:false` 且错误可诊断；未知 id 被拒绝；
-9. **checkUpdates 缓存命中回归**：5 分钟 TTL 内第二次查询命中缓存时，`updateAvailable` 按**当前安装版本**重算——仍落后版本 → 提醒保留（修复了缓存只存 latest 导致重开面板提醒丢失）；把安装版本抬到 latest 模拟升级完成 → 提醒自动消除（更新完删除提醒）。
+9. **checkUpdates 缓存命中回归**：5 分钟 TTL 内第二次查询命中缓存时，`updateAvailable` 按**当前安装版本**重算——仍落后版本 → 提醒保留（修复了缓存只存 latest 导致重开面板提醒丢失）；把安装版本抬到 latest 模拟升级完成 → 提醒自动消除（更新完删除提醒）；
+10. **checkUpdates 强制刷新（force）**：「⬆ 检查更新」传入 `force` 时**绕过 TTL 真正重查 registry**（stub 请求计数递增），返回值立即反映 registry 新版本，且**下一个 TTL 内的普通查询直接吃到 force 刷新后的缓存内容**（检查更新强制更新缓存内容）；升级到刷新后的 latest → 提醒消除。
 
 ---
 

package/lib/bring-explorer.ps1

@@ -1,6 +1,12 @@
 # dsh-plugin-admin: bring Explorer window to foreground
 # Usage: powershell -File bring-explorer.ps1 -Path <absolute path>
-param([Parameter(Mandatory=$true)][string]$Path)
+# Fail-soft contract: never waits on user input -- an empty/missing -Path
+# must NOT hit a Mandatory prompt (this console is HIDDEN; the process
+# would linger forever), so the parameter is optional and guarded below.
+param([string]$Path = '')
+
+$ErrorActionPreference = 'SilentlyContinue'
+if ([string]::IsNullOrWhiteSpace($Path)) { exit 0 }
 
 Add-Type @"
 using System;
@@ -18,8 +24,24 @@ public class Fr {
 }
 "@
 
-$base = ($Path -replace '\\', '/').Split('/')[-1]
-$script:pattern = [regex]::Escape($base) + '\s*-'
+# The title Explorer displays is the DISPLAY NAME of the revealed FOLDER:
+# the folder itself -- or its PARENT when reveal ran `/select,<file>` on a
+# file. Fall back to the last path segment when the item is gone/unreadable.
+$base = $null
+$item = Get-Item -LiteralPath $Path
+if ($null -ne $item) {
+  if ($item.PSIsContainer) { $base = $item.Name }
+  else { $base = Split-Path -Leaf $item.DirectoryName }
+} else {
+  $segments = ($Path -replace '\\', '/').Split('/') | Where-Object { $_ }
+  if ($segments.Count -gt 0) { $base = $segments[-1] }
+}
+if ([string]::IsNullOrWhiteSpace($base)) { exit 0 }
+
+# Stock Windows 10/11 titles are the bare folder name; some shell addons
+# append " - <suffix>". Anchor at start, make the dash clause optional so
+# both shapes match, and prefix collisions ("Test" vs "Test 2") stay safe.
+$script:pattern = '^' + [regex]::Escape($base) + '(?:\s*-|$)'
 $script:found = [IntPtr]::Zero
 
 function Find-Target {
@@ -45,12 +67,16 @@ for ($i = 0; $i -lt 30; $i++) {
   Start-Sleep -Milliseconds 200
 }
 
-if ($target -ne [IntPtr]::Zero) {
-  # Simulated ALT keypress grants foreground permission
-  [Fr]::keybd_event(0x12, 0, 0, [UIntPtr]::Zero)
-  [Fr]::keybd_event(0x12, 0, 2, [UIntPtr]::Zero)
-  Start-Sleep -Milliseconds 80
-  [Fr]::ShowWindow($target, 9) | Out-Null
-  [Fr]::SetForegroundWindow($target) | Out-Null
-  [Fr]::BringWindowToTop($target) | Out-Null
-}
+if ($target -eq [IntPtr]::Zero) { exit 1 }
+
+# Simulated ALT keypress grants foreground permission
+[Fr]::keybd_event(0x12, 0, 0, [UIntPtr]::Zero)
+[Fr]::keybd_event(0x12, 0, 2, [UIntPtr]::Zero)
+Start-Sleep -Milliseconds 80
+[Fr]::ShowWindow($target, 9) | Out-Null
+[Fr]::SetForegroundWindow($target) | Out-Null
+[Fr]::BringWindowToTop($target) | Out-Null
+
+# One debuggable line on stdout; the host pipe just drains it.
+Write-Output ("raised:{0}" -f $target)
+exit 0

package/lib/client.js

@@ -497,28 +497,38 @@ function setupMenuInjection(call, refreshSessions) {
  * Plugins management settings section (standalone, no internal tabs).
  */
 function PluginsSection(props) {
-  var pairPlugins = useState({
-    profileDir: '',
-    plugins: [],
-    busy: false,
-    error: '',
-    spec: '',
-    confirming: null,
-    note: '',
-    output: '',
-    filter: 'all',
-    needle: '',
-    checkingUpdates: false,
-    updateChecked: false, // true once a check finished (even if no updates)
-    // Seed from persisted reminders so the ⬆ 有新版本 badge is visible the
-    // moment the panel mounts (before the fresh host check resolves) — the
-    // reminder is only dropped once a check confirms the upgrade completed.
-    updates: loadUpdateReminders(), // name -> { latest, updateAvailable, error?, at? }
+  // Lazy initializer: the seed object (and its localStorage read) must be
+  // built once at mount, not re-parsed on every render.
+  var pairPlugins = useState(function () {
+    return {
+      profileDir: '',
+      plugins: [],
+      busy: false,
+      error: '',
+      spec: '',
+      confirming: null,
+      note: '',
+      output: '',
+      filter: 'all',
+      needle: '',
+      checkingUpdates: false,
+      updateChecked: false, // true once a check finished (even if no updates)
+      // Seed from persisted reminders so the ⬆ 有新版本 badge is visible the
+      // moment the panel mounts (before the fresh host check resolves) — the
+      // reminder is only dropped once a check confirms the upgrade completed.
+      updates: loadUpdateReminders(), // name -> { latest, updateAvailable, error?, at? }
+    }
   })
   var pView = pairPlugins[0]
   var setPView = pairPlugins[1]
 
   var alive = useRef(false)
+  // In-flight check guard as a ref, not state: the state field drives the
+  // disabled button visuals, but gating ASYNC handlers on it races — a stale
+  // closure reads TRUE after an earlier check already settled and silently
+  // skips a required follow-up (the post-upgrade refresh), or FALSE mid-flight
+  // and lets a second one through. Refs are immune to closure staleness.
+  var checkingRef = useRef(false)
 
   function patchPlugin(partial) {
     setPView(function (cur) {
@@ -559,68 +569,48 @@ function PluginsSection(props) {
    *   - newer version confirmed      -> (re)arm & persist the reminder
    *   - confirmed up to date         -> drop the reminder (更新完删除提醒)
    *   - per-plugin check error       -> keep the known reminder (a transient
-   *                                     registry failure must not erase it)
+   *                                     registry failure must not erase it);
+   *                                     with no known reminder the failure
+   *                                     itself is recorded so cards/strip/
+   *                                     note can surface it
    *   - no longer a registry install -> drop stale reminders
+   * The AUTO check on panel open is cache-friendly; a manual check passes
+   * force=true so the host bypasses its 5-minute TTL, re-queries the registry
+   * and refreshes the cached content (检查更新 = 强制重新查，而不是回放缓存).
    * Runs concurrently with the list so the panel stays responsive; failures
    * are per-plugin, never fatal.
+   * @param force - true to force the host to bypass its update cache.
    */
-  function checkUpdates() {
-    if (pView.checkingUpdates) return
+  function checkUpdates(force) {
+    if (checkingRef.current) return
+    checkingRef.current = true
     patchPlugin({ checkingUpdates: true, note: '' })
-    callRemote('pluginAdmin/checkUpdates', {}).then(function (result) {
+    callRemote('pluginAdmin/checkUpdates', { force: force === true }).then(function (result) {
+      checkingRef.current = false
       if (!alive.current) return
-      patchPlugin({ checkingUpdates: false })
       if (!result.ok) {
-        patchPlugin({ error: '检查更新失败：' + messageOf(result.error) })
+        patchPlugin({ checkingUpdates: false, error: '检查更新失败：' + messageOf(result.error) })
         // A failed call must not wipe previously known reminders — they stay
         // seeded from localStorage and keep rendering on the cards.
         return
       }
       var list = (result.value && result.value.updates) || []
-      // Only the plugins the host actually checked are "live" registry
-      // installs; builtins / local-path installs never carry a reminder and a
-      // reminder for a removed plugin must be dropped too.
-      var liveNames = {}
-      for (var a = 0; a < list.length; a++) liveNames[list[a].name] = true
-
-      var prev = pView.updates || {}
-      var map = {}
-      for (var k in prev) {
-        if (prev[k] && liveNames[k]) map[k] = prev[k]
-      }
-      for (var i = 0; i < list.length; i++) {
-        var u = list[i]
-        if (u.updateAvailable === true) {
-          map[u.name] = { latest: u.latest, updateAvailable: true, error: '', at: Date.now() }
-        } else if (u.latest !== null && u.latest !== undefined && !u.error) {
-          // Authoritatively current — the newer version is now installed.
-          delete map[u.name]
-        } else if (map[u.name]) {
-          // Query failed for this entry: keep the prior reminder, surface the
-          // transient error alongside it.
-          map[u.name] = mergeReminder(map[u.name], { error: u.error || '' })
-        }
-      }
-      // Persist whatever the check decided so the reminder survives dialog
-      // close/reopen and dsh restarts (best-effort; never fatal).
-      saveUpdateReminders(map)
-
-      var updateCount = 0
-      var checkErrorCount = 0
-      for (var n in map) {
-        if (map[n].updateAvailable === true) updateCount++
-        if (map[n].error) checkErrorCount++
-      }
-      patchPlugin({
-        updates: map,
-        updateChecked: true,
-        note: updateCount > 0
-          ? '发现 ' + updateCount + ' 个插件有新版本'
-          : (checkErrorCount > 0
-            ? '已检查 ' + list.length + ' 个插件（' + checkErrorCount + ' 个查询失败），其余均为最新版本'
-            : (list.length > 0 ? '已检查 ' + list.length + ' 个插件，均为最新版本' : '')),
+      // Merge INSIDE the functional updater against the LATEST committed
+      // state, never the render closure's snapshot: a reminder armed by an
+      // in-flight check resolving alongside an upgrade commit must survive
+      // (a stale-snapshot full replace erased it). The updater stays pure —
+      // localStorage persistence is owned by the mirror effect below.
+      setPView(function (cur) {
+        var next = {}
+        for (var k in cur) next[k] = cur[k]
+        next.checkingUpdates = false
+        next.updates = mergeUpdateReminders(cur.updates || {}, list)
+        next.updateChecked = true
+        next.note = updateCheckNote(next.updates, list.length)
+        return next
       })
     }, function (failure) {
+      checkingRef.current = false
       if (!alive.current) return
       patchPlugin({ checkingUpdates: false, error: '检查更新调用失败：' + messageOf(failure) })
     })
@@ -634,24 +624,33 @@ function PluginsSection(props) {
     callRemote('pluginAdmin/install', { spec: spec }).then(function (result) {
       if (!alive.current) return
       if (result.ok) {
-        patchPlugin({
-          busy: false,
-          note: '已更新 ' + name + '。更改在重启 dsh 后生效',
-          output: (result.value && result.value.output) || '',
-          profileDir: (result.value && result.value.profileDir) || '',
-          plugins: (result.value && result.value.plugins) || [],
+        // The upgrade consumed this reminder: strip it from the CURRENT state
+        // inside the updater (更新完删除提醒) — never from the click-time
+        // closure snapshot, which may miss reminders an in-flight check armed
+        // meanwhile (erasing those was exactly scenario 7's stale-snapshot
+        // bug). localStorage follows via the shared mirror effect; the forced
+        // refresh below confirms the new version is current.
+        setPView(function (cur) {
+          var next = {}
+          for (var k in cur) next[k] = cur[k]
+          next.busy = false
+          next.note = '已更新 ' + name + '。更改在重启 dsh 后生效'
+          next.output = (result.value && result.value.output) || ''
+          next.profileDir = (result.value && result.value.profileDir) || ''
+          next.plugins = (result.value && result.value.plugins) || []
+          var remaining = {}
+          for (var rk in cur.updates) {
+            if (rk !== name) remaining[rk] = cur.updates[rk]
+          }
+          next.updates = remaining
+          return next
         })
-        // The upgrade consumed this reminder: clear it right away and persist
-        // so it does not linger after the update (更新完删除提醒); the refresh
-        // check below confirms the new version is current.
-        var nextReminders = {}
-        for (var rk in pView.updates) {
-          if (rk !== name) nextReminders[rk] = pView.updates[rk]
-        }
-        saveUpdateReminders(nextReminders)
-        patchPlugin({ updates: nextReminders })
         // Refresh the update map so the upgraded entry stops flagging.
-        checkUpdates()
+        // Force: the @latest spec installed the registry's CURRENT latest,
+        // but the host TTL cache may still hold an older latest published
+        // minutes ago — comparing against that would re-flag the freshly
+        // upgraded plugin. Bypass the cache and resync its content instead.
+        checkUpdates(true)
         return
       }
       patchPlugin({ busy: false, error: '更新失败：' + messageOf(result.error) })
@@ -713,14 +712,25 @@ function PluginsSection(props) {
     alive.current = true
     reloadPlugins()
     // Auto-check for remote updates on mount (the panel loads lazily when
-    // the 插件管理 tab is opened, so this runs once per open). The host
-    // caches registry answers for 5 minutes, so re-opening the tab shortly
-    // after does not re-hit the registry. The manual ⬆ 检查更新 button stays
-    // for forcing a fresh check.
+    // the 插件管理 tab is opened, so this runs once per open). The auto path
+    // is cache-friendly: the host serves its 5-minute cache, so re-opening
+    // the tab shortly after does not re-hit the registry. The manual
+    // ⬆ 检查更新 button is the force path — it bypasses the cache and
+    // refreshes its content.
     checkUpdates()
     return function () { alive.current = false }
   }, [])
 
+  // Single persistence point: localStorage always mirrors the LATEST
+  // committed reminders. Moving saves out of the async handlers (and out of
+  // the functional updaters, which must stay pure) removes drift by
+  // construction — whatever merge won the last commit is what survives
+  // dialog reopen and dsh restarts (best-effort; unavailable storage just
+  // degrades to session-only badges).
+  useEffect(function () {
+    saveUpdateReminders(pView.updates || {})
+  }, [pView.updates])
+
   return createElement('div', { 'data-dsh-admin-section': '' },
     renderPluginsView(pView, patchPlugin, installPlugin, removePlugin, checkUpdates, upgradePlugin))
 }
@@ -844,7 +854,16 @@ function loadMcpTestCache() {
   if (store === null) return {}
   try {
     var parsed = JSON.parse(store.getItem(MCP_TEST_CACHE_KEY))
-    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+    if (parsed === null || typeof parsed !== 'object') return {}
+    // Purge failure records persisted by older builds: only a durable OK is
+    // worth restoring on mount; a stale ❌ from a past outage must not
+    // outlive the session it happened in.
+    var out = {}
+    for (var id in parsed) {
+      var entry = parsed[id]
+      if (entry && entry.result && entry.result.ok === true) out[id] = entry
+    }
+    return out
   } catch (e) {
     return {}
   }
@@ -858,8 +877,11 @@ function saveMcpTestCache(state) {
     var out = {}
     for (var id in state) {
       var s = state[id]
-      // Busy rows keep the previous cached result; failures stay ephemeral.
-      if (!s || s.busy || s.result === null || s.result === undefined) continue
+      // Busy rows keep the previous cached result; failures stay ephemeral —
+      // INCLUDING structured {ok:false} probes (timeout, connection refused),
+      // which arrive as a truthy result object and need their own ok check.
+      if (!s || s.busy || s.result === null || s.result === undefined
+        || s.result.ok !== true) continue
       out[id] = { result: s.result, at: typeof s.at === 'number' ? s.at : Date.now() }
     }
     store.setItem(MCP_TEST_CACHE_KEY, JSON.stringify(out))
@@ -974,6 +996,64 @@ function saveUpdateReminders(map) {
   }
 }
 
+/**
+ * Merge one check response into the CURRENT reminder map. Pure on purpose:
+ * it runs inside the setPView updater, so it reads only its arguments and
+ * must never touch localStorage or other component state. Per-entry semantics
+ * (list = fresh host results, one row per live registry install):
+ *   - updateAvailable  -> (re)arm the reminder
+ *   - confirmed current -> drop any entry (更新完删除提醒)
+ *   - query error      -> keep a prior reminder untouched (error attached);
+ *                         without one, record an ephemeral failure
+ *                         ({updateAvailable:false}) so cards/strip/note can
+ *                         surface it — saveUpdateReminders skips those
+ *   - entries absent from `list` are no longer live registry installs ->
+ *     stale reminders dropped
+ * @param curMap - the CURRENT updates state ({ name -> entry }).
+ * @param list - per-plugin check results.
+ * @returns the complete next map.
+ */
+function mergeUpdateReminders(curMap, list) {
+  var liveNames = {}
+  for (var a = 0; a < list.length; a++) liveNames[list[a].name] = true
+  var map = {}
+  for (var k in curMap) {
+    if (curMap[k] && liveNames[k]) map[k] = curMap[k]
+  }
+  for (var i = 0; i < list.length; i++) {
+    var u = list[i]
+    if (u.updateAvailable === true) {
+      map[u.name] = { latest: u.latest, updateAvailable: true, error: '', at: Date.now() }
+    } else if (u.error) {
+      // A prior reminder survives untouched with the transient error
+      // alongside; WITHOUT one the failure itself lands in the map so an
+      // all-failed first check cannot claim 全部为最新版本.
+      map[u.name] = map[u.name]
+        ? mergeReminder(map[u.name], { error: u.error || '' })
+        : { latest: '', updateAvailable: false, error: u.error || '', at: Date.now() }
+    } else if (u.latest !== null && u.latest !== undefined) {
+      delete map[u.name]
+    }
+  }
+  return map
+}
+
+/** Aggregate summary line for a finished check (pure). */
+function updateCheckNote(map, checkedCount) {
+  var updateCount = 0
+  var checkErrorCount = 0
+  for (var n in map) {
+    if (map[n].updateAvailable === true) updateCount++
+    if (map[n].error) checkErrorCount++
+  }
+  if (updateCount > 0) return '发现 ' + updateCount + ' 个插件有新版本'
+  if (checkErrorCount > 0) {
+    return '已检查 ' + checkedCount + ' 个插件（' + checkErrorCount + ' 个查询失败）'
+      + (checkedCount > checkErrorCount ? '，其余均为最新版本' : '')
+  }
+  return checkedCount > 0 ? '已检查 ' + checkedCount + ' 个插件，均为最新版本' : ''
+}
+
 function McpSection(props) {
   var pairMcp = useState({
     mcpEntries: [],
@@ -1103,6 +1183,18 @@ function McpSection(props) {
   function saveMcpDraft() {
     var draft = mView.mcpDraft
     if (draft === null) return
+    // A NEW entry must not collide with an existing id: the host's upsert
+    // locates its target block by id and would replace that entry in place,
+    // silently destroying its config. The edit form keeps its own id (the
+    // field is disabled), so this guard only ever fires on the add form.
+    if (draft.isNew) {
+      for (var ci = 0; ci < mView.mcpEntries.length; ci++) {
+        if (mView.mcpEntries[ci].id === draft.id) {
+          patchMcp({ mcpError: 'ID \'' + draft.id + '\' 已被其他 MCP 条目占用，请换一个再保存。' })
+          return
+        }
+      }
+    }
     var config
     if (draft.transport === 'streamable-http') {
       config = { transport: 'streamable-http', serverName: draft.serverName, url: draft.url }
@@ -1305,7 +1397,8 @@ function renderPluginsView(view, patch, install, remove, checkUpdates, upgrade)
       key: 'btn-check-updates',
       className: 'btn',
       disabled: view.busy || view.checkingUpdates,
-      onClick: checkUpdates,
+      title: '强制绕过 5 分钟缓存，重新查询 registry 并刷新缓存',
+      onClick: function () { checkUpdates(true) },
     },
       view.checkingUpdates ? createElement('span', { className: 'spinner', key: 'spin' }) : null,
       view.checkingUpdates ? '检查中...' : '⬆️ 检查更新'
@@ -1356,7 +1449,9 @@ function renderPluginsView(view, patch, install, remove, checkUpdates, upgrade)
   // Update-check status strip: gives the auto-check a visible outcome instead
   // of hiding it in the footer. Checking → spinner; done with updates →
   // orange; done without updates → green; per-plugin query failures surface
-  // on the strip rather than vanishing.
+  // on the strip rather than vanishing. Purely informational — the single
+  // re-check entry point is the toolbar「⬆️ 检查更新」button (which forces a
+  // fresh registry query), so no redundant button lives in the strip.
   if (view.checkingUpdates) {
     elements.push(createElement('div', { className: 'update-strip checking', key: 'update-checking' },
       createElement('span', { className: 'spinner', key: 'spin' }),
@@ -1377,14 +1472,7 @@ function renderPluginsView(view, patch, install, remove, checkUpdates, upgrade)
         ? '⚠️ 有 ' + errCount + ' 个插件查询版本失败（网络或 registry 不可达）'
         : '✅ 已自动检查版本更新，全部为最新版本')
     elements.push(createElement('div', { className: stripClass, key: 'update-result' },
-      createElement('span', { key: 't' }, stripText),
-      createElement('button', {
-        type: 'button',
-        key: 'btn-recheck',
-        className: 'btn sm',
-        disabled: view.busy || view.checkingUpdates,
-        onClick: checkUpdates,
-      }, '🔄 重新检查')
+      createElement('span', { key: 't' }, stripText)
     ))
   }
 

package/lib/index.js

@@ -1116,6 +1116,7 @@ export function apply(ctx) {
   // 'updateAvailable' flag is recomputed on every read against the CURRENT
   // installed version (see checkUpdates) — a still-outdated plugin keeps
   // flagging on each re-open, while one upgraded in between stops flagging.
+  // A manual check (force) bypasses this cache and refreshes its content.
   const updateCache = new Map()
 
   const pluginService = {
@@ -1131,9 +1132,18 @@ export function apply(ctx) {
      * hit still recomputes `updateAvailable` against the current installed
      * version so the reminder survives repeated panel opens and clears only
      * once the plugin is actually upgraded.
+     * When `force` is true the TTL cache is bypassed and every plugin is
+     * re-queried against the registry, refreshing the cached `latest` values —
+     * the toolbar 「⬆ 检查更新」button always forces, so a manual check really
+     * checks instead of replaying a cached answer.
+     * @param force - true to bypass the TTL cache and refresh cached content.
      * @returns { updates, checkedAt } where updates is per-plugin status.
      */
-    async checkUpdates() {
+    async checkUpdates(force) {
+      // Tolerate the RPC gateway passing the bound boolean or the raw args
+      // object ({ force: true }) whichever way it arrives.
+      const forceRefresh = force === true
+        || (force !== null && typeof force === 'object' && force.force === true)
       const now = Date.now()
       const { plugins } = listLayers()
       const registry = resolveNpmRegistry(profileDir)
@@ -1142,7 +1152,9 @@ export function apply(ctx) {
       for (const plugin of plugins) {
         if (!plugin.dependency || plugin.localPath !== null) continue
         const hit = updateCache.get(plugin.name)
-        if (hit !== undefined && hit.latest !== null && now - hit.at < UPDATE_CHECK_CACHE_TTL_MS) {
+        const cacheWarm = !forceRefresh && hit !== undefined && hit.latest !== null
+          && now - hit.at < UPDATE_CHECK_CACHE_TTL_MS
+        if (cacheWarm) {
           // Serve the cached 'latest' but recompute the flag against the
           // CURRENT installed version. The cached entry must carry
           // updateAvailable — a bare { name, latest } is read by the client
@@ -2001,6 +2013,7 @@ export function apply(ctx) {
   /* ---------------------- Typert Descriptors Register ---------------------- */
   const specParam = [{ name: 'spec', wire: 'spec', source: 'json', codec: { mode: 'src-json' } }]
   const nameParam = [{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'src-json' } }]
+  const forceParam = [{ name: 'force', wire: 'force', source: 'json', codec: { mode: 'src-json' } }]
   const sessionParam = [{ name: 'sessionId', wire: 'sessionId', source: 'json', codec: { mode: 'src-json' } }]
 
   ctx.effect(() => ctx.typert.register({
@@ -2043,7 +2056,7 @@ export function apply(ctx) {
         namespace: PLUGIN_NAMESPACE,
         method: 'checkUpdates',
         invocation: { kind: 'direct' },
-        parameters: [],
+        parameters: forceParam,
         result: { mode: 'src-json' },
       },
       // sessionAdmin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-admin",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "description": "dsh web UI plugin: unified administration panel — plugin and session management with modern tabbed Web UI (host remote + browser panel)",
   "main": "lib/index.js",