777-Zen / dsh-capability-index

dsh-capability-index

dsh-capability-index 是 DeepSeek Harness (dsh) 的元插件：让 agent 对自身插件库的处理， 从"机会主义的直觉判断"变成"规律性的预先审视"。任务量上来时，它在动手前给 agent 做一次插件库预检——任务型请求命中触发规则后，自动注入"可能适用的 Top-K 插件" 提示块，并带上插件作者声明的 use_when / not_for 能力说明；模型最终调不调， 决策权仍在模型。插件只读、只提示：不改写任何其他插件的工具定义，不强制调用， 不替代工具对比类插件。

三行要点：

• 三层触发：关键词规则（硬层）→ 能力声明集中渲染（中层）→ 插件库总览兜底（软层）
• 零侵入：通过 dsh 原生 runtime-context 通道注入，提示只在内容变化时替换、不逐轮堆积
• 状态：v0 雏形，中文词表起步，实验调优进行中；兼容 dsh developer preview 版本

设计初衷

以下话语是我的一些原始设计想法，尽量保留原样：

• "让 agent 对自身插件库的处理，从'机会主义的直觉判断'变成'规律性的预先审视'： 任务量上来时，动手前先系统性过一遍已知插件库，而不是做到哪算哪、凭感觉决定要不要用工具。"
• "现象：agent 明明有可用的插件/工具，却常常闭门造车（自己手搓），或机会主义地漏用， 直到任务中/任务后才发现'其实有个插件能用'。"
• "类比：给 agent 加一道'起飞前检查单'——先看清自己带了什么装备，再起飞。"
• "真正的价值：插件库利用率可预期——有合适插件时就用上，规律、稳定，不靠运气。"
• "规则宁缺毋滥，避免正常交流也被跑一遍（倒反天罡）。"
• "用户希望拿来就能用：插件一开，自己扫完插件库，对话过程中就自己识别、按触发规则来走。"
• "只扫已启用的插件库；没被启用的就不管，那是用户的隐私。"

状态（Status）

雏形 / early version。dsh 目前处于 developer preview，正式发布时本插件 的注入通道（systemPrompt.context 快照）、声明约定（capabilityIndex.declarations） 与触发表词表都可能有兼容性变化；升级 dsh 后如提示块消失或异常，先检查 README 与本仓库的发布说明。实验证据与方法见 eval-results/（活样本库 + 评分脚本 + 离线模拟器）。

实验证据（2026-08-16，B/C 对照）

这部分就是交给agent来进行的，没有人为干预 同 profile、同会话入口、同消息原文，仅切换本插件开关（部署级 disabled: true 补丁，热更新免重启）对比真实行为；真值信 tool/call 日志与 runtime-context 快照，不信模型总结。样本库 10 条（S1–S10，见 eval-results/samples.json）， 评分脚本 eval-results/eval-metrics.mjs。

指标	B 组（无提示，14 条）	C 组（有提示，7 条）
工具调用率（正例）	50%	100%
误触发（漏推/错推）	0 / 0	0 / 0
上下文增量	0 字符/条	约 180–200 字符/条（预算 ≤260）
（差异集中在非显而易见的工具）

执行主体（如实说明）：以上实验的执行、记录与统计由模型在会话中自主完成 （探针、模拟器与评分脚本均由模型编写运行），无人为干预、无筛选；真值由场景级 人工标注一次确定。样本规模小（B 14 条 / C 7 条，每场景 2~3 次），结论是方向性的， 不构成统计显著性验证。

结论：对显而易见的内置工具（read/echo 等），有无提示行为一致；对 不显而易见的插件工具（concat_text/format_text 等），提示块把调用率从 0% 提升到 100%（无提示时模型全程心算、完全没发现这些工具），且零误触发 （提示不会造成强制误用——样本 S9 中模型正确拒绝了不适用工具）。

v0 边界（实测）：提示面向主会话注入；子代理会话不接收提示块 （依赖 agent/inbox/claimed 消息路径，子会话不触发）。

工作方式（三层机制）

层	触发	行为
硬层	触发表 v0.1 命中（任务型请求）	注入 Top-K（默认 3）提示块：可能适用的工具 + 能力声明（use_when/not_for）
软层	未命中 / 模糊宏大 / 闲聊	注入轻量"插件库总览"兜底（当前可用工具清单）

• 触发表 v0.1（词表见 lib/trigger-table.js，中文起步，词条带 lang 标记）：
  • A 显式要求（"看看我有哪些插件"）→ T1
  • B 任务型动词 且（C 具体载体｜D 多子要求｜F 具体对象）→ T2
  • B 但无 C/D/F（"我想做个大项目"）→ T3，软层兜底
  • 无 B（闲聊/澄清）→ 不触发，软层兜底
• 注入通道：systemPrompt.context() 函数式提供者 → 提示落进 runtime-context 快照， 只在内容变化时替换、不逐轮堆积（快照 commit-on-change 语义）。
• 索引口径：tools.schemas(agent) —— 当前会话模型可见工具集的精确口径， 隐私边界自动成立（不可见工具不进索引）。

v0 边界（明确不做什么）

• 只读 + 建议性质：不改写任何其他插件注册的工具定义/description、不碰注册表。
• 不强制调用：只提示/引导，最终决策权在模型。
• 不自动下载/安装缺失插件；不替代 dsh-tool-search（本插件管"有什么、用不用"， 它管"哪个好"的二次比较）。

安装与开关

# 安装一次（在 DSH checkout 根目录跑；<path> 换成本目录绝对路径）
pnpm dsh plugin --profile <name> add <path>\dsh-capability-index

# 确认进了插件树
pnpm dsh --profile <name> --dump-config | Select-String capability-index

# 重启 web 应用后生效；设置 → Plugins 页可见本插件条目

• 安装一次进插件库，无需每次重新下载/安装；用户想在哪个会话里开，自己去启用就是， 不用一个会话一个会话来。
• 关闭/开启：在 profile 补丁层把行置 disabled: true（见 cordis.patch.yml 注释）后重启；会话粒度开关走 dsh 的 preset 机制（本插件挂在哪个组合， 就对哪个组合的会话生效）。
• 未启用时不加载任何代码（行被禁用 → 不进树 → 不 provide 任何服务）。

能力声明约定（capabilities）

插件作者随插件发布能力声明，本插件在命中时把它们集中渲染进自己的提示块 （不改写任何其他插件的工具定义）。声明通道：ctx.provide('capabilityIndex.declarations', …) ——v0 单聚合器约定：每个组合只应有一个插件提供该服务；多来源聚合属后续演进。

// 示例（见样例插件 dsh-tool-demo-cap）
ctx.provide('capabilityIndex.declarations', {
  version: 1,
  declarations: [
    {
      tool: 'echo',
      keywords: ['回显', '原样返回', 'echo'],   // 消息命中 → 排序加分
      use_when: '用户要求文本原样返回',          // 集中渲染进提示块
      not_for: '任何加工、转换、格式化',
      min_complexity: 'low',                    // 低于该任务量级不推
      lang: 'zh',
    },
  ],
})

• 无能力声明的存量插件照常进索引：工具 description 全文作为低置信条目 参与关键词匹配（权重低于有声明条目），提示块中标注"未提供能力声明"。
• 静态声明槽（package.json 扩展字段 / cordis_define 载荷扩展）属演进项， 需要改 harness 源码，v0 不做。

文件

• package.json — 包清单 + dsh.bundle.patch 声明
• cordis.patch.yml — patch 层：insert capability-index 行（含关闭示例）
• lib/index.js — 插件本体：触发表判定 + 索引排序 + 提示渲染
• lib/trigger-table.js — 触发表 v0.1 词表数据（lang 标记，实测校准只改这里）

发布

公开 GitHub 仓库 + dsh-plugin topic 即可被官方生态发现 （官方立场：社区插件与官方包地位平等，无 marketplace/审批制）； GitHub Discussions / Discord 社区用于反馈与曝光。

实验归因备忘（不属于 v0 构建）

三组消融：A 无工具列表 / B 有列表无提示 / C 有列表+提示；真值信 tool/call 日志不信总结；场景级人工标注（每场景标一次"该用哪些、绝不推哪些"）。

已知问题与潜在限制

PTC / Code Mode 呈现适配（待做）：

• PTC 模式（内置 code 预设）下模型只直接调用 run_code，其余工具经生成的 TypeScript SDK 间接调用；本插件索引读的是呈现无关的注册表视图，因此：
  1. run_code 传输工具会混入索引与推荐，应过滤（tools/src/code-mode.ts:20 的 RUN_CODE_NAME）；
  2. "当前可用工具 N 个"在 PTC 会话下口径失真（模型直接可调只有 1 个）， 总览文案需按模式区分；
  3. 模式探测：tools.schemas(agent) 中出现 run_code 即 code 模式 （visibility resolver 只为 code 作用域追加它），适配层可用此信号；
  4. plan 阶段只推只读工具，避免与 plan-mode 规则相抵。

插件规模（待做）：

• 每 step 对全部工具 schema 深克隆（tools/src/index.ts:1234-1236）， 插件变多后需 tools/change 事件驱动缓存；
• 软层总览列出全部工具名（260 字符截断），插件变多后退化为噪声，需改为插件级聚合摘要；
• Top-K 的 token 子串匹配随工具数放大噪声（"ok"泛命中教训），需倒排索引 + 候选集过滤；
• 子代理 scope 也会触发注入，成本随会话树放大（当前提示仅主会话注入，见"实验证据"）。

其它：多声明来源聚合（v0 单聚合器约定）；Q2 多轮遗忘后的重扫策略 （快照替换已防堆积，重扫阈值待实测）。

维护与迭代

• 词表与模糊边界是启发式，需要持续维护：T1/T2/T3 边界定义、关键词词表、排序权重 随使用持续校准；样本库（含误判/漏判样本）是校准的主要数据源，欢迎持续扩充；
• 语言：中文起步，词条带 lang 标记；英文覆盖后补为纯数据追加，不改判定代码；
• 数值：Top-K、描述截断、总览预算、min_complexity 全部集中在 lib/trigger-table.js， 实测校准只改数据文件；
• 贡献：欢迎提交能力声明、词表扩充、样本与反馈；dsh 尚处 developer preview， 正式版可能有兼容变化。

欢迎大家在GitHub Discussions里面交流和反馈以及互动