aegiscode 3.1.7 → 3.1.10

package/src/tools/schemas.ts

@@ -0,0 +1,109 @@
+/**
+ * 
+ * 
+ * 
+ */
+
+import { z } from 'zod';
+
+/**
+ * 
+ */
+export const ToolSchemas = {
+  /**
+   * 
+   */
+  filePath: (options?: { description?: string }) =>
+    z.string()
+      .min(1, '文件路径不能为空')
+      .describe(options?.description || '文件路径'),
+
+  /**
+   * 
+   */
+  absolutePath: (options?: { description?: string }) =>
+    z.string()
+      .min(1, '路径不能为空')
+      .refine(
+        (path) => path.startsWith('/') || path.startsWith('~'),
+        '必须是绝对路径（以 / 或 ~ 开头）'
+      )
+      .describe(options?.description || '绝对路径'),
+
+  /**
+   * 
+   */
+  lineNumber: (options?: { description?: string }) =>
+    z.number()
+      .int('必须是整数')
+      .min(0, '行号不能为负')
+      .describe(options?.description || '行号（从 0 开始）'),
+
+  /**
+   * 
+   */
+  lineLimit: (options?: { description?: string; max?: number }) =>
+    z.number()
+      .int('必须是整数')
+      .min(1, '至少读取 1 行')
+      .max(options?.max || 10000, `最多读取 ${options?.max || 10000} 行`)
+      .describe(options?.description || '读取行数'),
+
+  /**
+   * 
+   */
+  encoding: () =>
+    z.enum(['utf8', 'utf-8', 'ascii', 'base64', 'binary', 'hex'])
+      .default('utf8')
+      .describe('文件编码格式'),
+
+  /**
+   * Glob 模式
+   */
+  globPattern: (options?: { description?: string }) =>
+    z.string()
+      .min(1, '模式不能为空')
+      .describe(options?.description || 'Glob 匹配模式'),
+
+  /**
+   * 
+   */
+  regexPattern: (options?: { description?: string }) =>
+    z.string()
+      .min(1, '模式不能为空')
+      .describe(options?.description || '正则表达式模式'),
+
+  /**
+   * 
+   */
+  command: (options?: { description?: string }) =>
+    z.string()
+      .min(1, '命令不能为空')
+      .describe(options?.description || 'Shell 命令'),
+
+  /**
+   * 
+   */
+  timeout: (options?: { max?: number; default?: number }) =>
+    z.number()
+      .int()
+      .min(0)
+      .max(options?.max || 600000)
+      .default(options?.default || 30000)
+      .describe('超时时间（毫秒）'),
+
+  /**
+   * 
+   */
+  booleanWithDefault: (defaultValue: boolean, description?: string) =>
+    z.boolean()
+      .default(defaultValue)
+      .describe(description || '布尔选项'),
+};
+
+/**
+ * 
+ */
+export function optional<T extends z.ZodType>(schema: T): z.ZodOptional<T> {
+  return schema.optional();
+}

package/src/tools/test.ts

@@ -0,0 +1,220 @@
+/**
+ * 
+ * 
+ * 
+ */
+
+import { ToolRegistry, getBuiltinTools, ToolKind, createTool } from './index.js';
+import { z } from 'zod';
+import path from 'path';
+import fs from 'fs/promises';
+import os from 'os';
+
+async function testToolSystem() {
+  console.log('=== 工具系统测试 ===\n');
+
+  // 1. 创建注册表并注册内置工
+  console.log('1. 创建工具注册表并注册内置工具');
+  const registry = new ToolRegistry();
+  const builtinTools = getBuiltinTools();
+  registry.registerAll(builtinTools);
+  console.log(`   已注册 ${registry.size} 个工具: ${registry.getNames().join(', ')}`);
+  console.log(`   - 内置工具: ${registry.builtinSize}`);
+  console.log(`   - MCP 工具: ${registry.mcpSize}\n`);
+
+  // 2. 测试工具获
+  console.log('2. 测试工具获取');
+  const readTool = registry.get('Read');
+  console.log(`   Read 工具: ${readTool ? '✅ 存在' : '❌ 不存在'}`);
+  console.log(`   - 类型: ${readTool?.kind}`);
+  console.log(`   - 只读: ${readTool?.isReadOnly}`);
+  console.log(`   - 并发安全: ${readTool?.isConcurrencySafe}`);
+  console.log(`   - 分类: ${readTool?.category}`);
+  console.log(`   - 标签: ${readTool?.tags.join(', ')}\n`);
+
+  // 3. 测试只
+  console.log('3. 测试只读/写入工具过滤');
+  const readOnlyTools = registry.getReadOnlyTools();
+  const writeTools = registry.getWriteTools();
+  console.log(`   只读工具: ${readOnlyTools.map(t => t.name).join(', ')}`);
+  console.log(`   写入工具: ${writeTools.map(t => t.name).join(', ')}\n`);
+
+  // 4. 测试函数声明生
+  console.log('4. 测试函数声明生成');
+  const declarations = registry.getFunctionDeclarations();
+  for (const decl of declarations) {
+    console.log(`   ${decl.name}:`);
+    console.log(`     描述: ${decl.description.slice(0, 60)}...`);
+    console.log(`     参数: ${Object.keys(decl.parameters.properties || {}).join(', ')}`);
+  }
+  console.log();
+
+  // 5. 测试 Plan 模式函数声
+  console.log('5. 测试 Plan 模式函数声明');
+  const planDeclarations = registry.getFunctionDeclarationsByMode('plan');
+  console.log(`   Plan 模式工具数: ${planDeclarations.length}`);
+  console.log(`   Plan 模式工具: ${planDeclarations.map(d => d.name).join(', ')}\n`);
+
+  // 6. 测试 Read 工具执
+  console.log('6. 测试 Read 工具执行');
+  if (readTool) {
+    const packageJsonPath = path.join(process.cwd(), 'package.json');
+    const result = await readTool.execute({ file_path: packageJsonPath });
+    console.log(`   结果: ${result.success ? '✅ 成功' : '❌ 失败'}`);
+    console.log(`   显示内容: ${result.displayContent}`);
+    console.log(`   LLM 内容长度: ${result.llmContent.length} 字符\n`);
+  }
+
+  // 7. 测试 Edit 工
+  console.log('7. 测试 Edit 工具');
+  const editTool = registry.get('Edit');
+  if (editTool) {
+    // 创建临时文
+    const tmpDir = os.tmpdir();
+    const testFile = path.join(tmpDir, `aegis-test-${Date.now()}.txt`);
+    await fs.writeFile(testFile, 'Hello World\nFoo Bar\n', 'utf8');
+    
+    // 测试编
+    const result = await editTool.execute({
+      file_path: testFile,
+      old_string: 'World',
+      new_string: 'AEGIS',
+    });
+    console.log(`   结果: ${result.success ? '✅ 成功' : '❌ 失败'}`);
+    console.log(`   显示内容: ${result.displayContent}`);
+    
+    // 验证内
+    const content = await fs.readFile(testFile, 'utf8');
+    console.log(`   验证: ${content.includes('AEGIS') ? '✅ 替换正确' : '❌ 替换失败'}`);
+    
+    // 测试多重匹
+    await fs.writeFile(testFile, 'AAA BBB AAA', 'utf8');
+    const multiResult = await editTool.execute({
+      file_path: testFile,
+      old_string: 'AAA',
+      new_string: 'CCC',
+    });
+    console.log(`   多重匹配: ${multiResult.success ? '❌ 应该失败' : '✅ 正确拒绝'}`);
+    
+    // 清
+    await fs.unlink(testFile);
+    console.log();
+  }
+
+  // 8. 测试 Write 工
+  console.log('8. 测试 Write 工具');
+  const writeTool = registry.get('Write');
+  if (writeTool) {
+    const tmpDir = os.tmpdir();
+    const testFile = path.join(tmpDir, `aegis-write-${Date.now()}.txt`);
+    
+    const result = await writeTool.execute({
+      file_path: testFile,
+      contents: 'Test content\nLine 2\n',
+    });
+    console.log(`   结果: ${result.success ? '✅ 成功' : '❌ 失败'}`);
+    console.log(`   显示内容: ${result.displayContent}`);
+    
+    // 验
+    const exists = await fs.access(testFile).then(() => true).catch(() => false);
+    console.log(`   文件存在: ${exists ? '✅ 是' : '❌ 否'}`);
+    
+    // 清
+    if (exists) await fs.unlink(testFile);
+    console.log();
+  }
+
+  // 9. 测试 Bash 工
+  console.log('9. 测试 Bash 工具');
+  const bashTool = registry.get('Bash');
+  if (bashTool) {
+    const result = await bashTool.execute({
+      command: 'echo "Hello from Bash"',
+      description: '测试 echo 命令',
+    });
+    console.log(`   结果: ${result.success ? '✅ 成功' : '❌ 失败'}`);
+    console.log(`   显示内容: ${result.displayContent}`);
+    console.log(`   输出: ${result.llmContent.trim()}`);
+    
+    // 测试失败命
+    const failResult = await bashTool.execute({
+      command: 'exit 1',
+    });
+    console.log(`   失败命令: ${failResult.success ? '❌ 应该失败' : '✅ 正确失败'}\n`);
+  }
+
+  // 10. 测试 Glob 工具执
+  console.log('10. 测试 Glob 工具执行');
+  const globTool = registry.get('Glob');
+  if (globTool) {
+    const result = await globTool.execute({ pattern: '*.ts', path: path.join(process.cwd(), 'src') });
+    console.log(`   结果: ${result.success ? '✅ 成功' : '❌ 失败'}`);
+    console.log(`   显示内容: ${result.displayContent}`);
+    if (result.metadata?.count) {
+      console.log(`   找到文件数: ${result.metadata.count}\n`);
+    }
+  }
+
+  // 11. 测试 Grep 工具执
+  console.log('11. 测试 Grep 工具执行');
+  const grepTool = registry.get('Grep');
+  if (grepTool) {
+    const result = await grepTool.execute({ 
+      pattern: 'export', 
+      include: '*.ts',
+      path: path.join(process.cwd(), 'src/tools'),
+    });
+    console.log(`   结果: ${result.success ? '✅ 成功' : '❌ 失败'}`);
+    console.log(`   显示内容: ${result.displayContent}`);
+    if (result.metadata?.matches) {
+      console.log(`   匹配数: ${result.metadata.matches}\n`);
+    }
+  }
+
+  // 12. 测试 MCP 工具注
+  console.log('12. 测试 MCP 工具注册');
+  const mockMcpTool = createTool({
+    name: 'MockMcpTool',
+    displayName: 'Mock MCP Tool',
+    kind: ToolKind.ReadOnly,
+    schema: z.object({ input: z.string() }),
+    description: { short: 'A mock MCP tool for testing' },
+    async execute(params) {
+      return {
+        success: true,
+        llmContent: `Mock result for: ${params.input}`,
+        displayContent: '✅ Mock MCP 工具执行成功',
+      };
+    },
+  });
+  
+  registry.registerMcpTool(mockMcpTool);
+  console.log(`   MCP 工具注册: ✅`);
+  console.log(`   总工具数: ${registry.size}`);
+  console.log(`   MCP 工具数: ${registry.mcpSize}`);
+  console.log(`   获取 MCP 工具: ${registry.get('MockMcpTool') ? '✅ 存在' : '❌ 不存在'}`);
+  
+  // 测试注
+  registry.unregisterMcpTool('MockMcpTool');
+  console.log(`   注销后: ${registry.get('MockMcpTool') ? '❌ 仍存在' : '✅ 已移除'}\n`);
+
+  // 13. 测试 build 方
+  console.log('13. 测试 build 方法');
+  if (readTool) {
+    const invocation = readTool.build({ file_path: '/test/path.ts' });
+    console.log(`   工具名: ${invocation.toolName}`);
+    console.log(`   参数: ${JSON.stringify(invocation.params)}\n`);
+  }
+
+  // 14. 测试参数验
+  console.log('14. 测试参数验证');
+  if (readTool) {
+    const invalidResult = await readTool.execute({ file_path: '' });
+    console.log(`   空路径测试: ${invalidResult.success ? '❌ 应该失败' : '✅ 正确失败'}`);
+    console.log(`   错误信息: ${invalidResult.displayContent}\n`);
+  }
+
+  console.log('=== 测试完成 ===');
+}
+
+testToolSystem().catch(console.error);

package/src/tools/types.ts

@@ -0,0 +1,175 @@
+/**
+ * 
+ */
+
+// ========== 工具类型枚
+
+/**
+ * 
+ * 
+ */
+export enum ToolKind {
+  /** 只读操作，无副作用 */
+  ReadOnly = 'readonly',
+  /** 文件写入操作 */
+  Write = 'write',
+  /** 命令执行，可能有副作用 */
+  Execute = 'execute',
+}
+
+// ========== 工具描
+
+/**
+ * 
+ */
+export interface ToolExample {
+  description: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * 
+ */
+export interface ToolDescription {
+  /** 简短描述（一行） */
+  short: string;
+  /** 详细说明 */
+  long?: string;
+  /** 使用注意事项 */
+  usageNotes?: string[];
+  /** 使用示例 */
+  examples?: ToolExample[];
+  /** 重要提示 */
+  important?: string[];
+}
+
+// ========== 工具错
+
+/**
+ * 
+ */
+export enum ToolErrorType {
+  /** 参数验证错误 */
+  VALIDATION_ERROR = 'validation_error',
+  /** 执行错误 */
+  EXECUTION_ERROR = 'execution_error',
+  /** 权限错误 */
+  PERMISSION_ERROR = 'permission_error',
+  /** 超时错误 */
+  TIMEOUT_ERROR = 'timeout_error',
+  /** 未知错误 */
+  UNKNOWN_ERROR = 'unknown_error',
+}
+
+/**
+ * 
+ */
+export interface ToolError {
+  type: ToolErrorType;
+  message: string;
+  details?: unknown;
+}
+
+// ========== 工具结
+
+/**
+ * 
+ */
+export interface ToolResult {
+  /** 执行是否成功 */
+  success: boolean;
+  /** 传递给 LLM 的内容（可能很长） */
+  llmContent: string;
+  /** 显示给用户的内容（简洁摘要） */
+  displayContent: string;
+  /** 错误信息 */
+  error?: ToolError;
+  /** 额外元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+// ========== 执行上下
+
+/**
+ * 
+ */
+export interface ExecutionContext {
+  /** 会话 ID */
+  sessionId?: string;
+  /** 中断信号 */
+  signal?: AbortSignal;
+  /** 工作目录 */
+  cwd?: string;
+}
+
+// ========== 函数声
+
+/**
+ * LLM 函数声明（OpenAI 格式）
+ */
+export interface FunctionDeclaration {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+// ========== 工具调
+
+/**
+ * 
+ */
+export interface ToolInvocation<TParams = unknown> {
+  /** 工具名称 */
+  toolName: string;
+  /** 参数 */
+  params: TParams;
+  /** 调用 ID */
+  callId?: string;
+}
+
+// ========== 工具接
+
+/**
+ * 
+ */
+export interface Tool<TParams = unknown> {
+  /** 工具唯一名称 */
+  readonly name: string;
+  /** 显示名称 */
+  readonly displayName: string;
+  /** 工具类型 */
+  readonly kind: ToolKind;
+  /** 是否只读 */
+  readonly isReadOnly: boolean;
+  /** 是否并发安全 */
+  readonly isConcurrencySafe: boolean;
+  /** 是否启用结构化输出 */
+  readonly strict: boolean;
+  /** 工具描述 */
+  readonly description: ToolDescription;
+  /** 版本 */
+  readonly version: string;
+  /** 分类 */
+  readonly category?: string;
+  /** 标签 */
+  readonly tags: string[];
+
+  /** 生成 LLM 函数声明 */
+  getFunctionDeclaration(): FunctionDeclaration;
+
+  /** 构建执行实例 */
+  build(params: TParams): ToolInvocation<TParams>;
+
+  /** 执行工具 */
+  execute(params: TParams, context?: ExecutionContext): Promise<ToolResult>;
+
+  /** 提取签名内容（用于权限规则） */
+  extractSignatureContent?: (params: unknown) => string;
+
+  /** 抽象权限规则（用于权限匹配） */
+  abstractPermissionRule?: (params: unknown) => string;
+}