zhangzhenwen1/qmd-autosearch

自动补搜插件：当模型在知识库目录执行 grep / glob 搜索时，自动补充一次 QMD 语义检索，并把结果注入模型上下文。

DeepSeek Harness 插件（dsh-plugin）。零外部依赖。

功能

• 自动触发：模型在 QMD 集合对应的目录内执行 grep / glob（顶层调用）即触发，无需显式调用
• 语义补搜：QMD 单次查询（lex + vec，服务端 LLM 重排），检索范围限定在配置的 collections
• 智能查询词：以最近的用户消息（任务要求）为语义主查询；消息过短或与搜索主题无关时，回退使用 grep pattern
• 异步注入：结果排队到 agent.inbox.nextStep，下一个 pre-step 注入模型上下文，不阻塞当前工具调用
• 防重复：同一 agent 内相同（工具、路径、pattern）签名只补搜一次
• 容错：QMD 服务不可用或查询无结果时静默跳过，不影响原流程

工作原理

grep/glob 执行完成 → tools/result 钩子
  → 路径在触发范围内（由 QMD status 解析的集合路径）？
  → QMD query（collections 限定 + LLM 重排）
  → 结果排队 agent.inbox.nextStep
  → 下一个 pre-step 注入模型上下文（user 角色 system-reminder 风格）

安装

这是一个 dsh.bundle 包（package.json 的 dsh.bundle + dsh.client），推荐按 bundle 安装，这样它会在「插件」面板里出现并可启停/配置：

方式一：插件面板安装本地目录

「插件 → 添加插件 → 安装第三方插件」填入本目录绝对路径（或由 agent 调 plugin_manager install_bundle）：

/home/zhang/文档/DSH/plugins/qmd-autosearch

安装后插件以 link: 依赖挂在 profile 上，代码改动只需重启/重载即可生效。

方式二：npm / git 安装（发布后可用）

dsh plugin --profile web add qmd-autosearch
# 或
dsh plugin --profile web add github:zhangzhenwen1/qmd-autosearch

方式三：裸 patch 引用（仅调试，不推荐）

在 ~/.dsh/profiles/web/cordis.patch.yml 的 insert 列表追加 file:// 行。裸行不会出现在插件面板的「已安装插件」里，也无法使用可视化配置表单。

配置

所有字段都声明为 schemastery 的 volatile 配置，可在插件面板里可视化编辑、保存后立即生效（写入 profile 的 cordis.patch.yml）。 mcp* 字段是 QMD MCP 连接参数的唯一真源：保存后 Host 半会把它们写回 mcp-qmd 行并重载该行（重连 MCP）。

配置项	必填	默认值	说明
qmdUrl	✅	http://localhost:6179/mcp	补搜使用的 QMD MCP 服务地址
collections	✅	[]	搜索范围：QMD 集合名列表（qmd collection list 可查）
limit	否	5	注入结果的条数上限
minScore	否	25	最低匹配度过滤（百分数，低于此值的命中丢弃）
mcpServerName	否	qmd	MCP 实例名；模型工具前缀为 mcp__<名>__*
mcpTransport	否	streamable-http	MCP 传输方式；stdio 请直接改 patch
mcpUrl	否	http://localhost:6179/mcp	写入 mcp-qmd 行的连接地址
mcpToolCallTimeoutMs	否	180000	单次 MCP 请求超时（毫秒）
triggerRoots	否	自动	触发判断的文件系统根路径列表（非可视化）；缺省时从 QMD status 动态解析集合路径

未配置 qmdUrl / collections 时插件禁用并输出 warn 日志。

可视化配置

安装为 bundle 后：

1. 打开「插件」面板 → 已安装插件 → qmd-autosearch；
2. 在「包含的组件」里点 qmd-autosearch 行的配置按钮；
3. 表单分「自动补搜」和「QMD MCP 连接」两组；改动可保存/放弃，覆盖过的字段可「恢复默认」；
4. 保存写入 profile 的 cordis.patch.yml；补搜参数即时生效，MCP 连接参数会让 mcp-qmd 行重载重连。

代码层面的改动（JS 模块）只有 dsh 重启后才会重载：HMR 只跟踪 profile 目录内的模块，link: 到工作区的插件源码不在比较范围内。配置项变更不需要重启。

使用

插件全自动运行，无需手动调用。配置完成后，正常使用 DSH 即可：

1. 让模型在知识库目录内搜索（如 grep 某个概念）
2. 插件检测到搜索发生在 QMD 集合目录内，自动补充一次语义检索
3. 结果作为补充提示注入模型的下一步上下文，模型可据此用 read 读取命中文档正文

效果示例

模型执行 grep 内需 后，下一步上下文中会出现：

<system-reminder>
QMD 语义检索补充：你在知识库目录执行了「grep 内需」，系统已自动用语义检索（范围限定 QMD 集合，LLM 重排）补搜，查询词「内需」。结果如下（docid 映射为绝对路径后用 read 读取正文）：

Found 3 results for "内需":
#abc123 85% <collection>/concepts/<file>.md - <标题>
#def456 42% <collection>/principles/<file>.md - <标题>
...
</system-reminder>

验证插件已生效

• 让模型在集合目录内 grep 一个词，观察下一步是否出现上述补充消息
• 或查看宿主日志中的 qmd-autosearch: 触发路径池（来自 QMD 集合）N 个（插件启动后首次触发时输出）

前置条件

• 运行中的 QMD MCP 服务（qmd mcp --http --port 6179）
• 已建立至少一个 collection（qmd collection add <name> <path>）

License

MIT