dsh-capability-gateway

English | 中文

DeepSeek Harness 的按需能力网关：把主动接管的第三方技能与 MCP 工具收进一个入口。

装得多了会出两件事：模型可见的工具目录越长，越挤占真正要做的任务；所有能力同等可见，模型也更容易选错。这个插件把你主动选定的那部分从原生目录里收起来，只保留一个 capability 工具——按意图搜索、读参数或说明、再调用。

它是 DSH 的 host + client 插件：不转发远端流量、不额外起服务、也不向外发送任何数据。

它改变了什么

• 被接管的技能离开模型可见的技能目录，仍然可以由用户手动调用，通过 capability 加载。
• 被接管的 MCP 服务保留原生执行路径，但工具 schema 从提示里移除；调用仍走原有的权限与 guard 链。
• PTC 模式保留 run_code 与 SDK 中的 capability，受管 MCP 的完整声明不再预加载；先 search/describe，再通过 tools.capability 调用。不支持宿主呈现接口时保留原 SDK，status 与清单明确提示。
• 一个工具（capability）替代原本几十条工具定义。
• 一段有界的名称索引写进系统提示，让模型知道“有哪些能力”，即使词法搜索没命中。只有名字，不含描述和 schema。
• 本地日志记录搜索与调用的元数据（不记录查询原文、参数、返回值），可导出为周报。

安装

# 在 DSH profile 目录下
pnpm add link:/path/to/dsh-capability-gateway   # 或：pnpm add dsh-capability-gateway

在 ~/.dsh/profiles/<profile>/package.json 里注册 bundle：

{
  "dependencies": { "dsh-capability-gateway": "link:/path/to/dsh-capability-gateway" },
  "dsh": { "profile": { "bundles": [
    "@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-capability-gateway"
  ] } }
}

安装后打开 设置 → 内置插件 → 能力网关 → 配置，勾选 MCP 服务与技能目录，核对新增/移除预览后保存。宿主会保存配置并重载；刷新确认实际接管结果。没有配置编辑接口的宿主仍保留原有功能，可通过宿主配置管理声明范围。

也可以手动配置：

# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: capability-gateway
  config:
    skillRoots:
      - '~/.agents/skills'
    mcpServers:
      - my-mcp-server

包内默认什么都不接管：接管范围是安装数据，不是包数据。id 补丁会整体替换 config，所以需要的键要写全。

重载插件（或重启 DSH）。设置入口在 设置 → 内置插件 → 能力网关。

配置

键	默认	含义
enabled	true	false 让插件失效，并把所有能力恢复成原生暴露。
skillRoots	[]	交给网关的技能目录。
mcpServers	[]	接管的 MCP 服务名；其 mcp__<server>__* 工具被管理。
wrapSkills / wrapMcp	true	单独开关技能或 MCP 这一半。
mcpKeywords	{}	{ "服务": ["别名", ...] }。
skillKeywords	{}	{ "技能": ["别名", ...] }。
keywordPacks	[]	别名包 JSON 文件，按顺序叠加。
promptHint	true	加一句“能力在 capability 后面”的提示。
promptIndex	true	加有界的能力名索引。
promptIndexChars	2000	索引字符上限（200–6000）。
maxResults	5	搜索返回候选数（1–10）。
logDir	$DSH_HOME/data/capability-gateway	日志目录。

别名

中文提问很少与英文技能描述共享词元，词法搜索无法猜出没见过的词汇。别名就是补这个缺口的方式，而且始终是数据：

skillKeywords:
  release-notes: [发布说明, 变更记录]

或者一个可分享的别名包，由 keywordPacks 引用：

{ "release-notes": ["发布说明", "变更记录"] }

缺失或损坏的包不会阻塞启动；其他有效包与条目继续生效。状态、接入清单和模型提示会标记别名覆盖不完整；清单给出包的配置序号、错误类别和无效条目的序号，修正后重新加载插件。skillKeywords 的显式配置无效时返回 invalid_config，不会静默丢弃。每项为非空字符串数组，每个名称最多 50 个词，每词最多 80 字；多个来源合并去重。技能也可以在 SKILL.md 里用 keywords: 自带别名，随技能一起分发。

页面操作

能力网关分为「能力清单」「配置」「使用统计」和「运行日志」。接管范围与搜索试验位于配置，汇总与周报位于使用统计，逐条搜索、加载和调用记录位于运行日志。

• 选择接管范围：自动列出可观察的 MCP 服务与技能候选目录，保留当前已配置但暂未发现的项目。技能候选目录由文件位置推导，需核对路径；也可输入其他本机目录。按目录接管会包含目录内后续新增的技能。新增服务或目录不会自动勾选。保存只修改 skillRoots 和 mcpServers，保留其他配置；不会开启已关闭的 wrapSkills / wrapMcp。
• 搜索试验区：按当前查看会话搜索已接管能力，显示候选顺序、排序分与完整名称/别名/词法/路由入口原因。排序分不是置信度。只检索，不执行 MCP，不写查询日志，不影响调用统计；切换会话或刷新后重新试验。
• 效果与异常诊断：按当前清单与呈现模式显示 MCP 原生声明数量变化，技能单独计数，不推算 token 或费用。诊断覆盖发现、别名、PTC 降级与记录异常。调用诊断按记录范围的全部保留事件计算，不受列表分页和筛选影响；原生直接调用不自动判错。

保存遇到并发修改会拒绝覆盖，刷新后选择“重新载入选择”再编辑。保存期间若断连或返回失败，不假定成功；刷新核对实际范围后再操作。页面保存仅适用于宿主提供本插件配置编辑接口的安装方式。

capability 工具

action	用途
search	按目标、短关键词或名称找候选。
load	返回技能说明与基准目录。
describe	返回某个 MCP 工具的精确 JSON Schema。
call	调用 MCP 工具，调用前按该 schema 校验参数。
status	网关是否生效、接管了多少。
inventory	紧凑的计数、根目录、覆盖情况和有界异常。
history / stats	当前会话最近的路由元数据与窗口统计。
report	导出 Markdown 周报。

搜索刻意保守：没有匹配时返回 not_found 并指向原生方式，而不是编一个结果；网关也不会自己调用下游工具。

完整名称优先于词法停用词规则，但仍只能命中当前会话可见且已接管的能力。技能与 MCP 独立发现；某一类失败时，其他类别的结果带有“发现不完整”提示和 discovery 标记。不完整且无候选时明确报发现失败，不冒充未命中。

设置页周报沿用“记录范围”的全部会话或所选会话，不受结果/操作筛选影响；导出内容明确标注范围。所选会话失效会报错，不自动扩大范围。模型 action=report 返回调用会话的周报。

隐私

每条事件记录：动作、目标名、路由、结果、错误码、耗时、候选名与排名、插件版本。不记录：查询原文、工具参数、返回值、错误正文、凭据、文件路径。

全部在本地，不上传。周报只在你主动导出时生成，且只含计数与名称。别名包和本地检索快照属于本机数据，不进发布包。

限制

• 搜索是词法的，不是语义的。跨语言检索依赖别名是否齐全。
• 检索质量由固定任务集衡量（tests/retrieval.test.js），不保证对所有说法都成立。
• 日志只覆盖最近 7 天 / 10,000 条事件，是样本，不是审计。
• 提示里的能力名有长度上限，能力特别多时索引会被截断。
• 技能名称索引按当前会话的实际网关赢家生成；发现失败时标记不完整，不沿用其他会话或全局扫描的技能名单。
• PTC 精简只影响模型提示中的声明，执行绑定保持原样；它不是访问控制。当前对 DSH 0.2.1-rc.5 的运行库验证，真实应用验收另行进行。

开发

npm run check   # 语法
npm test        # 单元、组件、真实运行库启动与检索测试
npm pack --dry-run

设计与行为契约见 docs/DESIGN.md。

许可

MIT