deeper-cli 1.0.0

package/src/tools/builtin/search/search_package.ts

@@ -0,0 +1,50 @@
+import { execSync } from 'node:child_process';
+import type { Tool } from '../../tool-types.js';
+
+export const search_package: Tool = {
+  name: 'search_package',
+  description: '搜索 npm 包',
+  category: 'search',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: '包名关键词' },
+      count: { type: 'number', description: '返回数量' },
+    },
+    required: ['name'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const name = params.name as string;
+      const count = (params.count as number) ?? 10;
+      const output = execSync(
+        `npm search "${name}" --registry https://registry.npmmirror.com --json 2>&1`,
+        { encoding: 'utf-8', timeout: 15000 }
+      );
+      const results = JSON.parse(output);
+      const items = (Array.isArray(results) ? results.slice(0, count) : [results]).map(
+        (pkg: Record<string, unknown>) => ({
+          name: pkg.name as string,
+          version: pkg.version as string,
+          description: pkg.description as string,
+          author: (pkg.author as Record<string, unknown> | undefined)?.name || pkg.author,
+        })
+      );
+      return {
+        success: true,
+        output: items.map((i: Record<string, unknown>) =>
+          `${i.name}@${i.version}\n  ${i.description}\n  Author: ${i.author}`
+        ).join('\n\n'),
+        metadata: { count: items.length },
+      };
+    } catch {
+      return {
+        success: true,
+        output: `请在 npm 官网搜索: https://www.npmjs.com/search?q=${encodeURIComponent(params.name as string)}`,
+        metadata: { fallback: true },
+      };
+    }
+  },
+};

package/src/tools/builtin/search/symbol_search.ts

@@ -0,0 +1,82 @@
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+export const symbol_search: Tool = {
+  name: 'symbol_search',
+  description: '在代码库中搜索符号（函数、类、变量定义）',
+  category: 'search',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: '符号名称' },
+      cwd: { type: 'string', description: '搜索根目录' },
+      type: { type: 'string', description: '符号类型: function, class, variable, interface, type', enum: ['function', 'class', 'variable', 'interface', 'type', 'all'] },
+      max_results: { type: 'number', description: '最大结果数' },
+    },
+    required: ['name'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const name = params.name as string;
+      const cwd = (params.cwd as string) ? resolve(params.cwd as string) : process.cwd();
+      const symbolType = (params.type as string) ?? 'all';
+      const maxResults = (params.max_results as number) ?? 50;
+
+      const patterns: [string, RegExp][] = [];
+      if (symbolType === 'all' || symbolType === 'function') {
+        patterns.push(['function', new RegExp(`(?:function\\s+${name}|${name}\\s*[=:]\\s*(?:async\\s+)?(?:function|\\([^)]*\\)\\s*=>)|(?:async\\s+)?${name}\\s*\\([^)]*\\)\\s*\\{`, 'gmi')]);
+      }
+      if (symbolType === 'all' || symbolType === 'class') {
+        patterns.push(['class', new RegExp(`class\\s+${name}\\b`, 'gmi')]);
+      }
+      if (symbolType === 'all' || symbolType === 'variable') {
+        patterns.push(['variable', new RegExp(`(?:const|let|var)\\s+${name}\\b`, 'gmi')]);
+      }
+      if (symbolType === 'all' || symbolType === 'interface') {
+        patterns.push(['interface', new RegExp(`interface\\s+${name}\\b`, 'gmi')]);
+      }
+      if (symbolType === 'all' || symbolType === 'type') {
+        patterns.push(['type', new RegExp(`type\\s+${name}\\b`, 'gmi')]);
+      }
+
+      const fg = await import('fast-glob');
+      const files = await fg.default('**/*.{ts,js,tsx,jsx}', {
+        cwd,
+        absolute: true,
+        ignore: ['node_modules/**', '.git/**', 'dist/**'],
+        onlyFiles: true,
+      });
+
+      const results: string[] = [];
+      const maxFileSize = 2 * 1024 * 1024;
+
+      for (const fp of files) {
+        if (results.length >= maxResults) break;
+        try {
+          const stat = statSync(fp);
+          if (stat.size > maxFileSize) continue;
+          const content = readFileSync(fp, 'utf-8');
+          for (const [type, regex] of patterns) {
+            regex.lastIndex = 0;
+            let match;
+            while ((match = regex.exec(content)) !== null && results.length < maxResults) {
+              const line = content.slice(0, match.index).split('\n').length;
+              results.push(`${relative(cwd, fp)}:${line}: [${type}] ${match[0].trim()}`);
+            }
+          }
+        } catch { /* skip */ }
+      }
+
+      return {
+        success: true,
+        output: results.join('\n') || '未找到匹配符号',
+        metadata: { count: results.length },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/search/text_search.ts

@@ -0,0 +1,63 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+export const text_search: Tool = {
+  name: 'text_search',
+  description: '全文搜索，在文件内容中查找文本',
+  category: 'search',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: '搜索文本' },
+      dir_path: { type: 'string', description: '搜索目录' },
+      file_pattern: { type: 'string', description: '文件匹配模式，如 *.md' },
+      max_results: { type: 'number', description: '最大结果数' },
+    },
+    required: ['text', 'dir_path'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const text = params.text as string;
+      const dirPath = resolve(params.dir_path as string);
+      const filePattern = (params.file_pattern as string) ?? '**/*';
+      const maxResults = (params.max_results as number) ?? 100;
+
+      const fg = await import('fast-glob');
+      const files = await fg.default(filePattern, {
+        cwd: dirPath,
+        absolute: true,
+        ignore: ['node_modules/**', '.git/**', 'dist/**', '*.min.*', '*.jpg', '*.png', '*.gif', '*.ico', '*.svg'],
+        onlyFiles: true,
+      });
+
+      const results: string[] = [];
+      const maxFileSize = 2 * 1024 * 1024;
+
+      for (const fp of files) {
+        if (results.length >= maxResults) break;
+        try {
+          const stat = await import('node:fs').then(m => m.statSync(fp));
+          if (stat.size > maxFileSize) continue;
+          const content = readFileSync(fp, 'utf-8');
+          const lines = content.split('\n');
+          for (let i = 0; i < lines.length && results.length < maxResults; i++) {
+            if (lines[i].includes(text)) {
+              results.push(`${fp}:${i + 1}:${lines[i].trim()}`);
+            }
+          }
+        } catch { /* skip */ }
+      }
+
+      return {
+        success: true,
+        output: results.join('\n') || '未找到匹配结果',
+        metadata: { matches: results.length, dir: dirPath },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/security/decrypt_file.ts

@@ -0,0 +1,54 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+export const decrypt_file: Tool = {
+  name: 'decrypt_file',
+  description: '解密文件内容 (AES-256-CBC)',
+  category: 'security',
+  parameters: {
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: '要解密的文件路径' },
+      output: { type: 'string', description: '解密输出文件路径' },
+      password: { type: 'string', description: '解密密钥' },
+      algorithm: { type: 'string', description: '算法', enum: ['aes-256-cbc', 'aes-128-cbc'] },
+    },
+    required: ['file_path', 'output'],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const filePath = resolve(params.file_path as string);
+      const output = resolve(params.output as string);
+      const password = params.password as string | undefined;
+      const algorithm = (params.algorithm as string) ?? 'aes-256-cbc';
+
+      if (!existsSync(filePath)) return { success: false, error: `文件不存在: ${filePath}`, output: '' };
+
+      const crypto = await import('node:crypto');
+      const encrypted = readFileSync(filePath);
+
+      const iv = encrypted.subarray(0, 16);
+      const data = encrypted.subarray(16);
+
+      const key = crypto.scryptSync(password || 'default-secret-key', 'salt', algorithm === 'aes-256-cbc' ? 32 : 16);
+      const decipher = crypto.createDecipheriv(algorithm, key, iv);
+
+      const decrypted = Buffer.concat([decipher.update(data), decipher.final()]);
+
+      const outDir = dirname(output);
+      if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+      writeFileSync(output, decrypted);
+
+      return {
+        success: true,
+        output: `文件已解密: ${filePath} → ${output}`,
+        metadata: { algorithm, decryptedSize: decrypted.length },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/security/encrypt_file.ts

@@ -0,0 +1,52 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+export const encrypt_file: Tool = {
+  name: 'encrypt_file',
+  description: '加密文件内容 (AES-256-CBC)',
+  category: 'security',
+  parameters: {
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: '要加密的文件路径' },
+      output: { type: 'string', description: '加密输出文件路径' },
+      password: { type: 'string', description: '加密密钥' },
+      algorithm: { type: 'string', description: '加密算法', enum: ['aes-256-cbc', 'aes-128-cbc'] },
+    },
+    required: ['file_path', 'output'],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const filePath = resolve(params.file_path as string);
+      const output = resolve(params.output as string);
+      const password = params.password as string | undefined;
+      const algorithm = (params.algorithm as string) ?? 'aes-256-cbc';
+
+      if (!existsSync(filePath)) return { success: false, error: `文件不存在: ${filePath}`, output: '' };
+
+      const crypto = await import('node:crypto');
+      const content = readFileSync(filePath);
+
+      const key = crypto.scryptSync(password || 'default-secret-key', 'salt', algorithm === 'aes-256-cbc' ? 32 : 16);
+      const iv = crypto.randomBytes(16);
+      const cipher = crypto.createCipheriv(algorithm, key, iv);
+
+      const encrypted = Buffer.concat([iv, cipher.update(content), cipher.final()]);
+
+      const outDir = dirname(output);
+      if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+      writeFileSync(output, encrypted);
+
+      return {
+        success: true,
+        output: `文件已加密: ${filePath} → ${output}`,
+        metadata: { algorithm, encryptedSize: encrypted.length },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/security/hash_generate.ts

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+export const hash_generate: Tool = {
+  name: 'hash_generate',
+  description: '生成文件或字符串的哈希值',
+  category: 'security',
+  parameters: {
+    type: 'object',
+    properties: {
+      content: { type: 'string', description: '要哈希的字符串' },
+      file_path: { type: 'string', description: '文件路径' },
+      algorithm: { type: 'string', description: '算法', enum: ['sha256', 'sha512', 'md5'] },
+    },
+    required: [],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const content = params.content as string | undefined;
+      const filePath = params.file_path as string | undefined;
+      const algorithm = (params.algorithm as string) ?? 'sha256';
+
+      let hash: string;
+      if (filePath) {
+        const abs = resolve(filePath);
+        if (!existsSync(abs)) return { success: false, error: `文件不存在: ${abs}`, output: '' };
+        const fileContent = readFileSync(abs);
+        hash = createHash(algorithm).update(fileContent).digest('hex');
+      } else if (content) {
+        hash = createHash(algorithm).update(content, 'utf-8').digest('hex');
+      } else {
+        return { success: false, error: '请提供 content 或 file_path 参数', output: '' };
+      }
+
+      return {
+        success: true,
+        output: `${algorithm.toUpperCase()}: ${hash}`,
+        metadata: { algorithm, hash },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/security/jwt_decode.ts

@@ -0,0 +1,53 @@
+import type { Tool } from '../../tool-types.js';
+
+export const jwt_decode: Tool = {
+  name: 'jwt_decode',
+  description: '解码 JWT Token（不验证签名）',
+  category: 'security',
+  parameters: {
+    type: 'object',
+    properties: {
+      token: { type: 'string', description: 'JWT Token 字符串' },
+    },
+    required: ['token'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const token = params.token as string;
+      const parts = token.split('.');
+
+      if (parts.length !== 3) {
+        return { success: false, error: '无效的 JWT 格式（需要3部分）', output: '' };
+      }
+
+      const decodeBase64 = (str: string): string => {
+        const base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+        return Buffer.from(base64, 'base64').toString('utf-8');
+      };
+
+      const header = JSON.parse(decodeBase64(parts[0]));
+      const payload = JSON.parse(decodeBase64(parts[1]));
+
+      const output = [
+        '=== JWT Token 解码 ===',
+        '',
+        '--- Header ---',
+        JSON.stringify(header, null, 2),
+        '',
+        '--- Payload ---',
+        JSON.stringify(payload, null, 2),
+        '',
+        payload.exp ? `过期时间: ${new Date(payload.exp * 1000).toISOString()}${Date.now() > payload.exp * 1000 ? ' (已过期)' : ''}` : '',
+        payload.iat ? `签发时间: ${new Date(payload.iat * 1000).toISOString()}` : '',
+        '',
+        '注意: 签名未验证，仅解码。',
+      ].filter(Boolean).join('\n');
+
+      return { success: true, output, metadata: { ...header, sub: payload.sub } };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/security/secret_scan.ts

@@ -0,0 +1,82 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Tool } from '../../tool-types.js';
+
+export const secret_scan: Tool = {
+  name: 'secret_scan',
+  description: '扫描代码中的密钥和敏感信息',
+  category: 'security',
+  parameters: {
+    type: 'object',
+    properties: {
+      dir_path: { type: 'string', description: '扫描目录' },
+      file_path: { type: 'string', description: '扫描文件' },
+      max_results: { type: 'number', description: '最大结果数' },
+    },
+    required: [],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const dirPath = params.dir_path as string | undefined;
+      const filePath = params.file_path as string | undefined;
+      const maxResults = (params.max_results as number) ?? 100;
+
+      const patterns: [string, RegExp][] = [
+        ['API Key', /(?:api[_-]?key|apikey|api[_-]?secret)\s*[:=]\s*['"]([^'"]+)['"]/gi],
+        ['Password', /(?:password|passwd|pwd)\s*[:=]\s*['"]([^'"]+)['"]/gi],
+        ['Token', /(?:token|jwt|bearer)\s*[:=]\s*['"]([^'"]+)['"]/gi],
+        ['Secret', /(?:secret|secret[_-]key)\s*[:=]\s*['"]([^'"]+)['"]/gi],
+        ['Private Key', /-----BEGIN\s+(?:RSA|EC|DSA|OPENSSH)\s+PRIVATE\s+KEY-----/g],
+        ['AWS Key', /(?:AKIA[0-9A-Z]{16})/g],
+        ['GitHub Token', /(?:gh[pousr]_[A-Za-z0-9_]{36,})/g],
+      ];
+
+      const fg = await import('fast-glob');
+      let files: string[];
+      if (filePath) {
+        files = [resolve(filePath)];
+      } else {
+        const target = dirPath ? resolve(dirPath) : process.cwd();
+        files = await fg.default('**/*.{ts,js,tsx,jsx,py,yml,yaml,json,env,properties,xml,toml}', {
+          cwd: target,
+          absolute: true,
+          ignore: ['node_modules/**', '.git/**', 'dist/**'],
+          onlyFiles: true,
+        });
+      }
+
+      const results: string[] = [];
+      for (const fp of files.slice(0, 500)) {
+        if (results.length >= maxResults) break;
+        try {
+          const stat = await import('node:fs').then(m => m.statSync(fp));
+          if (stat.size > 1048576) continue;
+          const content = readFileSync(fp, 'utf-8');
+          for (const [type, regex] of patterns) {
+            regex.lastIndex = 0;
+            let match;
+            while ((match = regex.exec(content)) !== null && results.length < maxResults) {
+              const line = content.slice(0, match.index).split('\n').length;
+              const redacted = match[0].replace(/[:=]\s*['"][^'"]+/g, '=****');
+              results.push(`${fp}:${line}: [${type}] ${redacted.slice(0, 120)}`);
+            }
+          }
+        } catch { /* skip */ }
+      }
+
+      const output = results.length > 0
+        ? `发现 ${results.length} 个疑似敏感信息:\n\n${results.join('\n')}\n\n建议立即处理这些信息！`
+        : '未发现疑似敏感信息';
+
+      return {
+        success: true,
+        output,
+        metadata: { count: results.length, scanned: files.length },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

package/src/tools/builtin/security/vulnerability_check.ts

@@ -0,0 +1,71 @@
+import { execSync } from 'node:child_process';
+import type { Tool } from '../../tool-types.js';
+
+export const vulnerability_check: Tool = {
+  name: 'vulnerability_check',
+  description: '检查项目依赖漏洞 (npm audit)',
+  category: 'security',
+  parameters: {
+    type: 'object',
+    properties: {
+      project_path: { type: 'string', description: '项目路径' },
+    },
+    required: [],
+  },
+  dangerous: false,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const projectPath = params.project_path as string | undefined;
+      const cwd = projectPath ?? process.cwd();
+
+      try {
+        const output = execSync('npm audit --json', {
+          cwd,
+          encoding: 'utf-8',
+          timeout: 120000,
+          stdio: 'pipe',
+        });
+        const audit = JSON.parse(output);
+        const vulns = audit.vulnerabilities || {};
+
+        const summary = [
+          `漏洞扫描结果:`,
+          `发现 ${Object.keys(vulns).length} 个漏洞`,
+          '',
+          '操作建议:',
+          '  npm audit fix     # 自动修复（不破坏性更改）',
+          '  npm audit fix --force  # 强制修复（可能包含破坏性更改）',
+          '  npm audit         # 查看详细报告',
+        ].join('\n');
+
+        return {
+          success: true,
+          output: summary,
+          metadata: { vulnerabilityCount: Object.keys(vulns).length },
+        };
+      } catch (err: unknown) {
+        const e = err as { stdout?: string };
+        if (e.stdout) {
+          try {
+            const audit = JSON.parse(e.stdout);
+            const vulns = audit.vulnerabilities || {};
+            return {
+              success: false,
+              error: `发现 ${Object.keys(vulns).length} 个漏洞`,
+              output: `运行 'npm audit' 查看详情，或 'npm audit fix' 自动修复。`,
+              metadata: { vulnerabilityCount: Object.keys(vulns).length },
+            };
+          } catch { /* fall through */ }
+        }
+        return {
+          success: false,
+          error: 'npm audit 执行失败',
+          output: String(err),
+        };
+      }
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

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

@@ -0,0 +1,38 @@
+import { startBgProcess } from './process-pool.js';
+import type { Tool } from '../../tool-types.js';
+
+export const background_terminal: Tool = {
+  name: 'background_terminal',
+  description: '在后台终端中运行持久进程 (npm run dev, 服务器等)。启动后立即返回，可用 read_terminal 查看输出、list_terminals 查看状态、kill_terminal 终止。',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: '要运行的命令，如 npm run dev' },
+      cwd: { type: 'string', description: '工作目录' },
+      terminal_id: { type: 'string', description: '终端标识 (可选，自动生成)' },
+      env: { type: 'object', description: '额外环境变量' },
+    },
+    required: ['command'],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const command = params.command as string;
+      const cwd = params.cwd as string | undefined;
+      const terminalId = params.terminal_id as string | undefined;
+      const env = params.env as Record<string, string> | undefined;
+
+      const { terminalId: tid, pid } = startBgProcess({ command, cwd, terminalId, env });
+
+      return {
+        success: true,
+        output: `后台终端已启动\n  ID: ${tid}\n  PID: ${pid}\n  命令: ${command}\n  目录: ${cwd || process.cwd()}\n\n启动后等待 1-2 秒即可用 read_terminal 查看输出。`,
+        metadata: { terminalId: tid, pid },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

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

@@ -0,0 +1,48 @@
+import { runningProcesses } from './run_async.js';
+import type { Tool } from '../../tool-types.js';
+
+export const check_status: Tool = {
+  name: 'check_status',
+  description: '检查异步命令的执行状态',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: '任务标识' },
+      show_all: { type: 'boolean', description: '显示所有运行中的任务' },
+    },
+    required: [],
+  },
+  dangerous: false,
+  requiresApproval: false,
+  async execute(params) {
+    try {
+      const taskId = params.task_id as string | undefined;
+      const showAll = (params.show_all as boolean) ?? false;
+
+      if (showAll || !taskId) {
+        const tasks = Array.from(runningProcesses.keys());
+        return {
+          success: true,
+          output: tasks.length > 0
+            ? `运行中的任务 (${tasks.length}):\n${tasks.map(t => `  - ${t}`).join('\n')}`
+            : '没有运行中的任务',
+          metadata: { tasks },
+        };
+      }
+
+      const proc = runningProcesses.get(taskId);
+      if (!proc) {
+        return { success: false, error: `任务不存在或已完成: ${taskId}`, output: '' };
+      }
+
+      return {
+        success: true,
+        output: `任务 "${taskId}" 正在运行 (PID: ${proc.pid ?? 'unknown'})`,
+        metadata: { taskId, pid: proc.pid, running: true },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};

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

@@ -0,0 +1,31 @@
+import type { Tool } from '../../tool-types.js';
+
+export const interactive_terminal: Tool = {
+  name: 'interactive_terminal',
+  description: '启动交互式终端会话（在当前 CLI 环境中限制使用）',
+  category: 'shell',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: '要运行的交互式命令' },
+      terminal_id: { type: 'string', description: '终端标识' },
+    },
+    required: ['command'],
+  },
+  dangerous: true,
+  requiresApproval: true,
+  async execute(params) {
+    try {
+      const command = params.command as string;
+      const terminalId = (params.terminal_id as string) ?? `interactive_${Date.now()}`;
+
+      return {
+        success: true,
+        output: `交互式终端请求已记录: ${terminalId}\n命令: ${command}\n\n注意: 当前运行在非交互式环境，建议使用 background_terminal 运行此命令。`,
+        metadata: { terminalId, command, interactive: false },
+      };
+    } catch (err: unknown) {
+      return { success: false, error: (err as Error).message, output: '' };
+    }
+  },
+};