qmd-autosearch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qmd-autosearch authors
+
+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

@@ -0,0 +1,98 @@
+# 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 风格）
+```
+
+## 安装
+
+### 方式一：npm 安装（发布后可用）
+
+```bash
+dsh plugin --profile web add qmd-autosearch
+```
+
+### 方式二：本地路径引用（开发调试）
+
+在 `~/.dsh/profiles/web/cordis.patch.yml` 的 insert 列表追加：
+
+```yaml
+- insert:
+    - id: qmd-autosearch
+      name: 'file:///path/to/qmd-autosearch/index.js'
+      config:
+        qmdUrl: http://localhost:6179/mcp
+        collections:
+          - knowledge-concepts-keynes
+          - knowledge-principles-keynes
+        limit: 5
+        minScore: 25
+```
+
+## 配置
+
+| 配置项 | 必填 | 默认值 | 说明 |
+|---|---|---|---|
+| `qmdUrl` | ✅ | 无 | QMD MCP 服务地址（如 `http://localhost:6179/mcp`） |
+| `collections` | ✅ | 无 | 搜索范围：QMD 集合名列表（`qmd collection list` 可查） |
+| `limit` | 否 | `5` | 注入结果的条数上限 |
+| `minScore` | 否 | `25` | 最低匹配度过滤（百分数，低于此值的命中丢弃） |
+| `triggerRoots` | 否 | 自动 | 触发判断的文件系统根路径列表；缺省时从 QMD `status` 动态解析集合路径 |
+
+> 未配置 `qmdUrl` / `collections` 时插件禁用并输出 warn 日志。
+
+## 使用
+
+插件**全自动运行，无需手动调用**。配置完成后，正常使用 DSH 即可：
+
+1. 让模型在知识库目录内搜索（如 `grep 某个概念`）
+2. 插件检测到搜索发生在 QMD 集合目录内，自动补充一次语义检索
+3. 结果作为补充提示注入模型的下一步上下文，模型可据此用 `read` 读取命中文档正文
+
+### 效果示例
+
+模型执行 `grep 内需` 后，下一步上下文中会出现：
+
+```text
+<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

package/index.js

@@ -0,0 +1,285 @@
+// qmd-autosearch — 自动补搜插件
+// 触发：模型在 QMD 集合对应目录内执行 grep/glob（顶层调用）
+// 搜索：QMD 单次调用（服务端 LLM 重排），范围限定在配置的 collections
+// 查询词：以最近 user 消息（任务要求）为主，grep pattern 仅作词法辅助
+// 注入：结果排队到 agent.inbox.nextStep，下一个 pre-step 注入模型上下文
+// 配置（必填）：qmdUrl = QMD MCP 服务地址；collections = 搜索范围集合列表
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
+
+export const name = "qmd-autosearch";
+
+const SEARCH_TOOLS = new Set(["grep", "glob"]);
+const INTENT_MAX_CHARS = 300;
+
+function freezeMessage(input) {
+	return Object.freeze({
+		...input,
+		id: input.id ?? randomUUID()
+	});
+}
+
+function createUserMessage(input) {
+	return freezeMessage({
+		...input,
+		role: "user"
+	});
+}
+
+// 把 grep 正则 pattern 清洗成 QMD 词法查询（正则元字符 → 空格）
+function cleanPattern(pattern) {
+	return String(pattern ?? "")
+		.replace(/[|()[\]{}*+?^$\\]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function inRoot(root, path) {
+	return path === root || path.startsWith(root + "/") || path.startsWith(root + "\\");
+}
+
+// ── QMD MCP 直连（streamable-http）────────────────────────────────────
+async function mcpRequest(url, sessionId, method, params) {
+	const headers = {
+		"Content-Type": "application/json",
+		"Accept": "application/json, text/event-stream"
+	};
+	if (sessionId !== null) headers["mcp-session-id"] = sessionId;
+	const res = await fetch(url, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
+	});
+	const nextSessionId = res.headers.get("mcp-session-id") ?? sessionId;
+	const text = await res.text();
+	let payload;
+	try {
+		payload = JSON.parse(text);
+	} catch {
+		const messages = text
+			.split("\n")
+			.filter((line) => line.startsWith("data:"))
+			.map((line) => JSON.parse(line.slice(5)));
+		const error = messages.find((m) => m.error)?.error;
+		if (error) throw new Error(error.message);
+		payload = messages.find((m) => m.result) ?? { result: void 0 };
+	}
+	if (payload.error) throw new Error(payload.error.message);
+	return { result: payload.result, sessionId: nextSessionId };
+}
+
+function extractText(callResult) {
+	return (callResult?.content ?? [])
+		.filter((block) => block.type === "text")
+		.map((block) => block.text)
+		.join("\n")
+		.trim();
+}
+
+// 解析 QMD 结果行："#3db89d 97% <collection>/<path>.md - <title>"
+function parseHits(text) {
+	const hits = [];
+	for (const line of text.split("\n")) {
+		const m = line.match(/^#([0-9a-f]+)\s+(\d+)%\s+(\S+)\s+-\s+(.+)$/);
+		if (m) hits.push({ id: m[1], score: Number(m[2]), path: m[3], title: m[4] });
+	}
+	return hits;
+}
+
+// 解析 status 文本："  - knowledge-concepts-keynes: /abs/path (1016 docs)"（行首允许缩进）
+// 返回所有非 null 集合路径（用作触发判断的文件系统范围）
+function parseCollectionRoots(statusText) {
+	const roots = [];
+	for (const line of statusText.split("\n")) {
+		const m = line.match(/^\s*-\s+([\w-]+):\s+(null|\/\S+)\s+\(\d+\s+docs?\)/);
+		if (m && m[2] !== "null") {
+			try {
+				roots.push(realpathSync(m[2]));
+			} catch {
+				roots.push(resolve(m[2]));
+			}
+		}
+	}
+	return roots;
+}
+
+async function qmdSearch(qmdUrl, collections, intentQuery, pattern, toolName, { limit, minScore }) {
+	const lexQuery = cleanPattern(pattern);
+	const query = (intentQuery || lexQuery).slice(0, INTENT_MAX_CHARS);
+	if (!query) return { query, text: "" };
+	const { sessionId } = await mcpRequest(qmdUrl, null, "initialize", {
+		protocolVersion: "2025-03-26",
+		capabilities: {},
+		clientInfo: { name: "qmd-autosearch", version: "0.1.0" }
+	});
+	const searches = [
+		{ type: "vec", query } // 语义主查询：任务/user 要求（权重 2x）
+	];
+	if (lexQuery && lexQuery !== query) searches.push({ type: "lex", query: lexQuery }); // 词法辅助
+	const { result: callResult } = await mcpRequest(qmdUrl, sessionId, "tools/call", {
+		name: "query",
+		arguments: {
+			searches,
+			collections,
+			limit,
+			rerank: true,
+			intent: `模型在知识库目录用 ${toolName} 搜索了 "${pattern}"，自动补充语义检索结果`
+		}
+	});
+	const hits = parseHits(extractText(callResult)).filter((hit) => hit.score >= minScore);
+	if (hits.length === 0) return { query, text: "" };
+	const text = `Found ${hits.length} results for "${query}":\n\n` +
+		hits.map((hit) => `#${hit.id} ${hit.score}% ${hit.path} - ${hit.title}`).join("\n");
+	return { query, text };
+}
+
+function renderSupplement(toolName, pattern, payload) {
+	return `<system-reminder>
+QMD 语义检索补充：你在知识库目录执行了「${toolName} ${pattern}」，系统已按当前任务要求自动用语义检索（范围限定 QMD 集合，LLM 重排）补搜，查询词「${payload.query}」。结果如下（docid 映射为绝对路径后用 read 读取正文，规则见全局指引）：
+
+${payload.text}
+</system-reminder>`;
+}
+
+// 从 agent 会话事件中取最近的用户消息文本（任务要求；排除插件/指令注入）
+function recentUserText(agent) {
+	const nodes = agent.session?.surface?.nodes;
+	if (!nodes) return "";
+	for (let i = nodes.length - 1; i >= 0; i--) {
+		const event = agent.session.events?.[nodes[i]];
+		if (event?.type !== "user/message") continue;
+		const source = event.data?.source;
+		if (source?.kind === "plugin" || source?.kind === "agent-instructions") continue;
+		const text = (event.data?.content ?? [])
+			.filter((block) => block.type === "text")
+			.map((block) => block.text)
+			.join(" ")
+			.trim();
+		if (text) return text;
+	}
+	return "";
+}
+
+// 选择语义主查询词：user 消息足够表达意图时用任务要求，否则回退 grep pattern
+// 规则：≥20 字直接采用；10-19 字且包含 pattern 关键词才采用；其余（过短/无关运维消息）回退 pattern
+function chooseIntentQuery(userText, pattern) {
+	const text = String(userText ?? "").trim();
+	const cleaned = cleanPattern(pattern);
+	if (!text) return cleaned;
+	if (text.length >= 20) return text;
+	const tokens = cleaned.split(" ").filter((token) => token.length >= 2);
+	if (text.length >= 10 && tokens.some((token) => text.includes(token))) return text;
+	return cleaned;
+}
+
+// ── 插件主体 ────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+	// 必填配置：qmdUrl（QMD MCP 服务地址）、collections（搜索范围集合列表）
+	// 缺失时插件禁用并告警——不提供环境相关的默认值（适用于公开发布）
+	const qmdUrl = config.qmdUrl ?? "";
+	const collections = config.collections ?? [];
+	if (!qmdUrl || collections.length === 0) {
+		ctx.logger.warn(
+			"qmd-autosearch: 未配置 qmdUrl 或 collections，插件已禁用。" +
+			"请在 cordis.patch.yml 的 config 中显式指定，例如：\n" +
+			"  config:\n" +
+			"    qmdUrl: http://localhost:6179/mcp\n" +
+			"    collections:\n" +
+			"      - <collection-name>"
+		);
+		return;
+	}
+	const limit = config.limit ?? 5;
+	const minScore = config.minScore ?? 25;
+	const seen = new WeakMap();
+	// 触发路径池：配置的 triggerRoots 优先；否则从 QMD status 解析集合路径（懒加载）
+	let triggerRoots = (config.triggerRoots ?? []).map((p) => {
+		try {
+			return realpathSync(p);
+		} catch {
+			return resolve(p);
+		}
+	});
+	let rootsLoaded = false;
+	const loadTriggerRoots = async () => {
+		if (rootsLoaded || triggerRoots.length > 0) return;
+		rootsLoaded = true;
+		try {
+			const { sessionId } = await mcpRequest(qmdUrl, null, "initialize", {
+				protocolVersion: "2025-03-26",
+				capabilities: {},
+				clientInfo: { name: "qmd-autosearch", version: "0.1.0" }
+			});
+			const { result } = await mcpRequest(qmdUrl, sessionId, "tools/call", {
+				name: "status",
+				arguments: {}
+			});
+			triggerRoots = parseCollectionRoots(extractText(result));
+			ctx.logger.info("qmd-autosearch: 触发路径池（来自 QMD 集合）%d 个", triggerRoots.length);
+		} catch (error) {
+			ctx.logger.warn("qmd-autosearch: 解析 QMD 集合路径失败: %o", error);
+		}
+	};
+
+	const isOurs = (message) => message.source?.kind === "plugin" && message.source?.plugin === name;
+
+	ctx.on("tools/result", (exec) => {
+		if (exec.parent !== void 0) return; // 只处理顶层调用
+		if (exec.agent === void 0 || exec.signal?.aborted) return;
+		if (!SEARCH_TOOLS.has(exec.name)) return;
+		const args = exec.arguments;
+		if (typeof args !== "object" || args === null) return;
+		const path = typeof args.path === "string" ? args.path : typeof args.cwd === "string" ? args.cwd : "";
+		const pattern = typeof args.pattern === "string" ? args.pattern : "";
+		if (!path || !pattern) return;
+		const resolvedPath = resolve(path);
+
+		loadTriggerRoots().then(() => {
+			if (triggerRoots.length === 0) return;
+			if (!triggerRoots.some((root) => inRoot(root, resolvedPath) || inRoot(root, path))) return;
+
+			// 防重：同 agent 内同签名只补搜一次
+			const sig = `${exec.name}:${resolvedPath}:${pattern}`;
+			let cache = seen.get(exec.agent);
+			if (cache?.has(sig)) return;
+			if (cache === void 0) {
+				cache = new Set();
+				seen.set(exec.agent, cache);
+			}
+			cache.add(sig);
+			if (cache.size > 32) cache.clear();
+
+			const agent = exec.agent;
+			const intentQuery = chooseIntentQuery(recentUserText(agent), pattern);
+			qmdSearch(qmdUrl, collections, intentQuery, pattern, exec.name, { limit, minScore })
+				.then((payload) => {
+					if (!payload.text) return;
+					const message = createUserMessage({
+						content: [{ type: "text", text: renderSupplement(exec.name, pattern, payload) }],
+						source: { kind: "plugin", plugin: name }
+					});
+					agent.inbox.prepend("next-step", message);
+				})
+				.catch((error) => {
+					ctx.logger.warn("qmd-autosearch: %o", error);
+				});
+		});
+	});
+
+	ctx.on("agent/pre-step", async ({ agent, messages, step }, next) => {
+		const decision = await next();
+		const pending = agent.inbox.nextStep.filter(isOurs);
+		if (pending.length === 0) return decision;
+		if (decision.kind === "reject" || (step === 1 && decision.messages.length === 0)) {
+			for (const message of pending) agent.inbox.remove(message.id);
+			return decision;
+		}
+		const lastClaimedIndex = decision.messages.findLastIndex((message) => messages.includes(message));
+		for (const message of pending) agent.inbox.remove(message.id);
+		return {
+			kind: "enter",
+			messages: decision.messages.toSpliced(lastClaimedIndex + 1, 0, ...pending)
+		};
+	});
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "qmd-autosearch",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "description": "DSH plugin: auto-supplement QMD semantic search when the model greps/globs a knowledge-base directory",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "qmd",
+    "semantic-search",
+    "mcp",
+    "knowledge-base"
+  ],
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}