@yun520-1/heartflow 0.15.2

package/dist/agent/tools/FileWriteTool.js

@@ -0,0 +1,204 @@
+/**
+ * FileWriteTool — 文件写入工具
+ * @version v0.12.50
+ *
+ * 创建或覆盖写入本地文件，支持自动创建父目录。
+ * 默认工作目录为 workspacePath（ToolContext 提供）。
+ *
+ * 安全特性：
+ *   - 路径白名单校验（防止写入 /etc、/usr 等敏感目录）
+ *   - 不允许覆盖已存在文件（除非显式指定 force）
+ *   - 不允许写入二进制文件
+ *
+ * 使用示例：
+ *   const tool = new FileWriteTool();
+ *   const result = await tool.execute({
+ *     path: '~/project/new-file.ts',
+ *     content: 'export const version = "1.0";',
+ *   });
+ */
+'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOCKED_PREFIXES = exports.FILE_WRITE_TOOL_METADATA = exports.FileWriteTool = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os_1 = require("os");
+const Tool_1 = require("./Tool");
+const METADATA = {
+    name: 'file_write',
+    description: '创建或覆盖写入本地文件，自动创建父目录。支持文本内容。',
+    category: 'file',
+    params: [
+        {
+            name: 'path',
+            description: '文件绝对路径（支持 ~/ 展开）',
+            type: 'string',
+            required: true,
+        },
+        {
+            name: 'content',
+            description: '写入的文本内容',
+            type: 'string',
+            required: true,
+        },
+        {
+            name: 'force',
+            description: '是否强制覆盖已存在文件（默认 false）',
+            type: 'boolean',
+            required: false,
+            default: false,
+        },
+        {
+            name: 'encoding',
+            description: '文件编码（默认 utf8）',
+            type: 'string',
+            required: false,
+            default: 'utf8',
+        },
+    ],
+    examples: [
+        {
+            input: { path: '~/test.txt', content: 'Hello World' },
+            output: { success: true, output: { path: '...', bytesWritten: 11 } },
+        },
+    ],
+    version: '0.12.50',
+};
+exports.FILE_WRITE_TOOL_METADATA = METADATA;
+/** 禁止写入的路径前缀（扩展安全边界） */
+const BLOCKED_PREFIXES = [
+    '/etc', '/usr', '/var', '/bin', '/sbin', '/sys', '/proc', '/dev',
+    '/root', '/home', '/private', '/snap',
+    // 敏感配置和凭据文件
+    '.ssh', '.aws', '.env', '.git-credentials', '.netrc',
+    '.npmrc', '.pypirc', '.pip.conf',
+    // 关键配置
+    'credentials', 'secrets', 'keys', 'id_rsa', 'id_ed25519',
+];
+exports.BLOCKED_PREFIXES = BLOCKED_PREFIXES;
+class FileWriteTool extends Tool_1.Tool {
+    metadata = METADATA;
+    async execute(args, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _ctx) {
+        try {
+            this.validateArgs(args);
+            const rawPath = this.getArg(args, 'path');
+            const content = this.getArg(args, 'content');
+            const force = this.getArg(args, 'force', false) ?? false;
+            const encoding = this.getArg(args, 'encoding', 'utf8') ?? 'utf8';
+            // 解析路径
+            let filePath;
+            try {
+                filePath = this._resolvePath(rawPath);
+            }
+            catch (err) {
+                return { success: false, error: `Invalid path: ${String(err)}` };
+            }
+            // 安全校验：黑名单前缀（带路径分隔符检查防止 /etc-fake 绕过）
+            if (this._isBlocked(filePath)) {
+                return {
+                    success: false,
+                    error: `Access denied: writing to "${filePath}" is not allowed`,
+                };
+            }
+            // 检测二进制内容（包含 null 字节）
+            if (this._isBinary(content)) {
+                return {
+                    success: false,
+                    error: 'Binary content is not supported. Use a different tool for binary files.',
+                };
+            }
+            // 自动创建父目录
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // 写入文件（原子操作防止 TOCTOU）
+            // 使用 'wx' 标志：独占创建，文件存在则失败
+            // force=true 时降级为覆盖写入
+            const contentStr = typeof content === 'string' ? content : JSON.stringify(content);
+            try {
+                await fs.promises.writeFile(filePath, contentStr, { encoding: 'utf8', mode: 0o644, flag: force ? 'w' : 'wx' });
+            }
+            catch (err) {
+                const nodeErr = err;
+                if (nodeErr.code === 'EEXIST') {
+                    return { success: false, error: `File already exists: ${filePath}. Use force=true to overwrite.` };
+                }
+                throw err;
+            }
+            return {
+                success: true,
+                output: {
+                    path: filePath,
+                    bytesWritten: Buffer.byteLength(content, encoding),
+                    created: !force,
+                },
+                metadata: { encoding },
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /** 展开 ~ 并解析为绝对路径 */
+    _resolvePath(rawPath) {
+        // Expand ~ to HOME for ALL occurrences, not just ~/ prefix
+        const home = (0, os_1.homedir)();
+        const expanded = rawPath.replace(/^~/, home);
+        return path.isAbsolute(expanded) ? expanded : path.resolve(expanded);
+    }
+    /** 检查是否在黑名单前缀内（带路径分隔符边界检查） */
+    _isBlocked(filePath) {
+        const normalized = path.normalize(filePath);
+        const normalizedWithSep = normalized + path.sep;
+        return BLOCKED_PREFIXES.some(prefix => {
+            // 检查完整路径前缀 + 路径分隔符，防止 /etc-fake 绕过 /etc
+            return normalizedWithSep.startsWith(prefix + path.sep) || normalized === prefix;
+        });
+    }
+    /** 检测是否为二进制内容 */
+    _isBinary(content) {
+        // 包含 null 字节通常是二进制
+        return content.includes('\0');
+    }
+}
+exports.FileWriteTool = FileWriteTool;
+//# sourceMappingURL=FileWriteTool.js.map

package/dist/agent/tools/FileWriteTool.js.map

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

package/dist/agent/tools/Tool.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Tool.ts — HeartFlow 内置工具基类
+ * @version v0.12.50
+ *
+ * 所有内置工具（WebSearchTool、FileReadTool 等）都继承自 Tool。
+ * 工具是可组合的构建块，agent 通过工具注册表发现和调用工具。
+ *
+ * 设计原则：
+ *   - 每个工具职责单一（SRP）
+ *   - 输入/输出类型安全（TypeScript interface）
+ *   - 支持异步执行
+ *   - 工具元数据用于注册表发现
+ */
+/** 工具参数schema（JSON Schema draft-07 简化版） */
+export interface ToolParamSchema {
+    name: string;
+    description: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required?: boolean;
+    default?: unknown;
+    enum?: unknown[];
+}
+/** 工具执行结果 */
+export interface ToolResult {
+    success: boolean;
+    output?: unknown;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/** 工具元数据（用于注册表） */
+export interface ToolMetadata {
+    name: string;
+    description: string;
+    category: 'web' | 'file' | 'shell' | 'cognitive' | 'system';
+    params: ToolParamSchema[];
+    examples?: Array<{
+        input: Record<string, unknown>;
+        output: unknown;
+    }>;
+    version?: string;
+}
+/** 工具调用上下文（agent 传递给工具） */
+export interface ToolContext {
+    workspacePath?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+}
+export declare abstract class Tool {
+    /** 子类设置自己的 metadata */
+    protected abstract readonly metadata: ToolMetadata;
+    /**
+     * execute — 工具核心逻辑，由子类实现
+     * @param args  工具调用参数（符合 params schema）
+     * @param ctx   运行时上下文
+     */
+    abstract execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
+    /** 返回工具元数据（用于注册表） */
+    getMetadata(): ToolMetadata;
+    /** 返回工具名称 */
+    get name(): string;
+    /** 返回工具分类 */
+    get category(): ToolMetadata['category'];
+    /**
+     * validateArgs — 校验参数是否符合 schema
+     * @throws Error 当必填参数缺失或类型错误时
+     */
+    protected validateArgs(args: Record<string, unknown>): void;
+    /**
+     * getArg — 安全获取参数，带默认值
+     */
+    protected getArg<T>(args: Record<string, unknown>, name: string, defaultValue?: T): T | undefined;
+    /** 工具描述（方便日志） */
+    toString(): string;
+}
+//# sourceMappingURL=Tool.d.ts.map

package/dist/agent/tools/Tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/Tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,mBAAmB;AACnB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC5D,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID,8BAAsB,IAAI;IACxB,uBAAuB;IACvB,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEnD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAEvF,qBAAqB;IACrB,WAAW,IAAI,YAAY;IAI3B,aAAa;IACb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,aAAa;IACb,IAAI,QAAQ,IAAI,YAAY,CAAC,UAAU,CAAC,CAEvC;IAED;;;OAGG;IACH,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQ3D;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAIjG,iBAAiB;IACjB,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/agent/tools/Tool.js

@@ -0,0 +1,54 @@
+/**
+ * Tool.ts — HeartFlow 内置工具基类
+ * @version v0.12.50
+ *
+ * 所有内置工具（WebSearchTool、FileReadTool 等）都继承自 Tool。
+ * 工具是可组合的构建块，agent 通过工具注册表发现和调用工具。
+ *
+ * 设计原则：
+ *   - 每个工具职责单一（SRP）
+ *   - 输入/输出类型安全（TypeScript interface）
+ *   - 支持异步执行
+ *   - 工具元数据用于注册表发现
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+// ─── Tool 基类 ────────────────────────────────────────────────────────────────
+class Tool {
+    /** 返回工具元数据（用于注册表） */
+    getMetadata() {
+        return { ...this.metadata };
+    }
+    /** 返回工具名称 */
+    get name() {
+        return this.metadata.name;
+    }
+    /** 返回工具分类 */
+    get category() {
+        return this.metadata.category;
+    }
+    /**
+     * validateArgs — 校验参数是否符合 schema
+     * @throws Error 当必填参数缺失或类型错误时
+     */
+    validateArgs(args) {
+        for (const param of this.metadata.params) {
+            if (param.required && !(param.name in args)) {
+                throw new Error(`Missing required parameter: ${param.name}`);
+            }
+        }
+    }
+    /**
+     * getArg — 安全获取参数，带默认值
+     */
+    getArg(args, name, defaultValue) {
+        return args[name] ?? defaultValue;
+    }
+    /** 工具描述（方便日志） */
+    toString() {
+        return `Tool(${this.metadata.name})`;
+    }
+}
+exports.Tool = Tool;
+//# sourceMappingURL=Tool.js.map

package/dist/agent/tools/Tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../../src/agent/tools/Tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,YAAY,CAAC;;;AAuCb,+EAA+E;AAE/E,MAAsB,IAAI;IAWxB,qBAAqB;IACrB,WAAW;QACT,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC9B,CAAC;IAED,aAAa;IACb,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,aAAa;IACb,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAChC,CAAC;IAED;;;OAGG;IACO,YAAY,CAAC,IAA6B;QAClD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,+BAA+B,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACO,MAAM,CAAI,IAA6B,EAAE,IAAY,EAAE,YAAgB;QAC/E,OAAQ,IAAI,CAAC,IAAI,CAAO,IAAI,YAAY,CAAC;IAC3C,CAAC;IAED,iBAAiB;IACjB,QAAQ;QACN,OAAO,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC;IACvC,CAAC;CACF;AAjDD,oBAiDC"}

package/dist/agent/tools/WebSearchTool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * WebSearchTool — 通用网页搜索工具
+ * @version v0.12.50
+ *
+ * 使用 cn-web-search 技能执行中文/英文多引擎聚合搜索。
+ * 当没装 cn-web-search 时降级为 curl 裸请求。
+ *
+ * 使用示例：
+ *   const tool = new WebSearchTool();
+ *   const result = await tool.execute({ query: "HeartFlow 最新版本", maxResults: 5 });
+ */
+import { Tool, ToolMetadata, ToolResult } from './Tool';
+declare const METADATA: ToolMetadata;
+export declare class WebSearchTool extends Tool {
+    protected readonly metadata: ToolMetadata;
+    execute(args: Record<string, unknown>, _ctx?: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * 通过 cn-web-search 技能执行搜索
+     */
+    private _searchViaCnWebSearch;
+    /**
+     * 通过 curl 请求免费搜索 API（DuckDuckGo Instant Answer API）
+     */
+    private _searchViaCurl;
+}
+export { METADATA as WEB_SEARCH_TOOL_METADATA };
+//# sourceMappingURL=WebSearchTool.d.ts.map

package/dist/agent/tools/WebSearchTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearchTool.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/WebSearchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAmB,MAAM,QAAQ,CAAC;AAEzE,QAAA,MAAM,QAAQ,EAAE,YAuCf,CAAC;AAEF,qBAAa,aAAc,SAAQ,IAAI;IACrC,SAAS,CAAC,QAAQ,CAAC,QAAQ,eAAY;IAEjC,OAAO,CACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAE7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC;IAkCtB;;OAEG;YACW,qBAAqB;IAsBnC;;OAEG;YACW,cAAc;CA6B7B;AAED,OAAO,EAAE,QAAQ,IAAI,wBAAwB,EAAE,CAAC"}

package/dist/agent/tools/WebSearchTool.js

@@ -0,0 +1,136 @@
+/**
+ * WebSearchTool — 通用网页搜索工具
+ * @version v0.12.50
+ *
+ * 使用 cn-web-search 技能执行中文/英文多引擎聚合搜索。
+ * 当没装 cn-web-search 时降级为 curl 裸请求。
+ *
+ * 使用示例：
+ *   const tool = new WebSearchTool();
+ *   const result = await tool.execute({ query: "HeartFlow 最新版本", maxResults: 5 });
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEB_SEARCH_TOOL_METADATA = exports.WebSearchTool = void 0;
+const Tool_1 = require("./Tool");
+const METADATA = {
+    name: 'web_search',
+    description: '在互联网上搜索信息，支持多引擎聚合（百度/必应/Google等）。返回标题、URL、摘要。',
+    category: 'web',
+    params: [
+        {
+            name: 'query',
+            description: '搜索关键词或短语',
+            type: 'string',
+            required: true,
+        },
+        {
+            name: 'maxResults',
+            description: '最大返回结果数（默认 5）',
+            type: 'number',
+            required: false,
+            default: 5,
+        },
+        {
+            name: 'language',
+            description: '搜索语言偏好: "zh" | "en" | "auto"（默认 "auto"）',
+            type: 'string',
+            required: false,
+            default: 'auto',
+            enum: ['zh', 'en', 'auto'],
+        },
+    ],
+    examples: [
+        {
+            input: { query: 'HeartFlow AI framework', maxResults: 3 },
+            output: {
+                success: true,
+                output: [
+                    { title: '...', url: '...', snippet: '...' },
+                ],
+            },
+        },
+    ],
+    version: '0.12.50',
+};
+exports.WEB_SEARCH_TOOL_METADATA = METADATA;
+class WebSearchTool extends Tool_1.Tool {
+    metadata = METADATA;
+    async execute(args, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _ctx) {
+        try {
+            this.validateArgs(args);
+            const query = this.getArg(args, 'query');
+            const maxResults = this.getArg(args, 'maxResults', 5) ?? 5;
+            const language = this.getArg(args, 'language', 'auto') ?? 'auto';
+            // 优先使用 cn-web-search 技能
+            const searchResult = await this._searchViaCnWebSearch(query, maxResults, language);
+            if (searchResult) {
+                return {
+                    success: true,
+                    output: searchResult,
+                    metadata: { engine: 'cn-web-search', query, maxResults, language },
+                };
+            }
+            // 降级：使用 curl 请求免费搜索 API
+            const fallback = await this._searchViaCurl(query, maxResults);
+            return {
+                success: true,
+                output: fallback,
+                metadata: { engine: 'curl-fallback', query, maxResults },
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * 通过 cn-web-search 技能执行搜索
+     */
+    async _searchViaCnWebSearch(query, maxResults, language) {
+        try {
+            // 动态加载 cn-web-search 技能的搜索函数
+            // @ts-ignore — external skill path
+            const { search } = await import('../../../skills/cn-web-search/search.js').catch(() => null) ?? {};
+            if (typeof search === 'function') {
+                const result = await search(query, maxResults, language);
+                return result;
+            }
+        }
+        catch {
+            // 技能不存在或加载失败，静默降级
+        }
+        return null;
+    }
+    /**
+     * 通过 curl 请求免费搜索 API（DuckDuckGo Instant Answer API）
+     */
+    async _searchViaCurl(query, maxResults) {
+        const url = `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_redirect=1`;
+        const { execFileSync } = await import('child_process');
+        const output = execFileSync('curl', ['-s', '-L', '--max-time', '10', url], {
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024,
+        });
+        const data = JSON.parse(output);
+        const results = [];
+        if (data.RelatedTopics) {
+            for (const topic of data.RelatedTopics.slice(0, maxResults)) {
+                if (topic.Text && topic.FirstURL) {
+                    results.push({
+                        title: data.Heading ?? query,
+                        url: topic.FirstURL,
+                        snippet: topic.Text,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+}
+exports.WebSearchTool = WebSearchTool;
+//# sourceMappingURL=WebSearchTool.js.map

package/dist/agent/tools/WebSearchTool.js.map

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

package/dist/cli/commands/engines.d.ts

@@ -0,0 +1,39 @@
+/**
+ * engines.ts — HeartFlow 引擎面板
+ * @version v0.12.50
+ *
+ * 提供引擎状态查询接口：
+ *   - 记忆引擎 (Memory Engine)
+ *   - 检查点引擎 (Checkpoint Engine)
+ *   - 向量存储引擎 (Vector Store Engine)
+ *   - 核心引擎 (Core Engine)
+ *
+ * 支持 --watch 实时监控模式（每 3 秒刷新一次）
+ */
+export interface EngineStatus {
+    name: string;
+    status: 'online' | 'offline' | 'error' | 'unknown';
+    details: Record<string, any>;
+    uptime?: string;
+    memoryMB?: number;
+    lastActivity?: string;
+}
+export interface PanelSnapshot {
+    timestamp: string;
+    hostname: string;
+    platform: string;
+    uptime: string;
+    loadavg: number[];
+    memory: {
+        total: number;
+        free: number;
+        used: number;
+        usedPercent: number;
+    };
+    engines: EngineStatus[];
+    totalMemoryMB: number;
+}
+export declare function collectPanelSnapshot(): PanelSnapshot;
+export declare function renderPanelTable(snapshot: PanelSnapshot): string;
+export declare function watchPanel(intervalMs?: number, onUpdate?: (snap: PanelSnapshot) => void): Promise<() => void>;
+//# sourceMappingURL=engines.d.ts.map

package/dist/cli/commands/engines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/engines.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmBH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAkID,wBAAgB,oBAAoB,IAAI,aAAa,CA6BpD;AAWD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAoChE;AAID,wBAAsB,UAAU,CAAC,UAAU,SAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAqBjH"}