@ian2018cs/agenthub 0.1.75 → 0.1.77

package/server/services/builtin-tools/background-task-pool.js

@@ -0,0 +1,316 @@
+/**
+ * BackgroundTaskPool — 后台任务进程池
+ *
+ * 管理 child_process.spawn 子进程，提供 per-user 和全局并发限制、
+ * 超时处理、输出截断，以及 EventEmitter 'task-complete' 事件。
+ *
+ * PendingResultQueue — 待投递结果队列
+ *
+ * 保存已完成但尚未投递给 agent 的任务结果，
+ * 按 userUuid:sessionId 分组，支持逐条出队。
+ */
+
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import crypto from 'crypto';
+
+// ─── 配置 ───
+
+const PER_USER_LIMIT   = parseInt(process.env.BG_TASK_PER_USER_LIMIT, 10) || 3;
+const GLOBAL_LIMIT     = parseInt(process.env.BG_TASK_GLOBAL_LIMIT, 10)    || 20;
+const DEFAULT_TIMEOUT  = parseInt(process.env.BG_TASK_DEFAULT_TIMEOUT, 10) || 600_000;   // 10 min
+const MAX_TIMEOUT      = parseInt(process.env.BG_TASK_MAX_TIMEOUT, 10)     || 1_800_000; // 30 min
+const MAX_OUTPUT_BYTES = parseInt(process.env.BG_TASK_MAX_OUTPUT, 10)      || 102_400;   // 100 KB
+
+// 已完成任务保留时长（30 min），之后自动清理引用
+const COMPLETED_TTL_MS = 30 * 60 * 1000;
+// 清理扫描间隔（5 min）
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
+// ─── BackgroundTaskPool ───
+
+class BackgroundTaskPool extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, Task>} 所有任务（running + completed 未清理） */
+    this.tasks = new Map();
+    /** @type {Map<string, number>} 每用户当前 running 计数 */
+    this.userTaskCount = new Map();
+    /** 全局 running 计数 */
+    this.runningCount = 0;
+
+    // 定期清理已完成任务
+    this._cleanupTimer = setInterval(() => this._cleanupCompleted(), CLEANUP_INTERVAL_MS);
+    if (this._cleanupTimer.unref) this._cleanupTimer.unref();
+  }
+
+  /**
+   * 提交一个后台任务
+   * @returns {Task} 返回任务对象（status='running'）
+   * @throws {Error} 超出并发限制
+   */
+  submit({ userUuid, sessionId, cwd, command, timeout, label }) {
+    // 并发检查
+    const userCount = this.userTaskCount.get(userUuid) || 0;
+    if (userCount >= PER_USER_LIMIT) {
+      throw new Error(`每用户最多同时运行 ${PER_USER_LIMIT} 个后台任务（当前 ${userCount} 个）`);
+    }
+    if (this.runningCount >= GLOBAL_LIMIT) {
+      throw new Error(`系统后台任务已满（最多 ${GLOBAL_LIMIT} 个）`);
+    }
+
+    // 规范化 timeout
+    const timeoutMs = Math.min(Math.max(timeout || DEFAULT_TIMEOUT, 1000), MAX_TIMEOUT);
+
+    const id = this._genId();
+    const task = {
+      id,
+      userUuid,
+      sessionId,
+      cwd,
+      command,
+      label: label || command.slice(0, 80),
+      timeout: timeoutMs,
+      status: 'running',
+      startTime: Date.now(),
+      childProcess: null,
+      stdout: '',
+      stderr: '',
+      exitCode: null,
+      signal: null,
+      truncated: false,
+      _stdoutTruncated: false,
+      _stderrTruncated: false,
+    };
+
+    // 启动子进程
+    const child = spawn('sh', ['-c', command], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+    task.childProcess = child;
+
+    // 收集 stdout
+    child.stdout.on('data', (chunk) => {
+      if (task._stdoutTruncated) return;
+      const str = chunk.toString();
+      if (task.stdout.length + str.length > MAX_OUTPUT_BYTES) {
+        task.stdout += str.slice(0, MAX_OUTPUT_BYTES - task.stdout.length);
+        task._stdoutTruncated = true;
+        task.truncated = true;
+      } else {
+        task.stdout += str;
+      }
+    });
+
+    // 收集 stderr
+    child.stderr.on('data', (chunk) => {
+      if (task._stderrTruncated) return;
+      const str = chunk.toString();
+      if (task.stderr.length + str.length > MAX_OUTPUT_BYTES) {
+        task.stderr += str.slice(0, MAX_OUTPUT_BYTES - task.stderr.length);
+        task._stderrTruncated = true;
+        task.truncated = true;
+      } else {
+        task.stderr += str;
+      }
+    });
+
+    // 进程结束
+    child.on('close', (code, sig) => {
+      if (task.status !== 'running') return; // 已被 timeout/cancel 处理
+      task.status = 'completed';
+      task.exitCode = code;
+      task.signal = sig;
+      this._onFinished(task);
+    });
+
+    child.on('error', (err) => {
+      if (task.status !== 'running') return;
+      task.status = 'failed';
+      task.stderr += `\n[spawn error] ${err.message}`;
+      this._onFinished(task);
+    });
+
+    // 超时定时器
+    task._timeoutTimer = setTimeout(() => {
+      if (task.status !== 'running') return;
+      task.status = 'timeout';
+      // 先 SIGTERM
+      try { child.kill('SIGTERM'); } catch (_) { /* ignore */ }
+      // 5s 后 SIGKILL
+      task._killTimer = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch (_) { /* ignore */ }
+      }, 5000);
+      this._onFinished(task);
+    }, timeoutMs);
+
+    // 注册
+    this.tasks.set(id, task);
+    this.userTaskCount.set(userUuid, userCount + 1);
+    this.runningCount++;
+
+    console.log(`[BgTask] Task ${id} started for user ${userUuid}, session ${sessionId}: ${task.label}`);
+    return task;
+  }
+
+  /**
+   * 取消一个任务
+   * @returns {boolean} 是否成功取消
+   */
+  cancel(taskId, userUuid) {
+    const task = this.tasks.get(taskId);
+    if (!task) return false;
+    if (task.userUuid !== userUuid) return false; // 不允许跨用户取消
+    if (task.status !== 'running') return false;
+
+    task.status = 'killed';
+    try { task.childProcess.kill('SIGTERM'); } catch (_) { /* ignore */ }
+    setTimeout(() => {
+      try { task.childProcess.kill('SIGKILL'); } catch (_) { /* ignore */ }
+    }, 3000);
+
+    this._onFinished(task);
+    return true;
+  }
+
+  /** 获取单个任务 */
+  getTask(taskId) {
+    return this.tasks.get(taskId) || null;
+  }
+
+  /** 获取用户所有任务 */
+  getUserTasks(userUuid) {
+    return [...this.tasks.values()].filter(t => t.userUuid === userUuid);
+  }
+
+  /** 获取指定 session 的任务 */
+  getSessionTasks(userUuid, sessionId) {
+    return [...this.tasks.values()].filter(t => t.userUuid === userUuid && t.sessionId === sessionId);
+  }
+
+  /** 统计信息 */
+  getStats() {
+    return {
+      running: this.runningCount,
+      total: this.tasks.size,
+      perUser: Object.fromEntries(this.userTaskCount),
+    };
+  }
+
+  // ─── 内部方法 ───
+
+  _onFinished(task) {
+    // 清理定时器
+    if (task._timeoutTimer) { clearTimeout(task._timeoutTimer); task._timeoutTimer = null; }
+    if (task._killTimer) { clearTimeout(task._killTimer); task._killTimer = null; }
+
+    // 更新计数
+    const prev = this.userTaskCount.get(task.userUuid) || 1;
+    if (prev <= 1) {
+      this.userTaskCount.delete(task.userUuid);
+    } else {
+      this.userTaskCount.set(task.userUuid, prev - 1);
+    }
+    this.runningCount = Math.max(0, this.runningCount - 1);
+
+    // 释放进程引用
+    task.childProcess = null;
+
+    // 记录完成时间
+    task.endTime = Date.now();
+
+    console.log(`[BgTask] Task ${task.id} finished: status=${task.status}, exitCode=${task.exitCode}, duration=${task.endTime - task.startTime}ms`);
+
+    // 发出事件
+    this.emit('task-complete', task);
+  }
+
+  _cleanupCompleted() {
+    const now = Date.now();
+    for (const [id, task] of this.tasks) {
+      if (task.status !== 'running' && task.endTime && now - task.endTime > COMPLETED_TTL_MS) {
+        this.tasks.delete(id);
+      }
+    }
+  }
+
+  _genId() {
+    return 'bg_' + crypto.randomBytes(6).toString('hex');
+  }
+}
+
+// ─── PendingResultQueue ───
+
+/** @type {Map<string, object[]>} key = "userUuid:sessionId" */
+const pendingResults = new Map();
+
+function _key(userUuid, sessionId) {
+  return `${userUuid}:${sessionId}`;
+}
+
+/**
+ * 将已完成的任务结果加入待投递队列
+ */
+export function enqueueResult(userUuid, sessionId, taskResult) {
+  const k = _key(userUuid, sessionId);
+  if (!pendingResults.has(k)) pendingResults.set(k, []);
+  pendingResults.get(k).push({
+    id: taskResult.id,
+    command: taskResult.command,
+    label: taskResult.label,
+    status: taskResult.status,
+    exitCode: taskResult.exitCode,
+    signal: taskResult.signal,
+    stdout: taskResult.stdout,
+    stderr: taskResult.stderr,
+    truncated: taskResult.truncated,
+    startTime: taskResult.startTime,
+    endTime: taskResult.endTime,
+    cwd: taskResult.cwd,
+    sessionId: taskResult.sessionId,
+    userUuid: taskResult.userUuid,
+  });
+}
+
+/**
+ * 从队列取出一条结果（FIFO）
+ */
+export function dequeueResult(userUuid, sessionId) {
+  const k = _key(userUuid, sessionId);
+  const q = pendingResults.get(k);
+  if (!q || q.length === 0) return null;
+  const item = q.shift();
+  if (q.length === 0) pendingResults.delete(k);
+  return item;
+}
+
+/**
+ * 检查是否有待投递结果
+ */
+export function hasResults(userUuid, sessionId) {
+  const k = _key(userUuid, sessionId);
+  const q = pendingResults.get(k);
+  return q && q.length > 0;
+}
+
+/**
+ * 获取用户所有 session 的待投递结果
+ * @returns {Array<{sessionId: string, results: object[]}>}
+ */
+export function getAllPendingForUser(userUuid) {
+  const out = [];
+  for (const [k, results] of pendingResults) {
+    if (k.startsWith(userUuid + ':')) {
+      const sessionId = k.slice(userUuid.length + 1);
+      out.push({ sessionId, results: [...results] });
+    }
+  }
+  return out;
+}
+
+// ─── 单例导出 ───
+
+export const backgroundTaskPool = new BackgroundTaskPool();
+export default backgroundTaskPool;

package/server/services/builtin-tools/background-task.js

@@ -0,0 +1,231 @@
+/**
+ * 内置工具：后台任务执行器 + 状态查询
+ *
+ * __bg_exec__: AI 调用 Bash(__bg_exec__ '<json>') 提交后台任务
+ * __bg_status__: AI 调用 Bash(__bg_status__) 或 Bash(__bg_status__ '<taskId>') 查询任务状态
+ *
+ * 飞书端不支持此工具（无法自动发起新 query 投递结果）。
+ */
+
+import { backgroundTaskPool } from './background-task-pool.js';
+import { evaluate as evaluateToolGuard } from '../tool-guard/index.js';
+
+const ENABLED = process.env.BG_TASK_ENABLED !== 'false';
+
+// ─── __bg_exec__：提交后台任务 ───
+
+export default {
+  name: '__bg_exec__',
+
+  // 不需要 responseType — 结果通过 PendingResultQueue 投递，不走 resolveResponse 路径
+
+  systemPrompt: `
+
+## 后台任务执行器
+
+当你需要执行可能耗时超过 30 秒的命令时（如 git clone、npm install、大型构建、长时间脚本等），
+使用后台任务执行器代替 Bash 的 run_in_background + TaskOutput 轮询模式。
+
+### 提交后台任务
+\`\`\`bash
+__bg_exec__ '{"command":"要执行的命令","timeout":600000,"label":"任务描述"}'
+\`\`\`
+参数说明：
+- command（必需）：要执行的 shell 命令
+- timeout（可选）：超时时间（毫秒），默认 600000（10分钟），最大 1800000（30分钟）
+- label（可选）：人类可读的任务描述
+
+任务会在后台执行，你会立即收到任务 ID 确认。任务完成后结果会自动推送给你，
+你不需要轮询或等待，可以继续处理其他工作。
+
+### 查询任务状态
+\`\`\`bash
+__bg_status__
+\`\`\`
+不带参数：列出当前会话所有后台任务的状态。
+
+\`\`\`bash
+__bg_status__ bg_xxxxxxxxxxxx
+\`\`\`
+带任务 ID：查询指定任务的详细状态（包含已产生的输出）。
+
+注意事项：
+- 每个用户最多同时运行 3 个后台任务
+- 不要对交互式命令使用此工具（如需要用户输入的命令）
+- 不要对很快就能完成的命令使用此工具（<30 秒的用普通 Bash）
+- 如果服务器重启，正在运行的后台任务会丢失
+- 不要使用 TaskOutput 来查询后台任务状态，请使用 __bg_status__
+`,
+
+  match(hookInput) {
+    if (!ENABLED) return false;
+    return hookInput.tool_name === 'Bash' &&
+      hookInput.tool_input?.command?.trimStart().startsWith('__bg_exec__');
+  },
+
+  async execute(hookInput, context) {
+    const { userUuid, mutableWriter, cwd } = context;
+
+    // 飞书模式检测
+    if (!mutableWriter?.current?.ws) {
+      return { decision: 'deny', reason: '后台任务执行功能仅支持网页端使用。' };
+    }
+
+    // 解析参数
+    const rawArgs = hookInput.tool_input.command.replace(/^\s*__bg_exec__\s*/, '');
+    let jsonStr = rawArgs.trim();
+    if ((jsonStr.startsWith("'") && jsonStr.endsWith("'")) ||
+        (jsonStr.startsWith('"') && jsonStr.endsWith('"'))) {
+      jsonStr = jsonStr.slice(1, -1);
+    }
+
+    let params;
+    try {
+      params = JSON.parse(jsonStr);
+    } catch (e) {
+      return { decision: 'deny', reason: `参数解析失败: ${e.message}。请使用 JSON 格式：__bg_exec__ '{"command":"..."}'` };
+    }
+
+    if (!params.command || typeof params.command !== 'string') {
+      return { decision: 'deny', reason: '缺少必需参数 command（要执行的命令）。' };
+    }
+
+    const actualCommand = params.command.trim();
+    if (!actualCommand) {
+      return { decision: 'deny', reason: 'command 不能为空。' };
+    }
+
+    // ToolGuard 安全检查（对实际命令而非 __bg_exec__ 包装）
+    try {
+      const guardResult = await evaluateToolGuard('Bash', { command: actualCommand }, {
+        userUuid,
+        cwd,
+      });
+      if (!guardResult.allowed) {
+        return { decision: 'deny', reason: `[系统安全策略] ${guardResult.reason}` };
+      }
+    } catch (err) {
+      console.error(`[BgTask] ToolGuard error:`, err.message);
+      // 守卫出错不阻塞，降级为允许
+    }
+
+    // 提交到进程池
+    let task;
+    try {
+      task = backgroundTaskPool.submit({
+        userUuid,
+        sessionId: mutableWriter.getSessionId(),
+        cwd,
+        command: actualCommand,
+        timeout: params.timeout,
+        label: params.label,
+      });
+    } catch (err) {
+      return { decision: 'deny', reason: `后台任务提交失败: ${err.message}` };
+    }
+
+    const timeoutSec = Math.round(task.timeout / 1000);
+    return {
+      decision: 'deny',
+      reason: `后台任务已启动。\n` +
+        `- 任务 ID: ${task.id}\n` +
+        `- 命令: ${actualCommand}\n` +
+        `- 超时: ${timeoutSec}s\n` +
+        `任务完成后结果会自动推送给你，请继续处理其他工作。`,
+    };
+  }
+};
+
+// ─── __bg_status__：查询后台任务状态 ───
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  return `${Math.floor(s / 60)}m${s % 60}s`;
+}
+
+function formatTaskSummary(task) {
+  const elapsed = (task.endTime || Date.now()) - task.startTime;
+  const lines = [
+    `[${task.id}] ${task.status.toUpperCase()}`,
+    `  命令: ${task.command}`,
+    `  耗时: ${formatDuration(elapsed)}`,
+  ];
+  if (task.status !== 'running') {
+    lines.push(`  退出码: ${task.exitCode ?? 'N/A'}`);
+  }
+  if (task.label && task.label !== task.command.slice(0, 80)) {
+    lines.splice(1, 0, `  标签: ${task.label}`);
+  }
+  return lines.join('\n');
+}
+
+function formatTaskDetail(task) {
+  const elapsed = (task.endTime || Date.now()) - task.startTime;
+  const lines = [
+    `任务 ID: ${task.id}`,
+    `状态: ${task.status}`,
+    `命令: ${task.command}`,
+    `耗时: ${formatDuration(elapsed)}`,
+    `退出码: ${task.exitCode ?? 'N/A'}`,
+  ];
+  if (task.truncated) lines.push('(输出已截断至 100KB)');
+  if (task.stdout) lines.push('', '--- STDOUT ---', task.stdout);
+  if (task.stderr) lines.push('', '--- STDERR ---', task.stderr);
+  if (task.status === 'running' && !task.stdout && !task.stderr) {
+    lines.push('', '(暂无输出)');
+  }
+  return lines.join('\n');
+}
+
+export const bgStatusTool = {
+  name: '__bg_status__',
+
+  // systemPrompt 合并在 __bg_exec__ 的 systemPrompt 中，不需要单独的
+
+  systemPrompt: '',
+
+  match(hookInput) {
+    if (!ENABLED) return false;
+    return hookInput.tool_name === 'Bash' &&
+      hookInput.tool_input?.command?.trimStart().startsWith('__bg_status__');
+  },
+
+  async execute(hookInput, context) {
+    const { userUuid, mutableWriter } = context;
+    const sessionId = mutableWriter?.getSessionId();
+
+    // 解析可选的 taskId 参数
+    const rawArgs = hookInput.tool_input.command.replace(/^\s*__bg_status__\s*/, '').trim();
+    // 去掉可能的引号
+    let taskId = rawArgs.replace(/^['"]|['"]$/g, '').trim();
+
+    if (taskId) {
+      // 查询指定任务
+      const task = backgroundTaskPool.getTask(taskId);
+      if (!task) {
+        return { decision: 'deny', reason: `未找到任务 ${taskId}。任务可能已过期被清理。` };
+      }
+      if (task.userUuid !== userUuid) {
+        return { decision: 'deny', reason: `未找到任务 ${taskId}。` };
+      }
+      return { decision: 'deny', reason: formatTaskDetail(task) };
+    }
+
+    // 列出当前会话所有任务
+    const tasks = sessionId
+      ? backgroundTaskPool.getSessionTasks(userUuid, sessionId)
+      : backgroundTaskPool.getUserTasks(userUuid);
+
+    if (tasks.length === 0) {
+      return { decision: 'deny', reason: '当前没有后台任务。' };
+    }
+
+    const lines = [`后台任务列表（共 ${tasks.length} 个）：`, ''];
+    for (const task of tasks) {
+      lines.push(formatTaskSummary(task), '');
+    }
+    return { decision: 'deny', reason: lines.join('\n') };
+  }
+};

package/server/services/builtin-tools/index.js

@@ -0,0 +1,146 @@
+/**
+ * Builtin Tool Registry — 内置工具注册中心
+ *
+ * claude-agent-sdk 不提供添加自定义内置工具的 API，因此通过
+ * "注入 system prompt + PreToolUse hook 拦截 Bash 命令"的方式模拟。
+ *
+ * 本模块采用 Registry + Strategy 模式：
+ * - 每个工具是一个自包含的策略对象（name, systemPrompt, match, execute）
+ * - Registry 统一管理注册、system prompt 合并、hook 分发、异步响应等待
+ *
+ * 扩展新工具只需在 tools/ 目录添加新模块并调用 registry.register()。
+ */
+
+import crypto from 'crypto';
+
+// ─── 通用工具 ───
+
+/**
+ * 生成唯一请求 ID（用于 UI 审批/异步响应流）
+ */
+export function createRequestId() {
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString('hex');
+}
+
+// ─── Registry ───
+
+class BuiltinToolRegistry {
+  #tools = [];
+  #responseTypes = new Set();
+  #pendingRequests = new Map();
+
+  /**
+   * 注册一个内置工具
+   * @param {{ name: string, responseType?: string, systemPrompt: string, match: Function, execute: Function }} tool
+   */
+  register(tool) {
+    this.#tools.push(tool);
+    if (tool.responseType) {
+      this.#responseTypes.add(tool.responseType);
+    }
+  }
+
+  /**
+   * 合并所有工具的 systemPrompt 描述文本
+   */
+  getSystemPromptAppend() {
+    return this.#tools.map(t => t.systemPrompt).join('\n');
+  }
+
+  /**
+   * PreToolUse hook 入口：遍历工具匹配并执行
+   * @param {object} hookInput - SDK PreToolUse hook 输入
+   * @param {{ userUuid: string, cwd: string, mutableWriter: object }} ctx
+   * @returns {object|null} SDK hook 返回值，无匹配时返回 null
+   */
+  async handlePreToolUse(hookInput, ctx) {
+    for (const tool of this.#tools) {
+      if (tool.match(hookInput)) {
+        const toolContext = {
+          ...ctx,
+          createRequestId,
+          waitForResponse: (requestId, timeoutMs) => this.#waitForResponse(requestId, timeoutMs),
+        };
+
+        try {
+          const result = await tool.execute(hookInput, toolContext);
+          return {
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              permissionDecision: result.decision,
+              ...(result.reason && { permissionDecisionReason: result.reason }),
+              ...(result.updatedInput && { updatedInput: result.updatedInput }),
+            }
+          };
+        } catch (err) {
+          return {
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              permissionDecision: 'deny',
+              permissionDecisionReason: `内置工具 ${tool.name} 执行失败: ${err.message}`,
+            }
+          };
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * 检查 WS 消息类型是否属于内置工具的响应
+   */
+  canHandleResponse(type) {
+    return this.#responseTypes.has(type);
+  }
+
+  /**
+   * 解析异步等待中的 Promise（由 server/index.js WS 消息路由调用）
+   */
+  resolveResponse(requestId, data) {
+    const resolver = this.#pendingRequests.get(requestId);
+    if (resolver) resolver(data);
+  }
+
+  /**
+   * 带超时的异步响应等待
+   */
+  #waitForResponse(requestId, timeoutMs) {
+    return new Promise(resolve => {
+      let settled = false;
+      const finalize = (result) => {
+        if (settled) return;
+        settled = true;
+        this.#pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve(result);
+      };
+      const timeout = setTimeout(() => finalize(null), timeoutMs);
+      this.#pendingRequests.set(requestId, finalize);
+    });
+  }
+}
+
+// ─── 单例创建 & 工具注册 ───
+
+const registry = new BuiltinToolRegistry();
+
+import shareProjectTemplate from './share-project-template.js';
+registry.register(shareProjectTemplate);
+
+import backgroundTask, { bgStatusTool } from './background-task.js';
+registry.register(backgroundTask);
+registry.register(bgStatusTool);
+
+// 重新导出后台任务相关模块，供 server/index.js 使用
+export {
+  backgroundTaskPool,
+  enqueueResult,
+  dequeueResult,
+  hasResults,
+  getAllPendingForUser,
+} from './background-task-pool.js';
+
+export default registry;