@24klynx/tools 0.1.2 → 0.1.5

package/dist/index.mjs

@@ -1,11 +1,11 @@
-import { ToolError } from "@24klynx/core";
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { NotImplementedError, ToolError } from "@24klynx/core";
+import { mkdir, readFile, readdir, stat } from "node:fs/promises";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { exec, execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 //#region src/availability.ts
 function evalAlways() {
 	return { available: true };
@@ -166,7 +166,7 @@ function createToolRegistry() {
 *
 * Limits: 2000 lines per call, binary files return MIME + base64.
 */
-const descriptor$33 = {
+const descriptor$38 = {
 	name: "read_file",
 	description: "读取文件内容。支持 offset/limit 分页。二进制和图片文件以 base64 编码数据加 MIME 类型返回。",
 	inputSchema: {
@@ -233,13 +233,23 @@ const TEXT_EXTENSIONS = new Set([
 	".proto",
 	".vue",
 	".svelte",
-	".astro"
+	".astro",
+	""
+]);
+/** Common files without extensions that should be treated as text. */
+const TEXT_FILENAMES = new Set([
+	"dockerfile",
+	"makefile",
+	"license",
+	"changelog"
 ]);
 function isTextExtension(filePath) {
 	const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
-	return TEXT_EXTENSIONS.has(ext);
+	if (TEXT_EXTENSIONS.has(ext)) return true;
+	const basename = filePath.slice(filePath.lastIndexOf("/") + 1).toLowerCase();
+	return TEXT_FILENAMES.has(basename);
 }
-const handler$30 = { async handle(invocation, signal) {
+const handler$31 = { async handle(invocation, signal) {
 	const { file_path, offset, limit } = invocation.payload;
 	const startTime = Date.now();
 	if (signal.aborted) return {
@@ -337,7 +347,7 @@ function guessMime(filePath) {
 * Creates parent directories automatically. Overwrites existing files
 * without asking (permission pipeline handles safety).
 */
-const descriptor$32 = {
+const descriptor$37 = {
 	name: "write_file",
 	description: "创建新文件或完全覆盖已有文件。父目录不存在时会自动创建。",
 	inputSchema: {
@@ -360,7 +370,7 @@ const descriptor$32 = {
 	executor: "core:write_file",
 	owner: "core"
 };
-const handler$29 = { async handle(invocation, signal) {
+const handler$30 = { async handle(invocation, signal) {
 	const { file_path, content } = invocation.payload;
 	const startTime = Date.now();
 	if (signal.aborted) return {
@@ -370,7 +380,9 @@ const handler$29 = { async handle(invocation, signal) {
 	};
 	try {
 		await mkdir(dirname(file_path), { recursive: true });
-		await writeFile(file_path, content, "utf-8");
+		const tmpPath = file_path + ".tmp";
+		writeFileSync(tmpPath, content, "utf-8");
+		renameSync(tmpPath, file_path);
 		return {
 			success: true,
 			content: `已写入 ${content.length} 字节到 ${file_path}`,
@@ -393,7 +405,7 @@ const handler$29 = { async handle(invocation, signal) {
 * This is the primary editing tool — LLMs should use it instead of write_file
 * for targeted changes.
 */
-const descriptor$31 = {
+const descriptor$36 = {
 	name: "edit_file",
 	description: "在文件中执行精确字符串替换。old_string 必须在文件中精确匹配（包括空格和缩进），除非设置 replace_all 为 true。",
 	inputSchema: {
@@ -428,7 +440,7 @@ const descriptor$31 = {
 	executor: "core:edit_file",
 	owner: "core"
 };
-const handler$28 = { async handle(invocation, signal) {
+const handler$29 = { async handle(invocation, signal) {
 	const { file_path, old_string, new_string, replace_all } = invocation.payload;
 	const startTime = Date.now();
 	if (signal.aborted) return {
@@ -454,7 +466,10 @@ const handler$28 = { async handle(invocation, signal) {
 			content: `old_string 在 ${file_path} 中出现了 ${count} 次。请设置 replace_all: true 替换所有匹配项，或提供更多上下文使匹配唯一。`,
 			metadata: { durationMs: Date.now() - startTime }
 		};
-		await writeFile(file_path, replace_all ? original.replaceAll(old_string, new_string) : original.replace(old_string, new_string), "utf-8");
+		const updated = replace_all ? original.replaceAll(old_string, new_string) : original.replace(old_string, new_string);
+		const tmpPath = file_path + ".tmp";
+		writeFileSync(tmpPath, updated, "utf-8");
+		renameSync(tmpPath, file_path);
 		return {
 			success: true,
 			content: `已在 ${file_path} 中替换 ${replace_all ? count : 1} 处`,
@@ -491,7 +506,7 @@ function countOccurrences$1(haystack, needle) {
 *
 * Returns sorted absolute paths. Default excludes: node_modules, .git, dist, build.
 */
-const descriptor$30 = {
+const descriptor$35 = {
 	name: "glob",
 	description: "用 glob 模式匹配文件。返回排序后的绝对路径。支持 ** 递归匹配、* 通配符。",
 	inputSchema: {
@@ -526,7 +541,7 @@ const DEFAULT_EXCLUDE = new Set([
 	"venv"
 ]);
 const MAX_RESULTS = 1e4;
-const handler$27 = { async handle(invocation, signal) {
+const handler$28 = { async handle(invocation, signal) {
 	const { pattern, path: rootPath } = invocation.payload;
 	const startTime = Date.now();
 	const base = rootPath ? resolve(rootPath) : process.cwd();
@@ -620,13 +635,13 @@ function matchSegment(name, seg) {
 //#endregion
 //#region src/builtin/files/grep.ts
 /**
-* grep — Regular expression content search (ripgrep-backed).
+* grep — 基于 ripgrep 的正则内容搜索工具。
 *
-* Falls back to a pure-JS implementation when rg is not available.
-* Default head_limit=250 to prevent overwhelming output.
+* ripgrep (rg) 为必需依赖。未安装时给出各平台安装命令。
+* 输出有默认行数（250）和字节数（50KB）限制，防止 LLM 上下文溢出。
 */
 promisify(execFile);
-const descriptor$29 = {
+const descriptor$34 = {
 	name: "grep",
 	description: "使用正则表达式搜索文件内容。返回匹配行及可选的上下文。优先使用 ripgrep。",
 	inputSchema: {
@@ -750,7 +765,7 @@ function buildGrepResult(collected, limit, byteTruncated, startTime) {
 /**
 * Classify an error thrown during ripgrep execution and return the
 * appropriate {@link ToolResult}, or `null` if the caller should
-* fall through to the JS fallback.
+* fall through to return the "rg not installed" error.
 */
 function classifyRgError(err, signal, startTime) {
 	if (err.code === "ENOENT") return null;
@@ -776,7 +791,7 @@ function classifyRgError(err, signal, startTime) {
 		metadata: { durationMs: Date.now() - startTime }
 	};
 }
-const handler$26 = { async handle(invocation, signal) {
+const handler$27 = { async handle(invocation, signal) {
 	const { pattern, path, glob, output_mode, "-n": showLineNum, "-i": caseInsensitive, "-C": context, head_limit } = invocation.payload;
 	const startTime = Date.now();
 	if (signal.aborted) return {
@@ -807,7 +822,7 @@ const handler$26 = { async handle(invocation, signal) {
 	}
 	return {
 		success: false,
-		content: "ripgrep (rg) 未安装。请安装 ripgrep 以支持 grep 功能: https://github.com/BurntSushi/ripgrep",
+		content: "ripgrep (rg) 未安装，grep 功能依赖 ripgrep。安装方式：Windows: choco install ripgrep 或 winget install BurntSushi.ripgrep.MSVC、macOS: brew install ripgrep、Linux: apt install ripgrep 或 dnf install ripgrep。详见: https://github.com/BurntSushi/ripgrep",
 		metadata: { durationMs: Date.now() - startTime }
 	};
 } };
@@ -954,7 +969,7 @@ function isUrlAllowed(url) {
 		reason: `域名 "${host}" 不在允许列表中。如需访问请联系用户确认。`
 	};
 }
-const descriptor$28 = {
+const descriptor$33 = {
 	name: "web_fetch",
 	description: "从 URL 获取内容并以文本形式返回。HTTP 自动升级为 HTTPS。跨域重定向会返回给调用方而非自动跟随。每个 URL 的结果缓存 15 分钟。HTML 内容会转换为纯文本。",
 	inputSchema: {
@@ -1089,7 +1104,7 @@ function buildFetchError(err, startTime) {
 		metadata: { durationMs: Date.now() - startTime }
 	};
 }
-const handler$25 = { async handle(invocation, signal) {
+const handler$26 = { async handle(invocation, signal) {
 	const { url, maxChars } = invocation.payload;
 	const charLimit = maxChars ?? 5e4;
 	const startTime = Date.now();
@@ -1162,7 +1177,7 @@ const handler$25 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/files/web-search.ts
-const descriptor$27 = {
+const descriptor$32 = {
 	name: "web_search",
 	description: "搜索网页并返回包含标题、URL 和摘要的结果。支持域名白名单和黑名单过滤。",
 	inputSchema: {
@@ -1286,7 +1301,7 @@ function cacheKey(query, allowed, blocked) {
 	if (blocked?.length) parts.push("block:" + blocked.sort().join(","));
 	return parts.join("|");
 }
-const handler$24 = { async handle(invocation, signal) {
+const handler$25 = { async handle(invocation, signal) {
 	const { query, allowed_domains, blocked_domains } = invocation.payload;
 	const startTime = Date.now();
 	if (signal.aborted) return {
@@ -1348,7 +1363,7 @@ const handler$24 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/files/todo-write.ts
-const descriptor$26 = {
+const descriptor$31 = {
 	name: "todo_write",
 	description: "创建和更新任务列表以跟踪进度。每次调用会替换整个列表。每项任务必须包含 content、status 和 activeForm。",
 	inputSchema: {
@@ -1392,7 +1407,7 @@ const descriptor$26 = {
 	executor: "core:todo_write",
 	owner: "core"
 };
-const handler$23 = { async handle(invocation, _signal) {
+const handler$24 = { async handle(invocation, _signal) {
 	const { todos } = invocation.payload;
 	const startTime = Date.now();
 	if (!Array.isArray(todos)) return {
@@ -1432,6 +1447,117 @@ const handler$23 = { async handle(invocation, _signal) {
 	};
 } };
 //#endregion
+//#region src/builtin/files/bash.ts
+/**
+* bash — 跨平台执行 Shell 命令。
+*
+* Unix (Linux/macOS) 上使用 `bash -c` 执行，
+* Windows 上使用 `cmd /c` 执行（PowerShell 由独立的 powershell 工具处理）。
+* 默认 30 秒超时，stdout/stderr 各截断至 10KB。
+*/
+/** stdout/stderr 最大输出长度（字节），超出部分截断并标记。 */
+const MAX_OUTPUT_LENGTH = 1e4;
+const descriptor$30 = {
+	name: "bash",
+	description: "执行 Shell 命令。在 Unix (Linux/macOS) 上使用 bash -c，在 Windows 上使用 cmd /c。返回 stdout 和 stderr。默认 30 秒超时，输出超出 10KB 会被截断。",
+	inputSchema: {
+		type: "object",
+		properties: {
+			command: {
+				type: "string",
+				description: "要执行的 Shell 命令"
+			},
+			timeout: {
+				type: "number",
+				description: "超时时间（毫秒），默认 30000",
+				default: 3e4
+			}
+		},
+		required: ["command"]
+	},
+	kind: "ExecutesCode",
+	safety: "RequiresApproval",
+	availability: { type: "always" },
+	executor: "core:bash",
+	owner: "core"
+};
+const handler$23 = { async handle(invocation, signal) {
+	const { command, timeout } = invocation.payload;
+	const startTime = Date.now();
+	if (signal.aborted) return {
+		success: false,
+		content: "操作已取消",
+		metadata: { durationMs: Date.now() - startTime }
+	};
+	if (!command || command.trim().length === 0) return {
+		success: false,
+		content: "请输入要执行的命令。",
+		metadata: { durationMs: Date.now() - startTime }
+	};
+	const timeoutMs = timeout ?? 3e4;
+	const shellCmd = buildShellCommand(command);
+	return new Promise((resolve) => {
+		let aborted = false;
+		const onAbort = () => {
+			aborted = true;
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		exec(shellCmd, {
+			timeout: timeoutMs,
+			windowsHide: true
+		}, (err, stdout, stderr) => {
+			signal.removeEventListener("abort", onAbort);
+			if (aborted) {
+				resolve({
+					success: false,
+					content: "操作已取消",
+					metadata: { durationMs: Date.now() - startTime }
+				});
+				return;
+			}
+			if (err) {
+				resolve({
+					success: false,
+					content: err.code === "ETIMEDOUT" || err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ? `命令执行超时（${timeoutMs}ms）` : `命令执行失败 (exit ${err.code ?? "unknown"}): ${err.message}\n\nstderr:\n${stderr}`,
+					metadata: { durationMs: Date.now() - startTime }
+				});
+				return;
+			}
+			const truncatedStdout = truncate(stdout);
+			const truncatedStderr = truncate(stderr);
+			const parts = [];
+			if (truncatedStdout.text) parts.push(`stdout:\n${truncatedStdout.text}`);
+			if (truncatedStderr.text) parts.push(`stderr:\n${truncatedStderr.text}`);
+			const output = parts.join("\n\n") || "(无输出)";
+			const wasTruncated = truncatedStdout.truncated || truncatedStderr.truncated;
+			resolve({
+				success: true,
+				content: output,
+				metadata: {
+					durationMs: Date.now() - startTime,
+					truncated: wasTruncated
+				}
+			});
+		});
+	});
+} };
+/** 根据平台构建 Shell 命令字符串。 */
+function buildShellCommand(command) {
+	if (process.platform === "win32") return `cmd /c "${command.replace(/"/g, "\\\"")}"`;
+	return `bash -c '${command.replace(/'/g, `'\\''`)}'`;
+}
+/** 截断超长输出，末尾追加截断提示。 */
+function truncate(raw) {
+	if (raw.length <= MAX_OUTPUT_LENGTH) return {
+		text: raw,
+		truncated: false
+	};
+	return {
+		text: raw.slice(0, MAX_OUTPUT_LENGTH) + `\n...(截断，原 ${raw.length} 字节，仅显示前 ${MAX_OUTPUT_LENGTH} 字节)`,
+		truncated: true
+	};
+}
+//#endregion
 //#region src/builtin/files/powershell.ts
 /**
 * powershell — 在 Windows 上执行 PowerShell 命令。
@@ -1439,7 +1565,7 @@ const handler$23 = { async handle(invocation, _signal) {
 * 仅在 Windows 平台可用。使用 child_process.exec 执行，
 * 默认 30 秒超时。返回 stdout 和 stderr。
 */
-const descriptor$25 = {
+const descriptor$29 = {
 	name: "powershell",
 	description: "在 Windows 上执行 PowerShell 命令。返回 stdout 和 stderr。仅 Windows 平台可用。命令以 -NoProfile 模式运行。",
 	inputSchema: {
@@ -1484,6 +1610,16 @@ const handler$22 = { async handle(invocation, signal) {
 		content: "请输入要执行的 PowerShell 命令。",
 		metadata: { durationMs: Date.now() - startTime }
 	};
+	if (/\$\(/.test(command)) return {
+		success: false,
+		content: "命令包含不安全的子表达式 `$(`。请使用安全的替代方式。",
+		metadata: { durationMs: Date.now() - startTime }
+	};
+	if (/`/.test(command)) return {
+		success: false,
+		content: "命令包含不安全的转义符 `` ` ``。请使用安全的替代方式。",
+		metadata: { durationMs: Date.now() - startTime }
+	};
 	const timeoutMs = timeout ?? 3e4;
 	const escapedCommand = command.replace(/"/g, "\\\"");
 	return new Promise((resolve) => {
@@ -1535,7 +1671,7 @@ const handler$22 = { async handle(invocation, signal) {
 * .ipynb 文件结构为 JSON: { cells: [{ cell_type, source, ... }], ... }
 * source 字段可以是字符串或字符串数组，统一按字符串数组处理。
 */
-const descriptor$24 = {
+const descriptor$28 = {
 	name: "NotebookEditTool",
 	description: "编辑 Jupyter notebook (.ipynb) 文件中的单元格。支持插入、替换、删除和列出代码与 Markdown 单元格。",
 	inputSchema: {
@@ -1740,7 +1876,7 @@ const handler$21 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/files/secret-scan.ts
-const descriptor$23 = {
+const descriptor$27 = {
 	name: "SecretScanner",
 	description: "扫描文件内容以查找潜在的密钥、令牌和凭证。在写入操作前使用此工具检查敏感信息。检测模式包括：私钥、GitHub token、OpenAI key、Google API key、JWT、通用 API key、密码赋值。",
 	inputSchema: {
@@ -1862,7 +1998,7 @@ const handler$20 = { async handle(invocation, signal) {
 * 此工具默认隐藏（需设置 flag "lsp_enabled" 才会暴露）。
 * 当 IDE 连接后将提供完整的 LSP 集成，目前提供接口契约层。
 */
-const descriptor$22 = {
+const descriptor$26 = {
 	name: "LSPTool",
 	description: "查询语言服务器协议（LSP）以获取诊断、类型信息、跳转定义等。支持 diagnostics、hover、definition、references、format 等常见 LSP 操作。",
 	inputSchema: {
@@ -2020,7 +2156,7 @@ function countOccurrences(str, char) {
 */
 /** 活跃的 REPL 会话映射，key 为 session UUID。 */
 const activeSessions = /* @__PURE__ */ new Map();
-const descriptor$21 = {
+const descriptor$25 = {
 	name: "REPLTool",
 	description: "在持久化 REPL 会话中执行代码。启动运行时（Node.js/Python/Bash）并保持状态在多次调用之间。支持 start（启动）、eval（执行）、stop（停止）、status（状态）四种操作。",
 	inputSchema: {
@@ -2243,7 +2379,7 @@ function handleStatus$1() {
 }
 //#endregion
 //#region src/builtin/agent/agent.ts
-const descriptor$20 = {
+const descriptor$24 = {
 	name: "agent",
 	description: "启动子 Agent 自主处理复杂多步骤任务。每种子 Agent 类型拥有不同能力和可用工具。子 Agent 将最终结果返回给父 Agent。",
 	inputSchema: {
@@ -2314,7 +2450,7 @@ const handler$17 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/agent/task.ts
-const descriptor$19 = {
+const descriptor$23 = {
 	name: "task",
 	description: "管理后台任务——创建、列表、获取、更新或停止任务。任务持久化到 SQLite，会话重启后仍存在。适用于跨多个会话的长时间运行操作。",
 	inputSchema: {
@@ -2532,7 +2668,7 @@ function mockDispatch(action, taskId, taskType, taskPayload, taskStatus, startTi
 const handler$16 = buildHandler(null);
 //#endregion
 //#region src/builtin/agent/team-create.ts
-const descriptor$18 = {
+const descriptor$22 = {
 	name: "team_create",
 	description: "创建多 Agent 协作团队。每个成员拥有独立的角色、工具集和模型。团队通过可配置的策略协作完成工作（默认：共识模式）。",
 	inputSchema: {
@@ -2589,30 +2725,16 @@ const descriptor$18 = {
 };
 const handler$15 = { async handle(invocation, signal) {
 	const { name, members, strategy } = invocation.payload;
-	const startTime = Date.now();
 	if (signal.aborted) return {
 		success: false,
 		content: "团队创建已取消",
-		metadata: { durationMs: Date.now() - startTime }
-	};
-	const strat = strategy ?? "consensus";
-	const memberList = members.map((m) => `  - ${m.name} (${m.role})${m.model ? ` [${m.model}]` : ""}`).join("\n");
-	return {
-		success: true,
-		content: [
-			`团队已创建：${name}`,
-			`策略：${strat}`,
-			`成员（${members.length} 人）：`,
-			memberList,
-			"",
-			"[Phase 4 集成：通过 @24klynx/agent 子 Agent 通道实现真实团队编排]"
-		].join("\n"),
-		metadata: { durationMs: Date.now() - startTime }
+		metadata: { durationMs: 0 }
 	};
+	throw new NotImplementedError(`团队 "${name ?? "未命名"}" 创建失败：团队协作引擎将在 Phase 4 实现。当前不支持多 Agent 团队编排（${members?.length ?? 0} 名成员，策略：${strategy ?? "consensus"}）。`);
 } };
 //#endregion
 //#region src/builtin/agent/team-delete.ts
-const descriptor$17 = {
+const descriptor$21 = {
 	name: "team_delete",
 	description: "删除多 Agent 协作团队。移除团队前会终止所有正在执行的成员任务。",
 	inputSchema: {
@@ -2634,25 +2756,16 @@ const descriptor$17 = {
 };
 const handler$14 = { async handle(invocation, signal) {
 	const { team_id } = invocation.payload;
-	const startTime = Date.now();
 	if (signal.aborted) return {
 		success: false,
 		content: "团队删除已取消",
-		metadata: { durationMs: Date.now() - startTime }
-	};
-	return {
-		success: true,
-		content: [
-			`团队已删除：${team_id}`,
-			"所有成员任务已终止。",
-			"[Phase 4 集成：通过 @24klynx/agent 实现真实团队生命周期管理]"
-		].join("\n"),
-		metadata: { durationMs: Date.now() - startTime }
+		metadata: { durationMs: 0 }
 	};
+	throw new NotImplementedError(`团队 "${team_id}" 删除失败：团队协作引擎将在 Phase 4 实现。当前不支持多 Agent 团队生命周期管理。`);
 } };
 //#endregion
 //#region src/builtin/agent/verify-plan.ts
-const descriptor$16 = {
+const descriptor$20 = {
 	name: "verify_plan_execution",
 	description: "验证计划执行是否匹配其规范。逐一检查每个检查点的预期输出与实际输出是否一致。在实施计划后使用此工具，确保无遗漏。",
 	inputSchema: {
@@ -2730,7 +2843,7 @@ const handler$13 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/agent/remote-trigger.ts
-const descriptor$15 = {
+const descriptor$19 = {
 	name: "remote_trigger",
 	description: "通过发送 HTTP 请求（webhook / CI 回调）触发远程任务。支持 GET 和 POST 方法，可自定义请求头和请求体。默认超时 30 秒。",
 	inputSchema: {
@@ -2915,7 +3028,7 @@ function isValidCron(cron) {
 	});
 }
 init$1();
-const descriptor$14 = {
+const descriptor$18 = {
 	name: "ScheduleCronTool",
 	description: "使用 cron 语法安排定时任务。任务在指定时间或间隔触发。支持一次性提醒和循环计划。标准 cron 格式：分 时 日 月 周。也支持 @hourly、@daily、@weekly 别名。",
 	inputSchema: {
@@ -3060,7 +3173,7 @@ function persist() {
 	writeFileSync(STORAGE_FILE, JSON.stringify(Array.from(workflows.values()), null, 2));
 }
 init();
-const descriptor$13 = {
+const descriptor$17 = {
 	name: "WorkflowTool",
 	description: "定义并执行多步骤工作流。每个步骤可以是一个工具调用，步骤之间可以有依赖关系。支持 define（定义）、run（运行）、status（查看状态）、list（列出所有）四种操作。",
 	inputSchema: {
@@ -3167,7 +3280,13 @@ function handleDefine(name, steps) {
 		content: `工作流已定义。ID：${id}\n名称：${name}\n步骤：\n${steps.map((s, i) => `  ${i + 1}. ${s.name} — 调用 ${s.toolName}`).join("\n")}`
 	};
 }
-/** 运行工作流：返回步骤列表供 agent 按顺序执行。 */
+/**
+* 运行工作流：返回步骤指令供 Agent 循环按序执行。
+*
+* 本工具是"指令生成器"而非"执行引擎"——
+* 它输出清晰的步骤文本，由 Agent 循环（loop.ts）负责依次调用各步骤指定的工具。
+* 这样设计是为了让每一步的工具调用都经过权限检查和用户审批流程。
+*/
 function handleRun(workflowId) {
 	if (!workflowId) return {
 		success: false,
@@ -3235,7 +3354,7 @@ function handleList() {
 }
 //#endregion
 //#region src/builtin/agent/tungsten.ts
-const descriptor$12 = {
+const descriptor$16 = {
 	name: "TungstenTool",
 	description: "重型复合工具：并行调度多个子 Agent 处理复杂任务的各个部分，然后综合结果。支持 parallel（并行）、pipeline（流水线）、debate（辩论）三种策略。适用于代码审查、多模块重构、全面调研等大规模任务。",
 	inputSchema: {
@@ -3343,7 +3462,14 @@ function decomposeTask(task, maxAgents) {
 		suggestedAgentRole: "主执行 Agent"
 	}];
 }
-/** 根据策略生成执行计划文本。 */
+/**
+* 根据策略生成执行计划文本。
+*
+* 本工具是"任务规划器"而非"执行引擎"——
+* 它将复杂任务拆解为子任务并输出结构化指令，
+* 实际的子 Agent spawn 由 Agent 工具（agent.ts）负责。
+* Agent 循环读取此计划后逐一创建子 Agent 并收集结果。
+*/
 function buildExecutionPlan(task, subtasks, maxAgents, strategy) {
 	const planLines = [
 		"═══════════════════════════════════════",
@@ -3394,7 +3520,7 @@ function strategyLabel(strategy) {
 }
 //#endregion
 //#region src/builtin/mode/enter-plan-mode.ts
-const descriptor$11 = {
+const descriptor$15 = {
 	name: "enter_plan_mode",
 	description: "进入计划模式 — 切换为只读模式，Agent 只能读取文件和输出设计方案。所有写入/编辑/执行工具将自动被拒绝。在进行重大架构变更前使用此模式，以便在实施前获得用户对方案的认可。",
 	inputSchema: {
@@ -3428,7 +3554,7 @@ const handler$8 = { async handle(_invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/mode/exit-plan-mode.ts
-const descriptor$10 = {
+const descriptor$14 = {
 	name: "exit_plan_mode",
 	description: "退出计划模式，返回普通模式（写入工具重新启用）。计划方案将在执行前展示给用户审批。",
 	inputSchema: {
@@ -3461,7 +3587,7 @@ const handler$7 = { async handle(_invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/mode/enter-worktree.ts
-const descriptor$9 = {
+const descriptor$13 = {
 	name: "enter_worktree",
 	description: "创建新的 git worktree 或进入已有 worktree 进行隔离工作。Worktree 存放在 .claude/worktrees/ 目录下。使用 name 参数创建新 worktree，使用 path 参数进入已有 worktree。",
 	inputSchema: {
@@ -3525,7 +3651,7 @@ const handler$6 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/mode/exit-worktree.ts
-const descriptor$8 = {
+const descriptor$12 = {
 	name: "exit_worktree",
 	description: "退出 git worktree 并返回原始目录。使用 'keep' 保留 worktree，或使用 'remove' 删除（如有未提交变更需搭配 discard_changes）。",
 	inputSchema: {
@@ -3587,7 +3713,7 @@ const handler$5 = { async handle(invocation, signal) {
 * - list: 列出所有配置项
 * - path: 返回配置文件路径
 */
-const descriptor$7 = {
+const descriptor$11 = {
 	name: "ConfigTool",
 	description: "读取或修改 Lynx 配置。可以查看当前配置值或设置新的配置项。支持四种操作：get（获取单个配置项）、set（设置配置项）、list（列出所有配置项）、path（查看配置文件路径）。",
 	inputSchema: {
@@ -3722,7 +3848,7 @@ const handler$4 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/interact/ask-user-question.ts
-const descriptor$6 = {
+const descriptor$10 = {
 	name: "ask_user_question",
 	description: "向用户提出一个或多个澄清性问题并等待回答。支持单选、多选以及自由文本的「其他」选项。当您被一个只有用户才能做决定的问题卡住时使用。",
 	inputSchema: {
@@ -3809,7 +3935,7 @@ const handler$3 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/interact/brief.ts
-const descriptor$5 = {
+const descriptor$9 = {
 	name: "brief",
 	description: "生成当前对话上下文的结构化摘要简报。适用于进度检查点、会话间交接、或向用户提供状态更新。",
 	inputSchema: {
@@ -3869,7 +3995,7 @@ const handler$2 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/interact/synthetic-output.ts
-const descriptor$4 = {
+const descriptor$8 = {
 	name: "synthetic_output",
 	description: "生成符合 JSON Schema 的结构化输出。用于在子 Agent 和父 Agent 之间传递带类型的数据。如果输出无法通过 schema 校验，LLM 会自动重试。",
 	inputSchema: {
@@ -3913,7 +4039,7 @@ const handler$1 = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/interact/sleep.ts
-const descriptor$3 = {
+const descriptor$7 = {
 	name: "sleep",
 	description: "暂停执行指定秒数。用于速率限制退避、等待外部事件或轮询间隔。最长 300 秒。必须提供原因。",
 	inputSchema: {
@@ -3972,7 +4098,7 @@ const handler = { async handle(invocation, signal) {
 } };
 //#endregion
 //#region src/builtin/memory/memory-write.ts
-const descriptor$1 = {
+const descriptor$3 = {
 	name: "memory_write",
 	description: "管理持久化记忆。支持以下操作：create/update — 写入或更新一条记忆；delete — 按名称删除；search — 全文搜索记忆（按相关度排序）；compact — 去重压缩相似条目（Jaccard 相似度 > 0.8）；forget — 按 glob 模式批量删除匹配的记忆；export — 导出全部记忆为 JSON 字符串；import — 从 JSON 字符串批量导入记忆（跳过同名条目）；merge — 合并另一个 memory 目录中的记忆文件。当用户要求记住某事、搜索记忆、清理重复记忆或迁移记忆时使用。",
 	inputSchema: {
@@ -4190,9 +4316,291 @@ function createMemoryWriteHandler(memoryManager) {
 	} };
 }
 //#endregion
-//#region src/builtin/mcp/mcp-auth.ts
+//#region src/builtin/files/tool-search.ts
+const descriptor$6 = {
+	name: "ToolSearchTool",
+	description: "按名称或描述搜索可用的工具。返回匹配工具的摘要信息，包括工具名、用途和安全等级。",
+	inputSchema: {
+		type: "object",
+		properties: { query: {
+			type: "string",
+			description: "搜索关键词（大小写不敏感）"
+		} },
+		required: ["query"]
+	},
+	kind: "ReadOnly",
+	safety: "Safe",
+	availability: { type: "always" },
+	executor: "core:tool_search",
+	owner: "core"
+};
+/**
+* 创建 ToolSearchTool 的 handler。
+*
+* 工厂函数接收获取所有工具描述符的函数，返回 handler。
+* 这样可以在不引入循环依赖的情况下注入工具列表。
+*
+* @param getAllTools — 返回所有已注册 ToolDescriptor 的函数
+*/
+function createToolSearchHandler(getAllTools) {
+	return { async handle(invocation, signal) {
+		const { query } = invocation.payload;
+		const startTime = Date.now();
+		if (signal.aborted) return {
+			success: false,
+			content: "操作已取消",
+			metadata: { durationMs: Date.now() - startTime }
+		};
+		if (!query || query.trim().length === 0) return {
+			success: false,
+			content: "请输入搜索关键词。",
+			metadata: { durationMs: Date.now() - startTime }
+		};
+		const lowerQuery = query.trim().toLowerCase();
+		const matches = getAllTools().filter((tool) => {
+			const nameLower = tool.name.toLowerCase();
+			const descLower = tool.description.toLowerCase();
+			return nameLower.includes(lowerQuery) || descLower.includes(lowerQuery);
+		});
+		if (matches.length === 0) return {
+			success: true,
+			content: `未找到与 "${query.trim()}" 匹配的工具。`,
+			metadata: { durationMs: Date.now() - startTime }
+		};
+		const lines = matches.map((tool) => {
+			const safetyLabel = safetyToLabel(tool.safety);
+			return `- **${tool.name}** [${safetyLabel}]\n  ${tool.description}`;
+		});
+		return {
+			success: true,
+			content: `找到 ${matches.length} 个匹配的工具:\n\n${lines.join("\n\n")}`,
+			metadata: { durationMs: Date.now() - startTime }
+		};
+	} };
+}
+/** 将 safety 枚举值转为中文标签。 */
+function safetyToLabel(safety) {
+	switch (safety) {
+		case "Safe": return "安全";
+		case "WorkspaceSafe": return "工作区安全";
+		case "RequiresApproval": return "需审批";
+		case "Dangerous": return "危险";
+		default: return safety;
+	}
+}
+//#endregion
+//#region src/builtin/mcp/call-tool.ts
 /** 工具描述符 — 注册到 ToolRegistry 的静态元数据。 */
+const descriptor$2 = {
+	name: "mcp__call_tool",
+	description: "直接调用已连接的 MCP 服务器的工具。使用 serverName 和 toolName 指定目标工具。",
+	inputSchema: {
+		type: "object",
+		properties: {
+			serverName: {
+				type: "string",
+				description: "MCP 服务器名称"
+			},
+			toolName: {
+				type: "string",
+				description: "原始工具名（非命名空间格式）"
+			},
+			arguments: {
+				type: "object",
+				description: "传递给工具的参数"
+			}
+		},
+		required: ["serverName", "toolName"]
+	},
+	kind: "ExecutesCode",
+	safety: "RequiresApproval",
+	availability: { type: "always" },
+	executor: "core:mcp_call_tool",
+	owner: "core"
+};
+/**
+* 创建 mcp__call_tool 的 handler，绑定到给定的 McpManager。
+*
+* 工厂模式 — McpManager 在 bootstrap 时注入，
+* 因此 lynx-tools 无需依赖 lynx-agent。
+*/
+function createMcpCallToolHandler(mcpManager) {
+	return { async handle(invocation, signal) {
+		const { serverName, toolName, arguments: toolArgs } = invocation.payload;
+		if (!serverName || typeof serverName !== "string") return {
+			success: false,
+			content: "缺少必需参数 serverName"
+		};
+		if (!toolName || typeof toolName !== "string") return {
+			success: false,
+			content: "缺少必需参数 toolName"
+		};
+		const namespacedName = `mcp__${serverName}__${toolName}`;
+		if (signal.aborted) return {
+			success: false,
+			content: "操作已取消"
+		};
+		try {
+			const result = await mcpManager.callTool(namespacedName, toolArgs ?? {});
+			if (result.isError) return {
+				success: false,
+				content: result.content
+			};
+			return {
+				success: true,
+				content: result.content
+			};
+		} catch (err) {
+			return {
+				success: false,
+				content: `MCP 工具调用失败：${err.message}`
+			};
+		}
+	} };
+}
+//#endregion
+//#region src/builtin/mcp/list-resources.ts
+/** 工具描述符。 */
 const descriptor = {
+	name: "ListMcpResourcesTool",
+	description: "列出已连接 MCP 服务器提供的资源。可指定 server 名称进行过滤。",
+	inputSchema: {
+		type: "object",
+		properties: { server: {
+			type: "string",
+			description: "过滤特定 MCP 服务器（可选）"
+		} }
+	},
+	kind: "ReadOnly",
+	safety: "Safe",
+	availability: { type: "always" },
+	executor: "core:mcp_list_resources",
+	owner: "core"
+};
+/**
+* 创建 ListMcpResourcesTool 的 handler，绑定到给定的 McpManager。
+*
+* 工厂模式 — McpManager 在 bootstrap 时注入。
+*/
+function createListMcpResourcesHandler(mcpManager) {
+	return { async handle(invocation, _signal) {
+		const { server } = invocation.payload;
+		if (!mcpManager.hasResourceCapability()) return {
+			success: true,
+			content: "当前没有已连接且支持 resources 协议的 MCP 服务器。"
+		};
+		let resources = mcpManager.getAllResources();
+		if (server && typeof server === "string") {
+			resources = resources.filter((r) => r.server === server);
+			if (resources.length === 0) return {
+				success: true,
+				content: `服务器 "${server}" 未提供任何资源，或未连接。`
+			};
+		}
+		if (resources.length === 0) return {
+			success: true,
+			content: "已连接的 MCP 服务器未提供任何资源。"
+		};
+		const lines = resources.map((r) => {
+			const parts = [`- **${r.name}**`];
+			parts.push(`(server: ${r.server})`);
+			parts.push(`uri: \`${r.uri}\``);
+			if (r.mimeType) parts.push(`mimeType: ${r.mimeType}`);
+			if (r.description) parts.push(`${r.description}`);
+			return parts.join("  \n  ");
+		});
+		return {
+			success: true,
+			content: `已连接 MCP 服务器资源列表（共 ${resources.length} 项）：\n\n${lines.join("\n")}`
+		};
+	} };
+}
+//#endregion
+//#region src/builtin/mcp/read-resource.ts
+/**
+* ReadMcpResourceTool — 通过 URI 读取 MCP 资源的内容。
+*
+* 文本内容直接返回，二进制内容保存到临时文件并返回文件路径。
+*/
+/** 工具描述符。 */
+const descriptor$4 = {
+	name: "ReadMcpResourceTool",
+	description: "通过 URI 读取 MCP 资源的内容。二进制资源将保存到临时文件并返回文件路径。",
+	inputSchema: {
+		type: "object",
+		properties: {
+			server: {
+				type: "string",
+				description: "MCP 服务器名称"
+			},
+			uri: {
+				type: "string",
+				description: "资源 URI"
+			}
+		},
+		required: ["server", "uri"]
+	},
+	kind: "ReadOnly",
+	safety: "Safe",
+	availability: { type: "always" },
+	executor: "core:mcp_read_resource",
+	owner: "core"
+};
+/**
+* 创建 ReadMcpResourceTool 的 handler，绑定到给定的 McpManager。
+*
+* 工厂模式 — McpManager 在 bootstrap 时注入。
+*/
+function createReadMcpResourceHandler(mcpManager) {
+	return { async handle(invocation, _signal) {
+		const { server, uri } = invocation.payload;
+		if (!server || typeof server !== "string") return {
+			success: false,
+			content: "缺少必需参数 server"
+		};
+		if (!uri || typeof uri !== "string") return {
+			success: false,
+			content: "缺少必需参数 uri"
+		};
+		try {
+			const contents = (await mcpManager.readResource(server, uri)).contents;
+			if (!contents || contents.length === 0) return {
+				success: true,
+				content: `资源 "${uri}" 返回了空内容。`
+			};
+			const textContents = [];
+			const binaryContents = [];
+			for (const item of contents) {
+				const c = item;
+				if (c.text !== void 0) textContents.push(c.text);
+				else if (c.blob !== void 0) {
+					const tmpDir = join(tmpdir(), "lynx-mcp-resources");
+					mkdirSync(tmpDir, { recursive: true });
+					const filePath = join(tmpDir, uri.replace(/[^a-zA-Z0-9._-]/g, "_").slice(-64) || "resource");
+					writeFileSync(filePath, Buffer.from(c.blob, "base64"));
+					const mimeLabel = c.mimeType ? ` (${c.mimeType})` : "";
+					binaryContents.push(`二进制内容${mimeLabel}已保存到：${filePath}`);
+				}
+			}
+			const parts = [];
+			if (textContents.length > 0) parts.push(textContents.join("\n---\n"));
+			if (binaryContents.length > 0) parts.push(binaryContents.join("\n"));
+			return {
+				success: true,
+				content: parts.join("\n\n") || "(空内容)"
+			};
+		} catch (err) {
+			return {
+				success: false,
+				content: `读取 MCP 资源失败：${err.message}`
+			};
+		}
+	} };
+}
+//#endregion
+//#region src/builtin/mcp/mcp-auth.ts
+/** 工具描述符 — 注册到 ToolRegistry 的静态元数据。 */
+const descriptor$1 = {
 	name: "McpAuthTool",
 	description: "触发 MCP 服务器的重新认证流程（OAuth 或 XAA）。用于在工具调用失败并返回认证错误时。",
 	inputSchema: {
@@ -4240,7 +4648,7 @@ function createMcpAuthHandler(mcpOps) {
 }
 //#endregion
 //#region src/builtin/interact/send-message.ts
-const descriptor$2 = {
+const descriptor$5 = {
 	name: "SendMessageTool",
 	description: "通过配置的消息通道发送消息（飞书等）。用于向用户发送通知或进度摘要。需要提前配置消息通道。",
 	inputSchema: {
@@ -4309,127 +4717,131 @@ function createSendMessageHandler(sender) {
 /** All built‑in (descriptor, handler) pairs in registration order. */
 const BUILTIN_TOOLS = [
 	{
-		descriptor: descriptor$33,
+		descriptor: descriptor$38,
+		handler: handler$31
+	},
+	{
+		descriptor: descriptor$37,
 		handler: handler$30
 	},
 	{
-		descriptor: descriptor$32,
+		descriptor: descriptor$36,
 		handler: handler$29
 	},
 	{
-		descriptor: descriptor$31,
+		descriptor: descriptor$35,
 		handler: handler$28
 	},
 	{
-		descriptor: descriptor$30,
+		descriptor: descriptor$34,
 		handler: handler$27
 	},
 	{
-		descriptor: descriptor$29,
+		descriptor: descriptor$33,
 		handler: handler$26
 	},
 	{
-		descriptor: descriptor$28,
+		descriptor: descriptor$32,
 		handler: handler$25
 	},
 	{
-		descriptor: descriptor$27,
+		descriptor: descriptor$31,
 		handler: handler$24
 	},
 	{
-		descriptor: descriptor$26,
+		descriptor: descriptor$30,
 		handler: handler$23
 	},
 	{
-		descriptor: descriptor$25,
+		descriptor: descriptor$29,
 		handler: handler$22
 	},
 	{
-		descriptor: descriptor$24,
+		descriptor: descriptor$28,
 		handler: handler$21
 	},
 	{
-		descriptor: descriptor$23,
+		descriptor: descriptor$27,
 		handler: handler$20
 	},
 	{
-		descriptor: descriptor$22,
+		descriptor: descriptor$26,
 		handler: handler$19
 	},
 	{
-		descriptor: descriptor$21,
+		descriptor: descriptor$25,
 		handler: handler$18
 	},
 	{
-		descriptor: descriptor$20,
+		descriptor: descriptor$24,
 		handler: handler$17
 	},
 	{
-		descriptor: descriptor$19,
+		descriptor: descriptor$23,
 		handler: handler$16
 	},
 	{
-		descriptor: descriptor$18,
+		descriptor: descriptor$22,
 		handler: handler$15
 	},
 	{
-		descriptor: descriptor$17,
+		descriptor: descriptor$21,
 		handler: handler$14
 	},
 	{
-		descriptor: descriptor$16,
+		descriptor: descriptor$20,
 		handler: handler$13
 	},
 	{
-		descriptor: descriptor$15,
+		descriptor: descriptor$19,
 		handler: handler$12
 	},
 	{
-		descriptor: descriptor$14,
+		descriptor: descriptor$18,
 		handler: handler$11
 	},
 	{
-		descriptor: descriptor$13,
+		descriptor: descriptor$17,
 		handler: handler$10
 	},
 	{
-		descriptor: descriptor$12,
+		descriptor: descriptor$16,
 		handler: handler$9
 	},
 	{
-		descriptor: descriptor$11,
+		descriptor: descriptor$15,
 		handler: handler$8
 	},
 	{
-		descriptor: descriptor$10,
+		descriptor: descriptor$14,
 		handler: handler$7
 	},
 	{
-		descriptor: descriptor$9,
+		descriptor: descriptor$13,
 		handler: handler$6
 	},
 	{
-		descriptor: descriptor$8,
+		descriptor: descriptor$12,
 		handler: handler$5
 	},
 	{
-		descriptor: descriptor$7,
+		descriptor: descriptor$11,
 		handler: handler$4
 	},
 	{
-		descriptor: descriptor$6,
+		descriptor: descriptor$10,
 		handler: handler$3
 	},
 	{
-		descriptor: descriptor$5,
+		descriptor: descriptor$9,
 		handler: handler$2
 	},
 	{
-		descriptor: descriptor$4,
+		descriptor: descriptor$8,
 		handler: handler$1
 	},
 	{
-		descriptor: descriptor$3,
+		descriptor: descriptor$7,
 		handler
 	}
 ];
@@ -5002,6 +5414,6 @@ function redactSecrets(text) {
 	return result;
 }
 //#endregion
-export { SAFETY_LABELS, buildToolPlan, classifySensitivity as classifyPath, createMcpAuthHandler, createMemoryWriteHandler, createSendMessageHandler, createTaskHandler, createToolRegistry, escalateForSensitivePaths, evaluateAvailability, injectTaskManager, isBlockedCommand, isHeadlessSafe, isTrustedCommand, isPathSafe as isWithinWorkspace, listBuiltinDescriptors, descriptor as mcpAuthDescriptor, descriptor$1 as memoryWriteDescriptor, needsApproval, redactSecrets, registerBuiltinTools, sanitizeUnicode, descriptor$2 as sendMessageDescriptor };
+export { SAFETY_LABELS, buildToolPlan, classifySensitivity as classifyPath, createListMcpResourcesHandler, createMcpAuthHandler, createMcpCallToolHandler, createMemoryWriteHandler, createReadMcpResourceHandler, createSendMessageHandler, createTaskHandler, createToolRegistry, createToolSearchHandler, escalateForSensitivePaths, evaluateAvailability, injectTaskManager, isBlockedCommand, isHeadlessSafe, isTrustedCommand, isPathSafe as isWithinWorkspace, listBuiltinDescriptors, descriptor as listMcpResourcesDescriptor, descriptor$1 as mcpAuthDescriptor, descriptor$2 as mcpCallToolDescriptor, descriptor$3 as memoryWriteDescriptor, needsApproval, descriptor$4 as readMcpResourceDescriptor, redactSecrets, registerBuiltinTools, sanitizeUnicode, descriptor$5 as sendMessageDescriptor, descriptor$6 as toolSearchDescriptor };
 
 //# sourceMappingURL=index.mjs.map