@noob-stupid/dsh-plugin-console 0.3.47 → 0.3.48

package/README.md

@@ -308,7 +308,7 @@ MIT
 
 The layered-refactor preview lives in its **own repository**: [**`Noob-stupid/dsh-plugin-hub-refactor`**](https://github.com/Noob-stupid/dsh-plugin-hub-refactor)
 
-- **What it is**: the monolithic `lib/index.js` (7637 lines) split into layers — `lib/index.js` **142 lines** + `lib/server/**` **36 modules**; **feature-equivalent to `0.3.46`**, maintainability only;
-- **Verified**: 17 test suites green · 8 architecture-guard assertions · **47/47 routes identical** (`status` + response fields) against the stable build;
+- **What it is**: the monolithic `lib/index.js` (7637 lines) split into layers — `lib/index.js` **142 lines** + `lib/server/**` **36 modules**; **feature-equivalent to `0.3.48`**, maintainability only;
+- **Verified**: 18 test suites green · 8 architecture-guard assertions · **47/47 routes identical** (`status` + response fields) against the stable build;
 - **Not yet exercised**: real framework upgrade / rollback, restart guardian, real install/uninstall, component start/stop, real AI run, Gitee OAuth (~10–25% long-tail risk, subjective);
-- **For everyday use** stick to npm `@noob-stupid/dsh-plugin-console@0.3.46`, or `main` of this repo.
+- **For everyday use** stick to npm `@noob-stupid/dsh-plugin-console@0.3.48`, or `main` of this repo.

package/README.zh.md

@@ -1,281 +1,282 @@
-> **English**: [README.md](README.md) | **中文**: [README.zh.md](README.zh.md)
-
----
-
-<img width="1170" height="609" alt="image" src="https://github.com/user-attachments/assets/b802d606-14ba-4151-9956-ff642ed12b0a" />
-
-# DSH 插件中心（dsh-plugin-hub）
-
-> 一站式管理你的 DeepSeek Harness 插件：一键启用/停用、500+ 插件与技能市场一键安装、
-> 框架一键升级（失败自动回滚）。
-
-## 为什么是 DSH 插件中心
-
-- 🧩 **插件 + 技能双市场** — 自动收录 `dsh-plugin` 仓库（按 star **500+**）外加技能 tab；
-  浏览、搜索、一键安装，**零 GitHub API 调用**（CDN 分发，秒开零限流）。
-- 🚀 **框架一键升级** — 备份 → 在线安装（服务不中断）→ 校验 → **失败自动回滚**，端到端实测。
-- 🤖 **AI 赋能** — 输入 npm 包名或 GitHub 仓库，本地 AI 读文档生成**部署计划**
-  （安装/写配置/启动服务/健康检查），你确认后安全执行；服务器组件自动生成控制卡片。
-  → [详见](docs/ai-empower.zh.md)
-
-## 一键部署
-
-```bash
-# npm 发布版（推荐：预构建产物，无需 git / 构建授权）
-dsh plugin --profile web add @noob-stupid/dsh-plugin-console
-
-# 或直接装 GitHub 源码（需 git，首次需 allowBuilds 授权）
-dsh plugin --profile web add github:Noob-stupid/dsh-plugin-hub
-```
-
-然后重启 dsh 服务 → 刷新页面 → **设置 → 插件 → 插件控制台**。
-
-<details><summary><b>更多部署方式</b>（部署脚本 / 一句话交给 AI）</summary>
-
-### 方式二：部署脚本（网络受限时的兜底）
-
-Windows（PowerShell）：
-
-```powershell
-git clone https://github.com/Noob-stupid/dsh-plugin-hub "$env:TEMP\dsh-plugin-console" 2>$null; & "$env:TEMP\dsh-plugin-console\deploy.ps1"
-```
-
-Linux / macOS：
-
-```bash
-git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console 2>/dev/null; bash /tmp/dsh-plugin-console/deploy.sh
-```
-
-脚本会做两件事：把插件包拷进 `$DSH_HOME/profiles/<profile>/node_modules/`，
-并在 `cordis.patch.yml` 幂等追加启用条目。完成后：
-
-1. 重启 dsh 服务（宿主代码变更需要重启进程；命令行方式重启进程，桌面客户端退出重开）；
-2. 刷新页面 → 设置 → 插件 → **插件管理**。
-
-### 方式三：一句话交给 AI
-
-> 安装 DSH 插件中心（dsh-plugin-hub）：运行 `dsh plugin --profile web add @noob-stupid/dsh-plugin-console`（npm 发布版）；若没有 dsh CLI，则克隆 https://github.com/Noob-stupid/dsh-plugin-hub 到 `~/.dsh/profiles/web/node_modules/`，在 `cordis.patch.yml` 注册（id: plugin-console，name: @noob-stupid/dsh-plugin-console）。完成后重启 dsh web。
-
-要求：DSH ≥ 0.1.0-rc.6（web profile，含 `dsh-client-modules` / `dsh-host-plugin-inventory`）。
-
-</details>
-
----
-
-## 核心优势
-
-| | 优势 | 说明 |
-|---|---|---|
-| 🤖 | **AI 赋能** | 输入 npm 包名 / GitHub 仓库，本地 AI 读文档生成**部署计划**（安装/写配置/启动服务/健康检查），你确认后安全执行；服务器类组件自动生成控制卡片 |
-| 🛡️ | **框架升级适配门与安全** | 升级后不兼容插件强制禁用（适配门锁定，「检测更新 → 更新并适配 → 自动校验解锁」）；升级前全树 checkpoint、拉起失败自动全树回滚、框架卡片一键回滚到上一版 |
-| 🏠 | **全家桶分组卡片与安全** | 同根包子路径导出自动聚合为一张全家桶卡片（收起/展开、批量检测更新、一键启用已适配、已知校验预览）；永不崩安全（启用前导入探针 + 补丁自愈 + exports 回退）；适配门源码扫描硬判据与迁移检测；删除聚合包子行仅停用该行 |
-| 🚀 | **服务器组件卡片** | 左侧浮卡与主面板顶边对齐：启动 / 停止 / 状态 / 【打开】直达 Web UI，多服务器下拉、可折叠（状态记忆） |
-| 🧩 | **插件 + 技能双市场** | 自动收录 `dsh-plugin` topic 仓库（按 star **500+**），另有**技能 tab**（`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`，最多 300）——浏览、搜索、一键安装，零 GitHub API 调用；插件自带技能（如 openviking-memory）只读展示 |
-| 🤖 | **自动收录 CI** | GitHub Actions 每 6 小时自动重跑 `build-index`（也支持手动触发）；作者只需给自己的仓库打 `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` 标签，**无需申请、无需审核** |
-| ⚡ | **秒开、零限流** | 索引以静态 `marketplace/index.json` 提交仓库，经 jsDelivr CDN 分发（宿主 10 分钟缓存）——终端用户**零 GitHub API 调用、零限流** |
-| 🔄 | **版本检测与一键更新** | semver 比较 + beta/next 识别（本地已是测试版最新时不误报）；已安装条目自动比对 npm `dist-tags`，聚合包子包版本不配套时给出 depsOutdated 提示 |
-| 🔀 | **多源检索** | GitHub / Gitee（仓库直装模式）/ 自定义搜索源（URL 模板 + 请求头认证 + 私网 http）；「⊞」并行合并 GitHub + 全部自定义源 |
-| 🔒 | **安全默认** | 全部路由仅环回；AI 兜底置于明确费用授权弹窗之后；AI 赋能执行器命令/路径白名单；基础设施行禁止开关（受保护） |
-
-<details>
-<summary><b>📑 目录</b></summary>
-
-- [核心优势](#核心优势)
-- [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
-- [一键部署](#一键部署)
-- [使用方法](#使用方法)
-- [功能](#功能)
-- [原理](#原理)
-- [兼容性策略](#兼容性策略)
-- [项目结构](#项目结构)
-- [HTTP 接口](#http-接口)
-- [安全说明](#安全说明)
-- [已知限制](#已知限制)
-- [帮助 / Help](#帮助--help)
-- [生态与收录](#生态与收录)
-- [参与贡献](#参与贡献)
-- [许可证](#许可证)
-</details>
-
----
-
-## 使用方法
-
-1. 重启 DSH → 打开 Web GUI → **设置 → 插件 → 插件管理**。
-2. **已安装列表**：一键开关（HMR 约 1 秒生效）、按名称/id 搜索、展开详情（版本、仓库、README 摘要）。
-3. **插件市场**：GitHub 源空查询直接打开静态索引（秒开）；输入关键词实时搜索。顶部登录标切换
-   搜索源（GitHub / Gitee / 自定义）；「⊞」多源合并；「★」只看可 `dsh plugin add` 直装。
-4. **技能 tab**：搜索框旁切换「插件 / 技能」，浏览并一键安装技能（克隆到 `~/.dsh/skills/<名称>/`）。
-5. **安装**：点「添加到本地」→ 后台安装链自动执行（可放心离开页面）；已安装条目自动出现
-   「检测更新」/「更新 → vX」。
-
----
-
-## 功能
-
-### 已安装插件（一键开关 + 详情）
-
-- **默认只显示第三方插件**（后装/非 dsh 自带），带「第三方」标签与删除入口；点「全部」切换查看完整列表（1.5s 亮框反馈）；
-- 列出全部插件条目（名称、加载状态、启用状态）；支持按名称/id 搜索；
-- 点「停用」= 在用户补丁层写入 `- id: X` + `disabled: true`，HMR 立即生效；
-- 点「启用」= 移除该停用条目；bundle 层本就停用的行用 `disabled: false` 覆盖；
-- 打标「补丁停用 / 补丁强制启用」区分用户补丁状态；
-- **基础设施保护**：host 传输/热加载/存储/设置链上的插件（timer、hmr、webserver 等
-  70+ 行）标记「受保护」，禁止开关——误停用会破坏热加载本身；
-- **详情面板**：每个插件可点「详情」，展开简介、版本、仓库/主页链接与 README 摘要；
-- **版本检测**：「检测更新」走 curl 读 npm `dist-tags.latest`（node 网络黑洞时也可用），
-  并提示需要同步的子包版本（depsOutdated），避免半更新混搭导致启动冲突。
-
-### 框架一键升级（deepseek-harness 卡片）
-
-- **deepseek-harness 卡片**在检测到框架新版本时显示「框架升级 → vX」（稳定版 latest 优先；
-  latest 与当前相同时取 next 预发布渠道）；点击一键完成：备份配置与框架本体（回滚点）→
-  **在线安装**（服务保持运行、页面不断开）→ 版本校验 → **自动重启生效**；
-- **实时进度**：升级时弹出 `DSH-Upgrade` 窗口，实时显示 pnpm 下载进度；面板内进度卡片
-  同步显示等待时长；
-- **升级保护**：失败**自动回滚**（robocopy，升级前校验回滚点有效）、版本校验防假成功、
-  15 分钟硬超时、卡死检测（debug 日志无更新自动切换 registry）、全局异常兜底、
-  15 分钟残留状态清理——框架绝不处于损坏状态；
-- **pnpm 通道**：npm-cli.js 在 schtasks 任务环境启动即卡死（debug 日志 0 字节、网络请求
-  都发不出）；升级改用 `corepack pnpm`（实测 0.4s 秒启动、11.5s 装完 rc.8）+ **国内源
-  npmmirror**，并带 `dangerouslyAllowAllBuilds` 让 node-pty/koffi 等原生模块正常编译；
-- **运行时解析 bin.js**：pnpm 布局下 `@deepseek-ai/dsh` 是 Junction——拉起服务在运行时
-  解析（跟随 Junction 到当前版本），而非使用脚本生成时固化的路径；
-- **卡片关闭语义**：终态（成功/失败）点叉号永久关闭（持久化）；进行中点叉号仅本次会话
-  隐藏，刷新后恢复显示。
-
-### 插件市场（多搜索源）
-
-- **搜索源切换**：点击顶部登录态标识弹出菜单，在 **GitHub / Gitee / 自定义源** 间切换（选择持久化）；
-  市场标题、加载提示、搜索框占位符、说明行全部随源切换；
-- **GitHub 源**：默认搜索 `dsh-plugin`，浏览器直连（失败自动回退服务端通道）；
-- **Gitee 源**：Gitee 官方搜索 API 已停用，采用**仓库直装模式**——输入 `owner/repo`
-  （支持中文路径与完整 URL）精确查找仓库并安装；
-- **自定义搜索源**：软件源管理中添加（URL 模板含 `{q}`/`{page}` 占位符），支持
-  **请求头认证**（如 `Authorization: Bearer ...`）与**本机/私网 http 地址**；
-- **多源汇总**：搜索框旁「⊞」开启——GitHub + 全部自定义源并行检索，结果合并并标注来源；
-- **★ 官方筛选**：只筛**可 `dsh plugin add` 直装**的插件——根包带 `dsh.bundle` 清单（官方）
-  或聚合仓库中**子包带 `dsh.bundle`**（子包可直装）；标记由服务端 curl 双通道 + 客户端兜底补全，
-  搜索结果与筛选即时可用；
-- **类型徽标**：官方 / 聚合 / 技能（仓库含 SKILL.md）自动识别；
-- 「添加到本地」= 按当前源安装（registry 失败自动回退 git 通道）+ 写入启用条目，HMR 生效。
-
-### 静态索引市场（插件 / 技能双 tab）
-
-> **混合架构**：浏览走静态索引（秒开、零 API 调用），搜索走实时通道（GitHub 搜索 API / 多源并行）——
-> 两者互补：新仓库即使还没进索引，也能被实时搜索找到。
-
-- GitHub 源空查询展示**静态索引**（`marketplace/index.json`，jsDelivr CDN + 宿主 10 分钟缓存）：
-  按 star 排序 500+ 插件，秒开、**零 GitHub API 调用**；
-- 搜索框旁**「插件 / 技能」tab**：技能 tab 列出自动收录的 `agent-skills` ∪ `claude-skills` ∪
-  `dsh-skill` 仓库（最多 300）；
-- **自动版本比对**：市场中已安装的条目后台自动查 npm `dist-tags.latest`，卡片变「更新 → vX」；
-- **技能安装**：技能条目一键安装 = git clone → 复制 SKILL.md 及同目录资源到
-  `~/.dsh/skills/<名称>/`（frontmatter 的 name 优先于仓库名；SKILL.md 位于仓库根或第一层
-  子目录均可识别）；已装技能显示灰色「已装」徽标。
-
-### 软件源管理
-
-市场标题行右侧悬浮「软件源」按钮（半透明、颜色加深），弹出管理模态框：
-
-![软件源管理](https://github.com/user-attachments/assets/ef712900-65ae-4f6f-9584-bacdd8d34ea1)
-
-- **安装源（registry）**：添加 / 行内编辑 / 设为主源 / 恢复默认；支持私有源与内网地址；
-  **删除已保护**（插件安装依赖的 npm 源，避免误删）；
-- **搜索源**：内置 GitHub、Gitee + 自定义搜索源（增删、🔒 显示请求头数量）；
-- **Gitee 登录（可选）**：直装模式无需登录；登录仅提高接口限额——创建第三方应用
-  （gitee.com → 数据管理 → 第三方应用，权限勾选 user_info、projects）后填入
-  client_id / client_secret → 保存 → 授权登录。
-
----
-
-## 文档
-
-- [AI 赋能与服务器组件控制](docs/ai-empower.zh.md)
-- [框架升级适配门与升级安全](docs/upgrade-safety-adapt-gate.zh.md)
-- [原理](docs/how-it-works.zh.md) · [兼容性策略](docs/compatibility.zh.md) · [项目结构](docs/project-layout.zh.md)
-- [HTTP 接口](docs/http-endpoints.zh.md) · [AI 兜底安装与授权弹窗](docs/ai-fallback.zh.md)
-- [安全说明与免责声明](docs/security-disclaimer.zh.md)
-
----
-
-## 已知限制
-
-- 宿主代码变更需要**重启服务**（面板的重启按钮自带守护、安全）；客户端变更只需刷新页面；
-- 实时 GitHub 搜索依赖 GitHub 可达性（浏览器直连 + 服务端兜底；网络黑洞期请稍后重试）；
-- 版本检测只对已发布到 npm 的包生效；技能类仓库没有版本概念；
-- 静态索引有上限（每次构建 500 插件 / 300 技能）；新仓库靠 star 爬升或等下一轮 6 小时 CI 进入索引；
-- 技能由 `dsh-skill-filesystem` 扫描发现——若当前 profile 未启用该插件，装好的技能会休眠，启用并重启后生效。
-
----
-
-## 帮助 / Help
-
-遇到问题先看这里；仍有疑问请到 [Issues](https://github.com/Noob-stupid/dsh-plugin-hub/issues) 提问。
-
-- **面板没出现**：重启 dsh 服务 → 刷新页面 → 设置 → 插件 → 插件管理。
-- **点开关没反应**：基础设施行带"受保护"标签（禁止开关，这是保护机制）；普通插件开关经
-  HMR 生效，约 1-3 秒，可点刷新查看。
-- **顶部出现兼容性警告**：官方发布了破坏性更新，请到本仓库获取适配版本（见兼容性策略）。
-- **市场搜索没结果/报错**：GitHub 源走浏览器直连（与浏览器可用性一致），失败自动回退
-  服务端通道；Gitee 源为仓库直装模式（输入 `owner/repo`）；自定义源检查地址与请求头配置；
-  网络黑洞期请稍后重试。
-- **★ 筛选为空**：★ 只筛可 `dsh plugin add` 直装（官方 + 子包带 bundle 的聚合）；
-  标记 1-3 秒后台补全后自动出现，不会误报"没有"。
-- **安装失败**：确认仓库有 package.json 且包名已发布到 npm；npm 装不了的会回退
-  `github:owner/repo` 安装（需要 git）；可在软件源管理中换主源（如 npmmirror 网络波动时）。
-- **装好的技能 DSH 不识别**：在 profile 的 `cordis.yml` 启用 `@deepseek-ai/dsh-skill-filesystem`
-  并重启；技能位于 `~/.dsh/skills/<名称>/`。
-
----
-
-## 生态与收录
-
-- 已被 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)（社区主精选列表）与 [DSH Directory](https://dsh.directory) 收录；
-- 本中心的自动收录索引（500+ 插件 / 300 技能，CI 每 6 小时刷新）会收录**任何**打了 `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` 标签的仓库——作者打上标签即可自动出现在市场，无需申请；
-- 如果你在开发 DSH 插件，本面板就是你的分发渠道：所有使用本面板的用户都能一键安装你的插件。
-
-## 支持
-
-如果这个面板帮你省了时间、让 DSH 更好用：
-
-- ⭐ **给本仓库点个 Star**——直接帮助更多 DSH 用户发现它；
-- 分享给身边的 DSH 用户或社区；
-- 提交你自己的插件（打上 `dsh-plugin` 标签）一起壮大生态；
-- 发现 bug 或有新需求？[开一个 Issue](https://github.com/Noob-stupid/dsh-plugin-hub/issues)。
-
----
-
-## 参与贡献
-
-欢迎各种形式的贡献——Issue、PR、文档、翻译：
-
-- **贡献指南**：[CONTRIBUTING.md](CONTRIBUTING.md)
-- **行为准则**：[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
-- **安全政策**：[SECURITY.md](SECURITY.md)（漏洞私下报告）
-- **Issue 模板**：从 [新建 Issue](https://github.com/Noob-stupid/dsh-plugin-hub/issues/new/choose) 页面选择 Bug / 功能建议
-
----
-
-## 更新日志
-
-版本记录见 [CHANGELOG.md](CHANGELOG.md)。
-
----
-
-## License
-
-MIT
-
----
-
----
-
-## 预览版（实验性 · 请勿用于生产）
-
-分层重构预览线在**独立仓库**：[**`Noob-stupid/dsh-plugin-hub-refactor`**](https://github.com/Noob-stupid/dsh-plugin-hub-refactor)
-
-- **它是什么**：把单体 `lib/index.js`（7637 行）拆成分层结构 —— `lib/index.js` **142 行** + `lib/server/**` **36 个模块**，**功能与 `0.3.46` 等价**，只为可维护性；
-- **已验证**：17 套测试全绿 · 8 条架构守卫断言 · 与稳定版逐条对打 **47 条路由，`status` + 响应字段 47/47 一致**；
-- **尚未实测**：真框架升级 / 真回滚、重启守护链路、真装真卸、组件进程启停、AI 真跑、Gitee OAuth 回调（长尾风险主观估计 **10%~25%**）；
-- **日常使用请继续用**：npm `@noob-stupid/dsh-plugin-console@0.3.46`，或本仓库 `main`。
+> **English**: [README.md](README.md) | **中文**: [README.zh.md](README.zh.md)
+
+---
+
+<img width="1170" height="609" alt="image" src="https://github.com/user-attachments/assets/b802d606-14ba-4151-9956-ff642ed12b0a" />
+
+# DSH 插件中心（dsh-plugin-hub）
+
+> 一站式管理你的 DeepSeek Harness 插件：一键启用/停用、500+ 插件与技能市场一键安装、
+> 框架一键升级（失败自动回滚）。
+
+## 为什么是 DSH 插件中心
+
+- 🧩 **插件 + 技能双市场** — 自动收录 `dsh-plugin` 仓库（按 star **500+**）外加技能 tab；
+  浏览、搜索、一键安装，**零 GitHub API 调用**（CDN 分发，秒开零限流）。
+- 🚀 **框架一键升级** — 备份 → 在线安装（服务不中断）→ 校验 → **失败自动回滚**，端到端实测。
+- 🤖 **AI 赋能** — 输入 npm 包名或 GitHub 仓库，本地 AI 读文档生成**部署计划**
+  （安装/写配置/启动服务/健康检查），你确认后安全执行；服务器组件自动生成控制卡片。
+  → [详见](docs/ai-empower.zh.md)
+
+## 一键部署
+
+```bash
+# npm 发布版（推荐：预构建产物，无需 git / 构建授权）
+dsh plugin --profile web add @noob-stupid/dsh-plugin-console
+
+# 或直接装 GitHub 源码（需 git，首次需 allowBuilds 授权）
+dsh plugin --profile web add github:Noob-stupid/dsh-plugin-hub
+```
+
+然后重启 dsh 服务 → 刷新页面 → **设置 → 插件 → 插件控制台**。
+
+<details><summary><b>更多部署方式</b>（部署脚本 / 一句话交给 AI）</summary>
+
+### 方式二：部署脚本（网络受限时的兜底）
+
+Windows（PowerShell）：
+
+```powershell
+git clone https://github.com/Noob-stupid/dsh-plugin-hub "$env:TEMP\dsh-plugin-console" 2>$null; & "$env:TEMP\dsh-plugin-console\deploy.ps1"
+```
+
+Linux / macOS：
+
+```bash
+git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console 2>/dev/null; bash /tmp/dsh-plugin-console/deploy.sh
+```
+
+脚本会做两件事：把插件包拷进 `$DSH_HOME/profiles/<profile>/node_modules/`，
+并在 `cordis.patch.yml` 幂等追加启用条目。完成后：
+
+1. 重启 dsh 服务（宿主代码变更需要重启进程；命令行方式重启进程，桌面客户端退出重开）；
+2. 刷新页面 → 设置 → 插件 → **插件管理**。
+
+### 方式三：一句话交给 AI
+
+> 安装 DSH 插件中心（dsh-plugin-hub）：运行 `dsh plugin --profile web add @noob-stupid/dsh-plugin-console`（npm 发布版）；若没有 dsh CLI，则克隆 https://github.com/Noob-stupid/dsh-plugin-hub 到 `~/.dsh/profiles/web/node_modules/`，在 `cordis.patch.yml` 注册（id: plugin-console，name: @noob-stupid/dsh-plugin-console）。完成后重启 dsh web。
+
+要求：DSH ≥ 0.1.0-rc.6（web profile，含 `dsh-client-modules` / `dsh-host-plugin-inventory`）。
+
+</details>
+
+---
+
+## 核心优势
+
+| | 优势 | 说明 |
+|---|---|---|
+| 🤖 | **AI 赋能** | 输入 npm 包名 / GitHub 仓库，本地 AI 读文档生成**部署计划**（安装/写配置/启动服务/健康检查），你确认后安全执行；服务器类组件自动生成控制卡片 |
+| 🛡️ | **框架升级适配门与安全** | 升级后不兼容插件强制禁用（适配门锁定，「检测更新 → 更新并适配 → 自动校验解锁」）；升级前全树 checkpoint、拉起失败自动全树回滚、框架卡片一键回滚到上一版 |
+| 🏠 | **全家桶分组卡片与安全** | 同根包子路径导出自动聚合为一张全家桶卡片（收起/展开、批量检测更新、一键启用已适配、已知校验预览）；永不崩安全（启用前导入探针 + 补丁自愈 + exports 回退）；适配门源码扫描硬判据与迁移检测；删除聚合包子行仅停用该行 |
+| 🚀 | **服务器组件卡片** | 左侧浮卡与主面板顶边对齐：启动 / 停止 / 状态 / 【打开】直达 Web UI，多服务器下拉、可折叠（状态记忆） |
+| 🧩 | **插件 + 技能双市场** | 自动收录 `dsh-plugin` topic 仓库（按 star **500+**），另有**技能 tab**（`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`，最多 300）——浏览、搜索、一键安装，零 GitHub API 调用；插件自带技能（如 openviking-memory）只读展示 |
+| 🤖 | **自动收录 CI** | GitHub Actions 每 6 小时自动重跑 `build-index`（也支持手动触发）；作者只需给自己的仓库打 `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` 标签，**无需申请、无需审核** |
+| ⚡ | **秒开、零限流** | 索引以静态 `marketplace/index.json` 提交仓库，经 jsDelivr CDN 分发（宿主 10 分钟缓存）——终端用户**零 GitHub API 调用、零限流** |
+| 🔄 | **版本检测与一键更新** | semver 比较 + beta/next 识别（本地已是测试版最新时不误报）；已安装条目自动比对 npm `dist-tags`，聚合包子包版本不配套时给出 depsOutdated 提示 |
+| 🔀 | **多源检索** | GitHub / Gitee（仓库直装模式）/ 自定义搜索源（URL 模板 + 请求头认证 + 私网 http）；「⊞」并行合并 GitHub + 全部自定义源 |
+| 🔒 | **安全默认** | 全部路由仅环回；AI 兜底置于明确费用授权弹窗之后；AI 赋能执行器命令/路径白名单；基础设施行禁止开关（受保护） |
+
+<details>
+<summary><b>📑 目录</b></summary>
+
+- [核心优势](#核心优势)
+- [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
+- [一键部署](#一键部署)
+- [使用方法](#使用方法)
+- [功能](#功能)
+- [原理](#原理)
+- [兼容性策略](#兼容性策略)
+- [项目结构](#项目结构)
+- [HTTP 接口](#http-接口)
+- [安全说明](#安全说明)
+- [已知限制](#已知限制)
+- [帮助 / Help](#帮助--help)
+- [生态与收录](#生态与收录)
+- [参与贡献](#参与贡献)
+- [许可证](#许可证)
+</details>
+
+---
+
+## 使用方法
+
+1. 重启 DSH → 打开 Web GUI → **设置 → 插件 → 插件管理**。
+2. **已安装列表**：一键开关（HMR 约 1 秒生效）、按名称/id 搜索、展开详情（版本、仓库、README 摘要）。
+3. **插件市场**：GitHub 源空查询直接打开静态索引（秒开）；输入关键词实时搜索。顶部登录标切换
+   搜索源（GitHub / Gitee / 自定义）；「⊞」多源合并；「★」只看可 `dsh plugin add` 直装。
+4. **技能 tab**：搜索框旁切换「插件 / 技能」，浏览并一键安装技能（克隆到 `~/.dsh/skills/<名称>/`）。
+5. **安装**：点「添加到本地」→ 后台安装链自动执行（可放心离开页面）；已安装条目自动出现
+   「检测更新」/「更新 → vX」。
+
+---
+
+## 功能
+
+### 已安装插件（一键开关 + 详情）
+
+- **默认只显示第三方插件**（后装/非 dsh 自带），带「第三方」标签与删除入口；点「全部」切换查看完整列表（1.5s 亮框反馈）；
+- 列出全部插件条目（名称、加载状态、启用状态）；支持按名称/id 搜索；
+- 点「停用」= 在用户补丁层写入 `- id: X` + `disabled: true`，HMR 立即生效；
+- 点「启用」= 移除该停用条目；bundle 层本就停用的行用 `disabled: false` 覆盖；
+- 打标「补丁停用 / 补丁强制启用」区分用户补丁状态；
+- **基础设施保护**：host 传输/热加载/存储/设置链上的插件（timer、hmr、webserver 等
+  70+ 行）标记「受保护」，禁止开关——误停用会破坏热加载本身；
+- **详情面板**：每个插件可点「详情」，展开简介、版本、仓库/主页链接与 README 摘要；
+- **版本检测**：「检测更新」走 curl 读 npm `dist-tags.latest`（node 网络黑洞时也可用），
+  并提示需要同步的子包版本（depsOutdated），避免半更新混搭导致启动冲突。
+
+### 框架一键升级（deepseek-harness 卡片）
+
+- **deepseek-harness 卡片**在检测到框架新版本时显示「框架升级 → vX」（稳定版 latest 优先；
+  latest 与当前相同时取 next 预发布渠道）；点击一键完成：备份配置与框架本体（回滚点）→
+  **在线安装**（服务保持运行、页面不断开）→ 版本校验 → **自动重启生效**；
+- **实时进度**：升级时弹出 `DSH-Upgrade` 窗口，实时显示 pnpm 下载进度；面板内进度卡片
+  同步显示等待时长；
+- **升级保护**：失败**自动回滚**（robocopy，升级前校验回滚点有效）、版本校验防假成功、
+  15 分钟硬超时、卡死检测（debug 日志无更新自动切换 registry）、全局异常兜底、
+  15 分钟残留状态清理——框架绝不处于损坏状态；
+- **pnpm 通道**：npm-cli.js 在 schtasks 任务环境启动即卡死（debug 日志 0 字节、网络请求
+  都发不出）；升级改用 `corepack pnpm`（实测 0.4s 秒启动、11.5s 装完 rc.8）+ **国内源
+  npmmirror**，并带 `dangerouslyAllowAllBuilds` 让 node-pty/koffi 等原生模块正常编译；
+- **运行时解析 bin.js**：pnpm 布局下 `@deepseek-ai/dsh` 是 Junction——拉起服务在运行时
+  解析（跟随 Junction 到当前版本），而非使用脚本生成时固化的路径；
+- **卡片关闭语义**：终态（成功/失败）点叉号永久关闭（持久化）；进行中点叉号仅本次会话
+  隐藏，刷新后恢复显示。
+
+### 插件市场（多搜索源）
+
+- **搜索源切换**：点击顶部登录态标识弹出菜单，在 **GitHub / Gitee / 自定义源** 间切换（选择持久化）；
+  市场标题、加载提示、搜索框占位符、说明行全部随源切换；
+- **GitHub 源**：默认搜索 `dsh-plugin`，浏览器直连（失败自动回退服务端通道）；
+- **Gitee 源**：Gitee 官方搜索 API 已停用，采用**仓库直装模式**——输入 `owner/repo`
+  （支持中文路径与完整 URL）精确查找仓库并安装；
+- **自定义搜索源**：软件源管理中添加（URL 模板含 `{q}`/`{page}` 占位符），支持
+  **请求头认证**（如 `Authorization: Bearer ...`）与**本机/私网 http 地址**；
+- **多源汇总**：搜索框旁「⊞」开启——GitHub + 全部自定义源并行检索，结果合并并标注来源；
+- **★ 官方筛选**：只筛**可 `dsh plugin add` 直装**的插件——根包带 `dsh.bundle` 清单（官方）
+  或聚合仓库中**子包带 `dsh.bundle`**（子包可直装）；标记由服务端 curl 双通道 + 客户端兜底补全，
+  搜索结果与筛选即时可用；
+- **类型徽标**：官方 / 聚合 / 技能（仓库含 SKILL.md）自动识别；
+- 「添加到本地」= 按当前源安装（registry 失败自动回退 git 通道）+ 写入启用条目，HMR 生效。
+
+### 静态索引市场（插件 / 技能双 tab）
+
+> **混合架构**：浏览走静态索引（秒开、零 API 调用），搜索走实时通道（GitHub 搜索 API / 多源并行）——
+> 两者互补：新仓库即使还没进索引，也能被实时搜索找到。
+
+- GitHub 源空查询展示**静态索引**（`marketplace/index.json`，jsDelivr CDN + 宿主 10 分钟缓存）：
+  按 star 排序 500+ 插件，秒开、**零 GitHub API 调用**；
+- 搜索框旁**「插件 / 技能」tab**：技能 tab 列出自动收录的 `agent-skills` ∪ `claude-skills` ∪
+  `dsh-skill` 仓库（最多 300）；
+- **自动版本比对**：市场中已安装的条目后台自动查 npm `dist-tags.latest`，卡片变「更新 → vX」；
+- **技能安装**：技能条目一键安装 = git clone → 复制 SKILL.md 及同目录资源到
+  `~/.dsh/skills/<名称>/`（frontmatter 的 name 优先于仓库名；SKILL.md 位于仓库根或第一层
+  子目录均可识别）；已装技能显示灰色「已装」徽标。
+
+### 软件源管理
+
+市场标题行右侧悬浮「软件源」按钮（半透明、颜色加深），弹出管理模态框：
+
+![软件源管理](https://github.com/user-attachments/assets/ef712900-65ae-4f6f-9584-bacdd8d34ea1)
+
+- **安装源（registry）**：添加 / 行内编辑 / 设为主源 / 恢复默认；支持私有源与内网地址；
+  **删除已保护**（插件安装依赖的 npm 源，避免误删）；
+- **搜索源**：内置 GitHub、Gitee + 自定义搜索源（增删、🔒 显示请求头数量）；
+- **Gitee 登录（可选）**：直装模式无需登录；登录仅提高接口限额——创建第三方应用
+  （gitee.com → 数据管理 → 第三方应用，权限勾选 user_info、projects）后填入
+  client_id / client_secret → 保存 → 授权登录。
+
+---
+
+## 文档
+
+- [AI 赋能与服务器组件控制](docs/ai-empower.zh.md)
+- [框架升级适配门与升级安全](docs/upgrade-safety-adapt-gate.zh.md)
+- [原理](docs/how-it-works.zh.md) · [兼容性策略](docs/compatibility.zh.md) · [项目结构](docs/project-layout.zh.md)
+- [HTTP 接口](docs/http-endpoints.zh.md) · [AI 兜底安装与授权弹窗](docs/ai-fallback.zh.md)
+- [安全说明与免责声明](docs/security-disclaimer.zh.md)
+
+---
+
+## 已知限制
+
+- 宿主代码变更需要**重启服务**（面板的重启按钮自带守护、安全）；客户端变更只需刷新页面；
+- 实时 GitHub 搜索依赖 GitHub 可达性（浏览器直连 + 服务端兜底；网络黑洞期请稍后重试）；
+- 版本检测只对已发布到 npm 的包生效；技能类仓库没有版本概念；
+- 静态索引有上限（每次构建 500 插件 / 300 技能）；新仓库靠 star 爬升或等下一轮 6 小时 CI 进入索引；
+- 技能由 `dsh-skill-filesystem` 扫描发现——若当前 profile 未启用该插件，装好的技能会休眠，启用并重启后生效。
+
+---
+
+## 帮助 / Help
+
+遇到问题先看这里；仍有疑问请到 [议题](https://github.com/Noob-stupid/dsh-plugin-hub/issues) 提问。
+
+- **面板没出现**：重启 dsh 服务 → 刷新页面 → 设置 → 插件 → 插件管理。
+- **点开关没反应**：基础设施行带"受保护"标签（禁止开关，这是保护机制）；普通插件开关经
+  HMR 生效，约 1-3 秒，可点刷新查看。
+- **顶部出现兼容性警告**：官方发布了破坏性更新，请到本仓库获取适配版本（见兼容性策略）。
+- **市场搜索没结果/报错**：GitHub 源走浏览器直连（与浏览器可用性一致），失败自动回退
+  服务端通道；Gitee 源为仓库直装模式（输入 `owner/repo`）；自定义源检查地址与请求头配置；
+  网络黑洞期请稍后重试。
+- **★ 筛选为空**：★ 只筛可 `dsh plugin add` 直装（官方 + 子包带 bundle 的聚合）；
+  标记 1-3 秒后台补全后自动出现，不会误报"没有"。
+- **安装失败**：确认仓库有 package.json 且包名已发布到 npm；npm 装不了的会回退
+  `github:owner/repo` 安装（需要 git）；可在软件源管理中换主源（如 npmmirror 网络波动时）。
+- **装好的技能 DSH 不识别**：在 profile 的 `cordis.yml` 启用 `@deepseek-ai/dsh-skill-filesystem`
+  并重启；技能位于 `~/.dsh/skills/<名称>/`。
+
+---
+
+## 生态与收录
+
+- 已被 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)（社区主精选列表）与 [DSH Directory](https://dsh.directory) 收录；
+- 本中心的自动收录索引（500+ 插件 / 300 技能，CI 每 6 小时刷新）会收录**任何**打了 `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` 标签的仓库——作者打上标签即可自动出现在市场，无需申请；
+- 如果你在开发 DSH 插件，本面板就是你的分发渠道：所有使用本面板的用户都能一键安装你的插件。
+
+## 支持
+
+如果这个面板帮你省了时间、让 DSH 更好用：
+
+- ⭐ **给本仓库点个 Star**——直接帮助更多 DSH 用户发现它；
+- 分享给身边的 DSH 用户或社区；
+- 提交你自己的插件（打上 `dsh-plugin` 标签）一起壮大生态；
+- 发现 bug 或有新需求？[开一个 Issue](https://github.com/Noob-stupid/dsh-plugin-hub/issues)。
+
+---
+
+## 参与贡献
+
+欢迎各种形式的贡献——Issue、PR、文档、翻译：
+
+- **贡献指南**：[CONTRIBUTING.md](CONTRIBUTING.md)
+- **行为准则**：[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- **安全政策**：[SECURITY.md](SECURITY.md)（漏洞私下报告）
+- **Issue 模板**：从 [新建 Issue](https://github.com/Noob-stupid/dsh-plugin-hub/issues/new/choose) 页面选择 Bug / 功能建议
+
+---
+
+## 更新日志
+
+版本记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+---
+
+## License
+
+MIT
+
+---
+
+---
+
+## 预览版（实验性 · 请勿用于生产）
+
+分层重构预览线在**独立仓库**：[**`Noob-stupid/dsh-plugin-hub-refactor`**](https://github.com/Noob-stupid/dsh-plugin-hub-refactor)
+
+- **它是什么**：把单体 `lib/index.js`（7637 行）拆成分层结构 —— `lib/index.js` **142 行** + `lib/server/**` **36 个模块**，**功能与 `0.3.48` 等价**，只为可维护性；
+- **已验证**：18 套测试全绿 · 8 条架构守卫断言 · 与稳定版逐条对打 **47 条路由，`status` + 响应字段 47/47 一致**；
+- **尚未实测**：真框架升级 / 真回滚、重启守护链路、真装真卸、组件进程启停、AI 真跑、Gitee OAuth 回调（长尾风险主观估计 **10%~25%**）；
+- **日常使用请继续用**：npm `@noob-stupid/dsh-plugin-console@0.3.48`，或本仓库 `main`。
+- 请多反馈问题

package/lib/index.js

@@ -594,7 +594,7 @@ async function removeBundleFromManifest(profileDir, bundlePkg) {
 /** 用 corepack pnpm 移除包（与安装同一管理器与凭据抑制环境）。
  * 注意：pnpm remove 不支持 --registry 选项，去掉避免静默失败。 */
 async function pnpmRemove(profileDir, packageName) {
-  const args = ['pnpm', 'remove', packageName]
+  const args = ['remove', packageName]
   const opts = {
     cwd: profileDir,
     timeout: 120000,
@@ -602,17 +602,8 @@ async function pnpmRemove(profileDir, packageName) {
     maxBuffer: 4 * 1024 * 1024,
     env: { ...process.env, COREPACK_NPM_REGISTRY: 'https://registry.npmmirror.com', GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' },
   }
-  if (process.platform === 'win32') {
-    const corepackJs = join(dirname(process.execPath), 'node_modules', 'corepack', 'dist', 'corepack.js')
-    if (existsSync(corepackJs)) {
-      await execFileAsync(process.execPath, [corepackJs, ...args], opts)
-      return
-    }
-    const cmd = `${JSON.stringify('corepack')} ${args.map((arg) => JSON.stringify(arg)).join(' ')}`
-    await execFileAsync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', cmd], opts)
-    return
-  }
-  await execFileAsync('corepack', args, opts)
+  // 跨平台定位 corepack/pnpm（Linux 的 corepack 不在 <node bin>/node_modules 下，2026-09-20 事故）
+  await runPnpmWithFallback(args, { execOpts: opts })
 }
 
 /** 清理陈旧包目录与 pnpm _tmp_ 残留（Windows 原子替换 EPERM 的根因），返回清理数量。 */
@@ -1705,11 +1696,12 @@ const API_MIRROR_PREFIXES = [
   'https://ghfast.top/https://api.github.com',
 ]
 
-/** raw.githubusercontent.com 的镜像竞速前缀（与浏览器端四通道一致）。 */
+/** raw.githubusercontent.com 的镜像竞速前缀（与浏览器端四通道一致）。
+ * 2026-09-19 移除 mirror.ghproxy.com：该域名早已失效（实测连接超时；失效域名被停放页接管时
+ * 会回 2xx HTML —— 正是"普通插件被误判成 submodule 套装"的假阳性来源之一）。 */
 const RAW_MIRROR_PREFIXES = [
   'https://ghproxy.net/https://raw.githubusercontent.com',
   'https://ghfast.top/https://raw.githubusercontent.com',
-  'https://mirror.ghproxy.com/https://raw.githubusercontent.com',
 ]
 
 /** 并行竞速：任一分支拿到 2xx 即胜出；非 2xx 与错误都视为失败，全部失败则拒绝。 */
@@ -1868,9 +1860,12 @@ async function githubText(url, signal, token = null) {
 }
 
 /** 用 curl 子进程请求 JSON（绕过本机中间设备对 node:https TLS 指纹的拦截；curl 走系统网络栈）。 */
-async function curlJson(url, timeout = 15000, headers = {}) {
+async function curlJson(url, timeout = 15000, headers = {}, { ipv4 = false } = {}) {
   const bin = process.platform === 'win32' ? 'curl.exe' : 'curl'
   const args = ['-s', '-m', String(Math.max(5, Math.ceil(timeout / 1000))), '-H', 'accept: application/json', '-w', '\n__HTTP__%{http_code}']
+  // ipv4：只给 GitHub 域名用——「解析出 IPv6 但没有 IPv6 路由」的环境里 curl 默认要先空等 ~5.2s 才回退
+  // IPv4（2026-09-20 另一位用户实测：默认 5473ms vs `-4` 的 461ms）；双栈正常的环境无副作用。
+  if (ipv4) args.push('-4')
   for (const [key, value] of Object.entries(headers)) args.push('-H', `${key}: ${value}`)
   args.push(url)
   const { stdout } = await execFileAsync(bin, args, { timeout: timeout + 3000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 })
@@ -1881,12 +1876,17 @@ async function curlJson(url, timeout = 15000, headers = {}) {
   return JSON.parse(body)
 }
 
-/** 用 curl 拉取文本（raw 文件用：本机 curl 直连 raw.githubusercontent.com 秒回，绕开 node:https 黑洞）。 */
-async function curlText(url, timeout = 10000) {
+/** 用 curl 拉取文本（raw 文件用：本机 curl 直连 raw.githubusercontent.com 秒回，绕开 node:https 黑洞）。
+ * 导出供 test-suite-detect.mjs 断言传输层口径（200 空 body → 空串，404 → 抛 HTTP 404）。 */
+export async function curlText(url, timeout = 10000, { ipv4 = false } = {}) {
   const bin = process.platform === 'win32' ? 'curl.exe' : 'curl'
+  const args = ['-s', '-m', String(Math.max(3, Math.ceil(timeout / 1000))), '-H', 'accept: text/plain', '-w', '\n__HTTP__%{http_code}']
+  // 见 curlJson 注释：GitHub 域名走 IPv4 快通道（IPv6 无路由的环境下默认要白等 ~5.2s）
+  if (ipv4) args.push('-4')
+  args.push(url)
   const { stdout } = await execFileAsync(
     bin,
-    ['-s', '-m', String(Math.max(3, Math.ceil(timeout / 1000))), '-H', 'accept: text/plain', '-w', '\n__HTTP__%{http_code}', url],
+    args,
     { timeout: timeout + 3000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
   )
   const m = String(stdout).match(/\n__HTTP__(\d+)\s*$/u)
@@ -2049,7 +2049,9 @@ async function enrichItemOne(item) {
       detectSkillRepo(item.fullName, branch),
       rawTextWithFallback(item.fullName, branch, '.gitmodules'),
     ])
-    if (suiteResult.status === 'fulfilled' && suiteResult.value !== null) {
+    // 套装判定必须过内容校验：代理/CDN 对不存在的 .gitmodules 也可能回 2xx 空 body，
+    // 只判"探测非 null"会把普通插件标成套装置仓库（2026-09-19 事故）。
+    if (suiteResult.status === 'fulfilled' && looksLikeGitmodules(suiteResult.value)) {
       hasSuite = true
     }
     if (pkgResult.status === 'fulfilled') {
@@ -2149,11 +2151,53 @@ function githubRepoInfo(repo) {
   return `${match[1]}/${match[2]}`
 }
 
+/** 「真的读到了文件内容」判定：null / 空串 / 纯空白都不算。导出供 test-suite-detect.mjs 断言。
+ * 真实事故（2026-09-19，用户反馈装 dsh-whale-widget 报「未找到 .gitmodules」）：
+ * 本机加速器/代理（Watt Toolkit 之类，劫持 raw.githubusercontent.com 到 127.0.0.1）
+ * 会对**不存在的文件**回 2xx + 空 body；旧代码只判 `body === null`，
+ * 于是空串被当成"文件存在" → 普通插件被判定成 submodule 套装置仓库 → 安装必然失败。 */
+export function readBodyOrNull(body) {
+  return typeof body === 'string' && body.trim() !== '' ? body : null
+}
+
+/** .gitmodules 内容校验：必须是真 gitmodules（含 [submodule "x"] 段）才算套装仓库。导出供测试。
+ * 只判"探测非 null"会把代理/CDN 的垃圾响应也算成套装；判定权交给内容，不交给状态码。 */
+export function looksLikeGitmodules(text) {
+  return typeof text === 'string' && /^\s*\[submodule\s+"/mu.test(text)
+}
+
+/** raw 抓取外层预算（毫秒）。事件（2026-09-20，另一位用户：Android + proot Ubuntu 容器，域名解析出
+ * IPv6 但容器无 IPv6 路由）：4 条通道最快也要 5.4s（curl 直连被 -m 6 掐死、node:https 5435ms、
+ * jsDelivr 5564ms），旧的 5000ms 预算**必然先超时** → 抓取失败被当成"文件不存在"，
+ * 报成「仓库没有 package.json」。放宽到 10s：真 404 仍是毫秒级返回，只有全网慢时才多等。 */
+export const FETCH_BUDGET_MS = 10000
+/** 仓库元数据（默认分支）探测预算：旧值 3s 在同一环境下同样必输 → branch 恒为 'main'，
+ * 默认分支为 dev 的仓库会取错分支。 */
+export const META_BUDGET_MS = 8000
+export const FETCH_OK = 'ok'
+export const FETCH_NOT_FOUND = 'not-found'
+export const FETCH_UNREACHABLE = 'unreachable'
+
+/** 竞速组合（纯逻辑，导出供单测）：通道结果 + 预算 → { state, body }。
+ * · anyPromise 以 null 成功 = 某通道确定性 404 → not-found
+ * · anyPromise 以字符串成功 = 读到内容 → ok
+ * · anyPromise 全部失败（AggregateError）或超出预算 → unreachable（**不再与 404 混为一谈**） */
+export function raceFetchOutcome(anyPromise, budgetMs) {
+  const settled = Promise.resolve(anyPromise)
+    .then((body) => (body === null ? { state: FETCH_NOT_FOUND, body: null } : { state: FETCH_OK, body }))
+    .catch(() => ({ state: FETCH_UNREACHABLE, body: null }))
+  return Promise.race([
+    settled,
+    new Promise((resolve) => setTimeout(() => resolve({ state: FETCH_UNREACHABLE, body: null }), budgetMs)),
+  ])
+}
+
 /** raw 文件读取：https 主通道（含镜像）、gh CLI、curl 直连、curl jsDelivr CDN **四通道并行竞速**。
  * 黑洞期 https/ghproxy 全挂、gh 可能不在服务进程 PATH——jsDelivr CDN 走系统网络且国内可达，是最后兜底。
  * 关键语义：**404 是确定性结果**（文件不存在，探测 .gitmodules/SKILL.md 等时的正常答案），
- * 必须立即返回 null，不能等其它分支（黑洞期 https 通道 20s+ 才失败会拖死整个请求）。 */
-async function rawTextWithFallback(repo, branch, path) {
+ * 必须立即返回 null，不能等其它分支（黑洞期 https 通道 20s+ 才失败会拖死整个请求）。
+ * 返回值区分「确定性 404」与「超时/通道全灭」——二者都以"没内容"结束，但用户文案必须不同。 */
+async function rawTextFetch(repo, branch, path, budgetMs = FETCH_BUDGET_MS) {
   const url = `${GITHUB_RAW}/${repo}/${encodeURIComponent(branch)}/${path}`
   // 404/4xx：确定性"不存在"，立即以 null 胜出（不等慢分支）
   const notFound = (promise) => promise
@@ -2161,48 +2205,60 @@ async function rawTextWithFallback(repo, branch, path) {
       if (error instanceof Error && /HTTP 404|HTTP 400|Not Found|not found|非 2xx|HTTP 非 2xx/u.test(error.message)) return null
       throw error
     })
-  const https = notFound(githubText(url)
-    .then((body) => {
-      if (body === null) throw new Error('HTTP 非 2xx')
-      return body
-    }))
+  // 各通道统一口径：状态 2xx **且** body 非空白，才算读到文件（否则抛"非 2xx" → 归一为 null）
+  const real = (promise) => promise.then((body) => {
+    const text = readBodyOrNull(body)
+    if (text === null) throw new Error('HTTP 非 2xx')
+    return text
+  })
+  const https = notFound(real(githubText(url)))
   const gh = notFound(githubViaGh(`repos/${repo}/contents/${path}?ref=${encodeURIComponent(branch)}`)
     .then((data) => {
       if (data && typeof data.content === 'string') return Buffer.from(data.content, 'base64').toString('utf8')
       throw new Error('contents 无内容')
-    }))
-  const curl = notFound(curlText(url, 6000)
-    .then((body) => {
-      if (body === null) throw new Error('HTTP 非 2xx')
-      return body
-    }))
-  const cdn = notFound(curlText(`https://cdn.jsdelivr.net/gh/${repo}@${encodeURIComponent(branch)}/${path}`, 6000)
-    .then((body) => {
-      if (body === null) throw new Error('HTTP 非 2xx')
+    })
+    .then((text) => {
+      const body = readBodyOrNull(text)
+      if (body === null) throw new Error('contents 无内容')
       return body
     }))
-  try {
-    // 任一通道成功（含 404→null）立即返回；整体 5s 封顶（jsDelivr 正常 0.7s，
-    // 黑洞期快速失败优于等 12s），超时视为不可达（null）。
-    return await Promise.race([
-      Promise.any([https, gh, curl, cdn]),
-      new Promise((resolve) => setTimeout(() => resolve(null), 5000)),
-    ])
-  } catch {
-    return null
-  }
+  const curl = notFound(real(curlText(url, 9000, { ipv4: true })))
+  const cdn = notFound(real(curlText(`https://cdn.jsdelivr.net/gh/${repo}@${encodeURIComponent(branch)}/${path}`, 9000, { ipv4: true })))
+  return await raceFetchOutcome(Promise.any([https, gh, curl, cdn]), budgetMs)
 }
 
-async function fetchRepoPackage(repo, branch) {
+/** 兼容入口：调用方只关心"有没有内容"（null = 没有）。需要区分超时/404 的场景用 rawTextFetch。 */
+async function rawTextWithFallback(repo, branch, path) {
+  const { state, body } = await rawTextFetch(repo, branch, path)
+  return state === FETCH_OK ? body : null
+}
+
+/** 包探测（带失败原因）：reason ∈ ok / not-found / unreachable / invalid。导出供测试。
+ * 事故（2026-09-20，另一位用户：Android + proot Ubuntu，容器无 IPv6 路由）：
+ * 抓取超时与真 404 都让上层拿到同一个 null，于是「网络太慢」被报成「仓库没有 package.json」。 */
+async function fetchRepoPackageEx(repo, branch) {
+  const { state, body } = await rawTextFetch(repo, branch, 'package.json')
+  if (state !== FETCH_OK) return { pkg: null, reason: state }
   try {
-    const body = await rawTextWithFallback(repo, branch, 'package.json')
-    if (body === null) return null
     const pkg = JSON.parse(body)
-    if (pkg == null || typeof pkg !== 'object' || typeof pkg.name !== 'string') return null
-    return pkg
-  } catch {
-    return null
+    if (pkg !== null && typeof pkg === 'object' && typeof pkg.name === 'string') return { pkg, reason: 'ok' }
+  } catch {}
+  return { pkg: null, reason: 'invalid' }
+}
+
+async function fetchRepoPackage(repo, branch) {
+  return (await fetchRepoPackageEx(repo, branch)).pkg
+}
+
+/** 探测失败时的用户可读文案：「抓取超时/不可达」与「真的没有」必须区分开。导出供测试。 */
+export function packageProbeErrorText(repo, branch, reason) {
+  if (reason === FETCH_UNREACHABLE) {
+    return `抓取超时/网络不可达：没能读到 ${repo}（${branch} 分支）的 package.json —— 通常是网络到 GitHub 太慢（例如解析出 IPv6 却无 IPv6 路由）。请重试；若持续失败，可先用「仓库落地」克隆到本地目录。`
+  }
+  if (reason === 'invalid') {
+    return `仓库 ${repo} 的 package.json 不是合法的包描述（缺少 name 字段），无法作为插件安装——可改用「仓库落地」克隆到本地目录。`
   }
+  return `仓库 ${repo} 没有 package.json（也不是技能仓库），无法作为插件安装——可改用「仓库落地」克隆到本地目录。`
 }
 
 /**
@@ -2211,7 +2267,7 @@ async function fetchRepoPackage(repo, branch) {
  * （曾导致入口链接丢失、DSH 启动崩溃）。registry 走国内镜像。
  */
 async function pnpmInstall(profileDir, spec, registry = 'https://registry.npmmirror.com', timeout = 90000, signal = null) {
-  const args = ['pnpm', 'add', spec, '--registry', registry]
+  const args = ['add', spec, '--registry', registry]
   const opts = {
     cwd: profileDir,
     timeout,
@@ -2225,19 +2281,9 @@ async function pnpmInstall(profileDir, spec, registry = 'https://registry.npmmir
       GCM_INTERACTIVE: 'never',
     },
   }
-  if (process.platform === 'win32') {
-    // .cmd 批处理不能直接 execFile（EINVAL）：优先 node 直跑 corepack.js
-    const corepackJs = join(dirname(process.execPath), 'node_modules', 'corepack', 'dist', 'corepack.js')
-    if (existsSync(corepackJs)) {
-      await execFileAsync(process.execPath, [corepackJs, ...args], opts)
-      return
-    }
-    // 兜底：经 cmd.exe 运行 corepack
-    const cmd = `${JSON.stringify('corepack')} ${args.map((arg) => JSON.stringify(arg)).join(' ')}`
-    await execFileAsync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', cmd], opts)
-    return
-  }
-  await execFileAsync('corepack', args, opts)
+  // 跨平台定位 corepack/pnpm（Windows 布局 / Linux npm 全局布局 / PATH 兜底）；
+  // 旧代码只认 Windows 布局，Linux 上会生成 MODULE_NOT_FOUND 的命令（2026-09-20 事故）
+  await runPnpmWithFallback(args, { execOpts: opts })
 }
 
 /**
@@ -2783,6 +2829,64 @@ function packageEntryExists(dir, pkg) {
   return candidates.some((c) => existsSync(join(dir, c)))
 }
 
+/** git 可执行名（跨平台）。事故（2026-09-20，另一位用户：Android + proot Ubuntu）：
+ * 「仓库落地」硬编码 `git.exe` → 非 Windows 环境 spawn git.exe ENOENT，克隆必然失败。导出供测试。 */
+export function gitBin() {
+  return process.platform === 'win32' ? 'git.exe' : 'git'
+}
+
+/** pnpm 执行方式定位（跨平台，纯函数便于单测 → 按优先级返回列表，逐个尝试）。导出供测试。
+ * 事故（2026-09-20，同一位用户，node v24 + Linux）：只按 Windows 布局找 corepack.js
+ * （`<node bin>/node_modules/corepack/dist/corepack.js`），而 Linux 的 npm 全局布局在
+ * `<prefix>/lib/node_modules/corepack/...` → AI 赋能的 install-npm 生成
+ * `node /usr/local/bin/node_modules/corepack/dist/corepack.js pnpm add …` → MODULE_NOT_FOUND。 */
+export function resolvePnpmRunners({ platform = process.platform, execPath = process.execPath, comspec = process.env.ComSpec ?? 'cmd.exe', exists = existsSync } = {}) {
+  const binDir = dirname(execPath)
+  const corepackCandidates = [
+    join(binDir, 'node_modules', 'corepack', 'dist', 'corepack.js'), // Windows 官方安装器 / nvm-windows
+    join(binDir, '..', 'lib', 'node_modules', 'corepack', 'dist', 'corepack.js'), // Linux/macOS npm 全局
+    join(binDir, '..', 'libexec', 'lib', 'node_modules', 'corepack', 'dist', 'corepack.js'), // brew / 自编译布局
+  ]
+  const runners = []
+  for (const js of corepackCandidates) {
+    if (exists(js)) {
+      runners.push({ kind: 'node-corepack', note: `node ${js} pnpm`, run: (args) => ({ bin: execPath, argv: [js, 'pnpm', ...args] }) })
+    }
+  }
+  if (platform === 'win32') {
+    // .cmd 批处理不能直接 execFile（EINVAL）→ 经 cmd.exe 调用（整条命令作为一个参数）
+    runners.push({
+      kind: 'cmd-corepack',
+      note: 'cmd /c corepack pnpm',
+      run: (args) => ({ bin: comspec, argv: ['/d', '/s', '/c', ['corepack', 'pnpm', ...args].map((a) => JSON.stringify(a)).join(' ')] }),
+    })
+  } else {
+    runners.push({ kind: 'corepack', note: 'corepack pnpm', run: (args) => ({ bin: 'corepack', argv: ['pnpm', ...args] }) })
+    runners.push({ kind: 'pnpm', note: 'pnpm', run: (args) => ({ bin: 'pnpm', argv: args }) })
+  }
+  return runners
+}
+
+/** 依次尝试各执行方式；只有"执行方式本身不可用"（ENOENT / MODULE_NOT_FOUND）才换下一个，
+ * 真正的安装失败（网络、依赖冲突等）立即抛出，并附上已尝试的清单便于排查。 */
+async function runPnpmWithFallback(args, { execOpts = {}, runners = resolvePnpmRunners() } = {}) {
+  let lastError = null
+  for (const runner of runners) {
+    const { bin, argv } = runner.run(args)
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await execFileAsync(bin, argv, execOpts)
+      return { runner }
+    } catch (error) {
+      lastError = error
+      const message = String(error?.message ?? '')
+      if (!/ENOENT|Cannot find module/u.test(message)) throw error
+    }
+  }
+  const tried = runners.map((r) => r.note).join(' → ')
+  throw new Error(`${lastError?.message ?? 'pnpm 执行失败'}（已尝试：${tried}）`)
+}
+
 /** git 非交互环境：禁止任何登录/凭据窗口弹出（私有仓库或不可达源直接失败，不做交互式重试）。 */
 function gitEnv() {
   return {
@@ -2865,6 +2969,24 @@ async function installBundleFromRelease(subRepo, pkgName, target) {
   }
 }
 
+/** 套装探测（唯一入口）：main → master，且**必须内容像 .gitmodules**（含 [submodule "x"] 段）才算套装。
+ * 判据是内容、不是"探测非 null"：2026-09-19 用户反馈装 dsh-whale-widget 被判成 submodule 套装置仓库、
+ * clone 后报「未找到 .gitmodules」——根因就是代理/CDN 对**不存在的文件**回 2xx（空 body 也算"读到"）。 */
+async function probeGitmodules(repo) {
+  const main = await rawTextWithFallback(repo, 'main', '.gitmodules')
+  if (looksLikeGitmodules(main)) return main
+  const master = await rawTextWithFallback(repo, 'master', '.gitmodules')
+  return looksLikeGitmodules(master) ? master : null
+}
+
+/** 安装类型决策（纯函数，导出供 test-suite-detect.mjs 断言）：`.gitmodules` 的**内容**说了算——
+ * 显式 suite 请求若探测内容不像 .gitmodules 也回落普通插件安装（前端标记可能来自 24h 缓存的误判，
+ * 不能当判据）；技能请求不受影响。 */
+export function resolveInstallKind(requestKind, probeText) {
+  if (requestKind === 'skill') return 'skill'
+  return looksLikeGitmodules(probeText) ? 'suite' : 'plugin'
+}
+
 /** 套装安装（submodule 聚合仓库）：照仓库 install.ps1/README 语义——
  * clone 套装 → 手动镜像拉取子模块 → 按类型装配（bundle 插件含 Release tgz 兜底 / 普通插件 / 技能 / agent 预设）。
  * 不执行第三方脚本本体（安全护栏：脚本型只读语义不运行）。 */
@@ -2876,7 +2998,12 @@ async function runSuiteInstallJob(job, ctx) {
     mkdirSync(tmpDir, { recursive: true })
     await gitCloneRepo(job.repo, tmpDir, job.source)
     const subs = readGitmodules(tmpDir)
-    if (subs.length === 0) throw new Error('未找到 .gitmodules（不是 submodule 套装仓库）')
+    if (subs.length === 0) {
+      // 探测与仓库实际内容不符（假阳性 / 仓库已重构）：**不报失败**，把决定权交回调用方
+      // 回落普通插件安装（npm → Release → git 规格），用户不该因为一次误判装不上插件。
+      job.stage = 'detecting'
+      return { notASuite: true }
+    }
     job.stage = 'detecting'
     const patchPath = findPatchPath(ctx)
     const profileDir = dirname(patchPath)
@@ -3185,7 +3312,9 @@ async function aiRepair(job, ctx, profileDir, candidates, lastError) {
     job.error = `本地 AI 修复通道没有可用的子代理提供方：${String(error)}；请手动执行：dsh plugin --profile web add <包名>`
     return
   }
-  const corepackJs = join(dirname(process.execPath), 'node_modules', 'corepack', 'dist', 'corepack.js')
+  // 跨平台提示：corepack 的位置随安装方式/系统而异（Windows 官方安装器在 <node bin>/node_modules，
+  // Linux 的 npm 全局在 <prefix>/lib/node_modules），所以给子代理的提示不再写死路径
+  const corepackRunner = resolvePnpmRunners()[0]
   const prompt = [
     '你是 DeepSeek Harness 的插件安装专家。用户通过插件管理面板安装插件失败，现在由你主动接管安装（不是被动"修复"，而是像人工一样把它装好）。',
     `目标仓库：${job.repo}`,
@@ -3194,7 +3323,7 @@ async function aiRepair(job, ctx, profileDir, candidates, lastError) {
     `此前确定性通道的错误：${lastError ?? '未知'}`,
     '接管步骤：',
     `1) 先弄清楚装什么：若根包是 private 的聚合仓库（monorepo），用 gh api repos/${job.repo}/git/trees/main?recursive=1 或读 packages 目录下的 package.json 找出子包名；优先选聚合包（名字含 all，如 dsh-web-ui-all，一个包装全部）；`,
-    `2) 用 corepack pnpm 安装（Windows 执行 node ${JSON.stringify(corepackJs)} pnpm add <包名> --registry https://registry.npmmirror.com，工作目录 ${profileDir}）；镜像 404 时改 --registry https://registry.npmjs.org；都不行再用 git 通道；`,
+    `2) 用 corepack/pnpm 安装（本机可用的执行方式：${corepackRunner?.note ?? 'corepack pnpm 或 pnpm'}，即在该方式后接 add <包名> --registry https://registry.npmmirror.com，工作目录 ${profileDir}；Windows 上是 node <corepack.js> pnpm，Linux 上通常是 corepack pnpm 或直接 pnpm）；镜像 404 时改 --registry https://registry.npmjs.org；都不行再用 git 通道；`,
     '3) **node 网络黑洞判定**：pnpm 长时间无下载进度（Progress 停在 downloaded 0）、或报 socket hang up / EPERM / TIMEOUT、或 node 脚本连 127.0.0.1 都超时，说明本机拦截 node 进程网络——此时 curl 与系统 git 通常仍可用，立即改用 curl 手动安装：先 `curl -s https://registry.npmmirror.com/<包名>` 取最新版本号，再 `curl -sL -o <临时目录>/pkg.tgz https://registry.npmmirror.com/<包名>/-/<包名>-<版本>.tgz`，解压 tar -xzf 后把 package 内容放入 profile/node_modules/<包名>（先备份旧目录）；包有 dependencies 时用同样方式逐个 curl 拉取补齐到 node_modules；零依赖包（如 dsh-skin）一条龙即可完成；',
     `4) 安装成功后按官方 dsh plugin add 规则落配置：包声明 dsh.bundle 时把包名追加进 profile 目录 package.json 的 dsh.profile.bundles 数组；普通插件在 cordis.patch.yml 追加 insert 行（id 由包名去 scope、非字母数字转连字符生成，name 填包名）；`,
     '5) 装完自查：确认包已出现在 node_modules、配置已写入；必要时用 gh api 核对仓库信息；',
@@ -3773,10 +3902,13 @@ async function runAiStep(job, step, ctx, profileDir, signal) {
       const pkg = String(step.package ?? '')
       if (!/^(@[A-Za-z0-9_\-\.]+\/)?[A-Za-z0-9_\-\.]+(@[A-Za-z0-9_\-\.]+)?$/u.test(pkg)) throw new Error(`包名不合法：${pkg}`)
       const dir = resolvePlaceholders(String(step.directory ?? profile), { profileDir: profile })
-      const corepackJs = join(dirname(process.execPath), 'node_modules', 'corepack', 'dist', 'corepack.js')
-      const params = [corepackJs, 'pnpm', 'add', pkg, '--dir', dir, '--registry', 'https://registry.npmmirror.com']
-      jobLog(job, `  运行: node ${params.join(' ')}`)
-      await execFileAsync(process.execPath, params, { timeout: 900000, windowsHide: true, maxBuffer: 4 * 1024 * 1024, signal })
+      // 跨平台：不再拼 `node <node bin>/node_modules/corepack/dist/corepack.js`（Linux 上必 MODULE_NOT_FOUND，
+      // 2026-09-20 另一位用户的 install-npm 失败现场就是这一行），改为按优先级尝试可用的执行方式
+      const args = ['add', pkg, '--dir', dir, '--registry', 'https://registry.npmmirror.com']
+      const { runner } = await runPnpmWithFallback(args, {
+        execOpts: { timeout: 900000, windowsHide: true, maxBuffer: 4 * 1024 * 1024, signal },
+      })
+      jobLog(job, `  运行: ${runner.note} ${args.join(' ')}`)
       return
     }
     case 'write-file': {
@@ -4499,25 +4631,30 @@ async function runInstallJob(job, ctx) {
     let candidates = [job.packageName].filter((name) => typeof name === 'string' && name !== '')
     let subpackageMode = false
     if (candidates.length === 0) {
-      // 套装兜底：submodule 聚合仓库（根 .gitmodules 存在）→ 自动转套装安装，
-      // 不依赖前端标记（搜索结果 enrich 是异步的、索引浏览条目无 enrich）
-      let suiteProbe = await rawTextWithFallback(job.repo, 'main', '.gitmodules')
-      if (suiteProbe === null) suiteProbe = await rawTextWithFallback(job.repo, 'master', '.gitmodules')
-      if (suiteProbe !== null) {
+      // 套装兜底：submodule 聚合仓库（根 .gitmodules 内容校验通过）→ 自动转套装安装，
+      // 不依赖前端标记（搜索结果 enrich 是异步的、索引浏览条目无 enrich）。
+      // 判据是**内容**（resolveInstallKind），不是"探测非 null"：后者会把代理/CDN 对不存在文件回的
+      // 2xx 空 body、垃圾页当成套装（2026-09-19 用户反馈的「未找到 .gitmodules」事故根因）。
+      if (resolveInstallKind(job.kind, await probeGitmodules(job.repo)) === 'suite') {
         job.kind = 'suite'
-        await runSuiteInstallJob(job, ctx)
-        return
-      }
-      // 兜底：宿主端自行拉取仓库元数据（githubJson 与 curl 竞速 + 3s 超时降级，黑洞期不卡 40s）
+        const suiteResult = await runSuiteInstallJob(job, ctx)
+        // clone 后才发现没有 .gitmodules（探测假阳性 / 仓库已重构）→ 回落普通安装，不给用户一个失败
+        if (suiteResult?.notASuite !== true) return
+        job.kind = 'plugin'
+        job.suiteNote = '探测到的 .gitmodules 与仓库实际内容不符（不是 submodule 套装仓库），已自动回落普通插件安装'
+      }
+      // 兜底：宿主端自行拉取仓库元数据（githubJson 与 curl 竞速 + 8s 超时降级，黑洞期不卡 40s）。
+      // 8s 而非旧值 3s：IPv6 无路由的环境里单条通道就要 5.4s，3s 预算必输 → branch 恒为 main，
+      // 默认分支为 dev 的仓库会取错分支（2026-09-20 另一位用户实测）。
       const meta = await Promise.race([
         Promise.any([
           githubJson(`${GITHUB_API}/repos/${job.repo}`),
-          curlJson(`${GITHUB_API}/repos/${job.repo}`, 12000),
+          curlJson(`${GITHUB_API}/repos/${job.repo}`, 12000, {}, { ipv4: true }),
         ]),
-        new Promise((resolve) => setTimeout(() => resolve(null), 3000)),
+        new Promise((resolve) => setTimeout(() => resolve(null), META_BUDGET_MS)),
       ]).catch(() => null)
       const branch = meta?.default_branch ?? 'main'
-      const pkg = await fetchRepoPackage(job.repo, branch)
+      const { pkg, reason } = await fetchRepoPackageEx(job.repo, branch)
       if (pkg === null) {
         // 无 package.json：先探测是否技能仓库（含 SKILL.md）→ 自动转技能安装；
         // 否则标记 hint=repo-land，前端给出「仓库落地」一键入口（克隆到本地目录）。
@@ -4529,7 +4666,9 @@ async function runInstallJob(job, ctx) {
         }
         job.status = 'failed'
         job.hint = 'repo-land'
-        job.error = `仓库 ${job.repo} 没有 package.json（也不是技能仓库），无法作为插件安装——可改用「仓库落地」克隆到本地目录。`
+        // 文案区分「抓取超时/不可达」与「真的没有」——旧代码两者共用一个出口，报错永远说"文件不存在"
+        job.error = packageProbeErrorText(job.repo, branch, reason)
+        job.probeReason = reason
         return
       }
       if (pkg.private === true) {
@@ -5492,24 +5631,26 @@ async function handle(ctx, req, res) {
   if (pathname === `${ROUTE_PREFIX}/repo`) {
     const repo = githubRepoInfo(typeof body.repo === 'string' ? body.repo : '')
     const auth = readGithubAuth()
-    // meta 降级策略：githubJson（https+镜像+gh）与 curl 竞速，3 秒超时即降级——
+    // meta 降级策略：githubJson（https+镜像+gh）与 curl 竞速，8 秒超时即降级——
     // Promise.any 全失败时要等最慢分支（黑洞期 https 41.5s），加 race 超时避免拖累整体。
+    // 8s 而非旧值 3s：IPv6 无路由的环境里单条通道就要 5.4s（2026-09-20 实测），3s 必输 → branch 取错。
     let meta = null
     try {
       meta = await Promise.race([
         Promise.any([
           githubJson(`${GITHUB_API}/repos/${repo}`, req.signal, auth.token),
-          curlJson(`${GITHUB_API}/repos/${repo}`, 12000),
+          curlJson(`${GITHUB_API}/repos/${repo}`, 12000, {}, { ipv4: true }),
         ]),
-        new Promise((resolve) => setTimeout(() => resolve(null), 3000)),
+        new Promise((resolve) => setTimeout(() => resolve(null), META_BUDGET_MS)),
       ])
     } catch {}
     const branch = meta?.default_branch ?? 'main'
     const pkg = await fetchRepoPackage(repo, branch)
     const skill = await detectSkillRepo(repo, branch)
     const skillMeta = skill.hasSkill ? await fetchSkillMeta(repo, branch, skill.skillDir) : null
-    // 套装识别：根 .gitmodules 存在（submodule 聚合仓库）
-    const hasSuite = (await rawTextWithFallback(repo, branch, '.gitmodules')) !== null
+    // 套装识别：根 .gitmodules 存在**且内容真的是 gitmodules**（只判非 null 会被代理/CDN 对不存在
+    // 文件回的 2xx 空 body 骗到，把普通插件标成套装——2026-09-19 用户反馈事故）
+    const hasSuite = looksLikeGitmodules(await rawTextWithFallback(repo, branch, '.gitmodules'))
     // 官方安装方式（详情面板展示 + 一键复制，供用户手动安装）：
     // 套装 → 仓库 install.ps1/README 的官方步骤；普通/聚合 → dsh plugin add 官方命令
     let installCommand = null
@@ -7094,9 +7235,9 @@ async function handle(ctx, req, res) {
       sendError(res, 400, 'deepseek-harness 是 DSH 框架本体，不是插件——无需安装（升级请用官方 dsh 升级方式）')
       return
     }
-    const kind = body.kind === 'skill' ? 'skill' : body.kind === 'suite' ? 'suite' : 'plugin'
-    if ((kind === 'skill' || kind === 'suite') && repo === '') {
-      sendError(res, 400, `${kind === 'skill' ? '技能' : '套装'}安装必须提供仓库（owner/name）`)
+    const requestedKind = body.kind === 'skill' ? 'skill' : body.kind === 'suite' ? 'suite' : 'plugin'
+    if ((requestedKind === 'skill' || requestedKind === 'suite') && repo === '') {
+      sendError(res, 400, `${requestedKind === 'skill' ? '技能' : '套装'}安装必须提供仓库（owner/name）`)
       return
     }
     const source = body.source === 'gitee' ? body.source : 'github'
@@ -7113,6 +7254,14 @@ async function handle(ctx, req, res) {
       sendError(res, 409, '该插件正在安装/更新中，请等待当前任务完成后再试')
       return
     }
+    // 套装请求必须复检内容（2026-09-19 事故）：前端标记可能来自 24h enrich 缓存的误判，
+    // 探测内容不像 .gitmodules 就按普通插件安装——别把用户送进注定失败的套装通道。
+    let kind = requestedKind
+    let suiteNote = null
+    if (requestedKind === 'suite') {
+      kind = resolveInstallKind('suite', await probeGitmodules(repo))
+      if (kind !== 'suite') suiteNote = '探测未发现有效的 .gitmodules（不是 submodule 套装仓库），已按普通插件安装'
+    }
     const job = {
       id: `job-${installJobSeq += 1}`,
       repo,
@@ -7132,10 +7281,20 @@ async function handle(ctx, req, res) {
         update: body.update === true,
       kind,
     }
+    if (suiteNote !== null) job.suiteNote = suiteNote
     installJobs.set(job.id, job)
+    // 套装通道兜底：探测说有、clone 下来却没有 .gitmodules（假阳性 / 仓库已重构）时
+    // 回落普通插件安装，而不是给用户一个「未找到 .gitmodules」的失败。
+    const runSuiteThenFallback = async () => {
+      const result = await runSuiteInstallJob(job, ctx)
+      if (result?.notASuite !== true) return
+      job.kind = 'plugin'
+      job.suiteNote = '仓库实际内容与探测不符（没有 .gitmodules），已自动回落普通插件安装'
+      await runInstallJob(job, ctx)
+    }
     // 后台执行：请求立即返回，安装不受客户端断开/离开面板影响
-    void (kind === 'skill' ? runSkillInstallJob(job) : kind === 'suite' ? runSuiteInstallJob(job, ctx) : runInstallJob(job, ctx))
-    sendJson(res, 200, { ok: true, jobId: job.id, status: 'installing', kind })
+    void (kind === 'skill' ? runSkillInstallJob(job) : kind === 'suite' ? runSuiteThenFallback() : runInstallJob(job, ctx))
+    sendJson(res, 200, { ok: true, jobId: job.id, status: 'installing', kind, ...(suiteNote !== null ? { suiteNote } : {}) })
     return
   }
 
@@ -7383,7 +7542,7 @@ async function handle(ctx, req, res) {
       let usedUrl = ''
       for (const url of urls) {
         try {
-          await execFileAsync('git.exe', ['clone', '--depth', '1', url, target], { cwd: root, timeout: 600000, windowsHide: true, maxBuffer: 4 * 1024 * 1024, env: gitEnv() })
+          await execFileAsync(gitBin(), ['clone', '--depth', '1', url, target], { cwd: root, timeout: 600000, windowsHide: true, maxBuffer: 4 * 1024 * 1024, env: gitEnv() })
           cloned = true
           usedUrl = url
           break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.3.47",
+  "version": "0.3.48",
   "description": "DSH plugin management panel & marketplace: one-click enable/disable, multi-source market (GitHub/Gitee/custom), static-index market (500+ plugins / 300 skills), skills, suites, and one-click framework upgrade.",
   "repository": {
     "type": "git",