@yun520-1/heartflow 0.15.2 → 0.16.0

package/src/agent/tools/BashTool.ts

@@ -1,390 +0,0 @@
-/**
- * BashTool — Shell 命令执行工具
- * @version v0.13.60
- *
- * 在本地 shell 中执行命令，返回 stdout/stderr/exitCode。
- *
- * 安全特性：
- *   - 命令白名单模式（只允许预定义的安全操作）
- *   - 执行超时控制（默认 30s，可配置）
- *   - 不支持交互式命令（防止阻塞）
- *
- * 使用示例：
- *   const tool = new BashTool();
- *   const result = await tool.execute({ command: 'ls -la ~/', timeout: 10 });
- */
-
-'use strict';
-
-import { Tool, ToolMetadata, ToolResult } from './Tool';
-
-const METADATA: ToolMetadata = {
-  name: 'bash',
-  description: '在本地 shell 中执行命令，返回 stdout/stderr/exitCode。',
-  category: 'shell',
-  params: [
-    {
-      name: 'command',
-      description: '要执行的 shell 命令',
-      type: 'string',
-      required: true,
-    },
-    {
-      name: 'timeout',
-      description: '超时秒数（默认 30）',
-      type: 'number',
-      required: false,
-      default: 30,
-    },
-    {
-      name: 'cwd',
-      description: '执行目录（默认进程当前目录）',
-      type: 'string',
-      required: false,
-    },
-    {
-      name: 'env',
-      description: '额外的环境变量（key: value 对象）',
-      type: 'object',
-      required: false,
-    },
-  ],
-  examples: [
-    {
-      input: { command: 'echo "Hello World"', timeout: 5 },
-      output: { success: true, output: { stdout: 'Hello World\n', stderr: '', exitCode: 0 } },
-    },
-  ],
-  version: '0.13.60',
-};
-
-// ── 白名单模式：允许的命令及参数规范 ────────────────────────────────────────
-
-type ParamSchema = {
-  type: 'literal' | 'number' | 'string' | 'flag';
-  values?: string[];  // for literal type
-  max?: number;      // for number type
-  pattern?: RegExp;  // for string type
-};
-
-interface AllowedCommand {
-  description: string;
-  params: Record<string, ParamSchema>;
-  // 可选的验证函数（用于更复杂的约束）
-  validator?: (args: string[]) => boolean;
-}
-
-const PATH_PATTERN = /^(\/[\w\.\-]+)+$/;
-
-const ALLOWED_COMMANDS: Record<string, AllowedCommand> = {
-  // 文件查看
-  ls: {
-    description: '列出目录内容',
-    params: {
-      '-a': { type: 'flag' },
-      '-l': { type: 'flag' },
-      '-R': { type: 'flag' },
-      '-t': { type: 'flag' },
-      '-h': { type: 'flag' },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  cat: {
-    description: '查看文件内容',
-    params: {
-      '-n': { type: 'flag' },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  head: {
-    description: '查看文件开头',
-    params: {
-      '-n': { type: 'number', max: 1000 },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  tail: {
-    description: '查看文件结尾',
-    params: {
-      '-n': { type: 'number', max: 1000 },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  wc: {
-    description: '统计行数/词数/字符数',
-    params: {
-      '-l': { type: 'flag' },
-      '-w': { type: 'flag' },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  grep: {
-    description: '文本搜索',
-    params: {
-      '-r': { type: 'flag' },
-      '-i': { type: 'flag' },
-      '-n': { type: 'flag' },
-      '-l': { type: 'flag' },
-      pattern: { type: 'string', pattern: /^[^\"\';|&`$]+$/ },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  find: {
-    description: '查找文件',
-    params: {
-path: { type: 'string', pattern: PATH_PATTERN },
-      '-name': { type: 'string', pattern: /^[^\;\|\`]+$/ },
-      '-type': { type: 'literal', values: ['f', 'd', 'l'] },
-    },
-    validator: (args) => {
-      // find 禁止使用 -delete、-exec、| 等危险操作
-      return !args.some(a => ['-delete', '-exec', '-ok', '|', ';', '`'].includes(a));
-    },
-  },
-  // Git 命令
-  git: {
-    description: 'Git 版本控制',
-    params: {
-      'status': { type: 'literal' },
-      'log': { type: 'literal' },
-      'diff': { type: 'literal' },
-      '--oneline': { type: 'flag' },
-      '--graph': { type: 'flag' },
-      '-n': { type: 'number', max: 100 },
-    },
-    validator: (args) => {
-      // 禁止危险 git 操作
-      const dangerous = ['filter-branch', 'push', '--force', '-f', 'rebase'];
-      return !dangerous.some(d => args.includes(d));
-    },
-  },
-  // Node/npm
-  node: {
-    description: '执行 Node.js 脚本',
-    params: {
-      path: { type: 'string', pattern: /^\// },  // Only absolute paths, no -e/-p
-    },
-    validator: (args) => {
-      // Disallow -e, -p, -r flags that allow arbitrary code execution
-      return !args.some(a => a === '-e' || a === '-p' || a === '-r' || a === '--eval');
-    }
-  },
-  npm: {
-    description: 'npm 包管理',
-    params: {
-      'install': { type: 'literal' },
-      'run': { type: 'literal' },
-      '-y': { type: 'flag' },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-    validator: (args) => {
-      // 禁止全局安装、危险脚本
-      // Disallow dangerous flags that allow code execution
-      // Disallow dangerous flags that allow code execution
-      const dangerous = ['-e', '-p', '-r', '--eval', '--check', '-c'];
-      return !args.some(a => dangerous.some(d => a === d || a.startsWith(d + '=')));
-    },
-  },
-  // 文件操作（安全限制下）
-  mkdir: {
-    description: '创建目录',
-    params: {
-      '-p': { type: 'flag' },
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-    validator: (args) => {
-      // 禁止在 /etc、/var 等系统目录创建
-      return !args.some(a => /^\/(etc|var|usr|bin|sbin|sys|proc|dev)/.test(a));
-    },
-  },
-  touch: {
-    description: '创建空文件',
-    params: {
-path: { type: 'string', pattern: PATH_PATTERN },
-    },
-  },
-  // 进程/系统信息
-  ps: {
-    description: '进程状态',
-    params: {
-      'aux': { type: 'literal' },
-    },
-  },
-  env: {
-    description: '查看环境变量',
-    params: {},
-  },
-  whoami: {
-    description: '当前用户',
-    params: {},
-  },
-  pwd: {
-    description: '当前目录',
-    params: {},
-  },
-  date: {
-    description: '当前日期',
-    params: {},
-  },
-  // 简单输出
-  echo: {
-    description: '输出文本',
-    params: {
-      '-n': { type: 'flag' },
-      text: { type: 'string', pattern: /^[^\;\|\`\$\\]{0,500}$/ },
-    },
-  },
-};
-
-export class BashTool extends Tool {
-  protected readonly metadata = METADATA;
-
-  async execute(
-    args: Record<string, unknown>,
-    ctx?: Record<string, unknown>
-  ): Promise<ToolResult> {
-    try {
-      this.validateArgs(args);
-
-      const command = this.getArg<string>(args, 'command')!;
-      const timeout = this.getArg<number>(args, 'timeout', 30) ?? 30;
-      const cwd = this.getArg<string>(args, 'cwd', process.cwd()) ?? process.cwd();
-      const extraEnv = this.getArg<Record<string, string>>(args, 'env', {}) ?? {};
-
-      // 解析 workspacePath
-      const workspacePath = ctx?.workspacePath as string | undefined;
-
-      // 安全校验：白名单模式
-      const validation = this._validateCommand(command.trim());
-      if (!validation.valid) {
-        return {
-          success: false,
-          error: `Command not allowed: ${validation.reason}`,
-        };
-      }
-
-      // 执行命令
-      const { execSync } = await import('child_process');
-      const env = { ...process.env, ...extraEnv };
-
-      let stdout: string;
-      let stderr: string;
-      let exitCode: number;
-
-      try {
-        stdout = execSync(command, {
-          cwd: workspacePath ?? cwd,
-          env,
-          encoding: 'utf8',
-          timeout: timeout * 1000,
-          maxBuffer: 10 * 1024 * 1024,
-        });
-        stderr = '';
-        exitCode = 0;
-      } catch (err: unknown) {
-        const execError = err as { stdout?: string; stderr?: string; status?: number };
-        stdout = execError.stdout ?? '';
-        stderr = execError.stderr ?? '';
-        exitCode = execError.status ?? 1;
-      }
-
-      return {
-        success: exitCode === 0,
-        output: { stdout, stderr, exitCode },
-        metadata: { command, timeout, cwd },
-      };
-    } catch (err: unknown) {
-      return {
-        success: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-  }
-
-  /**
-   * 白名单命令验证
-   * @returns { valid: boolean, reason?: string }
-   */
-  private _validateCommand(command: string): { valid: boolean; reason?: string } {
-    // 第一道门：检查 shell 元字符（黑名单防止绕过白名单）
-    // 注意：不在字符类中放空格（会误杀 "ls -la" 等合法带空格命令）
-    // 只匹配真正的 shell 操作符和危险构造
-    const shellMetachars = /[;&|`$\x00{}\[\]!<>~#%^*\n\\]|&&|\|\||;;|<<|>>|<>|&\||\(|\\\(|\\\)/;
-    if (shellMetachars.test(command)) {
-      return { valid: false, reason: `Forbidden shell metacharacter in command` };
-    }
-
-    // 解析命令和参数
-    const parts = this._parseCommand(command);
-    if (parts.length === 0) {
-      return { valid: false, reason: 'Empty command' };
-    }
-
-    const cmdName = parts[0];
-    const cmdArgs = parts.slice(1);
-
-    // 检查命令是否在白名单中
-    const allowed = ALLOWED_COMMANDS[cmdName];
-    if (!allowed) {
-      return { valid: false, reason: `Command "${cmdName}" is not in whitelist` };
-    }
-
-    // 验证每个参数
-    const unknownArgs = cmdArgs.filter(arg => {
-      return !arg.startsWith('-') && !Object.keys(allowed.params).includes(arg);
-    });
-
-    if (unknownArgs.length > 0 && allowed.params.text) {
-      // echo/text 类型允许任意字符串参数
-    } else if (unknownArgs.length > 0) {
-      return { valid: false, reason: `Unknown argument(s): ${unknownArgs.join(', ')}` };
-    }
-
-    // 运行命令特定的验证器
-    if (allowed.validator && !allowed.validator(cmdArgs)) {
-      return { valid: false, reason: `Command "${cmdName}" has forbidden operation` };
-    }
-
-    return { valid: true };
-  }
-
-  /**
-   * 简单命令解析（处理引号和转义）
-   */
-  private _parseCommand(command: string): string[] {
-    const parts: string[] = [];
-    let current = '';
-    let inQuote = false;
-    let quoteChar = '';
-
-    for (let i = 0; i < command.length; i++) {
-      const c = command[i];
-
-      if (inQuote) {
-        if (c === quoteChar) {
-          inQuote = false;
-        } else {
-          current += c;
-        }
-      } else if (c === '"' || c === "'") {
-        inQuote = true;
-        quoteChar = c;
-      } else if (c === ' ' || c === '\t') {
-        if (current.length > 0) {
-          parts.push(current);
-          current = '';
-        }
-      } else {
-        current += c;
-      }
-    }
-
-    if (current.length > 0) {
-      parts.push(current);
-    }
-
-    return parts;
-  }
-}
-
-export { METADATA as BASH_TOOL_METADATA, ALLOWED_COMMANDS };

package/src/agent/tools/FileReadTool.ts

@@ -1,176 +0,0 @@
-/**
- * FileReadTool — 文件读取工具
- * @version v0.12.50
- *
- * 读取本地文件内容，支持路径规范化和安全校验。
- * 默认工作目录为 workspacePath（ToolContext 提供）。
- *
- * 使用示例：
- *   const tool = new FileReadTool();
- *   const result = await tool.execute({ path: '~/project/README.md', offset: 1, limit: 100 });
- */
-
-'use strict';
-
-import * as fs from "fs";
-import * as path from "path";
-import { homedir } from 'os';
-import { execFileSync } from 'child_process';
-import { Tool, ToolMetadata, ToolResult } from './Tool';
-
-const METADATA: ToolMetadata = {
-  name: 'file_read',
-  description: '读取本地文件内容，支持分页（offset/limit）和编码指定。',
-  category: 'file',
-  params: [
-    {
-      name: 'path',
-      description: '文件绝对路径（支持 ~/ 展开）',
-      type: 'string',
-      required: true,
-    },
-    {
-      name: 'offset',
-      description: '起始行号（1-indexed，默认 1）',
-      type: 'number',
-      required: false,
-      default: 1,
-    },
-    {
-      name: 'limit',
-      description: '最多读取行数（默认 500，max 2000）',
-      type: 'number',
-      required: false,
-      default: 500,
-    },
-    {
-      name: 'encoding',
-      description: '文件编码（默认 utf8）',
-      type: 'string',
-      required: false,
-      default: 'utf8',
-    },
-  ],
-  examples: [
-    {
-      input: { path: '~/README.md', limit: 50 },
-      output: { success: true, output: { content: '# Hello\n...', linesRead: 50 } },
-    },
-  ],
-  version: '0.12.50',
-};
-
-/** 允许读取的根目录白名单（收紧：不允许整个 home，只允许特定子目录） */
-const ALLOWED_ROOTS = [
-  path.join(homedir(), '.hermes', 'skills'),
-  path.join(homedir(), '.hermes', 'cron'),
-  path.join(homedir(), '.hermes', 'memory'),
-  path.join(homedir(), '.hermes', 'config'),
-  path.join(homedir(), '.hermes', 'data'),
-  '/tmp',
-  '/var/folders',  // macOS temporary directories
-];
-
-export class FileReadTool extends Tool {
-  protected readonly metadata = METADATA;
-
-  async execute(
-    args: Record<string, unknown>,
-    ctx?: Record<string, unknown>
-  ): Promise<ToolResult> {
-    try {
-      this.validateArgs(args);
-
-      const rawPath = this.getArg<string>(args, 'path')!;
-      const offset = this.getArg<number>(args, 'offset', 1) ?? 1;
-      const limit = Math.min(this.getArg<number>(args, 'limit', 500) ?? 500, 2000);
-      const encoding = this.getArg<string>(args, 'encoding', 'utf8') ?? 'utf8';
-
-      // 解析路径（展开 ~）
-      const filePath = this._resolvePath(rawPath);
-
-      // 安全校验：确保文件在白名单目录下
-      if (!this._isAllowed(filePath)) {
-        return {
-          success: false,
-          error: `Access denied: path "${filePath}" is outside allowed directories`,
-        };
-      }
-
-      // 检查文件是否存在
-      if (!fs.existsSync(filePath)) {
-        return { success: false, error: `File not found: ${filePath}` };
-      }
-
-      const stat = fs.statSync(filePath);
-      if (stat.isDirectory()) {
-        return { success: false, error: `Path is a directory, not a file: ${filePath}` };
-      }
-
-      // 分页读取
-      const content = this._readPaginated(filePath, offset, limit, encoding);
-
-      return {
-        success: true,
-        output: {
-          path: filePath,
-          content,
-          linesRead: content.split('\n').length,
-          totalLines: this._countLines(filePath, encoding),
-          offset,
-          limit,
-          encoding,
-        },
-        metadata: { sizeBytes: stat.size },
-      };
-    } catch (err: unknown) {
-      return {
-        success: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-  }
-
-  /** 展开 ~ 并解析为绝对路径 */
-  private _resolvePath(rawPath: string): string {
-    if (rawPath.startsWith('~/')) {
-      return path.join(homedir(), rawPath.slice(2));
-    }
-    return path.isAbsolute(rawPath) ? rawPath : path.resolve(rawPath);
-  }
-
-  /** 检查路径是否在白名单目录内 */
-  private _isAllowed(filePath: string): boolean {
-    // Reject path segments containing .. before normalization to prevent traversal bypass
-    if (filePath.includes('..')) return false;
-    const normalized = path.normalize(filePath);
-    return ALLOWED_ROOTS.some(root => normalized.startsWith(root + path.sep) || normalized === root);
-  }
-
-  /** 分页读取文件指定行范围 */
-  private _readPaginated(filePath: string, offset: number, limit: number, encoding: string): string {
-    const content = fs.readFileSync(filePath, encoding as BufferEncoding);
-    const lines = content.split('\n');
-    const start = Math.max(0, offset - 1);
-    const end = Math.min(start + limit, lines.length);
-    return lines.slice(start, end).join('\n');
-  }
-
-  /** 快速统计总行数（对大文件使用 wc -l 避免加载全部内容到内存） */
-  private _countLines(filePath: string, encoding: string): number {
-    const stat = fs.statSync(filePath);
-    // 对大于 1MB 的文件使用 wc -l 子进程来计数
-    if (stat.size > 1024 * 1024 && encoding === 'utf8') {
-      try {
-      const output = execFileSync('wc', ['-l', filePath], { encoding: 'utf8', shell: false });
-      return parseInt(output.trim().split(/\s+/)[0], 10) || 0;
-      } catch {
-        // 回退到内存读取方式
-      }
-    }
-    const content = fs.readFileSync(filePath, encoding as BufferEncoding);
-    return content.split('\n').length;
-  }
-}
-
-export { METADATA as FILE_READ_TOOL_METADATA, ALLOWED_ROOTS };