@yun520-1/heartflow 0.15.2

package/src/agent/tools/FileWriteTool.ts

@@ -0,0 +1,182 @@
+/**
+ * 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';
+
+import * as fs from "fs";
+import * as path from "path";
+import { homedir } from 'os';
+import { Tool, ToolMetadata, ToolResult } from './Tool';
+
+const METADATA: ToolMetadata = {
+  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',
+};
+
+/** 禁止写入的路径前缀（扩展安全边界） */
+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',
+];
+
+export class FileWriteTool extends Tool {
+  protected readonly metadata = METADATA;
+
+  async execute(
+    args: Record<string, unknown>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _ctx?: Record<string, unknown>
+  ): Promise<ToolResult> {
+    try {
+      this.validateArgs(args);
+
+      const rawPath = this.getArg<string>(args, 'path')!;
+      const content = this.getArg<string>(args, 'content')!;
+      const force = this.getArg<boolean>(args, 'force', false) ?? false;
+      const encoding = this.getArg<string>(args, 'encoding', 'utf8') ?? 'utf8';
+
+      // 解析路径
+      let filePath: string;
+      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 as NodeJS.ErrnoException;
+        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 as BufferEncoding),
+          created: !force,
+        },
+        metadata: { encoding },
+      };
+    } catch (err: unknown) {
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  /** 展开 ~ 并解析为绝对路径 */
+  private _resolvePath(rawPath: string): string {
+    // Expand ~ to HOME for ALL occurrences, not just ~/ prefix
+    const home = homedir();
+    const expanded = rawPath.replace(/^~/, home);
+    return path.isAbsolute(expanded) ? expanded : path.resolve(expanded);
+  }
+
+  /** 检查是否在黑名单前缀内（带路径分隔符边界检查） */
+  private _isBlocked(filePath: string): boolean {
+    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;
+    });
+  }
+
+  /** 检测是否为二进制内容 */
+  private _isBinary(content: string): boolean {
+    // 包含 null 字节通常是二进制
+    return content.includes('\0');
+  }
+}
+
+export { METADATA as FILE_WRITE_TOOL_METADATA, BLOCKED_PREFIXES };

package/src/agent/tools/Tool.ts

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

package/src/agent/tools/WebSearchTool.ts

@@ -0,0 +1,158 @@
+/**
+ * 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';
+
+import { Tool, ToolMetadata, ToolResult, ToolParamSchema } from './Tool';
+
+const METADATA: ToolMetadata = {
+  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',
+};
+
+export class WebSearchTool extends Tool {
+  protected readonly metadata = METADATA;
+
+  async execute(
+    args: Record<string, unknown>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _ctx?: Record<string, unknown>
+  ): Promise<ToolResult> {
+    try {
+      this.validateArgs(args);
+
+      const query = this.getArg<string>(args, 'query')!;
+      const maxResults = this.getArg<number>(args, 'maxResults', 5) ?? 5;
+      const language = this.getArg<string>(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: unknown) {
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  /**
+   * 通过 cn-web-search 技能执行搜索
+   */
+  private async _searchViaCnWebSearch(
+    query: string,
+    maxResults: number,
+    language: string
+  ): Promise<Array<{ title: string; url: string; snippet: string }> | null> {
+    try {
+      // 动态加载 cn-web-search 技能的搜索函数
+      // @ts-ignore — external skill path
+      const { search } = await import('../../../skills/cn-web-search/search.js').catch(
+        () => null
+      ) as { search?: (q: string, n: number, lang: string) => Promise<unknown> } ?? {};
+
+      if (typeof search === 'function') {
+        const result = await search(query, maxResults, language);
+        return result as Array<{ title: string; url: string; snippet: string }>;
+      }
+    } catch {
+      // 技能不存在或加载失败，静默降级
+    }
+    return null;
+  }
+
+  /**
+   * 通过 curl 请求免费搜索 API（DuckDuckGo Instant Answer API）
+   */
+  private async _searchViaCurl(
+    query: string,
+    maxResults: number
+  ): Promise<Array<{ title: string; url: string; snippet: string }>> {
+    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: Array<{ title: string; url: string; snippet: string }> = [];
+
+    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;
+  }
+}
+
+export { METADATA as WEB_SEARCH_TOOL_METADATA };