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

package/README.md

@@ -18,139 +18,23 @@
 [![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)
 [![dsh.so install](https://www.dsh.so/badge/install/dsh-plugin-hub.svg)](https://www.dsh.so/artifact/dsh-plugin-hub)
 
+> Manage all your DeepSeek Harness plugins in one panel: one-click enable/disable,
+> a 500+ plugin & skill marketplace with one-click install, and one-click framework
+> upgrade with auto-rollback.
 
+## Why DSH Plugin Hub
 
-> ## 🎉 v0.3.27 released — family-bundle cards, never-crash safety & adapt-gate hardening (2026-09-04)
->
-> **Family-bundle cards**: same-root subpath exports (e.g. `@linxin666/dsh-web-all/settings`) auto-group
-> into one family card at the bottom — collapse/expand, batch check-updates, **one-click unlock-adapted**,
-> known-check preview, `web-all/`-prefix-free sub-cards.
-> **Never-crash safety**: pre-enable import probe (child-process) + patch auto-heal (core-row restore &
-> missing-module auto-disable) + exports-fallback `package.json` resolution — the memory-plugin
-> false-disable incident is fixed.
-> **Adapt-gate hardening**: source-scan hard criterion (post-0.3.6 false-pass), migrate detection
-> (`dsh.migrate.to`), softened dependency-strict judgment, pending hints moved into details.
-> **Safe sub-package delete**: deleting a bundle sub-row disables only that row and keeps the bundle —
-> fixing the incident where deleting one sub-package removed the whole family bundle.
->
-> **Install:**
-> ```bash
-> npm i -g @noob-stupid/dsh-plugin-console
-> # or in DSH: dsh plugin --profile web add @noob-stupid/dsh-plugin-console
-> ```
-> **Try it:** Plugin Console → family card at the bottom → 「批量检测更新 / 一键启用已适配」.
->
-> Feedback: [GitHub Issues](https://github.com/Noob-stupid/dsh-plugin-hub/issues).
-A **plugin management panel** for the DeepSeek Harness (DSH) Web GUI: one-click
-enable/disable of installed plugins, a **multi-source plugin marketplace**
-(GitHub / Gitee / custom sources) with one-click install, an **auto-collected
-static plugin & skill index** refreshed by CI every 6 hours, skill install/disable,
-suite one-click assembly, and **one-click framework upgrade** (online install with
-auto-rollback).
-
-> ## 🎯 One-click framework upgrade (v0.3.13 highlight)
->
-> Open the "Plugin Console" panel → **Plugin Marketplace** → the
-> `deepseek-ai/deepseek-harness` card → click **"Framework Upgrade → vX"**:
-> **backup config & framework (rollback point) → online install (service stays up) →
-> version verification → auto-rollback on failure → auto-restart**.
->
-> After upgrade, framework packages are **auto-relinked** (fixes pnpm top-level link
-> staleness that caused mixed versions, e.g. an old model plugin missing vision models).
-> Tested: 0.1.0-rc.8 → **0.1.1-rc.2** end-to-end automatic, rollback-safe.
-
-<!-- TOC -->
-- [Highlights](#highlights)
-- [One-click install](#one-click-install)
-- [Usage](#usage)
-- [Features](#features)
-- [How it works](#how-it-works)
-- [Compatibility](#compatibility)
-- [Project layout](#project-layout)
-- [HTTP endpoints](#http-endpoints)
-- [Local AI fallback & consent dialog](#local-ai-fallback--consent-dialog)
-- [Framework patch (cordis.patch.yml parse tolerance)](#framework-patch-cordispatchyml-parse-tolerance)
-- [Security](#security)
-- [Disclaimer](#disclaimer)
-- [Known limitations](#known-limitations)
-- [Help](#help)
-- [Ecosystem & discoverability](#ecosystem--discoverability)
-- [Support](#support)
-- [Changelog](#changelog)
-- [License](#license)
-<!-- /TOC -->
-
----
-
-## Highlights
-
-| | Benefit | Detail |
-|---|---|---|
-| 🤖 | **AI Empower (v0.3.24)** | Give the console a package name or GitHub repo — the local AI reads docs, drafts a **deployment plan** (install / write config / start service / health check) and executes it safely after your confirmation; server-type components get an automatic control card |
-| 🛡️ | **Framework upgrade safety & adapt gate (v0.3.25)** | Force-disables plugins incompatible with the new framework (enable locked; 「Check update → Update & adapt」auto-verifies and unlocks); full-tree checkpoint before upgrade, automatic rollback on relaunch failure, one-click rollback to the previous version |
-| 🏠 | **Family-bundle cards & safety (v0.3.27)** | Same-root subpath exports group into one family card (collapse/expand, batch check-update, one-click unlock-adapted, known-check preview); never-crash safety (pre-enable import probe + patch auto-heal + exports fallback); adapt-gate source-scan hard criterion & migrate detection; deleting a bundle sub-row disables only that row |
-| 🚀 | **Server component cards** | Left-side floating card auto-aligned to the main panel: start / stop / status / **open Web UI** buttons, multi-server dropdown, collapsible |
-| 🧩 | **Plugin & skill hub** | Auto-collected index of `dsh-plugin` topic repos (**500+** by stars) plus a **Skills tab** (`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`, up to 300) — browse, search, one-click install, no GitHub API calls |
-| 🤖 | **Auto-collection CI** | GitHub Actions reruns `build-index` every 6 hours (manual trigger available); authors just add the `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` topic — no application needed |
-| ⚡ | **Instant, rate-limit-free** | The index is served as a static `marketplace/index.json` via jsDelivr CDN (10-min host cache); terminal users make **zero GitHub API calls** |
-| 🔄 | **Version detection & one-click update** | Semver-based; installed entries match npm `dist-tags.latest` / `beta`; subpackage mismatch warnings prevent mixed-version breakage |
-| 🔀 | **Multi-source** | GitHub / Gitee (direct-repo mode) / custom search sources (URL template + header auth + private http); `⊞` merges GitHub + all custom sources in parallel |
-| 🔒 | **Safe by default** | Loopback-only routes; AI fallback behind an explicit cost-consent modal; infrastructure rows are toggle-protected |
-
-<details>
-<summary><b>📑 目录 / Table of Contents</b></summary>
-
-- [Highlights](#highlights)
-- [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
-- [One-click install](#one-click-install)
-- [Usage](#usage)
-- [Features](#features)
-- [How it works](#how-it-works)
-- [Compatibility](#compatibility)
-- [Project layout](#project-layout)
-- [HTTP endpoints](#http-endpoints)
-- [Security](#security)
-- [Known limitations](#known-limitations)
-- [Help & Ecosystem](#help--ecosystem)
-- [Contributing](#contributing)
-- [Changelog](#changelog)
-- [License](#license)
-</details>
-
----
-
-## AI 赋能与服务器组件控制
-
-> **AI Empower** — v0.3.24 正式版核心功能。
-
-在插件控制台输入 **npm 包名或 GitHub 仓库**（如 `OpenViking`、`@noob-stupid/dsh-plugin-console`）：
-
-1. **AI 读文档出计划**：子代理调研 README/docs，产出结构化计划（类型：纯插件 / 服务器组件 / 仅配置；步骤：安装 / 写配置 / 下载 / 启动服务 / 健康检查）；
-2. **你确认**（计划在弹窗里逐步骤勾选）——安全护栏：命令/路径白名单、破坏性命令拦截、日志脱敏；
-3. **安全执行**：实时回显日志、可中断、幂等（已装/已下载/服务健康则复用）；
-4. **自动生成组件卡片**：服务器类组件注册到组件清单，卡片出现在主面板左侧（启动/停止/状态/【打开】直达 Web UI；多服务器时 ▾ 下拉；打开详情时自动隐藏；可折叠并有状态记忆）。
-
-**内置 OpenViking 模板**：输入 `OpenViking` 秒出计划（pip 装 `openviking[local-embed]` → 下载中文嵌入模型 → 写 `ov.conf`（复用 DSH 的 DeepSeek 凭据，支持独立区块覆盖）→ 启动服务器 → 健康检查）。
-
-**模型配置**：默认跟随 DSH（`settings.yaml` + `.credentials.yaml`）；可建 `~/.dsh/plugin-console/ai-empower.json` 独立覆盖：
-
-```json
-{ "vlm": { "provider": "openai", "api_base": "https://api.deepseek.com", "model": "deepseek-v4-flash-vision-exp" }, "api_key": "sk-..." }
-```
-
----
-
-> **For plugin authors**: add the `dsh-plugin` topic to your repo — the official
-> [topic list](https://github.com/topics/dsh-plugin) is how both the ecosystem and this
-> hub discover you. For skills, add `agent-skills` / `claude-skills` / `dsh-skill`.
-
----
-
-## One-click install
-
-### Option 1: official command (recommended)
+- 🧩 **Plugin & skill hub** — auto-collected index of `dsh-plugin` repos (500+ by
+  stars) plus a Skills tab; browse, search, one-click install, **zero GitHub API
+  calls** (served via CDN).
+- 🚀 **One-click framework upgrade** — backup → online install (service stays up) →
+  verify → **auto-rollback on failure**. Tested end-to-end.
+- 🤖 **AI Empower** — give the console a package name or GitHub repo, the local AI
+  reads its docs and drafts a safe, confirmable deployment plan (install / config /
+  start / health-check); server components get an automatic control card.
+  → [details](docs/ai-empower.md)
 
-The plugin declares a `dsh.bundle` manifest, so a single command installs and enables it:
+## Install
 
 ```sh
 # npm release (recommended: prebuilt, no git / build authorization needed)
@@ -160,14 +44,9 @@ dsh plugin --profile web add @noob-stupid/dsh-plugin-console
 dsh plugin --profile web add github:Noob-stupid/dsh-plugin-hub
 ```
 
-Uninstall / reinstall (update):
-
-```sh
-dsh plugin --profile web remove @noob-stupid/dsh-plugin-console
-dsh plugin --profile web add @noob-stupid/dsh-plugin-console
-```
+Then restart the dsh service → refresh the page → **Settings → Plugins → Plugin Console**.
 
-Then restart the dsh service → refresh the page → Settings → Plugins → Plugin Console.
+<details><summary><b>More install options</b> (deploy script / hand it to an AI)</summary>
 
 ### Option 2: deploy script (fallback when network is restricted)
 
@@ -196,6 +75,45 @@ idempotently appends an enable entry to `cordis.patch.yml`. Afterwards:
 
 Requires: DSH ≥ 0.1.0-rc.6 (web profile, with `dsh-client-modules` / `dsh-host-plugin-inventory`).
 
+</details>
+
+---
+
+## Highlights
+
+| | Benefit | Detail |
+|---|---|---|
+| 🤖 | **AI Empower ** | Give the console a package name or GitHub repo — the local AI reads docs, drafts a **deployment plan** (install / write config / start service / health check) and executes it safely after your confirmation; server-type components get an automatic control card |
+| 🛡️ | **Framework upgrade safety & adapt gate ** | Force-disables plugins incompatible with the new framework (enable locked; 「Check update → Update & adapt」auto-verifies and unlocks); full-tree checkpoint before upgrade, automatic rollback on relaunch failure, one-click rollback to the previous version |
+| 🏠 | **Family-bundle cards & safety ** | Same-root subpath exports group into one family card (collapse/expand, batch check-update, one-click unlock-adapted, known-check preview); never-crash safety (pre-enable import probe + patch auto-heal + exports fallback); adapt-gate source-scan hard criterion & migrate detection; deleting a bundle sub-row disables only that row |
+| 🚀 | **Server component cards** | Left-side floating card auto-aligned to the main panel: start / stop / status / **open Web UI** buttons, multi-server dropdown, collapsible |
+| 🧩 | **Plugin & skill hub** | Auto-collected index of `dsh-plugin` topic repos (**500+** by stars) plus a **Skills tab** (`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`, up to 300) — browse, search, one-click install, no GitHub API calls |
+| 🤖 | **Auto-collection CI** | GitHub Actions reruns `build-index` every 6 hours (manual trigger available); authors just add the `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` topic — no application needed |
+| ⚡ | **Instant, rate-limit-free** | The index is served as a static `marketplace/index.json` via jsDelivr CDN (10-min host cache); terminal users make **zero GitHub API calls** |
+| 🔄 | **Version detection & one-click update** | Semver-based; installed entries match npm `dist-tags.latest` / `beta`; subpackage mismatch warnings prevent mixed-version breakage |
+| 🔀 | **Multi-source** | GitHub / Gitee (direct-repo mode) / custom search sources (URL template + header auth + private http); `⊞` merges GitHub + all custom sources in parallel |
+| 🔒 | **Safe by default** | Loopback-only routes; AI fallback behind an explicit cost-consent modal; infrastructure rows are toggle-protected |
+
+<details>
+<summary><b>📑 目录 / Table of Contents</b></summary>
+
+- [Highlights](#highlights)
+- [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
+- [One-click install](#one-click-install)
+- [Usage](#usage)
+- [Features](#features)
+- [How it works](#how-it-works)
+- [Compatibility](#compatibility)
+- [Project layout](#project-layout)
+- [HTTP endpoints](#http-endpoints)
+- [Security](#security)
+- [Known limitations](#known-limitations)
+- [Help & Ecosystem](#help--ecosystem)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [License](#license)
+</details>
+
 ---
 
 ## Usage
@@ -253,47 +171,6 @@ Requires: DSH ≥ 0.1.0-rc.6 (web profile, with `dsh-client-modules` / `dsh-host
 - **Card dismiss semantics**: terminal states (done/failed) are permanently dismissed on ✕
   (persisted); in-progress dismissal is session-only and the card returns after a refresh.
 
-### Framework upgrade safety & plugin adapt gate (v0.3.25)
-
-> Origin: the 2026-09-04 DSH `0.1.1-rc.2 → 0.1.2-rc.1` incident — the upgrade script ran in
-> the wrong working directory, overwrote the new CLI into the old `.pnpm` entry, left a
-> mixed-version tree, and the service could not start. This version makes upgrade safety
-> and plugin compatibility detection first-class console mechanisms.
-
-**Upgrade safety trio**
-
-1. **Framework root detection**: locates the real install root (the top-level `node_modules`
-   containing `.pnpm`), fixing the `require.resolve`-returns-`.pnpm`-realpath root cause
-   (relink no-op / new package overwriting the old tree); refuses to upgrade when the root
-   cannot be identified (service stays running);
-2. **Full-tree checkpoint before upgrade**: mirrors every `@deepseek-ai` version package in
-   `.pnpm` + the top-level scope + `lock.yaml`
-   (under `~/.dsh/plugin-console/framework-backups/<version>/fw-tree/`);
-3. **Automatic full-tree rollback + retry**: install failure or relaunch failure restores
-   the pre-upgrade tree and relaunches automatically — no more "please run it manually"
-   dead-ends; after rollback, relink/repair steps are skipped to avoid damaging the
-   restored tree a second time.
-
-**One-click rollback**: after an upgrade the framework card shows a **「回滚到上一版」** button
-(`/plugin-console/framework-rollback`): stop service → restore full tree → relaunch →
-health check, state visible throughout.
-
-**Plugin adapt gate (compatibility detection)**
-
-- After an upgrade, plugin entries recorded in `~/.dsh/plugin-console/compat-pending.json`
-  are **force-disabled**; the enable button is locked and the server rejects `/toggle` with
-  409 (unbypassable). The enabled-button label itself shows「待适配」as the state hint;
-- The **details** panel explains the flow: **Check update → Update & adapt**;
-- **Post-update auto-verification**: scans the latest `package.json` for an explicit
-  `dsh.engines.framework` / `engines.dsh` declaration plus `@deepseek-ai/*` dependency
-  ranges (built-in zero-dependency semver engine — strict npm prerelease rules for
-  dependencies, loose for explicit declarations); if the version changed and no
-  incompatibility was found, the `disabled` block is **removed automatically** and the row
-  unlocks; aggregator updates validate all synced subpackages too;
-- **AI Empower pre-check**: during planning the server pre-checks the registry's latest
-  declaration and adapt-gate hits, injects them into the subagent prompt (the plan must
-  explain the conclusion to the user) and marks it on the plan panel (red for incompatible).
-
 ### Marketplace (multi-source)
 
 - **Source switcher**: click the login pill to switch between **GitHub / Gitee / custom
@@ -343,183 +220,13 @@ The floating "Sources" button (right of the title row, semi-transparent) opens t
 
 ---
 
-## How it works
-
-### Toggle semantics
-
-The DSH web profile is composed of a bundle patch layer plus the user patch layer
-(`$DSH_HOME/profiles/web/cordis.patch.yml`); patches are **per-key overrides**.
-Toggling a plugin just appends/removes two YAML lines:
-
-```yaml
-- id: plugin-entry-id
-  disabled: true
-```
-
-The config watcher (HMR) recomposes within ~1s — no restart needed except for host code.
-
-### Install chain
-
-```
-configured registries (primary→backup, default npmmirror → npmjs)
-  → curl manual install        (node networking blocked: tarball into node_modules)
-  → git channel                (GitHub via proxy+direct, Gitee via its platform)
-  → EPERM stale-dir cleanup retry
-  → repository subpackage expansion (aggregate packages first)
-  → local AI fallback          (behind an explicit cost-consent modal)
-```
-
-Skills install directly by `git clone --depth 1` → copy SKILL.md bundle into
-`~/.dsh/skills/<name>/` (no npm, no patch, no restart).
-
-### Data sources
-
-```
-GitHub Actions (every 6h, repo token)
-  └─ scripts/build-index.cjs: pages topic:dsh-plugin (500 by stars) + skills topics (300)
-       └─ commits marketplace/index.json back to main
-            └─ host reads it via jsDelivr CDN (10-min cache) → instant market, zero API calls
-                 └─ live search still uses the GitHub search API (browser-direct + server channel)
-```
-
-### Version detection & installed recognition
-
-- **Installed recognition**: match installed entries by `repository` field or module name
-  against market items (repo name → package name mapping);
-- **Version detection**: `check-update` reads npm `dist-tags.latest` via curl; for aggregate
-  packages it also compares subpackage declared vs actual versions (depsOutdated) to prevent
-  mixed-version startup conflicts.
-
----
-
-## Compatibility
-
-- Supports the **DSH 0.1.0 series** (`0.1.0-rc.6` and siblings).
-- The panel reads the running `@deepseek-ai/dsh-web-app` version: after a breaking upgrade
-  (0.2 / 1.0) a compatibility warning appears instead of silent failure.
-- **Plugin adapt gate (v0.3.25)**: third-party plugins incompatible with the current
-  framework are force-disabled after an upgrade (enable locked); run 「Check update」to
-  upgrade the plugin first — it unlocks automatically after the auto-verification passes.
-  See 「Framework upgrade safety & plugin adapt gate」.
-- Likely breaking seams: patch semantics, `webServer.register`, loader entry shape,
-  `dsh.client` bundle format, `settings.plugins.tab` slot.
-- Deploy scripts do not check versions; the in-panel warning is authoritative.
-
----
-
-## Project layout
-
-```
-lib/index.js       Host plugin (/plugin-console/* routes + patch I/O + multi-source search + install)
-lib/client.js      Browser bundle (ModuleLoader format, settings tab)
-scripts/build-index.cjs        Index builder (plugins --limit 500 / skills --skills --limit 300)
-scripts/apply-framework-patch.cjs   Framework patch (issue #5, idempotent)
-.github/workflows/registry.yml Auto-collection CI (every 6h + manual dispatch)
-marketplace/index.json         Generated static index (jsDelivr CDN)
-deploy.ps1 / deploy.sh   One-click deploy scripts (Windows / Linux·macOS)
-test-harness.mjs   Logic self-test (state/toggle/validation/loopback; search SKIP by network)
-```
-<img width="1878" height="945" alt="image" src="https://github.com/user-attachments/assets/b26f2f19-0ba4-4be7-9ca1-b3fd4c51a7a8" />
-
----
-
-## HTTP endpoints
-
-| Endpoint | Method | Purpose |
-|---|---|---|
-| `/plugin-console/state` | GET | Plugin list + patch state + compat + running install jobs |
-| `/plugin-console/toggle` | POST | Enable/disable an entry (writes user patch layer) |
-| `/plugin-console/uninstall` | POST | Remove entry + uninstall package (bundle-aware) |
-| `/plugin-console/search` | POST | Multi-source search (github/gitee/custom, `multi` merge) |
-| `/plugin-console/repo` | POST | Repo metadata: package.json, private root, dsh hint, **hasSkill** |
-| `/plugin-console/enrich` | POST | Server-side type markers (official/aggregate/skill) |
-| `/plugin-console/install` | POST | Install (plugin or `kind: skill`), returns a job id |
-| `/plugin-console/install-status` | POST | Poll an install job |
-| `/plugin-console/check-update` | POST | npm latest version + subpackage mismatch check |
-| `/plugin-console/market-index` | POST | Static index (jsDelivr CDN, 10-min cache) |
-| `/plugin-console/skills-installed` | GET | Installed skills under `~/.dsh/skills` |
-| `/plugin-console/sources` | GET/POST | Registry & search-source manager, Gitee OAuth setup |
-| `/plugin-console/gitee-oauth-url` / `gitee-oauth-callback` | GET | Gitee OAuth flow |
-| `/plugin-console/ai-consent` | POST | Approve/cancel the AI-fallback step |
-| `/plugin-console/restart` | POST | Watchdog-safe self-restart (panel button equivalent) |
-| `/plugin-console/framework-upgrade` | POST | One-click framework upgrade (full-tree checkpoint → online install → rollback protection) |
-| `/plugin-console/framework-rollback` | POST | One-click rollback to the previous version (stop → full-tree restore → auto relaunch → health check) |
-| `/plugin-console/self-update` | POST | Update the console itself (latest npm tarball into the profile) |
-| `/plugin-console/ai-empower/plan` / `status` / `run` / `cancel` | POST | AI Empower: plan (with framework compat pre-check) → status polling → confirmed run → cancel |
-| `/plugin-console/components` / `component/start` / `stop` / `status` | GET/POST | Server component registry and start/stop/status |
-
----
-
-## Local AI fallback & consent dialog
-
-Installation goes through a **deterministic channel chain**:
-`configured sources (primary→backup) → curl manual install → git channel → EPERM cleanup retry
-→ repository subpackage expansion`. Only when all deterministic channels fail does the
-**local AI fallback** take over.
-
-**What it is**: a local AI subagent takes over the install — it diagnoses like a human
-(inspects repo structure, finds subpackages/aggregate packages, cleans leftovers), installs
-with the right package manager and writes the config. **Note: this step calls a DeepSeek API
-model and may incur API costs.**
-
-**Consent dialog (cost transparency)**:
-
-1. After all deterministic channels fail, the task enters "waiting for authorization" and a
-   top-most modal appears:
-   - explicitly states "will call a DeepSeek API model, may incur API costs"
-   - offers **Approve, continue** / **Cancel** (Cancel = zero cost)
-   - auto-cancels after 10 minutes
-2. The modal offers **"Don't ask again"** (auto-approve) — restorable at the bottom of the
-   marketplace page.
-3. The floating **"AI fallback"** toggle can disable the feature entirely: deterministic
-   failures cancel the install, **never calling a model API (zero cost)**.
-
----
-
-## Framework patch (cordis.patch.yml parse tolerance)
-
-**Problem (issue #5)**: if `cordis.patch.yml` contains a top-level `[]` placeholder plus
-later entries (two YAML root nodes), DSH fails at startup:
-`end of the stream or a document separator is expected`.
-
-**Fix location**: `parsePatchList` in the DSH framework `dsh-app-boot` — on parse failure,
-top-level empty-array placeholder lines are dropped (treated as no-op) and parsing retries;
-normal files, pure `[]` files, and indented sub-arrays are unaffected.
-
-**Apply** (re-run after every DSH upgrade, which overwrites framework files):
-
-```bash
-node scripts/apply-framework-patch.cjs
-```
-
-The script locates `dsh-app-boot/lib/index.js` in the npx cache, skips when already patched
-(idempotent), and keeps a `.bak-issue5` backup on first apply.
-
----
-
-## Security
-
-- All routes are loopback-only;
-- GitHub metadata is used only to discover public plugins; npm installs keep full TLS
-  validation against the registry;
-- GitHub search is browser-direct; Gitee/custom source requests and headers (including
-  credentials) are handled server-side only and never shipped to the browser;
-- Custom source URLs accept https and local/private http only (127.0.0.1, localhost,
-  10.x, 192.168.x, 172.16-31.x, etc.);
-- Skills are plain files (SKILL.md + assets) — installing a skill does **not** execute code;
-  the git clone comes from the repo you chose, review the repo before installing.
-
----
-
-## Disclaimer
+## Documentation
 
-- The marketplace lists third-party repositories from GitHub; each plugin is developed and
-  maintained by its own author and has **no affiliation with DeepSeek Harness or this hub**.
-- This hub makes **no warranty** about any plugin's quality, reliability, security, license
-  compliance or compatibility. Listing is **not an endorsement** — install means you have
-  reviewed and accepted the risk. Read the repo source and README before installing.
-- This hub is provided AS-IS; neither the hub nor its developers are liable for any damage
-  (data loss, system damage, privacy leaks) caused by installing or using third-party plugins.
+- [AI Empower 与服务器组件控制](docs/ai-empower.md)
+- [Framework upgrade safety & plugin adapt gate](docs/upgrade-safety-adapt-gate.md)
+- [How it works](docs/how-it-works.md) · [Compatibility](docs/compatibility.md) · [Project layout](docs/project-layout.md)
+- [HTTP endpoints](docs/http-endpoints.md) · [Local AI fallback & consent](docs/ai-fallback.md)
+- [Framework patch (cordis.patch.yml)](docs/framework-patch.md) · [Security & disclaimer](docs/security-disclaimer.md)
 
 ---
 

package/README.zh.md

@@ -6,145 +6,21 @@
 
 # DSH 插件中心（dsh-plugin-hub）
 
-> ## 🎉 v0.3.27 正式发布 — 全家桶分组卡片、永不崩安全与适配门强化（2026-09-04）
->
-> **全家桶分组卡片**：同根包子路径导出（如 `@linxin666/dsh-web-all/settings`）自动聚合为一张
-> 全家桶卡片（列表底部）——收起/展开、批量检测更新、**一键启用已适配**、已知校验预览，子卡剥离
-> `web-all/` 前缀。
-> **永不崩安全**：启用前子进程导入探针 + 补丁自动自愈（核心行恢复/缺失模块自动禁用）+
-> exports 回退 `package.json` 解析——记忆插件被误禁用的事故已修复。
-> **适配门强化**：源码扫描硬判据（0.3.6 假通过教训）、迁移检测（`dsh.migrate.to`）、
-> 依赖严格判定软化、待适配提示移入详情。
-> **子包删除安全**：删除聚合包子行仅停用该行、不动 bundle——修复"删一个子包导致整个全家桶消失"的事故。
->
-> **安装：**
-> ```bash
-> npm i -g @noob-stupid/dsh-plugin-console
-> # 或在 DSH 中：dsh plugin --profile web add @noob-stupid/dsh-plugin-console
-> ```
-> **体验入口：** 插件控制台 → 列表底部全家桶卡片 → 批量检测更新 / 一键启用已适配。
->
-> 反馈：[GitHub Issues](https://github.com/Noob-stupid/dsh-plugin-hub/issues)。
-
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
-[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
-[![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)
-[![License](https://img.shields.io/github/license/Noob-stupid/dsh-plugin-hub?style=flat-square)](LICENSE)
-[![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)
-[![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)
-[![topic: dsh-plugin](https://img.shields.io/badge/topic-dsh_plugin-4D6BFE?style=flat-square)](https://github.com/topics/dsh-plugin)
-[![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)
-[![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)
-[![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)
-[![dsh.so install](https://www.dsh.so/badge/install/dsh-plugin-hub.svg)](https://www.dsh.so/artifact/dsh-plugin-hub)
-
-给 DeepSeek Harness（DSH）Web 界面加上**插件管理面板**：一键启用/停用已安装插件，
-在**多个搜索源**上浏览 dsh-plugin 插件项目（GitHub / Gitee / 自定义源），一键添加并启用——
-并带一份 **CI 每 6 小时自动收录的静态插件/技能索引**。
-
-> ## 🎯 框架一键升级（v0.3.13 亮点）
->
-> 打开「插件管理」面板 → **插件市场** → `deepseek-ai/deepseek-harness` 卡片 →
-> 点 **「框架升级 → vX」**，一步完成：
-> **备份配置与框架本体（回滚点）→ 在线安装（服务不中断）→ 版本校验 → 失败自动回滚 → 自动重启生效**。
->
-> 升级后**自动重链框架配套包**（避免 pnpm 顶层链接滞后导致的混版本问题，如模型插件旧版缺失 vision 模型）。
-> 已实测：0.1.0-rc.8 → **0.1.1-rc.2** 全程自动、失败可回滚、升级后可正常使用。
-
-<!-- TOC -->
-- [核心优势](#核心优势)
-- [一键部署](#一键部署)
-- [使用方法](#使用方法)
-- [功能](#功能)
-- [原理](#原理)
-- [兼容性策略](#兼容性策略)
-- [项目结构](#项目结构)
-- [HTTP 接口](#http-接口)
-- [AI 兜底安装与授权弹窗](#ai-兜底安装与授权弹窗)
-- [框架层补丁（cordis.patch.yml 解析容错）](#框架层补丁cordispatchyml-解析容错)
-- [安全说明](#安全说明)
-- [免责声明](#免责声明)
-- [已知限制](#已知限制)
-- [帮助 / Help](#帮助--help)
-- [生态与收录](#生态与收录)
-- [支持](#支持)
-- [更新日志](#更新日志)
-- [License](#license)
-<!-- /TOC -->
-
----
-
-## 核心优势
-
-| | 优势 | 说明 |
-|---|---|---|
-| 🤖 | **AI 赋能（v0.3.24）** | 输入 npm 包名 / GitHub 仓库，本地 AI 读文档生成**部署计划**（安装/写配置/启动服务/健康检查），你确认后安全执行；服务器类组件自动生成控制卡片 |
-| 🛡️ | **框架升级适配门与安全（v0.3.25）** | 升级后不兼容插件强制禁用（适配门锁定，「检测更新 → 更新并适配 → 自动校验解锁」）；升级前全树 checkpoint、拉起失败自动全树回滚、框架卡片一键回滚到上一版 |
-| 🏠 | **全家桶分组卡片与安全（v0.3.27）** | 同根包子路径导出自动聚合为一张全家桶卡片（收起/展开、批量检测更新、一键启用已适配、已知校验预览）；永不崩安全（启用前导入探针 + 补丁自愈 + 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>
-
----
-
-## AI 赋能与服务器组件控制
-
-> **AI 赋能** — v0.3.24 正式版核心功能。
-
-在插件控制台输入 **npm 包名或 GitHub 仓库**（如 `OpenViking`、`@noob-stupid/dsh-plugin-console`）：
-
-1. **AI 读文档出计划**：子代理调研 README/docs，产出结构化计划（类型：纯插件 / 服务器组件 / 仅配置；步骤：安装 / 写配置 / 下载 / 启动服务 / 健康检查）；
-2. **你确认**（计划弹窗里逐步骤勾选）——安全护栏：命令/路径白名单、破坏性命令拦截、日志脱敏；
-3. **安全执行**：实时回显日志、可中断、幂等（已装 / 已下载 / 服务健康则复用）；
-4. **自动生成组件卡片**：服务器类组件注册到组件清单，卡片出现在主面板左侧（启动/停止/状态/【打开】直达 Web UI；多服务器时 ▾ 下拉；打开详情时自动隐藏；可折叠并有状态记忆）。
+> 一站式管理你的 DeepSeek Harness 插件：一键启用/停用、500+ 插件与技能市场一键安装、
+> 框架一键升级（失败自动回滚）。
 
-**内置 OpenViking 模板**：输入 `OpenViking` 秒出计划（pip 装 `openviking[local-embed]` → 下载中文嵌入模型 → 写 `ov.conf`（复用 DSH 的 DeepSeek 凭据）→ 启动服务器 → 健康检查）。
+## 为什么是 DSH 插件中心
 
-**模型配置**：默认跟随 DSH（`settings.yaml` + `.credentials.yaml`）；可建 `~/.dsh/plugin-console/ai-empower.json` 独立覆盖：
-
-```json
-{ "vlm": { "provider": "openai", "api_base": "https://api.deepseek.com", "model": "deepseek-v4-flash-vision-exp" }, "api_key": "sk-..." }
-```
-
----
-
-> **给插件作者**：给仓库打上 `dsh-plugin` 标签即可被官方 [topic 列表](https://github.com/topics/dsh-plugin)
-> 与本中心自动收录；技能类仓库请打 `agent-skills` / `claude-skills` / `dsh-skill`。
-
----
+- 🧩 **插件 + 技能双市场** — 自动收录 `dsh-plugin` 仓库（按 star **500+**）外加技能 tab；
+  浏览、搜索、一键安装，**零 GitHub API 调用**（CDN 分发，秒开零限流）。
+- 🚀 **框架一键升级** — 备份 → 在线安装（服务不中断）→ 校验 → **失败自动回滚**，端到端实测。
+- 🤖 **AI 赋能** — 输入 npm 包名或 GitHub 仓库，本地 AI 读文档生成**部署计划**
+  （安装/写配置/启动服务/健康检查），你确认后安全执行；服务器组件自动生成控制卡片。
+  → [详见](docs/ai-empower.zh.md)
 
 ## 一键部署
 
-### 方式一：官方命令（推荐）
-
-插件声明了 `dsh.bundle` 官方清单，一条命令装好并自动启用：
-
-```sh
+```bash
 # npm 发布版（推荐：预构建产物，无需 git / 构建授权）
 dsh plugin --profile web add @noob-stupid/dsh-plugin-console
 
@@ -152,14 +28,9 @@ dsh plugin --profile web add @noob-stupid/dsh-plugin-console
 dsh plugin --profile web add github:Noob-stupid/dsh-plugin-hub
 ```
 
-卸载 / 重装（即更新）：
+然后重启 dsh 服务 → 刷新页面 → **设置 → 插件 → 插件控制台**。
 
-```sh
-dsh plugin --profile web remove @noob-stupid/dsh-plugin-console
-dsh plugin --profile web add @noob-stupid/dsh-plugin-console
-```
-
-然后重启 dsh 服务 → 刷新页面 → 设置 → 插件 → 插件管理。
+<details><summary><b>更多部署方式</b>（部署脚本 / 一句话交给 AI）</summary>
 
 ### 方式二：部署脚本（网络受限时的兜底）
 
@@ -187,6 +58,45 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
 
 要求：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>
+
 ---
 
 ## 使用方法
@@ -234,37 +144,6 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
 - **卡片关闭语义**：终态（成功/失败）点叉号永久关闭（持久化）；进行中点叉号仅本次会话
   隐藏，刷新后恢复显示。
 
-### 框架升级适配门与升级安全（v0.3.25）
-
-> 缘起：2026-09-04 DSH `0.1.1-rc.2 → 0.1.2-rc.1` 升级事故——升级脚本在错误的工作目录执行，
-> 把新 CLI 原位覆盖进旧 `.pnpm` 目录、依赖树混版本，服务无法拉起。本版本把「升级安全」与
-> 「插件兼容检测」固化为控制台机制。
-
-**升级安全三件套**
-
-1. **框架安装根识别**：定位真正的框架安装根（含 `.pnpm` 的顶层 `node_modules`），修复
-   `require.resolve` 返回 `.pnpm` 内部 realpath 导致的「重链空转 / 新包覆盖旧目录」根因；
-   定位不到时**拒绝升级**（不 kill 服务、服务保持运行）；
-2. **升级前全树 checkpoint**：镜像 `.pnpm` 全部 `@deepseek-ai` 版本包 + 顶层 scope +
-   `lock.yaml`（写入 `~/.dsh/plugin-console/framework-backups/<版本>/fw-tree/`）；
-3. **拉起失败自动全树回滚并重试**：安装失败或服务拉起失败都会自动恢复升级前全树并再次拉起，
-   不再只留「请手动运行」提示；回滚后跳过重链/修复（避免对已恢复旧树二次破坏）。
-
-**一键回滚**：升级后框架卡片出现「回滚到上一版」按钮（`/plugin-console/framework-rollback`）：
-停服 → 全树恢复 → 自动拉起 → 健康检测，全程状态可见。
-
-**插件适配门（插件检测）**
-
-- 升级后写入 `~/.dsh/plugin-console/compat-pending.json` 的插件行被**强制禁用**，启用按钮
-  锁定（服务端 `/toggle` 直接 409，无法绕过）；行状态以按钮文案「待适配」提示；
-- 「详情」面板给出说明与入口：**检测更新 → 更新并适配**；
-- **更新后自动校验**：扫描最新版 `package.json` 的 `dsh.engines.framework` / `engines.dsh`
-  显式声明 + `@deepseek-ai/*` 依赖范围（内置零依赖 semver 判定器：依赖判定遵循 npm
-  prerelease 严格规则、声明判定宽松）；版本已变化且未判定不兼容 → **自动移除禁用块解锁**；
-  聚合包更新连带校验同步的子包；
-- **AI 赋能适配预检**：规划时服务端预检 registry 最新版声明与适配门命中情况，注入子代理
-  提示词（要求计划向用户解释适配结论），并在计划面板标注（不兼容标红）。
-
 ### 插件市场（多搜索源）
 
 - **搜索源切换**：点击顶部登录态标识弹出菜单，在 **GitHub / Gitee / 自定义源** 间切换（选择持久化）；
@@ -310,161 +189,13 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
 
 ---
 
-## 原理
-
-### 开关语义
-
-DSH 的 web profile 由 bundle 补丁层 + 用户补丁层（`$DSH_HOME/profiles/web/cordis.patch.yml`）
-组合而成，补丁是**逐键覆盖**语义。插件开关只是往用户补丁层追加/移除两行 YAML：
-
-```yaml
-- id: 插件条目id
-  disabled: true
-```
-
-配置文件监视器（HMR）会在保存后 1 秒内重组合，无需重启——除宿主代码本身变更外。
-
-### 安装链
-
-```
-配置的软件源按主→备依次尝试（默认 npmmirror → npmjs）
-  → curl 手动安装     （node 网络黑洞时：curl 下载 tarball 解压进 node_modules）
-  → git 通道          （GitHub 走加速代理+直连，Gitee 走对应平台）
-  → Windows EPERM 陈旧目录自动清理重试
-  → 自动展开仓库子包  （聚合包优先）
-  → 本地 AI 兜底      （置于明确费用授权弹窗之后）
-```
-
-技能安装独立走：`git clone --depth 1` → 复制 SKILL.md 资源到 `~/.dsh/skills/<名称>/`
-（不碰 npm、不写补丁、无需重启）。
-
-### 数据源
-
-```
-GitHub Actions（每 6 小时，仓库自带 token）
-  └─ scripts/build-index.cjs：分页拉取 topic:dsh-plugin（按 star 500 个）+ 技能 topic（300 个）
-       └─ 提交 marketplace/index.json 回 main
-            └─ 宿主经 jsDelivr CDN 读取（10 分钟缓存）→ 市场秒开、零 API 调用
-                 └─ 实时搜索仍走 GitHub 搜索 API（浏览器直连 + 服务端通道兜底）
-```
-
-### 版本检测与已安装识别
-
-- **已安装识别**：按已装条目的 `repository` 字段或模块名与市场条目比对（仓库名 → 包名映射）；
-- **版本检测**：`check-update` 走 curl 读 npm `dist-tags.latest`；聚合包额外对比子包
-  声明版本 vs 本地实际版本（depsOutdated），防止半更新混搭导致启动冲突。
-
----
-
-## 兼容性策略
-
-- 当前支持 **DSH 0.1.0 系列**（`0.1.0-rc.6` 及同系列版本）。
-- 面板会读取运行中的 `@deepseek-ai/dsh-web-app` 版本：官方发布破坏性升级
-  （0.2 / 1.0 等）后，面板顶部会显示兼容性警告并给出本仓库地址，而不是默默失效。
-- **插件适配门（v0.3.25）**：框架升级后不兼容的第三方插件会被**强制禁用**（启用按钮锁定）；
-  请先「检测更新」升级该插件，更新并通过自动校验后才会解锁——详见
-  「框架升级适配门与升级安全」。
-- 官方破坏性更新可能改动的接口：补丁层语义、`webServer.register`、
-  加载器条目结构、`dsh.client` bundle 格式、`settings.plugins.tab` 插槽。
-  届时随官方版本更新本仓库即可（依赖面已收窄到上述几个点）。
-- 部署脚本不校验版本、直接安装；面板里的警告是权威提示。
-
----
-
-## 项目结构
-
-```
-lib/index.js       宿主端插件（/plugin-console/* 路由 + 补丁读写 + 多源检索 + 安装）
-lib/client.js      浏览器端 bundle（ModuleLoader 格式，设置页 tab）
-scripts/build-index.cjs        索引构建（插件 --limit 500 / 技能 --skills --limit 300）
-scripts/apply-framework-patch.cjs   框架层补丁（issue #5，幂等，可重复应用）
-.github/workflows/registry.yml 自动收录 CI（每 6 小时 + 手动触发）
-marketplace/index.json         生成的静态索引（jsDelivr CDN 分发）
-deploy.ps1 / deploy.sh   一键部署脚本（Windows / Linux·macOS）
-test-harness.mjs   逻辑自检（state/toggle/校验/环回保护；搜索视网络环境 SKIP）
-test-compat-gate.mjs   适配门单元测试（内置 semver 判定器：声明/依赖兼容规则）
-```
-<img width="1878" height="945" alt="image" src="https://github.com/user-attachments/assets/b26f2f19-0ba4-4be7-9ca1-b3fd4c51a7a8" />
-
----
-
-## HTTP 接口
-
-| 接口 | 方法 | 说明 |
-|---|---|---|
-| `/plugin-console/state` | GET | 插件清单 + 补丁状态 + 兼容性 + 运行中的安装任务 |
-| `/plugin-console/toggle` | POST | 启用/停用条目（写用户补丁层） |
-| `/plugin-console/uninstall` | POST | 删除条目并卸载包（bundle 感知） |
-| `/plugin-console/search` | POST | 多源搜索（github/gitee/自定义，`multi` 合并） |
-| `/plugin-console/repo` | POST | 仓库元数据：package.json、private 根、dsh 提示、**hasSkill** |
-| `/plugin-console/enrich` | POST | 服务端类型标记（官方/聚合/技能） |
-| `/plugin-console/install` | POST | 安装（插件或 `kind: skill` 技能），返回任务 id |
-| `/plugin-console/install-status` | POST | 轮询安装任务 |
-| `/plugin-console/check-update` | POST | npm 最新版本 + 子包不配套检查 |
-| `/plugin-console/market-index` | POST | 静态索引（jsDelivr CDN，10 分钟缓存） |
-| `/plugin-console/skills-installed` | GET | `~/.dsh/skills` 下已安装技能 |
-| `/plugin-console/sources` | GET/POST | 软件源与搜索源管理、Gitee OAuth 配置 |
-| `/plugin-console/gitee-oauth-url` / `gitee-oauth-callback` | GET | Gitee OAuth 流程 |
-| `/plugin-console/ai-consent` | POST | 同意/取消 AI 兜底步骤 |
-| `/plugin-console/restart` | POST | 自带守护的安全自重启（等同面板按钮） |
-| `/plugin-console/framework-upgrade` | POST | 框架一键升级（全树 checkpoint → 在线安装 → 全树回滚保护） |
-| `/plugin-console/framework-rollback` | POST | 一键回滚到升级前版本（停服 → 全树恢复 → 自动拉起 → 健康检测） |
-| `/plugin-console/self-update` | POST | 控制台自身一键更新（npm 最新 tarball 到当前 profile） |
-| `/plugin-console/ai-empower/plan` / `status` / `run` / `cancel` | POST | AI 赋能：规划（含框架适配预检）→ 状态轮询 → 确认执行 → 取消 |
-| `/plugin-console/components` / `component/start` / `stop` / `status` | GET/POST | 服务器组件清单与启动/停止/状态 |
-
----
-
-## AI 兜底安装与授权弹窗
-
-安装走**确定性通道链**：`配置源（主→备）→ curl 手动安装 → git 通道 → EPERM 清理重试 → 仓库子包展开`。常规通道全部失败时，才轮到**本地 AI 兜底**。
-
-**本地 AI 兜底是什么**：拉起一个本地 AI 子代理接管安装——它会像人工一样诊断（查仓库结构、识别子包/聚合包、清理残留），用正确管理器完成安装并落配置。**注意：这一步会调用 DeepSeek API 模型，可能产生 API 费用。**
-
-**授权弹窗逻辑（费用透明）**：
-
-1. 常规通道全失败后，任务进入「等待授权」状态，屏幕中央弹出**最上层模态框**：
-   - 明确说明"将调用 DeepSeek API 模型，可能产生 API 费用"
-   - 提供 **同意，继续** / **取消** 两个按钮（取消 = 零费用）
-   - 10 分钟未决定自动取消
-2. 模态框内可勾选 **"以后不再提醒"**（自动同意）——勾选后可随时在**插件市场页面最底部**恢复弹窗提醒
-3. 右上角悬浮的 **"AI 兜底"开关**可彻底关闭该功能：常规通道失败将直接取消安装，**永远不会调用模型 API（零费用）**
-
----
-
-## 框架层补丁（cordis.patch.yml 解析容错）
-
-**问题（issue #5）**：`cordis.patch.yml` 若含顶格 `[]` 占位符 + 后续条目（两个 YAML 根节点），
-DSH 启动时解析崩溃：`end of the stream or a document separator is expected`。
-
-**修复位置**：DSH 框架 `dsh-app-boot` 的 `parsePatchList`——解析失败时自动移除顶格空数组占位行（视为 no-op）后重试；
-正常文件、纯 `[]` 文件、缩进子数组均不受影响。
-
-**应用方式**（DSH 升级后需重新执行，升级会覆盖框架文件）：
-
-```bash
-node scripts/apply-framework-patch.cjs
-```
-
-脚本自动定位 npx 缓存中的 `dsh-app-boot/lib/index.js`，检测到已补丁则跳过（幂等），首次应用会保留 `.bak-issue5` 备份。
-
----
-
-## 安全说明
-
-- 全部路由仅允许环回地址访问；
-- GitHub 元数据只用于发现公开插件，npm 安装走 registry 的完整 TLS 校验；
-- GitHub 源搜索在浏览器内直连；Gitee / 自定义源检索与请求头（含认证信息）仅经服务端处理，不下发浏览器；
-- 自定义源地址仅允许 https 与本机/私网 http（127.0.0.1、localhost、10.x、192.168.x、172.16-31.x 等）；
-- 技能是纯文件（SKILL.md + 资源）——安装技能**不会执行任何代码**；git clone 来自你选择的仓库，安装前请自行核验。
-
----
-
-## 免责声明
+## 文档
 
-- 市场收录的均为 GitHub 第三方仓库，各插件由各自作者独立开发维护，**与 DeepSeek Harness 及本插件中心无任何关联**；
-- 本中心**不对任何插件的质量、可靠性、安全性、许可证合规性、兼容性作任何明示或默示担保**；收录**不构成推荐或背书**——安装即代表你已自行评估并接受相应风险，建议安装前阅读仓库源码与 README；
-- 本中心按「现状」（AS-IS）提供，因安装或使用任何第三方插件造成的任何直接或间接损失（数据丢失、系统损坏、隐私泄露等），本中心及其开发者不承担任何责任。
+- [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)
 
 ---
 

package/lib/index.js

@@ -179,26 +179,37 @@ function baseDirOf(baseUrl) {
  * （2026-09-04 教训：@openviking/dsh-memory-plugin 因此被 heal 误判模块缺失并自动禁用）——
  * fallback 直接查 node_modules 物理路径。
  */
-function resolvePackageJson(pkgName, baseDir) {
+function resolvePackageJson(pkgName, baseDir, fallbackBase) {
   const name = packageNameOf(pkgName)
   try {
     return createRequire(join(baseDir, 'package.json')).resolve(`${name}/package.json`)
   } catch {}
   const parts = String(name).split('/')
   const candidate = join(baseDir, 'node_modules', ...parts, 'package.json')
-  return existsSync(candidate) ? candidate : null
+  if (existsSync(candidate)) return candidate
+  // issue #15：npm 全局安装 dsh 时 ctx.baseUrl 落在框架安装树（而非 profile node_modules），
+  // 官方 @deepseek-ai/* 恰好可见、第三方插件全部解析失败 → 详情/版本/仓库全空。
+  // 回退到 profile 目录（fallbackBase）再试一次。
+  if (typeof fallbackBase === 'string' && fallbackBase !== '' && fallbackBase !== baseDir) {
+    try {
+      return createRequire(join(fallbackBase, 'package.json')).resolve(`${name}/package.json`)
+    } catch {}
+    const candidate2 = join(fallbackBase, 'node_modules', ...parts, 'package.json')
+    if (existsSync(candidate2)) return candidate2
+  }
+  return null
 }
 
 /** 已加载插件的包元信息缓存（安装日期/版本/仓库），60 秒 TTL。 */
 const pkgMetaCache = new Map()
 const PKG_META_TTL = 60000
-function entryPkgMeta(moduleName, baseUrl) {
+function entryPkgMeta(moduleName, baseUrl, profileDir) {
   if (typeof moduleName !== 'string' || moduleName.startsWith('cordis:')) return null
   const hit = pkgMetaCache.get(moduleName)
   if (hit !== undefined && Date.now() - hit.at < PKG_META_TTL) return hit
   const meta = { at: Date.now(), installDate: null, version: null, repository: null }
   try {
-    const pkgPath = resolvePackageJson(moduleName, baseDirOf(baseUrl))
+    const pkgPath = resolvePackageJson(moduleName, baseDirOf(baseUrl), profileDir ?? null)
     if (pkgPath === null) throw new Error('not found')
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
     // 安装日期：优先 curl 通道写入的 .dsh-installed-at 标记（真实安装时刻）；
@@ -1061,7 +1072,7 @@ function backupProfileSnapshot(profileDir, version, ctx) {
   try { copyFileSync(join(profileDir, 'package.json'), join(dir, 'profile-package.json')) } catch {}
   try {
     const plugins = listEntries(ctx).map((e) => {
-      const meta = entryPkgMeta(e.moduleName, ctx.baseUrl ?? 'file:///')
+      const meta = entryPkgMeta(e.moduleName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
       return { rowId: e.rowId, moduleName: e.moduleName, enabled: e.enabled, version: meta?.version ?? null, installDate: meta?.installDate ?? null }
     })
     writeFileSync(join(dir, 'plugins.json'), JSON.stringify(plugins, null, 2), 'utf8')
@@ -1106,6 +1117,15 @@ function findPatchPath(ctx) {
   return defaultPatchPath()
 }
 
+/** profile 根目录（resolvePackageJson 的 fallbackBase 用；失败返回 null）。 */
+function profileDirOf(ctx) {
+  try {
+    return dirname(findPatchPath(ctx))
+  } catch {
+    return null
+  }
+}
+
 /** 读取补丁文件并扫描：停用块与 insert 行的 id。 */
 async function readPatchState(patchPath) {
   let text = ''
@@ -1187,10 +1207,10 @@ function summarizeReadme(text) {
 }
 
 /** 读取一个已加载插件的 package.json 元信息与 README 摘要。 */
-async function readPluginDetails(moduleName, baseUrl) {
+async function readPluginDetails(moduleName, baseUrl, profileDir) {
   if (typeof moduleName !== 'string' || moduleName.startsWith('cordis:')) return { meta: null, readme: null }
   try {
-    const pkgPath = resolvePackageJson(moduleName, baseDirOf(baseUrl))
+    const pkgPath = resolvePackageJson(moduleName, baseDirOf(baseUrl), profileDir ?? null)
     if (pkgPath === null) throw new Error('not found')
     const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
     const meta = {
@@ -3877,7 +3897,7 @@ async function runInstallJob(job, ctx) {
           let ghRepo = typeof job.repo === 'string' && job.repo !== '' && job.repo.includes('/') ? job.repo : null
           if (ghRepo === null) {
             try {
-              const meta = entryPkgMeta(name, ctx.baseUrl ?? 'file:///')
+              const meta = entryPkgMeta(name, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
               const repoUrl = typeof meta?.repository === 'string' ? meta.repository : (meta?.repository && typeof meta.repository === 'object' ? meta.repository.url : null)
               const m = typeof repoUrl === 'string' ? repoUrl.replace(/^git\+/u, '').match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/u) : null
               if (m) ghRepo = m[1]
@@ -4110,7 +4130,7 @@ async function handle(ctx, req, res) {
       }
     } catch {}
     const entries = listEntries(ctx).map((entry) => {
-      const meta = entryPkgMeta(entry.moduleName, ctx.baseUrl ?? 'file:///')
+      const meta = entryPkgMeta(entry.moduleName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
       return {
         ...entry,
         userDisabled: patch.disables.includes(entry.rowId),
@@ -4301,7 +4321,7 @@ async function handle(ctx, req, res) {
       return
     }
     const moduleName = entry.options.name
-    const details = await readPluginDetails(moduleName, ctx.baseUrl ?? 'file:///')
+    const details = await readPluginDetails(moduleName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
     sendJson(res, 200, { ok: true, entryId, rowId: rowIdOf(ctx, entryId), moduleName, ...details })
     return
   }
@@ -4985,7 +5005,7 @@ async function handle(ctx, req, res) {
       // 覆盖 dsh-plugin-console（本面板）这类"源码在 GitHub、npm 上不存在"的宿主插件。
       let fallbackError = err instanceof Error ? err.message : String(err)
       try {
-        const meta = entryPkgMeta(packageName, ctx.baseUrl ?? 'file:///')
+        const meta = entryPkgMeta(packageName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
         const repo = typeof meta?.repository === 'string'
           ? meta.repository.replace(/^git\+/u, '').replace(/\.git$/u, '')
           : (meta?.repository && typeof meta.repository === 'object' ? meta.repository.url : null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "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",