@hilariouhiss/dsh-colgrep 1.1.0 → 1.2.0

package/README.md

@@ -18,7 +18,8 @@
 |---|---|---|
 | `query` | string（必填） | 自然语言查询 |
 | `command` | enum `search`(默认)/`init`/`status`/`clear` | 检索 / 建索引 / 查状态 / 清索引 |
-| `path` | string | 待检索/索引的文件或目录（默认工作区根） |
+| `root` | string | 检索/索引哪个项目（默认工作区根；可绝对路径或相对工作区解析） |
+| `path` | string | `root` 内的检索目标（默认整个 `root`）。注意：colgrep 会回落到项目索引，所以它是「聚焦」而非硬过滤 —— 要硬收窄请用 `include` / `pattern` |
 | `top_k` | integer | 结果数（`-k`，默认 15） |
 | `pattern` | string | 正则预筛（`-e`，hybrid：先 grep 再语义排序） |
 | `include` | string | 只检索匹配 glob 的文件（`--include`，如 `"*.rs"`） |
@@ -29,7 +30,9 @@
 
 - 结果以 `--json` 解析后折叠为紧凑可读文本（`文件:行-行 [语言, 类型, 名称] (score)` + 首行签名），不倾倒整段代码；模型可再 `read` 具体文件。解析兼容顶层数组与 `{results:[...]}` 两种 JSON 形状；`query` 为空或纯空白时返回明确错误。
 - **索引重定位**：DSH 文件沙箱禁止写工作区之外，而 colgrep 检索需要写索引锁文件。插件把索引目录重定位到 `<工作区>/.colgrep-data`（通过 `COLGREP_DATA_DIR`），使全部写入落在沙箱允许范围内。ColBERT 模型与 ONNX runtime 从 `~/.cache` 只读加载，无需联网。
+- **显式根目录**：`root` 只改变检索**运行的位置**（`workdir`），不改变索引位置 —— 索引数据始终留在 `<工作区>/.colgrep-data`，因为 colgrep 的索引是**按项目注册的**（`<data_dir>/indices/<项目名>-<hash>`），一个数据目录可以同时容纳多个项目的索引，跨项目检索不会把数据写到别人的仓库里。**真正限制结果范围的是 `root`**（换项目）；`path` 相对 `root` 解析（无 `root` 时相对工作区，与旧行为一致），只做聚焦、不保证排他。
 - 首次检索会自动建立索引（CPU 上大仓库可能需数分钟）；可用 `command:"init"` 显式建索引，`no_update:true` 走现有索引。
+- **主动使用**：注册 `colgrep:guidance` 提示词段（每回合重算，带上当前会话工作区路径），让模型在「按含义找代码、但说不出确切标识符」时优先用 `colgrep` 而不是 grep。
 
 ## 前置要求
 

package/lib/index.js

@@ -1,11 +1,30 @@
+import { resolve } from "node:path";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 
 export const name = "colgrep";
-export const inject = ["tools", "shell", "sandboxPolicy"];
+export const inject = ["tools", "shell", "sandboxPolicy", "systemPrompt"];
 
 const LONG_PATH_PREFIX = String.fromCharCode(92, 92, 63, 92); // "\\?\"
 
-const TOOL_DESCRIPTION = `Semantic code search over the workspace using the local colgrep CLI (ColBERT multi-vector search). Finds code by meaning, not exact text. Use a natural-language \`query\` such as "error handling for database connections". Defaults to \`search\`; the first search auto-builds/updates the index (can take a while). Use \`command:"status"\` to inspect the index, \`command:"init"\` to (re)build it explicitly, and \`no_update:true\` for a fast search over an existing index. Use \`pattern\` to pre-filter by regex, \`include\` to limit file types (e.g. "*.rs"), and \`code_only\` to skip text/config files.`;
+const TOOL_DESCRIPTION = `Semantic code search over the workspace using the local colgrep CLI (ColBERT multi-vector search). Finds code by meaning, not exact text. Use a natural-language \`query\` such as "error handling for database connections". Defaults to \`search\`; search auto-indexes, so the first run in a project builds the index and is slower. Use \`command:"status"\` to inspect the index, \`command:"init"\` to (re)build it explicitly, and \`no_update:true\` for a fast search over an existing index. Pass \`root\` to search a project other than the workspace, and \`path\` to narrow the search within it. Use \`pattern\` to pre-filter by regex, \`include\` to limit file types (e.g. "*.rs"), and \`code_only\` to skip text/config files.`;
+
+const GUIDANCE = [
+	"Semantic code search is available through the `colgrep` tool. ",
+	"Reach for it when you want code by meaning and cannot name the exact identifier — grep is for text you can already spell out. ",
+	"It auto-indexes on demand, so the first search in a project is slower; use `pattern` for a regex pre-filter that ranks semantically after. ",
+	"Pass `root` to search a project other than the workspace. ",
+].join("");
+
+/**
+ * Usage guidance carrying the current workspace, so the agent passes the right
+ * default root.
+ *
+ * @param {string} cwd the session workspace path.
+ * @returns {string} prompt text for the colgrep guidance section.
+ */
+export function guidanceFor(cwd) {
+	return `${GUIDANCE} Current workspace: ${cwd}; the default root.`;
+}
 
 export function stripPathPrefix(path) {
 	const value = String(path);
@@ -30,9 +49,11 @@ export function buildArgs(args) {
 		if (args.include) argv.push("--include", args.include);
 		if (args.code_only) argv.push("--code-only");
 		argv.push(String(args.query || ""));
+		if (args.root) argv.push(String(args.root));
 		if (args.path) argv.push(args.path);
 	} else if (command === "init") {
 		argv.push("init", "-y");
+		if (args.root) argv.push(String(args.root));
 		if (args.path) argv.push(args.path);
 	} else if (command === "status") {
 		argv.push("status");
@@ -94,13 +115,20 @@ export function renderOutput(value) {
 }
 
 export function apply(ctx) {
+	ctx.systemPrompt.section({
+		name: "colgrep:guidance",
+		order: 100,
+		text: (context) => guidanceFor(context.scope?.session?.header?.cwd ?? process.cwd()),
+	});
+
 	ctx.tools.register(defineTool({
 		name: "colgrep",
 		description: TOOL_DESCRIPTION,
 		parameters: {
 			query: { type: "string", description: "Natural-language query (used by search).", required: true },
 			command: { type: "string", enum: ["search", "init", "status", "clear"], description: "Operation. search (default) finds code; init builds/updates the index; status reports index state; clear removes the index." },
-			path: { type: "string", description: "File or directory to search/index (default: workspace root)." },
+			root: { type: "string", description: "Project directory to search or index (default: the workspace root). Absolute or relative to the workspace." },
+			path: { type: "string", description: "File or directory of `root` to search (default: the whole root). colgrep searches this target and falls back to the project index, so it is a focus, not a hard filter — narrow with `include` or `pattern` instead." },
 			top_k: { type: "integer", description: "Number of results to return (-k). Default 15." },
 			pattern: { type: "string", description: "Regex pre-filter (-e): grep first, then rank semantically (hybrid)." },
 			include: { type: "string", description: "Only search files matching this glob (--include), e.g. \"*.rs\"." },
@@ -118,6 +146,10 @@ export function apply(ctx) {
 			const root = policy && typeof policy.workspaceRoot === "string" ? policy.workspaceRoot : "";
 			const base = root.replace(/[\\/]+$/, "");
 			const dataDir = base + "/.colgrep-data";
+			// `root` moves the run, never the index: index data stays inside the
+			// workspace so it remains under the sandbox policy and the same
+			// registry serves every root.
+			const workdir = args.root && base ? resolve(base, args.root) : base;
 			const command = buildArgs(args).map((part, index) => (index === 0 ? part : quoteArg(part))).join(" ");
 			const spec = ctx.shell.resolve({
 				command,
@@ -125,7 +157,7 @@ export function apply(ctx) {
 				stdoutMaxBytes: 2 * 1024 * 1024,
 				signal: exec.signal,
 				sandboxPolicy: policy,
-				...(base ? { workdir: base, env: { COLGREP_DATA_DIR: dataDir } } : {}),
+				...(workdir ? { workdir, env: { COLGREP_DATA_DIR: dataDir } } : {}),
 			});
 			const run = await ctx.shell.run(spec);
 			const stdout = run.stdout && run.stdout.text ? run.stdout.text : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilariouhiss/dsh-colgrep",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "colgrep — semantic code search (ColBERT multi-vector) for DeepSeek Harness. Adds a `colgrep` tool that finds code by meaning, not exact text.",
   "keywords": [
     "dsh",