@tachu/extensions 1.0.0-alpha.1

package/dist/tools/apply-patch/executor.js

@@ -0,0 +1,193 @@
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ValidationError } from "@tachu/core";
+import { assertNotAborted, resolveSandboxPolicy } from "../shared";
+import { resolveAllowedPath, toWorkspaceRelativePath } from "../../common/path";
+const normalizePatchPath = (value) => value.replace(/^[ab]\//, "").trim();
+const splitContent = (content) => {
+    if (content.length === 0) {
+        return { lines: [], trailingNewline: false };
+    }
+    const normalized = content.replaceAll("\r\n", "\n");
+    const trailingNewline = normalized.endsWith("\n");
+    const lines = normalized.split("\n");
+    if (trailingNewline) {
+        lines.pop();
+    }
+    return { lines, trailingNewline };
+};
+const parsePatch = (rawPatch) => {
+    const lines = rawPatch.replaceAll("\r\n", "\n").split("\n");
+    const files = [];
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        if (!line.startsWith("--- ")) {
+            index += 1;
+            continue;
+        }
+        const oldPath = normalizePatchPath(line.slice(4));
+        const newLine = lines[index + 1] ?? "";
+        if (!newLine.startsWith("+++ ")) {
+            throw new ValidationError("VALIDATION_PATCH_FORMAT", "patch 缺少 +++ 文件头");
+        }
+        const newPath = normalizePatchPath(newLine.slice(4));
+        index += 2;
+        const hunks = [];
+        while (index < lines.length) {
+            const hunkHeader = lines[index] ?? "";
+            if (hunkHeader.startsWith("--- ")) {
+                break;
+            }
+            if (!hunkHeader.startsWith("@@ ")) {
+                index += 1;
+                continue;
+            }
+            const match = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(hunkHeader);
+            if (!match) {
+                throw new ValidationError("VALIDATION_PATCH_FORMAT", `无效 hunk 头: ${hunkHeader}`);
+            }
+            const oldStart = Number(match[1]);
+            const newStart = Number(match[2]);
+            index += 1;
+            const hunkLines = [];
+            while (index < lines.length) {
+                const hunkLine = lines[index] ?? "";
+                if (hunkLine.startsWith("@@ ") || hunkLine.startsWith("--- ")) {
+                    break;
+                }
+                if (hunkLine === "\") {
+                    index += 1;
+                    continue;
+                }
+                const marker = hunkLine[0];
+                if (marker !== " " && marker !== "+" && marker !== "-") {
+                    throw new ValidationError("VALIDATION_PATCH_FORMAT", `非法 hunk 行: ${hunkLine}`);
+                }
+                hunkLines.push({ type: marker, content: hunkLine.slice(1) });
+                index += 1;
+            }
+            hunks.push({ oldStart, newStart, lines: hunkLines });
+        }
+        files.push({ oldPath, newPath, hunks });
+    }
+    if (files.length === 0) {
+        throw new ValidationError("VALIDATION_PATCH_EMPTY", "patch 不包含任何文件");
+    }
+    return files;
+};
+const applyFilePatch = (original, patch) => {
+    const { lines: sourceLines, trailingNewline } = splitContent(original);
+    const result = [];
+    let cursor = 0;
+    for (const hunk of patch.hunks) {
+        const hunkStart = Math.max(0, hunk.oldStart - 1);
+        if (hunkStart < cursor) {
+            throw new ValidationError("VALIDATION_PATCH_CONFLICT", "patch hunk 重叠，无法应用");
+        }
+        result.push(...sourceLines.slice(cursor, hunkStart));
+        let sourceIndex = hunkStart;
+        for (const line of hunk.lines) {
+            if (line.type === " ") {
+                const actual = sourceLines[sourceIndex];
+                if (actual !== line.content) {
+                    throw new ValidationError("VALIDATION_PATCH_CONFLICT", `上下文不匹配: expected "${line.content}" got "${actual ?? "<eof>"}"`);
+                }
+                result.push(actual);
+                sourceIndex += 1;
+                continue;
+            }
+            if (line.type === "-") {
+                const actual = sourceLines[sourceIndex];
+                if (actual !== line.content) {
+                    throw new ValidationError("VALIDATION_PATCH_CONFLICT", `删除行不匹配: expected "${line.content}" got "${actual ?? "<eof>"}"`);
+                }
+                sourceIndex += 1;
+                continue;
+            }
+            result.push(line.content);
+        }
+        cursor = sourceIndex;
+    }
+    result.push(...sourceLines.slice(cursor));
+    return { content: result.join("\n"), trailingNewline };
+};
+/**
+ * 应用 unified diff Tool 执行器。
+ */
+export const applyPatchExecutor = async (input, context) => {
+    assertNotAborted(context.abortSignal);
+    const baseRoot = resolveAllowedPath(input.basePath ?? ".", resolveSandboxPolicy(context));
+    const filePatches = parsePatch(input.patch);
+    const backups = new Map();
+    const applied = [];
+    const rollback = async () => {
+        for (const [path, snapshot] of backups.entries()) {
+            if (!snapshot.exists) {
+                await rm(path, { force: true }).catch(() => undefined);
+                continue;
+            }
+            await mkdir(dirname(path), { recursive: true });
+            const suffix = snapshot.trailingNewline ? "\n" : "";
+            await writeFile(path, `${snapshot.content}${suffix}`);
+        }
+    };
+    try {
+        for (const patch of filePatches) {
+            assertNotAborted(context.abortSignal);
+            const logicalTarget = patch.newPath === "/dev/null" ? patch.oldPath : patch.newPath;
+            // 这里的校验语义与外层沙箱正交：patch 里声明的每个文件路径都必须
+            // 相对 `baseRoot` 不越界，即使外层整体已经 sandboxWaived 也不能让
+            // 单个 patch 跳出用户授权的 basePath（否则一次审批会变成无限通道）。
+            const absoluteTarget = resolveAllowedPath(logicalTarget, { allowedRoots: [baseRoot] });
+            if (!backups.has(absoluteTarget)) {
+                const existing = await readFile(absoluteTarget, "utf8").catch(() => null);
+                if (existing === null) {
+                    backups.set(absoluteTarget, { exists: false, content: "", trailingNewline: false });
+                }
+                else {
+                    const split = splitContent(existing);
+                    backups.set(absoluteTarget, {
+                        exists: true,
+                        content: split.lines.join("\n"),
+                        trailingNewline: split.trailingNewline,
+                    });
+                }
+            }
+            const original = backups.get(absoluteTarget)?.exists
+                ? (await readFile(absoluteTarget, "utf8").catch(() => "") ?? "")
+                : "";
+            const next = applyFilePatch(original, patch);
+            if (patch.newPath === "/dev/null") {
+                await rm(absoluteTarget, { force: true });
+            }
+            else {
+                await mkdir(dirname(absoluteTarget), { recursive: true });
+                const suffix = next.trailingNewline ? "\n" : "";
+                await writeFile(absoluteTarget, `${next.content}${suffix}`);
+            }
+            applied.push({
+                file: toWorkspaceRelativePath(context.workspaceRoot, absoluteTarget),
+                status: "ok",
+            });
+        }
+        return { applied, success: true };
+    }
+    catch (error) {
+        await rollback();
+        const reason = error instanceof Error ? error.message : String(error);
+        if (applied.length === 0) {
+            applied.push({ file: "<none>", status: "failed", reason });
+        }
+        else {
+            const previous = applied[applied.length - 1];
+            applied[applied.length - 1] = {
+                file: previous?.file ?? "<unknown>",
+                status: "failed",
+                reason,
+            };
+        }
+        return { applied, success: false };
+    }
+};
+//# sourceMappingURL=executor.js.map

package/dist/tools/apply-patch/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/tools/apply-patch/executor.ts"],"names":[],"mappings":"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"}

package/dist/tools/fetch-url/descriptor.md

@@ -0,0 +1,44 @@
+---
+kind: tool
+name: fetch-url
+description: 发送 HTTP 请求并返回响应内容
+sideEffect: readonly
+idempotent: false
+requiresApproval: false
+timeout: 15000
+inputSchema:
+  type: object
+  properties:
+    url:
+      type: string
+    method:
+      type: string
+      enum: [GET, POST]
+    headers:
+      type: object
+    body:
+      type: string
+    timeoutMs:
+      type: number
+  required: [url]
+outputSchema:
+  type: object
+  properties:
+    status:
+      type: number
+    headers:
+      type: object
+    body:
+      type: string
+    truncated:
+      type: boolean
+    contentType:
+      type: string
+execute: fetch-url
+---
+
+执行受控网络请求，默认阻止私网地址并限制响应体大小。
+
+响应体返回给 LLM 前会经过两道处理：
+1. `Content-Type: text/html` / `application/xhtml+xml` 时，会剥掉 `<script>` / `<style>` / `<noscript>` / `<svg>` / `<canvas>` 及 HTML 注释，再合并空白，得到一段信噪比更高的正文；
+2. 无论类型，都会按字符数上限（32KB 字符）截断；超出时在末尾追加 `... [内容已截断，完整长度 N 字符]` 提示。`truncated=true` 表示字节层或字符层任一发生了截断。

package/dist/tools/fetch-url/executor.d.ts

@@ -0,0 +1,28 @@
+import type { ToolExecutor } from "../shared";
+interface FetchUrlInput {
+    url: string;
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+}
+interface FetchUrlOutput {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    truncated: boolean;
+    contentType?: string;
+}
+/**
+ * URL 抓取 Tool 执行器。
+ *
+ * 返回给 LLM 的 body 经过两道处理：
+ *   1. 若 `Content-Type: text/html` / `application/xhtml+xml` → HTML → 纯文本清洗
+ *   2. 无论什么类型 → 按字符数截断到 {@link MAX_BODY_CHARS}，尾部追加截断提示
+ *
+ * `truncated` 为 true 时表示**字节层或字符层任一**发生了截断；`contentType` 归一化为小写主
+ * MIME（例如 `text/html` / `application/json`），供上层调用方做进一步判断。
+ */
+export declare const fetchUrlExecutor: ToolExecutor<FetchUrlInput, FetchUrlOutput>;
+export {};
+//# sourceMappingURL=executor.d.ts.map

package/dist/tools/fetch-url/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/tools/fetch-url/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAqED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAAY,CAAC,aAAa,EAAE,cAAc,CA4CxE,CAAC"}

package/dist/tools/fetch-url/executor.js

@@ -0,0 +1,115 @@
+import { assertPublicUrl, readResponseBodyWithLimit, withAbortTimeout } from "../../common/net";
+import { assertNotAborted } from "../shared";
+/**
+ * 响应体字节数上限（保护网络与内存层）。超过会走 {@link readResponseBodyWithLimit} 的尾部截断。
+ */
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/**
+ * 返回给 LLM 的字符数上限。经验值：32KB 字符 ≈ 8k~10k tokens，足以容纳一个文档页面的正文，
+ * 又不至于把下一轮 Agentic Loop 的 context 吹爆。超过会在末尾追加可见的截断提示。
+ */
+const MAX_BODY_CHARS = 32 * 1024;
+/**
+ * 从 `Content-Type` 头提取主 MIME 类型（小写、去掉 `charset=` 等参数）。
+ */
+const parseContentType = (raw) => {
+    if (!raw)
+        return undefined;
+    const main = raw.split(";")[0]?.trim().toLowerCase();
+    return main && main.length > 0 ? main : undefined;
+};
+/**
+ * HTML → 纯文本的极简清洗（不引入第三方解析器）：
+ *   1. 剥 `<!-- ... -->` 注释
+ *   2. 剥 `<script>` / `<style>` / `<noscript>` / `<svg>` / `<canvas>` 块（含内容）
+ *   3. 剥剩余标签
+ *   4. 解码常见 HTML 实体
+ *   5. 归一化空白（多空格 / 多空行合并）
+ *
+ * 目的不是 100% 还原原文结构，而是让 LLM 拿到一段信噪比尚可的正文。
+ */
+const stripHtmlForLlm = (html) => {
+    return html
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "")
+        .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, "")
+        .replace(/<svg\b[^>]*>[\s\S]*?<\/svg>/gi, "")
+        .replace(/<canvas\b[^>]*>[\s\S]*?<\/canvas>/gi, "")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/[ \t]+/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+};
+/**
+ * 按字符数截断，超出时在末尾追加可见的截断提示（让 LLM 知道自己只拿到部分内容）。
+ */
+const clipToChars = (text) => {
+    if (text.length <= MAX_BODY_CHARS)
+        return { text, truncated: false };
+    const clipped = text.slice(0, MAX_BODY_CHARS);
+    return {
+        text: `${clipped}\n\n... [内容已截断，完整长度 ${text.length} 字符]`,
+        truncated: true,
+    };
+};
+const isHtmlLike = (contentType) => {
+    if (!contentType)
+        return false;
+    return contentType === "text/html" || contentType === "application/xhtml+xml";
+};
+/**
+ * URL 抓取 Tool 执行器。
+ *
+ * 返回给 LLM 的 body 经过两道处理：
+ *   1. 若 `Content-Type: text/html` / `application/xhtml+xml` → HTML → 纯文本清洗
+ *   2. 无论什么类型 → 按字符数截断到 {@link MAX_BODY_CHARS}，尾部追加截断提示
+ *
+ * `truncated` 为 true 时表示**字节层或字符层任一**发生了截断；`contentType` 归一化为小写主
+ * MIME（例如 `text/html` / `application/json`），供上层调用方做进一步判断。
+ */
+export const fetchUrlExecutor = async (input, context) => {
+    assertNotAborted(context.abortSignal);
+    const parsed = await assertPublicUrl(input.url);
+    const timeout = withAbortTimeout(context.abortSignal, input.timeoutMs ?? 15_000, "TIMEOUT_FETCH_URL");
+    try {
+        const response = await fetch(parsed, {
+            method: input.method ?? "GET",
+            headers: input.headers,
+            body: input.body,
+            signal: timeout.signal,
+        });
+        const bodyResult = await readResponseBodyWithLimit(response, MAX_BODY_BYTES);
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        const contentType = parseContentType(response.headers.get("content-type"));
+        let body = bodyResult.body;
+        let truncated = bodyResult.truncated;
+        if (isHtmlLike(contentType)) {
+            body = stripHtmlForLlm(body);
+        }
+        const clipped = clipToChars(body);
+        body = clipped.text;
+        if (clipped.truncated)
+            truncated = true;
+        return {
+            status: response.status,
+            headers,
+            body,
+            truncated,
+            ...(contentType ? { contentType } : {}),
+        };
+    }
+    finally {
+        timeout.cleanup();
+    }
+};
+//# sourceMappingURL=executor.js.map

package/dist/tools/fetch-url/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/tools/fetch-url/executor.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDescriptor } from "@tachu/core";
+import type { ToolExecutor } from "./shared";
+/**
+ * 内置工具描述符列表。
+ */
+export declare const toolDescriptors: ToolDescriptor[];
+/**
+ * 工具执行函数注册表。
+ */
+export declare const toolExecutors: Record<string, ToolExecutor>;
+export type { ToolExecutor, ToolExecutionContext } from "./shared";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAW7C;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,EAqQ3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAUtD,CAAC;AAEF,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC"}