@downcity/agent 1.1.287 → 1.1.310

package/bin/workspace/file/FileEncoding.js

@@ -0,0 +1,152 @@
+/**
+ * 文件内容检测与编码辅助。
+ *
+ * 关键点（中文）
+ * - 二进制检测只把 NUL 和低位控制字符视为高风险，避免误判 UTF-8 中文。
+ * - 文本解码使用 fatal 模式，禁止静默插入替换字符。
+ * - 第一版仅接受 UTF-8 和带 BOM 的 UTF-16 文本。
+ */
+import crypto from "node:crypto";
+import path from "node:path";
+import { FileToolRuntimeError } from "../../workspace/file/FileToolError.js";
+const BINARY_SAMPLE_BYTES = 512;
+/** 计算文件内容的 SHA-256。 */
+export function create_file_sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+/** 根据 BOM 判断文本编码。 */
+export function detect_text_encoding(buffer) {
+    if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+        return "utf-16le";
+    }
+    if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+        return "utf-16be";
+    }
+    return "utf-8";
+}
+/** 保守判断一个文件是否为二进制。 */
+export function is_binary_file(buffer) {
+    const encoding = detect_text_encoding(buffer);
+    if (encoding !== "utf-8")
+        return false;
+    const sample = buffer.subarray(0, Math.min(buffer.length, BINARY_SAMPLE_BYTES));
+    if (sample.includes(0))
+        return true;
+    if (sample.length === 0)
+        return false;
+    let control_bytes = 0;
+    for (const byte of sample) {
+        if ((byte < 7 || (byte > 13 && byte < 32)) && byte !== 0) {
+            control_bytes += 1;
+        }
+    }
+    return control_bytes / sample.length > 0.3;
+}
+/** 根据文件签名识别模型可直接读取的静态图片 MIME。 */
+export function detect_image_file_mime_type(buffer) {
+    if (buffer.length >= 8 &&
+        buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return "image/png";
+    }
+    if (buffer.length >= 3 &&
+        buffer[0] === 0xff &&
+        buffer[1] === 0xd8 &&
+        buffer[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const header = buffer.subarray(0, 6).toString("ascii");
+    if (header === "GIF87a" || header === "GIF89a")
+        return "image/gif";
+    if (buffer.length >= 12 &&
+        buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
+        buffer.subarray(8, 12).toString("ascii") === "WEBP") {
+        return "image/webp";
+    }
+    if (buffer.length >= 2 &&
+        buffer[0] === 0x42 &&
+        buffer[1] === 0x4d) {
+        return "image/bmp";
+    }
+    return undefined;
+}
+/** 严格解码文本文件。 */
+export function decode_text_file(buffer) {
+    const encoding = detect_text_encoding(buffer);
+    try {
+        const decoder = new TextDecoder(encoding, { fatal: true });
+        return {
+            content: decoder.decode(buffer),
+            encoding,
+        };
+    }
+    catch {
+        throw new FileToolRuntimeError({
+            error_code: "encoding_error",
+            message: `File is not valid ${encoding} text`,
+        });
+    }
+}
+/** 按原文本编码重新编码内容，并保留 UTF-16 BOM。 */
+export function encode_text_file(content, encoding) {
+    if (encoding === "utf-8")
+        return Buffer.from(content, "utf8");
+    const utf16le_content = Buffer.from(content, "utf16le");
+    if (encoding === "utf-16le") {
+        return Buffer.concat([Buffer.from([0xff, 0xfe]), utf16le_content]);
+    }
+    const utf16be_content = Buffer.from(utf16le_content);
+    for (let index = 0; index + 1 < utf16be_content.length; index += 2) {
+        const first_byte = utf16be_content[index];
+        utf16be_content[index] = utf16be_content[index + 1];
+        utf16be_content[index + 1] = first_byte;
+    }
+    return Buffer.concat([Buffer.from([0xfe, 0xff]), utf16be_content]);
+}
+/** 把调用方文本统一为 LF 换行。 */
+export function normalize_text_to_lf(content) {
+    return content.replace(/\r\n|\r/g, "\n");
+}
+/** 统计可见文本行数，不把尾随换行后的空位置计为新行。 */
+export function count_text_lines(content) {
+    if (content.length === 0)
+        return 0;
+    const normalized = normalize_text_to_lf(content);
+    const lines = normalized.split("\n");
+    if (normalized.endsWith("\n"))
+        lines.pop();
+    return lines.length;
+}
+/** 根据扩展名识别常见 MIME 类型。 */
+export function detect_file_mime_type(file_path) {
+    const extension = path.extname(file_path).toLowerCase();
+    const by_extension = {
+        ".txt": "text/plain",
+        ".md": "text/markdown",
+        ".mdx": "text/mdx",
+        ".json": "application/json",
+        ".jsonl": "application/x-ndjson",
+        ".js": "text/javascript",
+        ".mjs": "text/javascript",
+        ".cjs": "text/javascript",
+        ".ts": "text/typescript",
+        ".tsx": "text/tsx",
+        ".jsx": "text/jsx",
+        ".css": "text/css",
+        ".html": "text/html",
+        ".xml": "application/xml",
+        ".yaml": "application/yaml",
+        ".yml": "application/yaml",
+        ".csv": "text/csv",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+        ".pdf": "application/pdf",
+        ".zip": "application/zip",
+    };
+    return by_extension[extension];
+}
+//# sourceMappingURL=FileEncoding.js.map

package/bin/workspace/file/FileEncoding.js.map

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

package/bin/workspace/file/FilePathPolicy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 文件工具路径策略。
+ *
+ * 关键点（中文）
+ * - 所有相对路径基于 Shell 的项目根目录解析。
+ * - 词法路径和真实路径都必须位于项目根目录内。
+ * - 最终目标不允许是符号链接，避免原子替换时产生歧义或逃逸。
+ */
+import type { ResolvedFileToolPath } from "../../types/workspace/FileTool.js";
+/** 解析并校验一个项目内文件路径。 */
+export declare function resolve_file_tool_path(params: {
+    /** Shell 当前绑定的项目根目录。 */
+    root_path: string;
+    /** 模型传入的相对路径或绝对路径。 */
+    file_path: string;
+    /** 目标文件不存在时是否仍允许返回路径。 */
+    allow_missing: boolean;
+}): Promise<ResolvedFileToolPath>;
+/** 解析并校验一个项目内搜索路径，允许普通文件或目录。 */
+export declare function resolve_search_tool_path(params: {
+    /** Shell 当前绑定的项目根目录。 */
+    root_path: string;
+    /** 模型传入的相对路径或绝对路径。 */
+    file_path: string;
+}): Promise<ResolvedFileToolPath>;
+//# sourceMappingURL=FilePathPolicy.d.ts.map

package/bin/workspace/file/FilePathPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilePathPolicy.d.ts","sourceRoot":"","sources":["../../../src/workspace/file/FilePathPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AA6H1E,sBAAsB;AACtB,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAEhC;AAED,gCAAgC;AAChC,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAMhC"}

package/bin/workspace/file/FilePathPolicy.js

@@ -0,0 +1,134 @@
+/**
+ * 文件工具路径策略。
+ *
+ * 关键点（中文）
+ * - 所有相对路径基于 Shell 的项目根目录解析。
+ * - 词法路径和真实路径都必须位于项目根目录内。
+ * - 最终目标不允许是符号链接，避免原子替换时产生歧义或逃逸。
+ */
+import path from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import { FileToolRuntimeError } from "../../workspace/file/FileToolError.js";
+/** 判断目标路径是否等于根目录或位于根目录之下。 */
+function is_path_inside_root(root_path, target_path) {
+    const relative_path = path.relative(root_path, target_path);
+    return (relative_path === "" ||
+        (relative_path !== ".." &&
+            !relative_path.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative_path)));
+}
+/** 返回最接近目标且已经存在的祖先目录。 */
+async function resolve_existing_ancestor(target_path) {
+    let current_path = path.dirname(target_path);
+    while (true) {
+        try {
+            const metadata = await lstat(current_path);
+            if (metadata.isSymbolicLink())
+                return current_path;
+            if (!metadata.isDirectory()) {
+                throw new FileToolRuntimeError({
+                    error_code: "not_a_file",
+                    message: `Parent path is not a directory: ${current_path}`,
+                    file_path: target_path,
+                });
+            }
+            return current_path;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const parent_path = path.dirname(current_path);
+        if (parent_path === current_path)
+            return current_path;
+        current_path = parent_path;
+    }
+}
+/** 解析并校验一个项目内文件或搜索路径。 */
+async function resolve_project_tool_path(params) {
+    const raw_root_path = String(params.root_path || "").trim();
+    const raw_file_path = String(params.file_path || "").trim();
+    if (!raw_root_path) {
+        throw new FileToolRuntimeError({
+            error_code: "invalid_path",
+            message: "Workspace file tools require a non-empty root_path",
+        });
+    }
+    if (!raw_file_path || raw_file_path.includes("\0")) {
+        throw new FileToolRuntimeError({
+            error_code: "invalid_path",
+            message: "file_path must be a non-empty valid path",
+        });
+    }
+    const root_path = path.resolve(raw_root_path);
+    const root_real_path = await realpath(root_path);
+    const file_path = path.resolve(path.isAbsolute(raw_file_path)
+        ? raw_file_path
+        : path.join(root_path, raw_file_path));
+    if (!is_path_inside_root(root_path, file_path)) {
+        throw new FileToolRuntimeError({
+            error_code: "sandbox_denied",
+            message: `File path escapes project root: ${raw_file_path}`,
+            file_path,
+        });
+    }
+    try {
+        const metadata = await lstat(file_path);
+        if (metadata.isSymbolicLink()) {
+            throw new FileToolRuntimeError({
+                error_code: "sandbox_denied",
+                message: `Symbolic link targets are not allowed: ${file_path}`,
+                file_path,
+            });
+        }
+        if (params.require_file && !metadata.isFile()) {
+            throw new FileToolRuntimeError({
+                error_code: "not_a_file",
+                message: `Expected a regular file: ${file_path}`,
+                file_path,
+            });
+        }
+        const file_real_path = await realpath(file_path);
+        if (!is_path_inside_root(root_real_path, file_real_path)) {
+            throw new FileToolRuntimeError({
+                error_code: "sandbox_denied",
+                message: `Resolved file path escapes project root: ${file_path}`,
+                file_path,
+            });
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        if (!params.allow_missing) {
+            throw new FileToolRuntimeError({
+                error_code: "file_not_found",
+                message: `File not found: ${file_path}`,
+                file_path,
+            });
+        }
+        const ancestor_path = await resolve_existing_ancestor(file_path);
+        const ancestor_real_path = await realpath(ancestor_path);
+        if (!is_path_inside_root(root_real_path, ancestor_real_path)) {
+            throw new FileToolRuntimeError({
+                error_code: "sandbox_denied",
+                message: `Resolved parent path escapes project root: ${file_path}`,
+                file_path,
+            });
+        }
+    }
+    return { file_path, root_path };
+}
+/** 解析并校验一个项目内文件路径。 */
+export async function resolve_file_tool_path(params) {
+    return await resolve_project_tool_path({ ...params, require_file: true });
+}
+/** 解析并校验一个项目内搜索路径，允许普通文件或目录。 */
+export async function resolve_search_tool_path(params) {
+    return await resolve_project_tool_path({
+        ...params,
+        allow_missing: false,
+        require_file: false,
+    });
+}
+//# sourceMappingURL=FilePathPolicy.js.map

package/bin/workspace/file/FilePathPolicy.js.map

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

package/bin/workspace/file/FileToolError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 文件工具内部错误。
+ *
+ * 关键点（中文）
+ * - 内部流程通过类型化错误中断，tool 边界再统一转换为结构化失败结果。
+ * - 不把 Node.js 原始错误码直接暴露为公共协议。
+ */
+import type { FileEditDetail, FileToolErrorCode, FileToolFailure } from "../../types/workspace/FileTool.js";
+/** 文件工具可识别的内部错误。 */
+export declare class FileToolRuntimeError extends Error {
+    /** 稳定的公共错误码。 */
+    readonly error_code: FileToolErrorCode;
+    /** 已完成解析时的目标绝对路径。 */
+    readonly file_path?: string;
+    /** 编辑失败时的匹配详情。 */
+    readonly details?: FileEditDetail[];
+    constructor(params: {
+        /** 稳定的公共错误码。 */
+        error_code: FileToolErrorCode;
+        /** 人类可读错误信息。 */
+        message: string;
+        /** 已完成解析时的目标绝对路径。 */
+        file_path?: string;
+        /** 编辑失败时的匹配详情。 */
+        details?: FileEditDetail[];
+    });
+}
+/** 把内部或 Node.js 错误转换为稳定失败结果。 */
+export declare function to_file_tool_failure(error: unknown, fallback_file_path?: string): FileToolFailure;
+//# sourceMappingURL=FileToolError.d.ts.map

package/bin/workspace/file/FileToolError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileToolError.d.ts","sourceRoot":"","sources":["../../../src/workspace/file/FileToolError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EAChB,MAAM,+BAA+B,CAAC;AAEvC,oBAAoB;AACpB,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,gBAAgB;IAChB,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,qBAAqB;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB;IAClB,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;gBAExB,MAAM,EAAE;QAClB,gBAAgB;QAChB,UAAU,EAAE,iBAAiB,CAAC;QAC9B,gBAAgB;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,qBAAqB;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,kBAAkB;QAClB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;KAC5B;CAOF;AAED,gCAAgC;AAChC,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,kBAAkB,CAAC,EAAE,MAAM,GAC1B,eAAe,CAqDjB"}

package/bin/workspace/file/FileToolError.js

@@ -0,0 +1,78 @@
+/**
+ * 文件工具内部错误。
+ *
+ * 关键点（中文）
+ * - 内部流程通过类型化错误中断，tool 边界再统一转换为结构化失败结果。
+ * - 不把 Node.js 原始错误码直接暴露为公共协议。
+ */
+/** 文件工具可识别的内部错误。 */
+export class FileToolRuntimeError extends Error {
+    /** 稳定的公共错误码。 */
+    error_code;
+    /** 已完成解析时的目标绝对路径。 */
+    file_path;
+    /** 编辑失败时的匹配详情。 */
+    details;
+    constructor(params) {
+        super(params.message);
+        this.name = "FileToolRuntimeError";
+        this.error_code = params.error_code;
+        this.file_path = params.file_path;
+        this.details = params.details;
+    }
+}
+/** 把内部或 Node.js 错误转换为稳定失败结果。 */
+export function to_file_tool_failure(error, fallback_file_path) {
+    if (error instanceof FileToolRuntimeError) {
+        return {
+            success: false,
+            error_code: error.error_code,
+            message: error.message,
+            ...(error.file_path || fallback_file_path
+                ? { file_path: error.file_path || fallback_file_path }
+                : {}),
+            ...(error.details ? { details: error.details } : {}),
+        };
+    }
+    const node_error = error;
+    const code = String(node_error?.code || "");
+    if (code === "ENOENT") {
+        return {
+            success: false,
+            error_code: "file_not_found",
+            message: `File not found: ${fallback_file_path || "unknown path"}`,
+            ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+        };
+    }
+    if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+        return {
+            success: false,
+            error_code: "permission_denied",
+            message: `Permission denied: ${fallback_file_path || "unknown path"}`,
+            ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+        };
+    }
+    if (code === "EISDIR") {
+        return {
+            success: false,
+            error_code: "not_a_file",
+            message: `Expected a file: ${fallback_file_path || "unknown path"}`,
+            ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+        };
+    }
+    if (code === "EEXIST") {
+        return {
+            success: false,
+            error_code: "file_exists",
+            message: `File already exists: ${fallback_file_path || "unknown path"}`,
+            ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+        };
+    }
+    return {
+        success: false,
+        error_code: "internal_error",
+        message: error instanceof Error ? error.message : String(error),
+        ...(fallback_file_path ? { file_path: fallback_file_path } : {}),
+    };
+}
+//# sourceMappingURL=FileToolError.js.map

package/bin/workspace/file/FileToolError.js.map

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

package/bin/workspace/search/SearchActionRuntime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 项目搜索 action 运行时。
+ *
+ * 关键点（中文）
+ * - `grep` 通过参数数组执行 `rg --json`，不会把模型输入拼接进 shell 命令。
+ * - `find` 通过 globby 流式发现文件，尊重 `.gitignore` 且不跟随符号链接。
+ * - 两个 action 都复用项目根目录约束，并在结果达到上限后尽快停止扫描。
+ */
+import type { SearchToolActionRequest, SearchToolActionResult } from "../../types/workspace/SearchTool.js";
+/** 执行一个项目搜索 action。 */
+export declare function run_search_action(context: {
+    readonly rootPath: string;
+}, request: SearchToolActionRequest): Promise<SearchToolActionResult>;
+//# sourceMappingURL=SearchActionRuntime.d.ts.map

package/bin/workspace/search/SearchActionRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchActionRuntime.d.ts","sourceRoot":"","sources":["../../../src/workspace/search/SearchActionRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAMV,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AA6YzC,uBAAuB;AACvB,wBAAsB,iBAAiB,CACrC,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACtC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAajC"}