dsh-mcp-skill-panel

dsh plugin --profile web add dsh-mcp-skill-panel

<p align="center">

<strong style="font-size: 2.2em">🧩 MCP 与技能管理面板</strong><br>

<span style="font-size: 1.1em">DeepSeek Harness（DSH）Web 插件 · MCP 服务器与 Skill 目录的实时启停 · 可选中间层（让AI按需调用）</span>

</p>

<p align="center">

<a href="./README.en.md">🌐 English</a> · <strong>中文</strong>

</p>

<p align="center">

<img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg">

<img alt="Version" src="https://img.shields.io/badge/version-0.6.0-green.svg">

</p>

---

✨ 是什么

一个把 MCP 服务器 与 Skill 目录 变成可操作清单的设置页面板：每个条目一个启停开关，停用即释放上下文占用，启用无需重启。

还内置可选的 AI 中间层（autoManage）：开启中间层时，停用的 MCP 立即释放上下文，被中间层接管；模型需要 MCP 工具时，由中间层临时开启 MCP，按需调用工具；用户手动打开的 MCP 全程对模型保持可见以维持高灵敏调用 —— 上下文占用完全由你的开关决定。

🎯 核心能力

能力 · 说明

🟢 MCP 实时启停 · 停用 → loader entry 卸载（断开连接 + 注销全部 mcp__<server>__* 工具），工具从模型目录立即消失、schema token 即时释放；启用 → 重新连接 + 恢复工具，无需重启

🧠 Skill 启停 · 往 SKILL.md frontmatter 注入/移除 disable-model-invocation: true，模型 catalog 实时失效

📊 停用态回填 · 停用的 MCP 卡片仍显示「目录中有多少工具、约多少 token」（来自私有 catalog 的 last-good 快照），决策是否启用更有依据

🤖 AI 中间层（可选） · autoManage 开启后：停用的 MCP 对模型隐藏，模型经 dsh_mcp_search / dsh_mcp_call 按需使用；用户打开的 MCP 保持模型可见；AI 临时启用不污染上下文

🔒 用户启停不被模型干预 · 回收器只回收「AI 从停用态临时启用」的 server；用户手动打开的 server 永不被自动关闭

💾 重启保持 · 启停意图持久化（~/.dsh/dsh-mcp-skill-panel/state.json）并在启动早期物化进预设组合文件；catalog 快照（catalog.json）重启后仍可回填

⚡ 响应快 · 开关点击即翻转（乐观更新 + 服务端确认），分域缓存 + 事件驱动失效（tools/change / skills/change），MCP 页不触发 skill 目录扫描

🌐 双语界面 · 全部文案 zh/en 双语，跟随 DSH 界面语言；明暗主题适配

🪶 零上下文占用 · 插件自身不注册任何模型工具，不消耗模型注入面（开关关闭时与未安装无异）

⏱️ 生效时机选项 · 手动开关可选「立即生效」或「下次会话生效」，后者零缓存失效、零额外费用；AI 中间层按需调用始终不触发缓存 miss

➕ 快速迁移添加 · 面板粘贴其它 harness 的 mcpServers JSON（Claude Code / Codex 等）→ 转换预览 → 一键添加为全局（写入 profile patch）或项目（.dsh/mcps/mcp.json）；type/transport 自动推断、${VAR} 环境变量自动插值

📁 项目级 MCP · 读取 <工作空间>/.dsh/mcps//mcp.json（根目录先读、子目录按 serverName 覆盖），仅该项目工作空间的会话可见**（按会话 cwd 过滤）；文件改动热更新

🛠️ 工具级禁用 · 在 server 级启停之上按工具精确控制：被禁工具从 dsh_mcp_search 检索结果过滤、dsh_mcp_call 直接拒绝；项目 MCP 按工作区作用域隔离（A 区禁用不影响 B 区）

🧮 工具级批量启停 · POST /mcp/toolBulk 一次读-改-写落整批（不写 N 次盘）：toolNames 三态 —— 省略=该 server 当前目录里的全部工具 / 数组=精确集合（[] 为空操作）/ 非数组、或非空却 0 命中=400（不静默降级成「全部」，也不静默 no-op）；响应含 ignoredToolNames，把「点名了但不在当前目录」的项回传，目录漂移可见化

📈 有效统计 · 工具数 / token 数同时给「目录总数」与「工具级启用数」：面板按与装配过滤同源的谓词（isToolDisabled + 会话工作区）复算，禁用 400 个工具后不再仍显示 450。口径边界：只扣「工具级禁用」，不覆盖 server 级隐藏（AI 临时启用 / middleLayerHides='all'）与 project-mcp 工作区过滤

🎯 工具预算 · toolBudget 设一条工具数红线（如 350），超线卡片变红；比较对象是全部工具（含 read/edit/bash/skill 等非 MCP 工具），数据源优先请求面真值 —— toolsAllSource='request'（会话上一次已落盘请求的装配后工具表），取不到时回退注册表 'registry'，且口径来源在卡片上标注（注册表口径是近似值，不得混同）

🧭 AI 中间层按模型分流 · autoManageByRoute：按 provider 或 provider/model 分别开中间层；查表序 provider/model → provider → autoManage 总开关。覆盖项为真时即使总开关关也会挂载中间层（被覆盖的模型可用 dsh_mcp_search / dsh_mcp_call），其余模型维持直用形态

🙈 middleLayerHides · 中间层隐藏范围，默认 'disabled'（只隐藏停用的 server）；'all' 时连已启用的 server 也从模型装配面隐藏，模型统一改经中间层取用 —— 只改「本次装配的可见性」，工具注册表与 dsh_mcp_call 执行通道不受影响

🪄 创建技能 · 面板填写名称/描述/指令即可创建技能（全局 ~/.dsh/skills 或项目根 .dsh/skills），可上传 SKILL.md 自动解析 frontmatter 预填，创建后立即可见

🧾 配置项

面板可写的配置落在 ~/.dsh/dsh-mcp-skill-panel/state.json（优先于 cordis config），可用 GET/POST /config 读写：

配置项 · 取值 · 说明

autoManage · false（默认）/ true · AI 中间层总开关（形态 1 ↔ 形态 2）

applyMode · immediate（默认）/ next-session · 手动开关的生效时机（见「生效时机」一节）

toolBudget · 正整数 / 空 · 工具数红线：全部工具（含 read/edit/bash/skill 等非 MCP 工具）超过它即告警；空 = 不提示。数值只是可配置默认值，见「已知限制」

autoManageByRoute · { "<provider>": bool, "<provider>/<model>": bool } · 中间层按模型分流；查表序 provider/model → provider → autoManage 总开关。经 POST /config 的 routeOverride: { key, value } 单条增删（value: null = 删除该键）；任一覆盖项为真即挂载中间层

middleLayerHides · 'disabled'（默认）/ 'all' · 中间层隐藏范围：'disabled' 只隐藏停用的 server；'all' 连已启用的 server 也从模型装配面隐藏

🏗️ 两种形态（面板上的「AI 中间层」开关）

stateDiagram-v2
    [*] --> 形态1直用: autoManage 关
    [*] --> 形态2中间层: autoManage 开
    形态1直用 --> 形态2中间层: 面板开关 / POST /config
    形态2中间层 --> 形态1直用: 面板开关 / POST /config

    state 形态1直用 {
        direction LR
        M1: 模型直接使用所有已启用 MCP 的原生工具（mcp__*）
        M1a: 启停只靠面板手动
    }
    state 形态2中间层 {
        direction LR
        M2: 停用的 MCP 对模型隐藏
        M2a: 模型经 dsh_mcp_search / dsh_mcp_call 按需调用
        M2b: 用户打开的 MCP 保持模型可见
        M2c: AI 临时启用不污染上下文
    }

形态 2 的装配过滤（每回合实时判定）：

flowchart TD
    A[system-prompt/assemble] --> B{工具名以 mcp__ 开头?}
    B -- 否 --> K[保留: 进入模型上下文]
    B -- 是 --> C{解析 server}
    C -- 失败 --> K
    C -- 成功 --> D{server 当前状态?}
    D -- 用户打开 disabled=false 且非 AI 启用 --> K
    D -- 用户停用 disabled=true --> F[过滤: 模型不可见]
    D -- AI 临时启用 dsh_mcp_call 保活中 --> F
    F --> G[需要时: dsh_mcp_search 检索 / dsh_mcp_call 按需调用]

工具级禁用（v0.5.3+，常开）：除上述 server 级过滤外，被禁用的单个工具从装配结果剔除、dsh_mcp_search 检索结果过滤、dsh_mcp_call 直接拒绝并提示「请在 MCP 管理面板打开该工具后再调用」；禁用集合持久化在 state.json，重启保持。

⏱️ 生效时机：立即生效 vs 下次会话生效

面板为手动开关提供「生效时机」选项（位于开关旁的下拉菜单），两档：立即生效（默认）和 下次会话生效。理解两者区别对 Prompt Cache 费用有直接影响。

手动开关的两种模式

• 立即生效（默认）：切换在下一轮对话即生效，该轮起工具前缀变更 → 前缀 KV-Cache 100% 失效，该轮按 miss 费率计费（约为 hit 的 5 ~ 12.5 倍）。适合需要马上释放/恢复上下文的场景。

• 下次会话生效：仅记录意图，当前会话全程工具集不变 → 零缓存失效、零额外费用。直到以下边界之一到来才真正应用：
• 新会话首次请求前（agent/session-start 阶段）；
• DSH 重启（启动早期 syncPresetFiles 物化到预设组合文件）。

面板提供 「立即应用待生效变更」 按钮，作为"已知晓费用"的强制生效出口——点击后立即生效（等同于选择"立即生效"并应用）。

AI 中间层按需调用：天然免缓存失效

开启 AI 中间层（autoManage）后，模型经 dsh_mcp_search / dsh_mcp_call 按需调用已停用的 MCP——这种临时启用不会造成缓存 miss。原因：每回合的装配过滤（system-prompt/assemble Waterfall）让临时启用的 server 工具对模型保持不可见，前缀恒定，KV-Cache 持续命中。

默认值与生效边界

项目 · 说明

默认值 · immediate（维持历史行为）

选择 next-session · 需在面板显式切换

生效边界 · 新会话首次请求前 + DSH 重启

当前会话 · 已开会话的后续轮次不受影响

一句话结论

想省费用又不急着释放上下文 → 用 下次会话生效；要当前会话立刻释放/拿回工具 → **立即

…(truncated)