@hilariouhiss/dsh-colgrep 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-colgrep contributors
+
+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,93 @@
+# @hilariouhiss/dsh-colgrep
+
+把 [colgrep](https://github.com/lightonai/next-plaid/tree/main/colgrep)（LightOn 的语义代码检索工具：ColBERT 多向量搜索，按“含义”而非“精确文本”找代码）接入 DeepSeek Harness。
+
+本插件以 DSH **bundle 插件**形式提供一个宿主侧模型工具 `colgrep`，安装后对 `web`、`headless` 等任意 profile 的所有会话生效。
+
+## 功能
+
+注册一个 `colgrep` 工具，智能体可用自然语言检索工作区代码，例如：
+
+- `colgrep "error handling for database connections"`
+- `colgrep "auth" -e "async fn" --include "*.rs"`
+- `colgrep command:"init"` / `command:"status"` / `command:"clear"`
+
+工具参数：
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `query` | string（必填） | 自然语言查询 |
+| `command` | enum `search`(默认)/`init`/`status`/`clear` | 检索 / 建索引 / 查状态 / 清索引 |
+| `path` | string | 待检索/索引的文件或目录（默认工作区根） |
+| `top_k` | integer | 结果数（`-k`，默认 15） |
+| `pattern` | string | 正则预筛（`-e`，hybrid：先 grep 再语义排序） |
+| `include` | string | 只检索匹配 glob 的文件（`--include`，如 `"*.rs"`） |
+| `code_only` | boolean | 只检索代码文件，跳过 md/txt/yaml/json 等 |
+| `no_update` | boolean | 跳过自动重建索引，直接检索现有索引 |
+
+行为要点：
+
+- 结果以 `--json` 解析后折叠为紧凑可读文本（`文件:行-行 [语言, 类型, 名称] (score)` + 首行签名），不倾倒整段代码；模型可再 `read` 具体文件。
+- **索引重定位**：DSH 文件沙箱禁止写工作区之外，而 colgrep 检索需要写索引锁文件。插件把索引目录重定位到 `<工作区>/.colgrep-data`（通过 `COLGREP_DATA_DIR`），使全部写入落在沙箱允许范围内。ColBERT 模型与 ONNX runtime 从 `~/.cache` 只读加载，无需联网。
+- 首次检索会自动建立索引（CPU 上大仓库可能需数分钟）；可用 `command:"init"` 显式建索引，`no_update:true` 走现有索引。
+
+## 前置要求
+
+- 已安装 [colgrep](https://github.com/lightonai/next-plaid/tree/main/colgrep) CLI（`cargo install colgrep` 或官方预编译二进制），且 `colgrep` 在 PATH 上。
+- 首次使用前，colgrep 需已下载默认模型 `lightonai/LateOn-Code-edge`（`colgrep "任意查询"` 会自动下载；私有模型需 `HF_TOKEN`，可用 `colgrep set-model` 切换）。
+
+## 安装
+
+```powershell
+dsh plugin --profile web add @hilariouhiss/dsh-colgrep
+```
+
+把 `web` 换成你的 profile 名（例如 `headless`）。然后**重启 dsh**。
+
+`dsh plugin` 会把本包安装进 profile 的 `node_modules`；因为 `package.json` 声明了 `dsh.bundle.patch`，profile 的 bundle 列表会自动追加 `@hilariouhiss/dsh-colgrep`，重启后插件行自动激活。
+
+## 验证
+
+1. 重启后在会话中让模型调用 `colgrep`，例如“用 colgrep 搜索 error handling 相关代码”。
+2. 或让模型执行 `colgrep command:"status"`，应看到当前工作区的索引状态。
+
+## 卸载
+
+```powershell
+dsh plugin --profile web remove @hilariouhiss/dsh-colgrep
+```
+
+然后重启 dsh。
+
+## 开发
+
+```powershell
+pnpm install
+pnpm test
+```
+
+结构：
+
+```
+lib/index.js        插件入口：apply(ctx) 注册 colgrep 工具（defineTool）
+cordis.patch.yml    bundle patch：插入本插件的宿主行
+test/               node:test 单元测试（argv 组装、渲染、execute 管道）
+```
+
+## 发布（给维护者）
+
+```powershell
+cd dsh-colgrep
+pnpm install
+pnpm test
+npm login       # 首次发布前登录 npm
+npm publish     # publishConfig.access 已设为 public
+```
+
+`prepublishOnly` 会在每次发布前自动运行 `npm test`；发布新版本前记得递增 `package.json` 的 `version`。
+
+## 许可与来源
+
+本插件为 MIT 许可。它只调用外部的 `colgrep` CLI，未内置 colgrep 源码；colgrep 本身来自 [lightonai/next-plaid](https://github.com/lightonai/next-plaid)（© LightOn，其自身许可见上游仓库）。
+
+> 提示：若日后升级 dsh 后 `@deepseek-ai/dsh-tools` 的公开 API 发生变化，需同步更新本插件的依赖版本。

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# @hilariouhiss/dsh-colgrep bundle patch: one self-referencing host row.
+#
+# `dsh plugin --profile <name> add @hilariouhiss/dsh-colgrep` installs this
+# package into the profile; because it declares `dsh.bundle.patch`, the profile
+# manifest appends it to the bundle list, and this patch is applied as a layer
+# on boot. The row resolves `@hilariouhiss/dsh-colgrep` from the profile's own
+# node_modules, so the plugin's `apply(ctx)` runs in the host plane: it
+# registers the `colgrep` model tool into the global `tools` layer (visible to
+# every agent preset).
+- insert:
+    - id: colgrep
+      name: '@hilariouhiss/dsh-colgrep'

package/lib/index.js

@@ -0,0 +1,153 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+export const name = "colgrep";
+export const inject = ["tools", "shell", "sandboxPolicy"];
+
+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.`;
+
+export function stripPathPrefix(path) {
+	const value = String(path);
+	return value.startsWith(LONG_PATH_PREFIX) ? value.slice(4) : value;
+}
+
+export function quoteArg(value) {
+	return "'" + String(value).replace(/'/g, "''") + "'";
+}
+
+export function buildArgs(args) {
+	const command = args.command || "search";
+	const argv = ["colgrep"];
+	if (command === "search") {
+		argv.push("--json", "--color", "never", "-y");
+		if (args.no_update) argv.push("--no-update");
+		argv.push("-k", String(args.top_k ? Number(args.top_k) : 15));
+		if (args.pattern) argv.push("-e", args.pattern);
+		if (args.include) argv.push("--include", args.include);
+		if (args.code_only) argv.push("--code-only");
+		argv.push(String(args.query || ""));
+		if (args.path) argv.push(args.path);
+	} else if (command === "init") {
+		argv.push("init", "-y");
+		if (args.path) argv.push(args.path);
+	} else if (command === "status") {
+		argv.push("status");
+	} else if (command === "clear") {
+		argv.push("clear");
+	} else {
+		throw new Error("command must be one of: search, init, status, clear");
+	}
+	return argv;
+}
+
+export function normalizeResults(parsed) {
+	return parsed.map((item) => {
+		const unit = item && item.unit ? item.unit : {};
+		return {
+			file: stripPathPrefix(unit.file),
+			name: unit.name || "",
+			qualified_name: unit.qualified_name || "",
+			line: unit.line,
+			end_line: unit.end_line,
+			language: unit.language || "",
+			unit_type: unit.unit_type || "",
+			signature: unit.signature || "",
+			score: item ? item.score : null,
+		};
+	});
+}
+
+export function renderOutput(value) {
+	if (!value || typeof value !== "object") return String(value);
+	const lines = [];
+	if (value.command === "search" && Array.isArray(value.results)) {
+		lines.push(`colgrep: ${value.results.length} result(s) for ${JSON.stringify(value.query)}`);
+		value.results.forEach((result, index) => {
+			const file = result.file || result.qualified_name || "?";
+			const location = typeof result.line === "number" && typeof result.end_line === "number"
+				? `:${result.line}-${result.end_line}`
+				: "";
+			const meta = [result.language, result.unit_type, result.name].filter(Boolean).join(", ");
+			const score = typeof result.score === "number" ? `score ${result.score.toFixed(2)}` : "";
+			lines.push("");
+			lines.push(`${index + 1}. ${file}${location}${meta ? `  [${meta}]` : ""}${score ? `  (${score})` : ""}`);
+			if (result.signature) {
+				lines.push(`   ${String(result.signature).split("\n")[0].slice(0, 200)}`);
+			}
+		});
+	} else if (value.command === "search") {
+		lines.push(`colgrep search failed (ok=${value.ok})`);
+		if (value.stderr) lines.push(`[stderr]\n${value.stderr}`);
+		else if (value.stdout) lines.push(`[stdout]\n${value.stdout}`);
+	} else {
+		lines.push(`colgrep ${value.command} (exit ${value.exitCode})`);
+		if (value.stdout) lines.push(value.stdout);
+		if (!value.ok && value.stderr) lines.push(`[stderr]\n${value.stderr}`);
+	}
+	if (value.timedOut) lines.push("[timed out]");
+	if (value.aborted) lines.push("[aborted]");
+	return lines.join("\n");
+}
+
+export function apply(ctx) {
+	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)." },
+			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\"." },
+			code_only: { type: "boolean", description: "Only search code files; skip text/config files such as md/txt/yaml/json (--code-only)." },
+			no_update: { type: "boolean", description: "Skip automatic index update and search the existing index as-is (--no-update)." },
+		},
+		output: {
+			schema: { type: "json" },
+			render(_args, value) {
+				return [{ type: "text", text: renderOutput(value) }];
+			},
+		},
+		async execute(args, exec) {
+			const policy = ctx.sandboxPolicy.resolve({ session: exec.agent && exec.agent.session });
+			const root = policy && typeof policy.workspaceRoot === "string" ? policy.workspaceRoot : "";
+			const base = root.replace(/[\\/]+$/, "");
+			const dataDir = base + "/.colgrep-data";
+			const command = buildArgs(args).map((part, index) => (index === 0 ? part : quoteArg(part))).join(" ");
+			const spec = ctx.shell.resolve({
+				command,
+				timeoutMs: 300000,
+				stdoutMaxBytes: 2 * 1024 * 1024,
+				signal: exec.signal,
+				sandboxPolicy: policy,
+				...(base ? { workdir: base, env: { COLGREP_DATA_DIR: dataDir } } : {}),
+			});
+			const run = await ctx.shell.run(spec);
+			const stdout = run.stdout && run.stdout.text ? run.stdout.text : "";
+			const stderr = run.stderr && run.stderr.text ? run.stderr.text : "";
+			const commandName = args.command || "search";
+			const common = {
+				ok: run.exitCode === 0,
+				command: commandName,
+				exitCode: run.exitCode,
+				...(run.timedOut ? { timedOut: true } : {}),
+				...(run.aborted ? { aborted: true } : {}),
+			};
+			if (commandName !== "search") {
+				return { ...common, stdout, stderr };
+			}
+			let parsed = null;
+			try {
+				parsed = JSON.parse(stdout);
+			} catch {
+				parsed = null;
+			}
+			if (Array.isArray(parsed)) {
+				return { ...common, query: args.query, count: parsed.length, results: normalizeResults(parsed) };
+			}
+			return { ...common, query: args.query, results: null, stdout, stderr };
+		},
+	}));
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hilariouhiss/dsh-colgrep",
+  "version": "1.0.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",
+    "deepseek-harness",
+    "dsh-plugin",
+    "colgrep",
+    "semantic-search",
+    "code-search",
+    "colbert"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "dsh-colgrep contributors"
+  },
+  "homepage": "https://github.com/hilariouhiss/dsh-hiss-plugins/tree/main/dsh-colgrep",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hilariouhiss/dsh-hiss-plugins.git",
+    "directory": "dsh-colgrep"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}