deeper-cli 1.0.0

package/src/tools/builtin/shell/kill_terminal.ts

@@ -0,0 +1,29 @@
+import { killProcess } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const kill_terminal: Tool = {
+  name: 'kill_terminal',
+  description: '强制关闭后台终端',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      terminal_id: { type: 'string', description: '终端标识' },
+    },
+    required: ['terminal_id'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const terminalId = params.terminal_id as string;
+      const ok = killProcess(terminalId);
+      if (!ok) {
+        return { success: false, error: `终端不存在: ${terminalId}`, output: '' };
+      }
+      return { success: true, output: `已关闭终端: ${terminalId}`, metadata: { terminalId } };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/shell/list_terminals.ts

@@ -0,0 +1,61 @@
+import { listProcesses, readOutput as poolRead } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const list_terminals: Tool = {
+  name: 'list_terminals',
+  description: '列出所有后台终端及最近输出',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute() {
+    try {
+      const entries = listProcesses();
+      if (entries.length === 0) {
+        return { success: true, output: '没有后台终端' };
+      }
+      let out = `后台终端 (${entries.length}):\n`;
+      for (const e of entries) {
+        const status = e.alive ? `运行 ${e.runningSec}s` : '已结束';
+        out += `  ${e.id}  PID:${e.pid ?? '-'}  ${e.command}\n`;
+        out += `  ${status} | 输出:${e.outputLen}B | ${e.outputTail}\n\n`;
+      }
+      return { success: true, output: out, metadata: { entries } };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};
+
+export const read_terminal: Tool = {
+  name: 'read_terminal',
+  description: '读取后台终端的输出内容',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      terminal_id: { type: 'string', description: '终端标识' },
+      tail: { type: 'boolean', description: '仅显示末尾输出' },
+    },
+    required: ['terminal_id'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const terminalId = params.terminal_id as string;
+      const tail = (params.tail as boolean) ?? true;
+      const output = poolRead(terminalId, tail);
+      if (output === null) {
+        return { success: false, error: `终端不存在: ${terminalId}`, output: '' };
+      }
+      return { success: true, output, metadata: { terminalId, tail } };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/shell/pipe_commands.ts

@@ -0,0 +1,55 @@
+import { exec as execCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { Tool } from '../../tool-types.js';
+
+const execAsync = promisify(execCb);
+
+export const pipe_commands: Tool = {
+  name: 'pipe_commands',
+  description: '管道串联多个命令',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      commands: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '命令列表，按顺序通过管道串联',
+      },
+      cwd: { type: 'string', description: '工作目录' },
+      timeout_ms: { type: 'number', description: '超时毫秒数' },
+    },
+    required: ['commands'],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const commands = params.commands as string[];
+      const cwd = (params.cwd as string) ?? process.cwd();
+      const timeout = (params.timeout_ms as number) ?? 30000;
+      const pipeline = commands.join(' | ');
+
+      const { stdout, stderr } = await execAsync(pipeline, {
+        cwd,
+        timeout,
+        maxBuffer: 10 * 1024 * 1024,
+        encoding: 'utf-8',
+        shell: process.env.SHELL || process.env.ComSpec || 'cmd.exe',
+      });
+
+      return {
+        success: true,
+        output: stdout + (stderr ? `\n[stderr]\n${stderr}` : ''),
+        metadata: { pipeline },
+      };
+    } catch (err: unknown) {
+      const e = err as { message?: string; stdout?: string; stderr?: string };
+      return {
+        success: false,
+        error: e.message || String(err),
+        output: [e.stdout, e.stderr].filter(Boolean).join('\n'),
+      };
+    }
+  },
+};

package/src/tools/builtin/shell/process-pool.ts

@@ -0,0 +1,150 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+
+export interface ProcessEntry {
+  proc: ChildProcess;
+  output: string;
+  startTime: number;
+  command: string;
+  cwd: string;
+  alive: boolean;
+}
+
+const pool = new Map<string, ProcessEntry>();
+const RING_SIZE = 64_000;
+const TAIL_SIZE = 16_000;
+
+export function decodeBuffer(bufs: Buffer[]): string {
+  const buf = Buffer.concat(bufs);
+  if (process.platform === 'win32') {
+    try {
+      const decoder = new TextDecoder('gbk', { fatal: false });
+      return decoder.decode(buf);
+    } catch {
+      return buf.toString('utf-8');
+    }
+  }
+  return buf.toString('utf-8');
+}
+
+function ringPush(entry: ProcessEntry, chunk: string): void {
+  entry.output += chunk;
+  if (entry.output.length > RING_SIZE) {
+    entry.output = entry.output.slice(-RING_SIZE);
+  }
+}
+
+export function startBgProcess(params: {
+  command: string;
+  cwd?: string;
+  terminalId?: string;
+  env?: Record<string, string>;
+}): { terminalId: string; pid: number | undefined } {
+  const cwd = params.cwd || process.cwd();
+  const terminalId = params.terminalId || `bg_${Date.now()}_${Math.random().toString(36).slice(2,6)}`;
+  const [cmd, ...args] = params.command.split(/\s+/);
+
+  if (pool.has(terminalId)) {
+    const old = pool.get(terminalId)!;
+    try { old.proc.kill(); } catch {}
+    pool.delete(terminalId);
+  }
+
+  const proc = spawn(cmd, args, {
+    cwd,
+    shell: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: params.env ? { ...process.env, ...params.env } : process.env,
+  });
+
+  const entry: ProcessEntry = {
+    proc,
+    output: '',
+    startTime: Date.now(),
+    command: params.command,
+    cwd,
+    alive: true,
+  };
+
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+
+  proc.stdout?.on('data', (d: Buffer) => stdoutChunks.push(d));
+  proc.stderr?.on('data', (d: Buffer) => stderrChunks.push(d));
+
+  const flushInterval = setInterval(() => {
+    if (stdoutChunks.length > 0) {
+      ringPush(entry, decodeBuffer(stdoutChunks.splice(0)));
+    }
+    if (stderrChunks.length > 0) {
+      ringPush(entry, '[stderr] ' + decodeBuffer(stderrChunks.splice(0)));
+    }
+  }, 50);
+
+  proc.on('close', (code) => {
+    clearInterval(flushInterval);
+    if (stdoutChunks.length > 0) ringPush(entry, decodeBuffer(stdoutChunks.splice(0)));
+    if (stderrChunks.length > 0) ringPush(entry, '[stderr] ' + decodeBuffer(stderrChunks.splice(0)));
+    entry.alive = false;
+    ringPush(entry, `\n[进程结束, exitCode=${code}]\n`);
+  });
+
+  proc.on('error', (err) => {
+    clearInterval(flushInterval);
+    entry.alive = false;
+    ringPush(entry, `\n[进程错误: ${err.message}]\n`);
+  });
+
+  pool.set(terminalId, entry);
+  return { terminalId, pid: proc.pid ?? undefined };
+}
+
+export function readOutput(terminalId: string, tailOnly?: boolean): string | null {
+  const entry = pool.get(terminalId);
+  if (!entry) return null;
+  const full = entry.output || '(暂无输出)';
+  if (tailOnly) {
+    return full.length > TAIL_SIZE ? '...(截断)\n' + full.slice(-TAIL_SIZE) : full;
+  }
+  return full.length > TAIL_SIZE * 2 ? full.slice(-TAIL_SIZE * 2) : full;
+}
+
+export function listProcesses(): Array<{
+  id: string; pid: number | undefined; command: string;
+  alive: boolean; runningSec: number; outputLen: number; outputTail: string;
+}> {
+  return Array.from(pool.entries()).map(([id, e]) => ({
+    id,
+    pid: e.proc.pid ?? undefined,
+    command: e.command.slice(0, 60),
+    alive: e.alive,
+    runningSec: Math.round((Date.now() - e.startTime) / 1000),
+    outputLen: e.output.length,
+    outputTail: e.output.slice(-200).replace(/\n/g, '↵').slice(0, 160),
+  }));
+}
+
+export function killProcess(terminalId: string): boolean {
+  const entry = pool.get(terminalId);
+  if (!entry) return false;
+  try { entry.proc.kill('SIGKILL'); } catch {}
+  pool.delete(terminalId);
+  return true;
+}
+
+export function getProcess(terminalId: string): ProcessEntry | undefined {
+  return pool.get(terminalId);
+}
+
+export function sendToStdin(terminalId: string, text: string): boolean {
+  const entry = pool.get(terminalId);
+  if (!entry || !entry.alive || !entry.proc.stdin) return false;
+  entry.proc.stdin.write(text + '\n');
+  return true;
+}
+
+export function sendSignal(terminalId: string, signal: 'SIGINT' | 'SIGTERM' | 'SIGKILL'): boolean {
+  const entry = pool.get(terminalId);
+  if (!entry || !entry.alive) return false;
+  try { entry.proc.kill(signal); } catch { return false; }
+  return true;
+}

package/src/tools/builtin/shell/run_async.ts

@@ -0,0 +1,73 @@
+import { spawn } from 'node:child_process';
+import { decodeBuffer } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+const runningProcesses = new Map<string, ReturnType<typeof spawn>>();
+
+export const run_async: Tool = {
+  name: 'run_async',
+  description: '异步执行命令并等待完成 (可配合 check_status / stop_command)',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: '命令和参数' },
+      cwd: { type: 'string', description: '工作目录' },
+      task_id: { type: 'string', description: '任务标识，用于后续查询' },
+    },
+    required: ['command'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const command = params.command as string;
+      const cwd = (params.cwd as string) ?? process.cwd();
+      const taskId = (params.task_id as string) ?? `async_${Date.now()}`;
+
+      const [cmd, ...args] = command.split(/\s+/);
+      const proc = spawn(cmd, args, {
+        cwd,
+        shell: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: process.env,
+      });
+
+      runningProcesses.set(taskId, proc);
+
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+      proc.stdout?.on('data', (d: Buffer) => stdoutChunks.push(d));
+      proc.stderr?.on('data', (d: Buffer) => stderrChunks.push(d));
+
+      try {
+        await new Promise<void>((resolve, reject) => {
+          proc.on('close', (code) => {
+            runningProcesses.delete(taskId);
+            if (code === 0) resolve();
+            else reject(new Error(`进程退出码: ${code}`));
+          });
+          proc.on('error', reject);
+        });
+      } catch (e) {
+        runningProcesses.delete(taskId);
+        return {
+          success: false,
+          error: (e as Error).message,
+          output: decodeBuffer(stdoutChunks) + decodeBuffer(stderrChunks),
+          metadata: { taskId },
+        };
+      }
+
+      return {
+        success: true,
+        output: decodeBuffer(stdoutChunks) + (stderrChunks.length ? '\n[stderr]\n' + decodeBuffer(stderrChunks) : '') || '(无输出)',
+        metadata: { taskId, command },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};
+
+export { runningProcesses };

package/src/tools/builtin/shell/run_command.ts

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import { decodeBuffer } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const run_command: Tool = {
+  name: 'run_command',
+  description: '执行系统命令并返回结果 (阻塞等待完成)',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: '要执行的命令' },
+      cwd: { type: 'string', description: '工作目录' },
+      timeout_ms: { type: 'number', description: '超时毫秒数 (默认 30s)' },
+    },
+    required: ['command'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    return new Promise((resolve) => {
+      const command = params.command as string;
+      const cwd = (params.cwd as string) || process.cwd();
+      const timeout = (params.timeout_ms as number) ?? 30_000;
+
+      const proc = spawn(command, {
+        cwd, shell: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      const timer = setTimeout(() => {
+        try { proc.kill(); } catch {}
+        resolve({ success: false, error: `命令超时 (${timeout}ms)`, output: '' });
+      }, timeout);
+
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+      proc.stdout?.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+      proc.stderr?.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+
+      proc.on('error', (err: Error) => {
+        clearTimeout(timer);
+        resolve({ success: false, error: err.message, output: '' });
+      });
+
+      proc.on('close', (code: number | null) => {
+        clearTimeout(timer);
+        const stdout = decodeBuffer(stdoutChunks);
+        const stderr = decodeBuffer(stderrChunks);
+        const output = (stdout + (stderr ? `\n[stderr]\n${stderr}` : '')).slice(0, 8000);
+
+        if (code === 0) {
+          resolve({ success: true, output, metadata: { command, cwd, exitCode: code } });
+        } else {
+          resolve({ success: false, error: `Exit code: ${code}`, output });
+        }
+      });
+    });
+  },
+};

package/src/tools/builtin/shell/send_ctrl_keys.ts

@@ -0,0 +1,43 @@
+import { sendSignal } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const send_ctrl_keys: Tool = {
+  name: 'send_ctrl_keys',
+  description: '向后台终端发送控制信号 (Ctrl+C=SIGINT, Ctrl+D=关闭stdin)',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      terminal_id: { type: 'string', description: '终端标识' },
+      signal: { type: 'string', enum: ['ctrl_c', 'ctrl_d', 'ctrl_z'], description: 'ctrl_c=SIGINT, ctrl_d=关闭stdin, ctrl_z=SIGTSTP' },
+    },
+    required: ['terminal_id', 'signal'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const terminalId = params.terminal_id as string;
+      const signal = params.signal as string;
+
+      switch (signal) {
+        case 'ctrl_c':
+          sendSignal(terminalId, 'SIGINT');
+          return { success: true, output: `已发送 Ctrl+C 到终端: ${terminalId}`, metadata: { terminalId }, };
+        case 'ctrl_d': {
+          const { getProcess } = await import('./process-pool.js');
+          const entry = getProcess(terminalId);
+          if (entry?.proc.stdin) { entry.proc.stdin.end(); }
+          return { success: true, output: `已发送 Ctrl+D 到终端: ${terminalId}`, metadata: { terminalId }, };
+        }
+        case 'ctrl_z':
+          sendSignal(terminalId, 'SIGTERM');
+          return { success: true, output: `已发送 Ctrl+Z 到终端: ${terminalId}`, metadata: { terminalId }, };
+        default:
+          return { success: false, error: `未知信号: ${signal}`, output: '' };
+      }
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/shell/send_keys.ts

@@ -0,0 +1,36 @@
+import { getProcess } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const send_keys: Tool = {
+  name: 'send_keys',
+  description: '检查后台终端是否可写入',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      terminal_id: { type: 'string', description: '终端标识' },
+    },
+    required: ['terminal_id'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const terminalId = params.terminal_id as string;
+      const entry = getProcess(terminalId);
+      if (!entry || !entry.alive) {
+        return { success: false, error: `终端不可用: ${terminalId}`, output: '' };
+      }
+      if (!entry.proc.stdin) {
+        return { success: false, error: `终端 stdin 不可写: ${terminalId}`, output: '' };
+      }
+      return {
+        success: true,
+        output: `终端 "${terminalId}" 就绪，可通过 send_text 发送文本`,
+        metadata: { terminalId, pid: entry.proc.pid },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/shell/send_text.ts

@@ -0,0 +1,35 @@
+import { sendToStdin } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const send_text: Tool = {
+  name: 'send_text',
+  description: '向后台终端发送文本输入',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      terminal_id: { type: 'string', description: '终端标识' },
+      text: { type: 'string', description: '要发送的文本' },
+    },
+    required: ['terminal_id', 'text'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const terminalId = params.terminal_id as string;
+      const text = params.text as string;
+      const ok = sendToStdin(terminalId, text);
+      if (!ok) {
+        return { success: false, error: `无法发送到终端: ${terminalId}`, output: '' };
+      }
+      return {
+        success: true,
+        output: `已发送文本到终端: ${terminalId}`,
+        metadata: { terminalId, length: text.length },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/shell/shell_script.ts

@@ -0,0 +1,65 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { exec as execCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+const execAsync = promisify(execCb);
+
+export const shell_script: Tool = {
+  name: 'shell_script',
+  description: '执行 Shell 脚本文件',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      script_path: { type: 'string', description: '脚本文件路径' },
+      args: { type: 'array', items: { type: 'string' }, description: '脚本参数' },
+      cwd: { type: 'string', description: '工作目录' },
+      timeout_ms: { type: 'number', description: '超时毫秒数' },
+    },
+    required: ['script_path'],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const scriptPath = resolve(params.script_path as string);
+      const args = (params.args as string[]) ?? [];
+      const cwd = (params.cwd as string) ?? process.cwd();
+      const timeout = (params.timeout_ms as number) ?? 30000;
+
+      if (!existsSync(scriptPath)) {
+        return { success: false, error: `脚本文件不存在: ${scriptPath}`, output: '' };
+      }
+
+      const shell = process.platform === 'win32'
+        ? process.env.ComSpec || 'cmd.exe'
+        : process.env.SHELL || '/bin/sh';
+
+      const cmd = process.platform === 'win32'
+        ? `"${shell}" /c "${scriptPath}" ${args.join(' ')}`
+        : `${shell} "${scriptPath}" ${args.join(' ')}`;
+
+      const { stdout, stderr } = await execAsync(cmd, {
+        cwd,
+        timeout,
+        maxBuffer: 10 * 1024 * 1024,
+        encoding: 'utf-8',
+      });
+
+      return {
+        success: true,
+        output: stdout + (stderr ? `\n[stderr]\n${stderr}` : ''),
+        metadata: { script: scriptPath },
+      };
+    } catch (err: unknown) {
+      const e = err as { message?: string; stdout?: string; stderr?: string };
+      return {
+        success: false,
+        error: e.message || String(err),
+        output: [e.stdout, e.stderr].filter(Boolean).join('\n'),
+      };
+    }
+  },
+};

package/src/tools/builtin/shell/stop_command.ts

@@ -0,0 +1,40 @@
+import { runningProcesses } from './run_async.js';
+import type { Tool } from '../../tool-types.js';
+
+export const stop_command: Tool = {
+  name: 'stop_command',
+  description: '终止正在执行的异步命令',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: '任务标识' },
+      signal: { type: 'string', description: '终止信号: SIGTERM, SIGKILL', enum: ['SIGTERM', 'SIGKILL'] },
+    },
+    required: ['task_id'],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const taskId = params.task_id as string;
+      const signal = (params.signal as string) ?? 'SIGTERM';
+      const proc = runningProcesses.get(taskId);
+
+      if (!proc) {
+        return { success: false, error: `任务不存在或已完成: ${taskId}`, output: '' };
+      }
+
+      if (signal === 'SIGKILL') {
+        proc.kill('SIGKILL');
+      } else {
+        proc.kill('SIGTERM');
+      }
+
+      runningProcesses.delete(taskId);
+      return { success: true, output: `已终止任务: ${taskId} (信号: ${signal})` };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/shell/terminal_resize.ts

@@ -0,0 +1,31 @@
+import type { Tool } from '../../tool-types.js';
+
+export const terminal_resize: Tool = {
+  name: 'terminal_resize',
+  description: '调整终端尺寸',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      rows: { type: 'number', description: '行数' },
+      cols: { type: 'number', description: '列数' },
+    },
+    required: ['rows', 'cols'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const rows = params.rows as number;
+      const cols = params.cols as number;
+      process.stdout.write(`\x1b[8;${rows};${cols}t`);
+      return {
+        success: true,
+        output: `终端尺寸已调整: ${cols}x${rows}`,
+        metadata: { rows, cols },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};