@noob-stupid/dsh-plugin-console 0.3.26 → 0.3.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +61 -351
  2. package/README.zh.md +57 -321
  3. package/lib/client.js +162 -8
  4. package/lib/index.js +348 -36
  5. package/package.json +1 -1
package/README.zh.md CHANGED
@@ -6,140 +6,21 @@
6
6
 
7
7
  # DSH 插件中心（dsh-plugin-hub）
8
8
 
9
- > ## 🎉 v0.3.25 正式发布 — 框架升级安全与插件适配门（2026-09-04）
10
- >
11
- > **升级安全三件套**：框架安装根识别（修复 `.pnpm` realpath 混版本根因）、升级前**全树 checkpoint**、
12
- > 拉起失败**自动全树回滚**；升级后框架卡片**一键回滚到上一版**。
13
- > **插件适配门**：升级后不兼容插件强制禁用（启用锁定），「检测更新 → 更新并适配」→
14
- > 自动校验声明/依赖，通过即解锁；AI 赋能规划时自动预检框架适配并给出说明。
15
- >
16
- > **安装：**
17
- > ```bash
18
- > npm i -g @noob-stupid/dsh-plugin-console
19
- > # 或在 DSH 中更新：dsh plugin --profile web add @noob-stupid/dsh-plugin-console
20
- > ```
21
- > **体验入口：** 插件控制台 → 右上角 **AI 赋能** 按钮 → 输入如 `OpenViking` → 确认计划 → 自动部署。
22
- >
23
- > 反馈：[GitHub Issues](https://github.com/Noob-stupid/dsh-plugin-hub/issues)。
24
-
25
-
26
- [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
27
- [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
28
- [![GitHub stars](https://img.shields.io/github/stars/Noob-stupid/dsh-plugin-hub?style=flat-square&logo=github)](https://github.com/Noob-stupid/dsh-plugin-hub/stargazers)
29
- [![License](https://img.shields.io/github/license/Noob-stupid/dsh-plugin-hub?style=flat-square)](LICENSE)
30
- [![Last commit](https://img.shields.io/github/last-commit/Noob-stupid/dsh-plugin-hub?style=flat-square)](https://github.com/Noob-stupid/dsh-plugin-hub/commits/main)
31
- [![Registry CI](https://img.shields.io/github/actions/workflow/status/Noob-stupid/dsh-plugin-hub/registry.yml?label=registry%20CI&style=flat-square)](https://github.com/Noob-stupid/dsh-plugin-hub/actions/workflows/registry.yml)
32
- [![topic: dsh-plugin](https://img.shields.io/badge/topic-dsh_plugin-4D6BFE?style=flat-square)](https://github.com/topics/dsh-plugin)
33
- [![npm version](https://img.shields.io/npm/v/@noob-stupid/dsh-plugin-console?style=flat-square)](https://www.npmjs.com/package/@noob-stupid/dsh-plugin-console)
34
- [![npm downloads](https://img.shields.io/npm/dm/@noob-stupid/dsh-plugin-console?style=flat-square)](https://www.npmjs.com/package/@noob-stupid/dsh-plugin-console)
35
- [![GitHub Release](https://img.shields.io/github/v/release/Noob-stupid/dsh-plugin-hub?style=flat-square)](https://github.com/Noob-stupid/dsh-plugin-hub/releases)[![dsh.so security](https://www.dsh.so/badge/dsh-plugin-hub.svg)](https://www.dsh.so/artifact/dsh-plugin-hub)
36
- [![dsh.so install](https://www.dsh.so/badge/install/dsh-plugin-hub.svg)](https://www.dsh.so/artifact/dsh-plugin-hub)
37
-
38
- 给 DeepSeek Harness（DSH）Web 界面加上**插件管理面板**：一键启用/停用已安装插件，
39
- 在**多个搜索源**上浏览 dsh-plugin 插件项目（GitHub / Gitee / 自定义源），一键添加并启用——
40
- 并带一份 **CI 每 6 小时自动收录的静态插件/技能索引**。
41
-
42
- > ## 🎯 框架一键升级（v0.3.13 亮点）
43
- >
44
- > 打开「插件管理」面板 → **插件市场** → `deepseek-ai/deepseek-harness` 卡片 →
45
- > 点 **「框架升级 → vX」**，一步完成：
46
- > **备份配置与框架本体（回滚点）→ 在线安装（服务不中断）→ 版本校验 → 失败自动回滚 → 自动重启生效**。
47
- >
48
- > 升级后**自动重链框架配套包**（避免 pnpm 顶层链接滞后导致的混版本问题，如模型插件旧版缺失 vision 模型）。
49
- > 已实测：0.1.0-rc.8 → **0.1.1-rc.2** 全程自动、失败可回滚、升级后可正常使用。
50
-
51
- <!-- TOC -->
52
- - [核心优势](#核心优势)
53
- - [一键部署](#一键部署)
54
- - [使用方法](#使用方法)
55
- - [功能](#功能)
56
- - [原理](#原理)
57
- - [兼容性策略](#兼容性策略)
58
- - [项目结构](#项目结构)
59
- - [HTTP 接口](#http-接口)
60
- - [AI 兜底安装与授权弹窗](#ai-兜底安装与授权弹窗)
61
- - [框架层补丁（cordis.patch.yml 解析容错）](#框架层补丁cordispatchyml-解析容错)
62
- - [安全说明](#安全说明)
63
- - [免责声明](#免责声明)
64
- - [已知限制](#已知限制)
65
- - [帮助 / Help](#帮助--help)
66
- - [生态与收录](#生态与收录)
67
- - [支持](#支持)
68
- - [更新日志](#更新日志)
69
- - [License](#license)
70
- <!-- /TOC -->
71
-
72
- ---
73
-
74
- ## 核心优势
75
-
76
- | | 优势 | 说明 |
77
- |---|---|---|
78
- | 🤖 | **AI 赋能（v0.3.24）** | 输入 npm 包名 / GitHub 仓库，本地 AI 读文档生成**部署计划**（安装/写配置/启动服务/健康检查），你确认后安全执行；服务器类组件自动生成控制卡片 |
79
- | 🛡️ | **框架升级适配门与安全（v0.3.25）** | 升级后不兼容插件强制禁用（适配门锁定，「检测更新 → 更新并适配 → 自动校验解锁」）；升级前全树 checkpoint、拉起失败自动全树回滚、框架卡片一键回滚到上一版 |
80
- | 🚀 | **服务器组件卡片** | 左侧浮卡与主面板顶边对齐：启动 / 停止 / 状态 / 【打开】直达 Web UI，多服务器下拉、可折叠（状态记忆） |
81
- | 🧩 | **插件 + 技能双市场** | 自动收录 `dsh-plugin` topic 仓库（按 star **500+**），另有**技能 tab**（`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`，最多 300）——浏览、搜索、一键安装，零 GitHub API 调用；插件自带技能（如 openviking-memory）只读展示 |
82
- | 🤖 | **自动收录 CI** | GitHub Actions 每 6 小时自动重跑 `build-index`（也支持手动触发）；作者只需给自己的仓库打 `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` 标签，**无需申请、无需审核** |
83
- | ⚡ | **秒开、零限流** | 索引以静态 `marketplace/index.json` 提交仓库，经 jsDelivr CDN 分发（宿主 10 分钟缓存）——终端用户**零 GitHub API 调用、零限流** |
84
- | 🔄 | **版本检测与一键更新** | semver 比较 + beta/next 识别（本地已是测试版最新时不误报）；已安装条目自动比对 npm `dist-tags`，聚合包子包版本不配套时给出 depsOutdated 提示 |
85
- | 🔀 | **多源检索** | GitHub / Gitee（仓库直装模式）/ 自定义搜索源（URL 模板 + 请求头认证 + 私网 http）；「⊞」并行合并 GitHub + 全部自定义源 |
86
- | 🔒 | **安全默认** | 全部路由仅环回；AI 兜底置于明确费用授权弹窗之后；AI 赋能执行器命令/路径白名单；基础设施行禁止开关（受保护） |
87
-
88
- <details>
89
- <summary><b>📑 目录</b></summary>
90
-
91
- - [核心优势](#核心优势)
92
- - [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
93
- - [一键部署](#一键部署)
94
- - [使用方法](#使用方法)
95
- - [功能](#功能)
96
- - [原理](#原理)
97
- - [兼容性策略](#兼容性策略)
98
- - [项目结构](#项目结构)
99
- - [HTTP 接口](#http-接口)
100
- - [安全说明](#安全说明)
101
- - [已知限制](#已知限制)
102
- - [帮助 / Help](#帮助--help)
103
- - [生态与收录](#生态与收录)
104
- - [参与贡献](#参与贡献)
105
- - [许可证](#许可证)
106
- </details>
107
-
108
- ---
109
-
110
- ## AI 赋能与服务器组件控制
111
-
112
- > **AI 赋能** — v0.3.24 正式版核心功能。
113
-
114
- 在插件控制台输入 **npm 包名或 GitHub 仓库**（如 `OpenViking`、`@noob-stupid/dsh-plugin-console`）：
115
-
116
- 1. **AI 读文档出计划**：子代理调研 README/docs，产出结构化计划（类型：纯插件 / 服务器组件 / 仅配置；步骤：安装 / 写配置 / 下载 / 启动服务 / 健康检查）；
117
- 2. **你确认**（计划弹窗里逐步骤勾选）——安全护栏：命令/路径白名单、破坏性命令拦截、日志脱敏；
118
- 3. **安全执行**：实时回显日志、可中断、幂等（已装 / 已下载 / 服务健康则复用）；
119
- 4. **自动生成组件卡片**：服务器类组件注册到组件清单，卡片出现在主面板左侧（启动/停止/状态/【打开】直达 Web UI；多服务器时 ▾ 下拉；打开详情时自动隐藏；可折叠并有状态记忆）。
9
+ > 一站式管理你的 DeepSeek Harness 插件：一键启用/停用、500+ 插件与技能市场一键安装、
10
+ > 框架一键升级（失败自动回滚）。
120
11
 
121
- **内置 OpenViking 模板**：输入 `OpenViking` 秒出计划（pip 装 `openviking[local-embed]` → 下载中文嵌入模型 → 写 `ov.conf`（复用 DSH 的 DeepSeek 凭据）→ 启动服务器 → 健康检查）。
12
+ ## 为什么是 DSH 插件中心
122
13
 
123
- **模型配置**：默认跟随 DSH（`settings.yaml` + `.credentials.yaml`）；可建 `~/.dsh/plugin-console/ai-empower.json` 独立覆盖：
124
-
125
- ```json
126
- { "vlm": { "provider": "openai", "api_base": "https://api.deepseek.com", "model": "deepseek-v4-flash-vision-exp" }, "api_key": "sk-..." }
127
- ```
128
-
129
- ---
130
-
131
- > **给插件作者**：给仓库打上 `dsh-plugin` 标签即可被官方 [topic 列表](https://github.com/topics/dsh-plugin)
132
- > 与本中心自动收录；技能类仓库请打 `agent-skills` / `claude-skills` / `dsh-skill`。
133
-
134
- ---
14
+ - 🧩 **插件 + 技能双市场** — 自动收录 `dsh-plugin` 仓库（按 star **500+**）外加技能 tab；
15
+ 浏览、搜索、一键安装，**零 GitHub API 调用**（CDN 分发，秒开零限流）。
16
+ - 🚀 **框架一键升级** — 备份 → 在线安装（服务不中断）→ 校验 → **失败自动回滚**，端到端实测。
17
+ - 🤖 **AI 赋能** — 输入 npm 包名或 GitHub 仓库，本地 AI 读文档生成**部署计划**
18
+ （安装/写配置/启动服务/健康检查），你确认后安全执行；服务器组件自动生成控制卡片。
19
+ → [详见](docs/ai-empower.zh.md)
135
20
 
136
21
  ## 一键部署
137
22
 
138
- ### 方式一：官方命令（推荐）
139
-
140
- 插件声明了 `dsh.bundle` 官方清单，一条命令装好并自动启用：
141
-
142
- ```sh
23
+ ```bash
143
24
  # npm 发布版（推荐：预构建产物，无需 git / 构建授权）
144
25
  dsh plugin --profile web add @noob-stupid/dsh-plugin-console
145
26
 
@@ -147,14 +28,9 @@ dsh plugin --profile web add @noob-stupid/dsh-plugin-console
147
28
  dsh plugin --profile web add github:Noob-stupid/dsh-plugin-hub
148
29
  ```
149
30
 
150
- 卸载 / 重装（即更新）：
31
+ 然后重启 dsh 服务 → 刷新页面 → **设置 → 插件 → 插件控制台**。
151
32
 
152
- ```sh
153
- dsh plugin --profile web remove @noob-stupid/dsh-plugin-console
154
- dsh plugin --profile web add @noob-stupid/dsh-plugin-console
155
- ```
156
-
157
- 然后重启 dsh 服务 → 刷新页面 → 设置 → 插件 → 插件管理。
33
+ <details><summary><b>更多部署方式</b>（部署脚本 / 一句话交给 AI）</summary>
158
34
 
159
35
  ### 方式二：部署脚本（网络受限时的兜底）
160
36
 
@@ -182,6 +58,45 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
182
58
 
183
59
  要求：DSH ≥ 0.1.0-rc.6（web profile，含 `dsh-client-modules` / `dsh-host-plugin-inventory`）。
184
60
 
61
+ </details>
62
+
63
+ ---
64
+
65
+ ## 核心优势
66
+
67
+ | | 优势 | 说明 |
68
+ |---|---|---|
69
+ | 🤖 | **AI 赋能** | 输入 npm 包名 / GitHub 仓库，本地 AI 读文档生成**部署计划**（安装/写配置/启动服务/健康检查），你确认后安全执行；服务器类组件自动生成控制卡片 |
70
+ | 🛡️ | **框架升级适配门与安全** | 升级后不兼容插件强制禁用（适配门锁定，「检测更新 → 更新并适配 → 自动校验解锁」）；升级前全树 checkpoint、拉起失败自动全树回滚、框架卡片一键回滚到上一版 |
71
+ | 🏠 | **全家桶分组卡片与安全** | 同根包子路径导出自动聚合为一张全家桶卡片（收起/展开、批量检测更新、一键启用已适配、已知校验预览）；永不崩安全（启用前导入探针 + 补丁自愈 + exports 回退）；适配门源码扫描硬判据与迁移检测；删除聚合包子行仅停用该行 |
72
+ | 🚀 | **服务器组件卡片** | 左侧浮卡与主面板顶边对齐：启动 / 停止 / 状态 / 【打开】直达 Web UI，多服务器下拉、可折叠（状态记忆） |
73
+ | 🧩 | **插件 + 技能双市场** | 自动收录 `dsh-plugin` topic 仓库（按 star **500+**），另有**技能 tab**（`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`，最多 300）——浏览、搜索、一键安装，零 GitHub API 调用；插件自带技能（如 openviking-memory）只读展示 |
74
+ | 🤖 | **自动收录 CI** | GitHub Actions 每 6 小时自动重跑 `build-index`（也支持手动触发）；作者只需给自己的仓库打 `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` 标签，**无需申请、无需审核** |
75
+ | ⚡ | **秒开、零限流** | 索引以静态 `marketplace/index.json` 提交仓库，经 jsDelivr CDN 分发（宿主 10 分钟缓存）——终端用户**零 GitHub API 调用、零限流** |
76
+ | 🔄 | **版本检测与一键更新** | semver 比较 + beta/next 识别（本地已是测试版最新时不误报）；已安装条目自动比对 npm `dist-tags`，聚合包子包版本不配套时给出 depsOutdated 提示 |
77
+ | 🔀 | **多源检索** | GitHub / Gitee（仓库直装模式）/ 自定义搜索源（URL 模板 + 请求头认证 + 私网 http）；「⊞」并行合并 GitHub + 全部自定义源 |
78
+ | 🔒 | **安全默认** | 全部路由仅环回；AI 兜底置于明确费用授权弹窗之后；AI 赋能执行器命令/路径白名单；基础设施行禁止开关（受保护） |
79
+
80
+ <details>
81
+ <summary><b>📑 目录</b></summary>
82
+
83
+ - [核心优势](#核心优势)
84
+ - [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
85
+ - [一键部署](#一键部署)
86
+ - [使用方法](#使用方法)
87
+ - [功能](#功能)
88
+ - [原理](#原理)
89
+ - [兼容性策略](#兼容性策略)
90
+ - [项目结构](#项目结构)
91
+ - [HTTP 接口](#http-接口)
92
+ - [安全说明](#安全说明)
93
+ - [已知限制](#已知限制)
94
+ - [帮助 / Help](#帮助--help)
95
+ - [生态与收录](#生态与收录)
96
+ - [参与贡献](#参与贡献)
97
+ - [许可证](#许可证)
98
+ </details>
99
+
185
100
  ---
186
101
 
187
102
  ## 使用方法
@@ -229,37 +144,6 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
229
144
  - **卡片关闭语义**：终态（成功/失败）点叉号永久关闭（持久化）；进行中点叉号仅本次会话
230
145
  隐藏，刷新后恢复显示。
231
146
 
232
- ### 框架升级适配门与升级安全（v0.3.25）
233
-
234
- > 缘起：2026-09-04 DSH `0.1.1-rc.2 → 0.1.2-rc.1` 升级事故——升级脚本在错误的工作目录执行，
235
- > 把新 CLI 原位覆盖进旧 `.pnpm` 目录、依赖树混版本，服务无法拉起。本版本把「升级安全」与
236
- > 「插件兼容检测」固化为控制台机制。
237
-
238
- **升级安全三件套**
239
-
240
- 1. **框架安装根识别**：定位真正的框架安装根（含 `.pnpm` 的顶层 `node_modules`），修复
241
- `require.resolve` 返回 `.pnpm` 内部 realpath 导致的「重链空转 / 新包覆盖旧目录」根因；
242
- 定位不到时**拒绝升级**（不 kill 服务、服务保持运行）；
243
- 2. **升级前全树 checkpoint**：镜像 `.pnpm` 全部 `@deepseek-ai` 版本包 + 顶层 scope +
244
- `lock.yaml`（写入 `~/.dsh/plugin-console/framework-backups/<版本>/fw-tree/`）；
245
- 3. **拉起失败自动全树回滚并重试**：安装失败或服务拉起失败都会自动恢复升级前全树并再次拉起，
246
- 不再只留「请手动运行」提示；回滚后跳过重链/修复（避免对已恢复旧树二次破坏）。
247
-
248
- **一键回滚**：升级后框架卡片出现「回滚到上一版」按钮（`/plugin-console/framework-rollback`）：
249
- 停服 → 全树恢复 → 自动拉起 → 健康检测，全程状态可见。
250
-
251
- **插件适配门（插件检测）**
252
-
253
- - 升级后写入 `~/.dsh/plugin-console/compat-pending.json` 的插件行被**强制禁用**，启用按钮
254
- 锁定（服务端 `/toggle` 直接 409，无法绕过）；行状态以按钮文案「待适配」提示；
255
- - 「详情」面板给出说明与入口：**检测更新 → 更新并适配**；
256
- - **更新后自动校验**：扫描最新版 `package.json` 的 `dsh.engines.framework` / `engines.dsh`
257
- 显式声明 + `@deepseek-ai/*` 依赖范围（内置零依赖 semver 判定器：依赖判定遵循 npm
258
- prerelease 严格规则、声明判定宽松）；版本已变化且未判定不兼容 → **自动移除禁用块解锁**；
259
- 聚合包更新连带校验同步的子包；
260
- - **AI 赋能适配预检**：规划时服务端预检 registry 最新版声明与适配门命中情况，注入子代理
261
- 提示词（要求计划向用户解释适配结论），并在计划面板标注（不兼容标红）。
262
-
263
147
  ### 插件市场（多搜索源）
264
148
 
265
149
  - **搜索源切换**：点击顶部登录态标识弹出菜单，在 **GitHub / Gitee / 自定义源** 间切换（选择持久化）；
@@ -305,161 +189,13 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
305
189
 
306
190
  ---
307
191
 
308
- ## 原理
309
-
310
- ### 开关语义
311
-
312
- DSH 的 web profile 由 bundle 补丁层 + 用户补丁层（`$DSH_HOME/profiles/web/cordis.patch.yml`）
313
- 组合而成，补丁是**逐键覆盖**语义。插件开关只是往用户补丁层追加/移除两行 YAML：
314
-
315
- ```yaml
316
- - id: 插件条目id
317
- disabled: true
318
- ```
319
-
320
- 配置文件监视器（HMR）会在保存后 1 秒内重组合，无需重启——除宿主代码本身变更外。
321
-
322
- ### 安装链
323
-
324
- ```
325
- 配置的软件源按主→备依次尝试（默认 npmmirror → npmjs）
326
- → curl 手动安装 （node 网络黑洞时：curl 下载 tarball 解压进 node_modules）
327
- → git 通道 （GitHub 走加速代理+直连，Gitee 走对应平台）
328
- → Windows EPERM 陈旧目录自动清理重试
329
- → 自动展开仓库子包 （聚合包优先）
330
- → 本地 AI 兜底 （置于明确费用授权弹窗之后）
331
- ```
332
-
333
- 技能安装独立走：`git clone --depth 1` → 复制 SKILL.md 资源到 `~/.dsh/skills/<名称>/`
334
- （不碰 npm、不写补丁、无需重启）。
335
-
336
- ### 数据源
337
-
338
- ```
339
- GitHub Actions（每 6 小时，仓库自带 token）
340
- └─ scripts/build-index.cjs：分页拉取 topic:dsh-plugin（按 star 500 个）+ 技能 topic（300 个）
341
- └─ 提交 marketplace/index.json 回 main
342
- └─ 宿主经 jsDelivr CDN 读取（10 分钟缓存）→ 市场秒开、零 API 调用
343
- └─ 实时搜索仍走 GitHub 搜索 API（浏览器直连 + 服务端通道兜底）
344
- ```
345
-
346
- ### 版本检测与已安装识别
347
-
348
- - **已安装识别**：按已装条目的 `repository` 字段或模块名与市场条目比对（仓库名 → 包名映射）；
349
- - **版本检测**：`check-update` 走 curl 读 npm `dist-tags.latest`；聚合包额外对比子包
350
- 声明版本 vs 本地实际版本（depsOutdated），防止半更新混搭导致启动冲突。
351
-
352
- ---
353
-
354
- ## 兼容性策略
355
-
356
- - 当前支持 **DSH 0.1.0 系列**（`0.1.0-rc.6` 及同系列版本）。
357
- - 面板会读取运行中的 `@deepseek-ai/dsh-web-app` 版本：官方发布破坏性升级
358
- （0.2 / 1.0 等）后，面板顶部会显示兼容性警告并给出本仓库地址，而不是默默失效。
359
- - **插件适配门（v0.3.25）**：框架升级后不兼容的第三方插件会被**强制禁用**（启用按钮锁定）；
360
- 请先「检测更新」升级该插件，更新并通过自动校验后才会解锁——详见
361
- 「框架升级适配门与升级安全」。
362
- - 官方破坏性更新可能改动的接口：补丁层语义、`webServer.register`、
363
- 加载器条目结构、`dsh.client` bundle 格式、`settings.plugins.tab` 插槽。
364
- 届时随官方版本更新本仓库即可（依赖面已收窄到上述几个点）。
365
- - 部署脚本不校验版本、直接安装；面板里的警告是权威提示。
366
-
367
- ---
368
-
369
- ## 项目结构
370
-
371
- ```
372
- lib/index.js 宿主端插件（/plugin-console/* 路由 + 补丁读写 + 多源检索 + 安装）
373
- lib/client.js 浏览器端 bundle（ModuleLoader 格式，设置页 tab）
374
- scripts/build-index.cjs 索引构建（插件 --limit 500 / 技能 --skills --limit 300）
375
- scripts/apply-framework-patch.cjs 框架层补丁（issue #5，幂等，可重复应用）
376
- .github/workflows/registry.yml 自动收录 CI（每 6 小时 + 手动触发）
377
- marketplace/index.json 生成的静态索引（jsDelivr CDN 分发）
378
- deploy.ps1 / deploy.sh 一键部署脚本（Windows / Linux·macOS）
379
- test-harness.mjs 逻辑自检（state/toggle/校验/环回保护；搜索视网络环境 SKIP）
380
- test-compat-gate.mjs 适配门单元测试（内置 semver 判定器：声明/依赖兼容规则）
381
- ```
382
- <img width="1878" height="945" alt="image" src="https://github.com/user-attachments/assets/b26f2f19-0ba4-4be7-9ca1-b3fd4c51a7a8" />
383
-
384
- ---
385
-
386
- ## HTTP 接口
387
-
388
- | 接口 | 方法 | 说明 |
389
- |---|---|---|
390
- | `/plugin-console/state` | GET | 插件清单 + 补丁状态 + 兼容性 + 运行中的安装任务 |
391
- | `/plugin-console/toggle` | POST | 启用/停用条目（写用户补丁层） |
392
- | `/plugin-console/uninstall` | POST | 删除条目并卸载包（bundle 感知） |
393
- | `/plugin-console/search` | POST | 多源搜索（github/gitee/自定义，`multi` 合并） |
394
- | `/plugin-console/repo` | POST | 仓库元数据：package.json、private 根、dsh 提示、**hasSkill** |
395
- | `/plugin-console/enrich` | POST | 服务端类型标记（官方/聚合/技能） |
396
- | `/plugin-console/install` | POST | 安装（插件或 `kind: skill` 技能），返回任务 id |
397
- | `/plugin-console/install-status` | POST | 轮询安装任务 |
398
- | `/plugin-console/check-update` | POST | npm 最新版本 + 子包不配套检查 |
399
- | `/plugin-console/market-index` | POST | 静态索引（jsDelivr CDN，10 分钟缓存） |
400
- | `/plugin-console/skills-installed` | GET | `~/.dsh/skills` 下已安装技能 |
401
- | `/plugin-console/sources` | GET/POST | 软件源与搜索源管理、Gitee OAuth 配置 |
402
- | `/plugin-console/gitee-oauth-url` / `gitee-oauth-callback` | GET | Gitee OAuth 流程 |
403
- | `/plugin-console/ai-consent` | POST | 同意/取消 AI 兜底步骤 |
404
- | `/plugin-console/restart` | POST | 自带守护的安全自重启（等同面板按钮） |
405
- | `/plugin-console/framework-upgrade` | POST | 框架一键升级（全树 checkpoint → 在线安装 → 全树回滚保护） |
406
- | `/plugin-console/framework-rollback` | POST | 一键回滚到升级前版本（停服 → 全树恢复 → 自动拉起 → 健康检测） |
407
- | `/plugin-console/self-update` | POST | 控制台自身一键更新（npm 最新 tarball 到当前 profile） |
408
- | `/plugin-console/ai-empower/plan` / `status` / `run` / `cancel` | POST | AI 赋能：规划（含框架适配预检）→ 状态轮询 → 确认执行 → 取消 |
409
- | `/plugin-console/components` / `component/start` / `stop` / `status` | GET/POST | 服务器组件清单与启动/停止/状态 |
410
-
411
- ---
412
-
413
- ## AI 兜底安装与授权弹窗
414
-
415
- 安装走**确定性通道链**：`配置源（主→备）→ curl 手动安装 → git 通道 → EPERM 清理重试 → 仓库子包展开`。常规通道全部失败时，才轮到**本地 AI 兜底**。
416
-
417
- **本地 AI 兜底是什么**：拉起一个本地 AI 子代理接管安装——它会像人工一样诊断（查仓库结构、识别子包/聚合包、清理残留），用正确管理器完成安装并落配置。**注意：这一步会调用 DeepSeek API 模型，可能产生 API 费用。**
418
-
419
- **授权弹窗逻辑（费用透明）**：
420
-
421
- 1. 常规通道全失败后，任务进入「等待授权」状态，屏幕中央弹出**最上层模态框**：
422
- - 明确说明"将调用 DeepSeek API 模型，可能产生 API 费用"
423
- - 提供 **同意，继续** / **取消** 两个按钮（取消 = 零费用）
424
- - 10 分钟未决定自动取消
425
- 2. 模态框内可勾选 **"以后不再提醒"**（自动同意）——勾选后可随时在**插件市场页面最底部**恢复弹窗提醒
426
- 3. 右上角悬浮的 **"AI 兜底"开关**可彻底关闭该功能：常规通道失败将直接取消安装，**永远不会调用模型 API（零费用）**
427
-
428
- ---
429
-
430
- ## 框架层补丁（cordis.patch.yml 解析容错）
431
-
432
- **问题（issue #5）**：`cordis.patch.yml` 若含顶格 `[]` 占位符 + 后续条目（两个 YAML 根节点），
433
- DSH 启动时解析崩溃：`end of the stream or a document separator is expected`。
434
-
435
- **修复位置**：DSH 框架 `dsh-app-boot` 的 `parsePatchList`——解析失败时自动移除顶格空数组占位行（视为 no-op）后重试；
436
- 正常文件、纯 `[]` 文件、缩进子数组均不受影响。
437
-
438
- **应用方式**（DSH 升级后需重新执行，升级会覆盖框架文件）：
439
-
440
- ```bash
441
- node scripts/apply-framework-patch.cjs
442
- ```
443
-
444
- 脚本自动定位 npx 缓存中的 `dsh-app-boot/lib/index.js`，检测到已补丁则跳过（幂等），首次应用会保留 `.bak-issue5` 备份。
445
-
446
- ---
447
-
448
- ## 安全说明
449
-
450
- - 全部路由仅允许环回地址访问；
451
- - GitHub 元数据只用于发现公开插件，npm 安装走 registry 的完整 TLS 校验；
452
- - GitHub 源搜索在浏览器内直连；Gitee / 自定义源检索与请求头（含认证信息）仅经服务端处理，不下发浏览器；
453
- - 自定义源地址仅允许 https 与本机/私网 http（127.0.0.1、localhost、10.x、192.168.x、172.16-31.x 等）；
454
- - 技能是纯文件（SKILL.md + 资源）——安装技能**不会执行任何代码**；git clone 来自你选择的仓库，安装前请自行核验。
455
-
456
- ---
457
-
458
- ## 免责声明
192
+ ## 文档
459
193
 
460
- - 市场收录的均为 GitHub 第三方仓库，各插件由各自作者独立开发维护，**与 DeepSeek Harness 及本插件中心无任何关联**；
461
- - 本中心**不对任何插件的质量、可靠性、安全性、许可证合规性、兼容性作任何明示或默示担保**；收录**不构成推荐或背书**——安装即代表你已自行评估并接受相应风险，建议安装前阅读仓库源码与 README；
462
- - 本中心按「现状」（AS-IS）提供，因安装或使用任何第三方插件造成的任何直接或间接损失（数据丢失、系统损坏、隐私泄露等），本中心及其开发者不承担任何责任。
194
+ - [AI 赋能与服务器组件控制](docs/ai-empower.zh.md)
195
+ - [框架升级适配门与升级安全](docs/upgrade-safety-adapt-gate.zh.md)
196
+ - [原理](docs/how-it-works.zh.md) · [兼容性策略](docs/compatibility.zh.md) · [项目结构](docs/project-layout.zh.md)
197
+ - [HTTP 接口](docs/http-endpoints.zh.md) · [AI 兜底安装与授权弹窗](docs/ai-fallback.zh.md)
198
+ - [安全说明与免责声明](docs/security-disclaimer.zh.md)
463
199
 
464
200
  ---
465
201