npm - @gyp8735abc/dsh-mcp-manager - Versions diffs - 0.0.0-stage → 0.2.0 - Mend

@gyp8735abc/dsh-mcp-manager 0.0.0-stage → 0.2.0

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 (13) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,48 @@
+# Changelog
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.2.0] — 2026-11-01
+First public release, as `@gyp8735abc/dsh-mcp-manager`.
+### Added
+- Per-workspace MCP switching: a popup on each workspace row lists that
+  workspace's own `.mcp.json` servers, the global servers from `~/.claude.json`,
+  profile-declared ("manual") servers, and the skills visible to the workspace,
+  each with its own switch.
+- Per-workspace skill switching, enforced for the model through a
+  `SkillRegistry` prototype filter plus a `tools.guard()` refusal.
+- Union mounting: every workspace with a live session keeps its MCP servers
+  mounted, one process per (workspace, server); focusing another session never
+  stops them, and a workspace's servers unload with its last session.
+- Session-scoped tool filtering, so another live workspace's `mcp__*` tools never
+  reach the current session.
+- Claude Code compatibility: project `.claude/skills` and user `~/.claude/skills`
+  roots, including `SKILL.md` files without YAML frontmatter.
+- Dynamic rescan on every popup open, so workspaces and `.mcp.json` edits apply
+  without restarting.
+- `GET /api/dsh-mcp-manager/inventory`, `POST /api/dsh-mcp-manager/activate` and
+  `POST /api/dsh-mcp-manager/set` endpoints.
+- Plugin market index entry (`docs/index.json`) for one-click installs from the
+  Plugins → Discover tab.
+### Changed
+- State moved out of the DSH settings namespace into
+  `$DSH_HOME/mcp-manager/state.json`; the legacy `mcp:` settings section is
+  imported once on first start.
+- No core package is patched any more: the workspace-row button, the Claude skill
+  roots and the skill filter are all implemented through public seams
+  (`MutationObserver` DOM injection, `ctx.skills.registerProvider()`,
+  `SkillRegistry.prototype`).
+### Known limitations
+- No filesystem watcher for skills; a skill added while DSH runs appears after a
+  restart.
+- The workspace-row button is injected into the sidebar DOM, because DSH 0.2.x
+  declares slots for session rows only.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 gyp8735abc
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,3 +1,279 @@
-# Temporary Holding Version
+# dsh-mcp-manager
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh.md) · [![npm](https://img.shields.io/npm/v/@gyp8735abc/dsh-mcp-manager)](https://www.npmjs.com/package/@gyp8735abc/dsh-mcp-manager) · [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+A **per-workspace** MCP and skill manager for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+One button on each workspace row opens a popup where you decide which MCP servers and which
+skills that workspace gets. Global MCP, project MCP and skills all switch **independently per
+workspace**.
+## The problem it solves
+DSH's own MCP configuration is **profile-wide**: whatever is in `mcp:` applies to every
+workspace and every session. In daily use that means:
+- `codebase` is useful in project A and in project B, but the two projects keep different
+  `.codebase/codebase.db` files — one global config can only point at one of them.
+- You keep five MCP servers around, but this workspace needs one. The other four hold their
+  processes open and stuff the tool list, so the model picks the wrong tool more often.
+- The same for skills: the dozens under `~/.claude/skills` show up in every session although
+  only a couple of workspaces really want them.
+This plugin moves the switches down to the **workspace** layer:
+| Object | Source | Switch granularity |
+|---|---|---|
+| Global MCP | `mcpServers` in `~/.claude.json` | per workspace |
+| Project MCP | the workspace's own `.mcp.json` | per workspace |
+| Manual MCP | hand-written `dsh-mcp-client` rows in the profile | per workspace |
+| Skills | `.dsh/skills`, `.claude/skills`, `.agents/skills`, `~/.dsh/skills`, `~/.claude/skills`, `~/.agents/skills` | per workspace |
+## Features
+- **One popup for everything** — grouped into project MCP / global MCP / manual MCP / project
+  skills / global skills, one switch per row, with `Enabled`/`Disabled` and
+  `Connected`/`Not connected` shown inline.
+- **Real per-workspace isolation** — the state key is the workspace path; a server you turn
+  off in A stays on in B.
+- **Union mounting** — every workspace with a live session keeps its own MCP servers mounted,
+  one process per (workspace, server) with its own config and `cwd`. Focusing or switching a
+  session never stops another workspace's servers; a workspace's servers unload with its last
+  session.
+- **Session-scoped tool filtering** — only this workspace's `mcp__<workspace>__*` tools plus
+  global/manual ones reach the current session, so another live workspace's tools never leak in.
+- **Skills filtered the same way** — a disabled skill disappears from the model's catalog and
+  from `/name` injection, and a direct `skill` tool call is refused with an explicit reason.
+- **Claude Code skill compatibility** — project `.claude/skills` and user `~/.claude/skills`
+  are scanned, including `SKILL.md` files without YAML frontmatter.
+- **Dynamic rescan** — every popup open re-reads the workspace list and each workspace's
+  `.mcp.json`, so new workspaces and edited configs apply without restarting DSH.
+- **Zero core patches** — nothing inside the DSH installation is modified; installing or
+  removing the plugin only touches the profile and `$DSH_HOME`.
+- **Bilingual UI** — follows the DSH interface language (English / 简体中文).
+## Install
+### Option 1: plugin market (two steps)
+1. Open **Plugins → Discover → Add index source** and enter:
+   ```
+   https://gyp8735abc.github.io/dsh-mcp-manager/index.json
+   ```
+2. Search for `MCP manager`, open the entry, press **Install**.
+> Market indexes are unsigned; titles, authors and sources are publisher claims. Only add
+> index sources you trust, and check in the confirmation dialog that the source is
+> `@gyp8735abc/dsh-mcp-manager`.
+### Option 2: one command
+```sh
+dsh plugin --profile web add @gyp8735abc/dsh-mcp-manager
+```
+The package is also a DSH bundle (`dsh.bundle.patch`), so the plugin row is inserted into the
+profile composition automatically — no hand-written `cordis.patch.yml` needed.
+### Option 3: from source
+```sh
+git clone https://github.com/gyp8735abc/dsh-mcp-manager.git
+cd dsh-mcp-manager
+dsh plugin --profile web add .
+```
+### Verify
+```sh
+dsh --profile web --dump-config | grep -A 3 dsh-mcp-manager
+```
+Seeing `id: dsh-mcp-manager` means it is in the composition tree. Then **restart `dsh web`**
+and hard-reload the browser (`Ctrl+Shift+R`) — the client bundle is injected at startup only.
+After that, every workspace row gains a plug icon to the left of its `⋯` menu.
+## Usage
+The popup shows:
+```
+┌ MCP & skills ───────────────────────────────┐
+│ Workspace  D:\ai-workspace   Active          │
+│                                              │
+│ Project MCP (.mcp.json)                      │
+│   ● codebase      stdio   Enabled  Connected │
+│   ○ e2e-runner    stdio   Disabled —         │
+│                                              │
+│ Global MCP (~/.claude.json)                  │
+│   ● everything-search  http  Enabled Connected│
+│                                              │
+│ Manual MCP (profile)                         │
+│   ○ codegraph     stdio   Disabled —         │
+│                                              │
+│ Project skills (this workspace)              │
+│   ● officecli  .dsh    Enabled               │
+│   ○ probe      .claude Disabled              │
+│                                              │
+│ Global skills (all workspaces)               │
+│   ● diagnose-windows-sandbox-acl  ~/.dsh     │
+└──────────────────────────────────────────────┘
+```
+- **Active workspace** (noted at the top): toggles apply **immediately** — enabling connects the
+  process and registers its tools, disabling disconnects and unmounts them.
+- **Not the active workspace**: toggles only save state; the servers mount when that workspace
+  gets a session.
+- Empty groups are hidden; a workspace with nothing to show gets an empty-state hint.
+- Project servers carry a workspace prefix at runtime: `codebase` in workspace A becomes
+  `a__codebase`, and the model sees `mcp__a__codebase__search_code`. That is what lets two
+  workspaces' same-named servers coexist as separate processes instead of shadowing each other.
+## State
+`$DSH_HOME/mcp-manager/state.json` (`$DSH_HOME` defaults to `~/.dsh`):
+```json
+{
+  "projects": [
+    {
+      "path": "D:\\ai-workspace",
+      "disabled": ["dsh-mcp-manager__codebase"],
+      "disabledSkills": ["office"]
+    }
+  ]
+}
+```
+| Field | Meaning |
+|---|---|
+| `path` | Absolute workspace path (identity key) |
+| `disabled` | MCP runtime names disabled in this workspace; project servers use the workspace-qualified name (`<slug>__<name>`), global/manual servers their plain name |
+| `disabledSkills` | Skill names disabled in this workspace |
+- On first start the legacy `mcp:` section of `$DSH_HOME/settings.yaml` is imported once.
+- Both qualified and legacy plain names (`codebase`) are honoured in `disabled`, so old lists
+  keep working.
+- Editing the file by hand takes effect on restart or on the next popup open.
+### HTTP API
+The popup uses three same-origin endpoints, which you can also call yourself:
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/dsh-mcp-manager/inventory?active=<workspace path>` | Full inventory for one workspace (MCP groups, skills, connection state) |
+| `POST` | `/api/dsh-mcp-manager/activate` | `{ "path": "..." }` — remember the focused workspace |
+| `POST` | `/api/dsh-mcp-manager/set` | `{ "path": "...", "kind": "mcp"\|"skill", "name": "...", "enabled": true }` |
+## Mounting semantics
+- **Union model**: the mount set is the union of what every workspace with a live session wants.
+  With no live session it falls back to the focused workspace's set.
+- **Process granularity**: one process per (workspace, server) for project servers, with `cwd`
+  defaulting to the workspace directory — so relative paths such as `.codebase/codebase.db`
+  land in their own workspace.
+- **Global servers**: one shared process, mounted while any live workspace enables it.
+- **Manual servers** (hand-written `dsh-mcp-client` rows): kept enabled while any live workspace
+  wants them, because one loader row can only own one process.
+- **Unmount**: a workspace's dedicated processes are disposed after its last session closes, and
+  the manager sweeps leftover child processes by their command-line signature.
+- **Orphans**: when a managed server is disabled or unmounted, a sweep kills leftover children
+  so stdio servers do not survive as stray processes.
+## Skills
+- Roots are merged with **lowest rank winning**, one entry per skill name:
+  | Order | Root | Source tag |
+  |---|---|---|
+  | 1 | `<workspace>/.dsh/skills` | `project-dsh` |
+  | 2 | `<workspace>/.claude/skills` | `project-claude` |
+  | 3 | `<workspace>/.agents/skills` | `project-agents` |
+  | 4 | `~/.dsh/skills` | `user-dsh` |
+  | 5 | `~/.claude/skills` | `user-claude` |
+  | 6 | `~/.agents/skills` | `user-agents` |
+  The `.claude` roots and the frontmatter-less parser are added through
+  `ctx.skills.registerProvider()` — the same public seam the shipped provider uses — so no core
+  package is patched.
+- A skill is `<dir>/SKILL.md` or a bare `.md` file directly under a root. Without frontmatter the
+  directory name becomes the skill name and the first body line the description (the usual Claude
+  Code shape).
+- A disabled skill takes effect in three places: the session catalog stops listing it,
+  `/skill-name` is no longer injected, and the `skill` tool refuses it with an explicit
+  “disabled for this workspace” message.
+## Compatibility
+| Item | Requirement |
+|---|---|
+| DSH | `>=0.2.0-rc.2 <0.3.0` (checked against the running version at install time) |
+| Node.js | `>=22` |
+| Surface | Web only (`dsh web` and the desktop GUI's web view); `headless` / `acp` have no UI entry |
+The only runtime dependencies are packages that ship with the DSH installation
+(`@deepseek-ai/dsh-mcp-client` etc.); the plugin itself has none.
+## Known limitations
+- **No skill file watcher** — a skill added to `.claude/skills` while DSH is running appears after
+  a restart (existing and project skills all load at startup).
+- **The workspace button is DOM-injected** — DSH 0.2.x declares slots for session rows only, so
+  the button is inserted with a `MutationObserver` and re-added after re-renders. If it does not
+  show up, first check that the DSH version is inside `>=0.2.0-rc.2 <0.3.0`.
+- **The skill filter patches a prototype** — it affects every consumer of the skill service (for
+  example a skill picker UI). That is intended: the switch is per workspace and every lookup
+  carries the `cwd`.
+- **State is not in the DSH settings page** — DSH 0.2.x no longer lets a plugin claim an arbitrary
+  settings namespace, so the switches live in the plugin's own `state.json`.
+- **Non-active workspaces only save state** — they do not spawn processes eagerly, which keeps
+  unused workspaces from holding servers open.
+## Security
+- The plugin spawns the **stdio commands** declared in project `.mcp.json` files and
+  `~/.claude.json` — that is the same trust you would give that configuration. Only use it with
+  repositories and configs you trust.
+- The three HTTP endpoints are **unauthenticated**; the design assumes `dsh web` listens on
+  loopback only (the default `127.0.0.1`). With `--host 0.0.0.0`, anyone who can reach the port
+  can toggle your MCP servers.
+- The plugin never modifies the DSH installation and never writes `settings.yaml`; its only write
+  is `$DSH_HOME/mcp-manager/state.json`.
+## Development
+```sh
+node --check lib/index.js        # host: inventory, per-workspace state, union mounting, routes
+node --check lib/skill-filter.js # skill filter (SkillRegistry prototype + tools.guard)
+node --check lib/skill-roots.js  # Claude skill-root provider
+node --check client/client.js    # browser bundle (ModuleLoader factory form)
+npm run pack:check               # verify the npm package contents (run before publishing)
+npm run market:index             # regenerate docs/index.json
+```
+| Path | Purpose |
+|---|---|
+| `lib/index.js` | Host: state, `inventory` / `activate` / `set`, union mounting, session tool filtering |
+| `lib/skill-filter.js` | Per-workspace skill filtering (catalog, injection, tool call) |
+| `lib/skill-roots.js` | `.claude` roots and frontmatter-less `SKILL.md` parsing |
+| `client/client.js` | Browser half: workspace-row button and the popup (English / 中文) |
+| `cordis.patch.yml` | Bundle patch that inserts the plugin row |
+| `locale/{en,zh}.json` | Title/description shown on the Plugins page |
+| `docs/index.json` | Plugin market index (format 1), served from GitHub Pages |
+| `docs/PUBLISHING.md` | Release process (npm, GitHub, market index) |
+The browser half is a **hand-written ModuleLoader bundle**
+(`window.__ModuleLoader__.load({ factory })`) with no build step — edit and reload the page.
+## Publishing
+See [docs/PUBLISHING.md](docs/PUBLISHING.md).
+## License
+[MIT](LICENSE)

package/README.zh.md ADDED Viewed

@@ -0,0 +1,263 @@
+# dsh-mcp-manager
+[English](README.md) | 中文 · [![npm](https://img.shields.io/npm/v/@gyp8735abc/dsh-mcp-manager)](https://www.npmjs.com/package/@gyp8735abc/dsh-mcp-manager) · [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的 **按工作区** MCP 与技能管理器。
+在每个工作区行点一个按钮，就能决定「这个工作区要挂哪些 MCP 服务器、要看哪些技能」——
+全局 MCP 和项目 MCP 的开关**按工作区独立**，互不影响。
+## 它解决什么问题
+DSH 自带的 MCP 配置是 **profile 级**的：`mcp:` 里写什么，所有工作区、所有会话都吃同一份。
+于是日常用起来是这样的：
+- 你在 A 项目里用 `codebase`（SQLite 索引）、在 B 项目里也想用，但两边的 `.codebase/codebase.db`
+  是不同文件——一份全局配置只能指向一个库；
+- 你常开 5 个 MCP 服务器，但当前这个工作区只需要 1 个，另外 4 个的进程白白常驻，
+  工具列表也被塞满，模型选错工具的概率跟着上去；
+- 技能同理：用户级 `~/.claude/skills` 下的几十个技能，在每个会话里都出现，
+  但只有个别工作区真的需要它们。
+这个插件把「开关」下沉到**工作区**这一层：
+| 对象 | 来源 | 开关粒度 |
+|---|---|---|
+| 全局 MCP | `~/.claude.json` 的 `mcpServers` | 每个工作区独立 |
+| 项目 MCP | 该工作区自己的 `.mcp.json` | 每个工作区独立 |
+| 手动 MCP | profile 配置里手写的 `dsh-mcp-client` 行 | 每个工作区独立 |
+| 技能 | `.dsh/skills`、`.claude/skills`、`.agents/skills`、`~/.dsh/skills`、`~/.claude/skills`、`~/.agents/skills` | 每个工作区独立 |
+## 功能
+- **一个弹窗管全部** — 弹窗按「项目 MCP / 全局 MCP / 手动 MCP / 项目技能 / 全局技能」分组，
+  每行一个开关，直接显示 `已启用 / 已停用` 与 `已连接 / 未连接`。
+- **真正的按工作区隔离** — 状态键是工作区路径；在 A 里关掉的服务器，B 照常启用。
+- **并集挂载，切换不打架** — 所有「有存活会话」的工作区同时挂载各自的 MCP，每个
+  （工作区, 服务器）一个独立进程（各自的配置和 `cwd`）。切换/聚焦会话**不会**停掉别的工作区的 MCP；
+  某个工作区的 MCP 在它最后一个会话关闭后才卸载。
+- **会话级工具过滤** — 只有本工作区的 `mcp__<工作区>__*` 和全局/手动服务器进入当前会话的
+  工具列表，别的工作区挂着的服务器不会漏进来。
+- **技能也按工作区过滤** — 停用的技能从模型侧目录里消失、`skill` 工具调用会被明确拒绝，
+  而不是变成「未知工具」。
+- **兼容 Claude Code 的技能目录** — 项目 `.claude/skills` 与用户 `~/.claude/skills` 都会被扫描，
+  包括没有 YAML frontmatter 的 `SKILL.md`。
+- **动态扫描** — 每次打开弹窗都重新读工作区列表与各工作区的 `.mcp.json`，
+  新增工作区、改配置文件都不需要重启 DSH。
+- **零核心补丁** — 不改 DSH 安装目录里的任何文件，装/卸插件只动 profile 与 `$DSH_HOME`。
+- **中英双语 UI** — 跟随 DSH 界面语言。
+## 安装
+### 方式一：插件市场（推荐，两步）
+1. 打开 **插件 → 发现 → 添加索引源**，填入：
+   ```
+   https://gyp8735abc.github.io/dsh-mcp-manager/index.json
+   ```
+2. 搜索 `MCP manager`，打开条目，点 **安装**。
+> 索引没有签名，市场里的标题、作者、来源都是发布方的声明。只添加你信任的索引源，
+> 并在安装确认框里核对来源是 `@gyp8735abc/dsh-mcp-manager`。
+### 方式二：一条命令
+```sh
+dsh plugin --profile web add @gyp8735abc/dsh-mcp-manager
+```
+本包同时是一个 DSH bundle（`dsh.bundle.patch`），安装后插件行会自动插入 profile 的组合，
+不需要手写 `cordis.patch.yml`。
+### 方式三：从源码
+```sh
+git clone https://github.com/gyp8735abc/dsh-mcp-manager.git
+cd dsh-mcp-manager
+dsh plugin --profile web add .
+```
+### 验证安装
+```sh
+dsh --profile web --dump-config | grep -A 3 dsh-mcp-manager
+```
+能看到 `id: dsh-mcp-manager` 就说明它已经进组合树。然后**重启 `dsh web`** 并强制刷新浏览器
+（`Ctrl+Shift+R`）——浏览器端的 bundle 只在启动时注入。
+装好后，工作区列表每一行的 `⋯` 菜单**左边**会多出一个插头图标按钮。
+## 使用
+点工作区行上的插头按钮，弹窗会显示：
+```
+┌ MCP 与技能 ────────────────────────────────┐
+│ 工作区  D:\ai-workspace      当前工作区      │
+│                                               │
+│ 项目 MCP（.mcp.json）                         │
+│   ● codebase      stdio   已启用  已连接      │
+│   ○ e2e-runner    stdio   已停用  未连接      │
+│                                               │
+│ 全局 MCP（~/.claude.json）                    │
+│   ● everything-search  http  已启用  已连接    │
+│                                               │
+│ 手动 MCP（profile 配置）                      │
+│   ○ codegraph     stdio   已停用  未连接      │
+│                                               │
+│ 项目技能（本工作区）                          │
+│   ● officecli  .dsh   已启用                  │
+│   ○ probe      .claude 已停用                 │
+│                                               │
+│ 全局技能（所有工作区）                        │
+│   ● diagnose-windows-sandbox-acl  ~/.dsh      │
+└───────────────────────────────────────────────┘
+```
+- **当前工作区**（弹窗顶部有提示）：拨动开关**立即生效**——启用就连接进程并注册工具，
+  停用就断开并卸载工具。
+- **非当前工作区**：开关只保存状态，等这个工作区有会话时才按状态挂载。
+- 空分组不显示；某个工作区一个 MCP、一个技能都没有时，弹窗给出空状态提示。
+- 项目 MCP 的名字会带工作区前缀：A 工作区里的 `codebase` 在运行时叫 `a__codebase`，
+  模型看到的工具名是 `mcp__a__codebase__search_code`。这样两个工作区的同名服务器可以
+  以各自独立的进程共存，而不是互相顶掉。
+## 数据与状态
+状态文件是 `$DSH_HOME/mcp-manager/state.json`（`$DSH_HOME` 默认 `~/.dsh`）：
+```json
+{
+  "projects": [
+    {
+      "path": "D:\\ai-workspace",
+      "disabled": ["dsh-mcp-manager__codebase"],
+      "disabledSkills": ["office"]
+    }
+  ]
+}
+```
+| 字段 | 含义 |
+|---|---|
+| `path` | 工作区绝对路径（身份键） |
+| `disabled` | 该工作区停用的 MCP 运行名列表；项目服务器写工作区限定名（`<slug>__<name>`），全局/手动服务器写原名 |
+| `disabledSkills` | 该工作区停用的技能名列表 |
+- 首次启动会自动从旧的 `$DSH_HOME/settings.yaml` 的 `mcp:` 段导入一次，无需手工迁移。
+- 停用名单里同时认限定名与旧 plain 名（`codebase`），所以老配置不会失效。
+- 手改这个文件后，重启 DSH 或重新打开弹窗即生效。
+### HTTP API
+弹窗只用这三个接口，也可以自己调用（同源，无鉴权）：
+| 方法 | 路径 | 用途 |
+|---|---|---|
+| `GET` | `/api/dsh-mcp-manager/inventory?active=<工作区路径>` | 该工作区的完整清单（MCP 分组 + 技能 + 连接状态） |
+| `POST` | `/api/dsh-mcp-manager/activate` | `{ "path": "..." }`，记住当前聚焦的工作区 |
+| `POST` | `/api/dsh-mcp-manager/set` | `{ "path": "...", "kind": "mcp"\|"skill", "name": "...", "enabled": true }` |
+## 挂载语义（想改配置文件前先读这段）
+- **并集模型**：挂载集合 = 所有「有存活会话」的工作区各自想要的服务器之并集。
+  没有任何存活会话时，退化为「当前聚焦工作区」的集合。
+- **进程粒度**：项目服务器每个（工作区, 服务器）一个进程，`cwd` 默认是该工作区目录，
+  所以 `.codebase/codebase.db` 这类相对路径各自落到自己的工作区。
+- **全局服务器**：只要任一存活工作区启用，就挂一个共享进程。
+- **手动服务器**（profile 里手写的 `dsh-mcp-client` 行）：只要任一存活工作区需要就保持启用，
+  因为一个 loader 行只能有一个进程。
+- **卸载时机**：某工作区最后一个会话关闭后，它专属的服务器进程被卸载；
+  卸载后会按命令行特征清扫可能残留的子进程。
+- **孤儿进程**：托管服务器被停用/卸载时，插件会用启动命令的特征串找并杀掉残留子进程，
+  避免 stdio 服务器变成野进程。
+## 技能
+- 技能根按以下优先级合并（**rank 小者赢**，同名技能只出现一次）：
+  | 顺序 | 根 | 来源标记 |
+  |---|---|---|
+  | 1 | `<工作区>/.dsh/skills` | `project-dsh` |
+  | 2 | `<工作区>/.claude/skills` | `project-claude` |
+  | 3 | `<工作区>/.agents/skills` | `project-agents` |
+  | 4 | `~/.dsh/skills` | `user-dsh` |
+  | 5 | `~/.claude/skills` | `user-claude` |
+  | 6 | `~/.agents/skills` | `user-agents` |
+  `.claude` 与 `.agents` 这两组是 DSH 默认不认的（DSH 只认 `.dsh` 与 `.agents`），
+  由本插件通过 `ctx.skills.registerProvider()` 补上，不 patch 任何核心包。
+- **技能目录**里每个技能是一层目录下的 `SKILL.md`，或根目录下的单个 `.md` 文件；
+  没有 frontmatter 时用目录名作名字、正文第一行作描述（Claude Code 的常见写法）。
+- **停用技能的三重生效点**：会话技能目录不再列出、`/技能名` 不会被注入、
+  `skill` 工具调用被拒绝并返回「该技能在此工作区已停用」。
+## 兼容性
+| 项目 | 要求 |
+|---|---|
+| DSH | `>=0.2.0-rc.2 <0.3.0`（安装时按运行时版本校验，不匹配会拒绝安装） |
+| Node.js | `>=22` |
+| 界面 | 仅 Web（`dsh web` 与桌面版 GUI 的 Web 视图）；`headless` / `acp` 无 UI 入口 |
+运行时依赖只有 DSH 安装目录自带的包（`@deepseek-ai/dsh-mcp-client` 等），
+插件本身没有 npm 运行时依赖。
+## 已知限制
+- **技能文件没有 watcher** — DSH 运行期间新增到 `.claude/skills` 的技能，要重启才会出现
+  （已有技能与项目技能在启动时全部加载）。
+- **工作区按钮是 DOM 注入的** — DSH 0.2.x 只为「会话行」声明了 slot，工作区行没有，
+  所以按钮通过 `MutationObserver` 注入并在重渲染后补回。按钮若在某些主题/布局下没出现，
+  先确认 DSH 版本是否仍在 `>=0.2.0-rc.2 <0.3.0` 区间。
+- **技能过滤是原型补丁** — 它影响所有访问技能服务的消费者（比如技能选择器 UI）。
+  这是有意为之：开关本身就是按工作区的，而每次查询都带 `cwd`。
+- **状态不在 DSH 设置页** — DSH 0.2.x 不再允许插件注册任意设置命名空间，
+  所以开关状态存在自己的 `state.json` 里，不出现在设置页。
+- **切换语义** — 「非当前工作区」的开关只保存状态，不会立刻拉起进程；这是为了避免
+  给没在用的工作区白开进程。
+## 安全
+- 插件会拉起项目 `.mcp.json` 与 `~/.claude.json` 里声明的 **stdio 命令**，
+  等同于把代码执行权交给这些配置。只在你信任的仓库/配置里使用。
+- 三个 HTTP 接口**没有鉴权**，设计前提是 `dsh web` 只监听 loopback（默认 `127.0.0.1`）。
+  用 `--host 0.0.0.0` 暴露到网络时，任何能访问该端口的人都能开关你的 MCP 服务器。
+- 插件不改 DSH 安装目录，不写 `settings.yaml`，只写 `$DSH_HOME/mcp-manager/state.json`。
+## 开发
+```sh
+node --check lib/index.js        # host：清单收集、按工作区状态、并集挂载、路由
+node --check lib/skill-filter.js # 技能过滤（SkillRegistry 原型 + tools.guard）
+node --check lib/skill-roots.js  # Claude 技能根 provider
+node --check client/client.js    # 浏览器 bundle（ModuleLoader factory 形式）
+npm run pack:check               # 校验 npm 包内容（发布前必跑）
+npm run market:index             # 生成 docs/index.json 插件市场索引
+```
+| 路径 | 作用 |
+|---|---|
+| `lib/index.js` | Host 主逻辑：状态、`inventory` / `activate` / `set`、并集挂载、会话工具过滤 |
+| `lib/skill-filter.js` | 按工作区过滤技能（目录 / 注入 / 工具调用三处） |
+| `lib/skill-roots.js` | `.claude` 技能根 + 无 frontmatter 的 `SKILL.md` 解析 |
+| `client/client.js` | 浏览器半：工作区行按钮 + 弹窗（中英双语） |
+| `cordis.patch.yml` | bundle 补丁：把插件行插进 profile 组合 |
+| `locale/{en,zh}.json` | 插件页显示用的标题/简介 |
+| `docs/index.json` | 插件市场索引（format 1），托管在 GitHub Pages |
+| `docs/PUBLISHING.md` | 发布流程（npm + GitHub + 市场索引） |
+浏览器半是**手写的 ModuleLoader bundle**（`window.__ModuleLoader__.load({ factory })`），
+没有构建步骤；改完直接刷新页面即可。
+## 发布
+见 [docs/PUBLISHING.md](docs/PUBLISHING.md)。
+## 许可证
+[MIT](LICENSE)