@cicctencent/agent-core 0.1.1 → 0.1.3

package/src/tool/delegate.ts

@@ -1,105 +0,0 @@
-// ============================================================
-// DelegateTool — 任务分发工具（默认 Agent 将子任务委托给专业 Agent）
-// ============================================================
-
-import type { RegisteredTool, ToolContext } from './types.ts';
-import type { StructuredAgentOutput, WorkflowRole } from '../agent/workflow.ts';
-
-/**
- * 子 Agent 执行器接口
- * 由上层（agent.service.ts）实现，Core 层只定义接口
- */
-export interface SubAgentRunOptions {
-  role?: WorkflowRole | string;
-  structured?: boolean;
-}
-
-export interface SubAgentRunResult {
-  content: string;
-  structured?: StructuredAgentOutput;
-}
-
-export type SubAgentRunResponse = string | SubAgentRunResult;
-
-export interface SubAgentRunner {
-  /** 子 Agent 的标识名（用于 LLM 选择） */
-  name: string;
-  /** 子 Agent 的领域描述（用于 LLM 理解其能力） */
-  description: string;
-  /** 执行子任务，返回结果文本或结构化结果 */
-  run(task: string, context: ToolContext, options?: SubAgentRunOptions): Promise<SubAgentRunResponse>;
-}
-
-/**
- * 创建 delegate_task 工具
- *
- * 根据可用的子 Agent 列表动态生成工具定义：
- * - LLM 会看到所有子 Agent 的 name + description，据此选择分发目标
- * - executor 根据 LLM 选择的 agent name 调用对应的 SubAgentRunner
- *
- * @param runners 可用的子 Agent 列表（由上层注入）
- */
-export function createDelegateTool(runners: SubAgentRunner[]): RegisteredTool | null {
-  if (runners.length === 0) return null;
-
-  // 动态生成 agent 参数的 enum 和描述
-  const agentOptions = runners.map(r => r.name);
-  const agentDescriptions = runners
-    .map(r => `  - ${r.name}: ${r.description}`)
-    .join('\n');
-
-  return {
-    definition: {
-      type: 'function',
-      function: {
-        name: 'delegate_task',
-        description: `Delegate a complex task to a specialized agent. Use smart routing: delegate for complex/domain tasks (multi-step analysis, specialized output), handle directly for simple queries (single data point, general chat). Specialists have optimized prompts, curated tools, and domain skills. Available agents:\n${agentDescriptions}`,
-        parameters: {
-          type: 'object',
-          properties: {
-            agent: {
-              type: 'string',
-              description: `The specialist agent to delegate to. Available: ${agentOptions.join(', ')}`,
-              enum: agentOptions,
-            },
-            task: {
-              type: 'string',
-              description: 'A clear, self-contained description of the subtask. KEEP UNDER 2000 chars. For longer tasks: write details to a file first (write_file), then reference it: "Read task_brief.md and execute..."',
-            },
-            role: {
-              type: 'string',
-              description: 'Optional workflow role for this delegation, such as researcher, implementer, reviewer, critic, risk_checker, or final_approver',
-              enum: ['researcher', 'implementer', 'reviewer', 'critic', 'risk_checker', 'final_approver'],
-            },
-            structured: {
-              type: 'boolean',
-              description: 'Set true when the result should include structured findings, risks, recommendation, confidence, and next_actions',
-            },
-          },
-          required: ['agent', 'task'],
-        },
-      },
-    },
-    executor: async (args, ctx): Promise<string> => {
-      const agentName = args.agent as string;
-      const task = args.task as string;
-      const role = args.role as WorkflowRole | string | undefined;
-      const structured = args.structured === true;
-
-      const runner = runners.find(r => r.name === agentName);
-      if (!runner) {
-        return `Error: Agent "${agentName}" not found. Available agents: ${agentOptions.join(', ')}`;
-      }
-
-      try {
-        const result = await runner.run(task, ctx, { role, structured });
-        return typeof result === 'string' ? result : result.content;
-      } catch (err: any) {
-        return `Error delegating to ${agentName}: ${err.message || err}`;
-      }
-    },
-    category: 'builtin',
-    concurrent: true,  // 支持 LLM 同一轮并行调用多个 delegate_task
-    metadata: { type: 'delegate', agentCount: runners.length },
-  };
-}

package/src/tool/registry.ts

@@ -1,64 +0,0 @@
-// ============================================================
-// ToolRegistry — 统一工具注册表
-// ============================================================
-
-import type { ToolDefinition, ToolExecutor, ToolContext, RegisteredTool, ToolCategory } from './types.ts';
-
-export class ToolRegistry {
-  private tools = new Map<string, RegisteredTool>();
-
-  /** 注册工具 */
-  register(tool: RegisteredTool): void {
-    const name = tool.definition.function.name;
-    this.tools.set(name, tool);
-  }
-
-  /** 批量注册 */
-  registerAll(tools: RegisteredTool[]): void {
-    for (const tool of tools) {
-      this.register(tool);
-    }
-  }
-
-  /** 注销工具 */
-  unregister(name: string): void {
-    this.tools.delete(name);
-  }
-
-  /** 获取指定工具 */
-  get(name: string): RegisteredTool | undefined {
-    return this.tools.get(name);
-  }
-
-  /** 获取所有工具定义（传给 LLM） */
-  getDefinitions(filter?: { category?: ToolCategory; names?: string[] }): ToolDefinition[] {
-    let tools = [...this.tools.values()];
-
-    if (filter?.category) {
-      tools = tools.filter((t) => t.category === filter.category);
-    }
-    if (filter?.names && filter.names.length > 0) {
-      const nameSet = new Set(filter.names);
-      tools = tools.filter((t) => nameSet.has(t.definition.function.name));
-    }
-
-    return tools.map((t) => t.definition);
-  }
-
-  /** 执行工具（内部调用，AgentEngine 使用） */
-  async execute(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<string> {
-    const tool = this.tools.get(name);
-    if (!tool) throw new Error(`Unknown tool: ${name}`);
-    return tool.executor(args, ctx);
-  }
-
-  /** 列出所有已注册工具名称 */
-  listNames(): string[] {
-    return [...this.tools.keys()];
-  }
-
-  /** 检查工具是否存在 */
-  has(name: string): boolean {
-    return this.tools.has(name);
-  }
-}

package/src/tool/types.ts

@@ -1,124 +0,0 @@
-// ============================================================
-// Tool Registry 类型定义
-// ============================================================
-
-import type { EnvInfo } from '../context/types.ts';
-
-// ---- ToolDefinition（OpenAI Function Calling 格式）----
-
-export interface ToolDefinition {
-  type: 'function';
-  function: {
-    name: string;
-    description: string;
-    parameters: {
-      type: 'object';
-      properties: Record<
-        string,
-        {
-          type: string;
-          description: string;
-          enum?: string[];
-          items?: unknown;
-          [key: string]: unknown;
-        }
-      >;
-      required?: string[];
-    };
-  };
-}
-
-// ---- ToolExecutor / ToolContext ----
-
-/** Shell 执行器接口（上层提供 SSH / local PTY 实现） */
-export interface ShellExecutor {
-  exec(command: string, timeout?: number): Promise<string>;
-  write(data: string): void;
-  read(lines?: number): string;
-}
-
-/** 文件系统执行器接口 */
-export interface FileSystemExecutor {
-  readFile(path: string): Promise<string>;
-  /** 读取二进制文件（可选实现，用于 PDF/图片等二进制 Artifact） */
-  readFileBuffer?(path: string): Promise<Buffer>;
-  writeFile(path: string, content: string): Promise<void>;
-  /** 追加内容到文件（文件不存在则创建） */
-  appendFile?(path: string, content: string): Promise<void>;
-  listDir(path: string): Promise<string[]>;
-}
-
-/** 子 Agent 事件转发回调（由上层 SSE 流注入） */
-export type SubAgentEventEmitter = (event: {
-  /** 父级 delegate_task 的 callId */
-  parentToolCallId: string;
-  /** 子 Agent 名称 */
-  agentName: string;
-  /** 子 Agent 事件类型 */
-  eventType: string;
-  /** 事件数据 */
-  data: Record<string, unknown>;
-}) => void;
-
-/** Widget 事件发射回调（由上层 SSE 流注入，供 show_widget 工具使用） */
-export type WidgetEventEmitter = (event: {
-  widgetId: string;
-  html: string;
-  title: string;
-  height?: number;
-}) => void;
-
-/** 文件 Artifact 数据（由 save_artifact 工具生成，前端用于展示/下载） */
-export interface ArtifactData {
-  artifactId: string;
-  filename: string;
-  mimeType: string;
-  size: number;
-  /** HTTP URL 用于下载或预览 */
-  url: string;
-  description?: string;
-}
-
-/** Artifact 事件发射回调（由上层 SSE 流注入，供 save_artifact 工具使用） */
-export type ArtifactEventEmitter = (artifact: ArtifactData) => void;
-
-/** 工具执行上下文（由 AgentEngine 注入） */
-export interface ToolContext {
-  sessionId: string;
-  /** Shell 执行能力（上层提供 SSH / local PTY 实现） */
-  shell: ShellExecutor;
-  /** 文件系统操作能力 */
-  fs?: FileSystemExecutor;
-  /** 环境信息 */
-  env?: EnvInfo;
-  /** 中止信号 */
-  abortSignal: AbortSignal;
-  /** 上层注入的自定义能力 */
-  custom?: Record<string, unknown>;
-  /** 子 Agent 事件转发（由 runAgentStream 注入，delegate_task 使用） */
-  emitSubEvent?: SubAgentEventEmitter;
-  /** Widget 事件发射（由 runAgentStream 注入，show_widget 使用） */
-  emitWidget?: WidgetEventEmitter;
-  /** Artifact 事件发射（由 runAgentStream 注入，save_artifact 使用） */
-  emitArtifact?: ArtifactEventEmitter;
-  /** 当前工具调用的 callId（由引擎注入） */
-  currentToolCallId?: string;
-}
-
-/** 工具执行器签名 */
-export type ToolExecutor = (args: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
-
-// ---- RegisteredTool ----
-
-export type ToolCategory = 'builtin' | 'skill' | 'mcp' | 'custom';
-
-export interface RegisteredTool {
-  definition: ToolDefinition;
-  executor: ToolExecutor;
-  /** 工具分类 */
-  category?: ToolCategory;
-  /** 扩展元数据（如 MCP server name） */
-  metadata?: Record<string, unknown>;
-  /** 是否可与其他工具并行执行（默认 false） */
-  concurrent?: boolean;
-}

package/src/types.ts

@@ -1,188 +0,0 @@
-// ============================================================
-// Core 全局共享类型
-// ============================================================
-
-// ---- Message — LLM 消息（兼容 OpenAI Chat Completion 格式）----
-
-/** 消息角色 */
-export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
-
-/** LLM 发起的工具调用 */
-export interface ToolCall {
-  id: string;
-  type: 'function';
-  function: {
-    name: string;
-    arguments: string; // JSON string
-  };
-}
-
-/** LLM 消息 */
-export interface Message {
-  role: MessageRole;
-  content: string | null;
-  /** assistant 消息中的工具调用请求 */
-  tool_calls?: ToolCall[];
-  /** tool 消息对应的 tool_call id */
-  tool_call_id?: string;
-  /** assistant 消息的 name 字段 */
-  name?: string;
-  /** 推理/思考内容（DeepSeek R1 等模型） */
-  reasoning_content?: string | null;
-  /** 扩展字段，上层可附加任意元数据 */
-  metadata?: Record<string, unknown>;
-}
-
-// ---- AgentEvent — Agent 执行事件流（discriminated union）----
-
-/** 所有事件的公共基座 */
-export interface BaseEvent {
-  /** 事件时间戳（毫秒） */
-  timestamp: number;
-  /** 会话 ID */
-  sessionId: string;
-  /** 扩展字段 */
-  metadata?: Record<string, unknown>;
-}
-
-/** LLM 正在思考 */
-export interface ThinkingEvent extends BaseEvent {
-  type: 'thinking';
-  /** 推理文本增量（流式逐字推送） */
-  content?: string;
-}
-
-/** LLM 请求调用工具 */
-export interface ToolCallEvent extends BaseEvent {
-  type: 'tool_call';
-  tool: string;
-  args: Record<string, unknown>;
-  /** 工具调用 ID（用于关联后续的 tool_result） */
-  callId: string;
-}
-
-/** 工具执行结果 */
-export interface ToolResultEvent extends BaseEvent {
-  type: 'tool_result';
-  tool: string;
-  result: string;
-  /** 是否执行出错 */
-  isError: boolean;
-  /** 执行耗时（毫秒） */
-  duration: number;
-  callId: string;
-}
-
-/** LLM 输出文本片段（流式） */
-export interface MessageEvent extends BaseEvent {
-  type: 'message';
-  content: string;
-  /** 是否为增量片段（true=追加，false=完整替换） */
-  delta: boolean;
-}
-
-/** Agent 执行完成 */
-export interface DoneEvent extends BaseEvent {
-  type: 'done';
-  /** 最终回复文本 */
-  content: string;
-  /** 总迭代轮次 */
-  iterations: number;
-  /** LLM token 消耗统计 */
-  usage?: TokenUsage;
-}
-
-/** Agent 执行出错 */
-export interface ErrorEvent extends BaseEvent {
-  type: 'error';
-  error: string;
-  /** 是否可恢复（true 时 Agent 可能自动重试） */
-  recoverable: boolean;
-}
-
-/** Steering 消息注入事件（实时转向） */
-export interface SteeringEvent extends BaseEvent {
-  type: 'steering';
-  /** 注入的 steering 消息列表 */
-  messages: string[];
-  /** 注入的消息数量 */
-  count: number;
-}
-
-/** LLM 调用重试事件（模型韧性） */
-export interface RetryEvent extends BaseEvent {
-  type: 'retry';
-  /** 当前重试次数（从 1 开始） */
-  attempt: number;
-  /** 最大重试次数 */
-  maxRetries: number;
-  /** 本次重试等待时间（毫秒） */
-  delay: number;
-  /** 失败原因 */
-  error: string;
-  /** 当前使用的 Provider 标识 */
-  provider: string;
-}
-
-/** Agent 执行事件（discriminated union） */
-export type AgentEvent =
-  | ThinkingEvent
-  | ToolCallEvent
-  | ToolResultEvent
-  | MessageEvent
-  | DoneEvent
-  | ErrorEvent
-  | SteeringEvent
-  | RetryEvent;
-
-// ---- AgentResult — Agent 执行最终结果 ----
-
-/** Token 消耗统计 */
-export interface TokenUsage {
-  promptTokens: number;
-  completionTokens: number;
-  totalTokens: number;
-}
-
-/** 工具调用记录（审计用） */
-export interface ToolCallRecord {
-  callId: string;
-  tool: string;
-  args: Record<string, unknown>;
-  result: string;
-  isError: boolean;
-  duration: number;
-  timestamp: number;
-}
-
-/** Agent 执行最终结果 */
-export interface AgentResult {
-  status: 'completed' | 'aborted' | 'max_iterations' | 'error';
-  /** 最终回复内容 */
-  content: string;
-  /** 总迭代轮次 */
-  iterations: number;
-  /** 累计 token 消耗 */
-  usage?: TokenUsage;
-  /** 执行过程中的工具调用记录 */
-  toolCalls: ToolCallRecord[];
-  /** 总耗时（毫秒） */
-  duration: number;
-}
-
-// ---- AgentStatus — Agent 状态 ----
-
-export type AgentStatus = 'idle' | 'thinking' | 'executing_tool' | 'streaming' | 'aborting';
-
-// ---- SessionContext — 会话上下文 ----
-
-/** 会话上下文（上层构建，传给 Core） */
-export interface SessionContext {
-  sessionId: string;
-  /** 环境信息（EnvCollector 采集结果） */
-  env?: import('./context/types.ts').EnvInfo;
-  /** 终端当前输出（最近 N 行） */
-  terminalOutput?: string;
-  /** 自定义上下文（上层注入的任意数据） */
-  custom?: Record<string, unknown>;
-}

package/src/utils/token-counter.ts

@@ -1,108 +0,0 @@
-// ============================================================
-// Token 计数器 — 基于 tiktoken 的精确 token 计数
-// ============================================================
-
-import { Tiktoken, encodingForModel } from 'js-tiktoken';
-import type { Message } from '../types.ts';
-
-/** 默认编码器（cl100k_base，兼容 GPT-4 / Claude 等主流模型） */
-let encoder: Tiktoken | null = null;
-
-/**
- * LRU 缓存：避免对相同文本重复计算 token
- * 缓存容量 2000 条，命中率高时可显著减少 encode 调用
- */
-const TOKEN_CACHE_MAX = 2000;
-const tokenCache = new Map<string, number>();
-
-/**
- * 获取 tiktoken 编码器实例（延迟初始化）
- */
-function getEncoder(): Tiktoken {
-  if (!encoder) {
-    try {
-      encoder = encodingForModel('gpt-4');
-    } catch {
-      // fallback: 使用 cl100k_base 编码
-      encoder = new Tiktoken(
-        require('js-tiktoken/ranks/cl100k_base'),
-      );
-    }
-  }
-  return encoder!;
-}
-
-/**
- * 计算文本的 token 数量（带 LRU 缓存）
- * @param text 输入文本
- * @returns token 数量
- */
-export function countTokens(text: string): number {
-  if (!text) return 0;
-
-  // 缓存查找
-  const cached = tokenCache.get(text);
-  if (cached !== undefined) {
-    // LRU: 删除旧位置并在末尾重新插入
-    tokenCache.delete(text);
-    tokenCache.set(text, cached);
-    return cached;
-  }
-
-  const count = getEncoder().encode(text).length;
-
-  // 缓存写入 + 淘汰策略
-  if (tokenCache.size >= TOKEN_CACHE_MAX) {
-    // 删除最早的 entry（Map 迭代按插入顺序）
-    const oldestKey = tokenCache.keys().next().value;
-    if (oldestKey !== undefined) tokenCache.delete(oldestKey);
-  }
-  tokenCache.set(text, count);
-
-  return count;
-}
-
-/**
- * 计算消息数组的总 token 数量（含 overhead）
- * 每条消息有约 4 token 的 overhead（role 等元数据）
- * @param messages 消息列表
- * @returns 总 token 数量
- */
-export function countMessageTokens(messages: Message[]): number {
-  let total = 0;
-  for (const msg of messages) {
-    // 每条消息 overhead: role + content 分隔
-    total += 4;
-    // role
-    total += countTokens(msg.role || '');
-    // content
-    if (msg.content) {
-      total += countTokens(typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content));
-    }
-    // tool_calls (序列化后的 token 数)
-    if (msg.tool_calls) {
-      for (const tc of msg.tool_calls) {
-        total += countTokens(tc.function?.name || '');
-        total += countTokens(tc.function?.arguments || '');
-      }
-    }
-    // tool result (name + content)
-    if (msg.name) {
-      total += countTokens(msg.name);
-    }
-  }
-  // 额外 reply prefix overhead
-  total += 2;
-  return total;
-}
-
-/**
- * 估算文本 token 数（快速估算，不加载 tiktoken）
- * 适用于对精度要求不高的场景，约 4 字符 = 1 token
- * @param text 输入文本
- * @returns 估算 token 数量
- */
-export function estimateTokens(text: string): number {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
-}