@cicctencent/agent-core 0.1.1

package/src/hooks/types.ts

@@ -0,0 +1,77 @@
+// ============================================================
+// Hooks — 生命周期钩子类型定义
+// ============================================================
+
+import type { Message, TokenUsage } from '../types.ts';
+import type { ToolDefinition } from '../tool/types.ts';
+
+// ---- Hook 事件类型（7 个）----
+
+export type HookEvent =
+  | 'before_tool'        // 工具执行前（可阻止/修改参数）
+  | 'after_tool'         // 工具执行后（可注入信息到结果）
+  | 'before_ll_call'     // LLM 调用前（可审查 messages/tools）
+  | 'after_ll_call'      // LLM 调用后（可审查响应）
+  | 'on_iteration_start' // 每轮迭代开始（可注入上下文信息）
+  | 'on_error'           // 任何错误发生时
+  | 'on_complete';       // Agent Loop 完成时
+
+// ---- Hook 上下文 ----
+
+/**
+ * Hook 处理器接收的上下文信息
+ * 不同事件携带不同的字段组合
+ */
+export interface HookContext {
+  sessionId: string;
+  iteration: number;
+  traceId?: string;
+
+  // before_tool / after_tool
+  tool?: string;
+  args?: Record<string, unknown>;
+  result?: string;
+  isError?: boolean;
+  duration?: number;
+
+  // before_ll_call / after_ll_call
+  messages?: Message[];
+  tools?: ToolDefinition[];
+  response?: Message;
+
+  // on_error
+  error?: string;
+  recoverable?: boolean;
+
+  // on_complete
+  totalIterations?: number;
+  usage?: TokenUsage;
+}
+
+// ---- Hook 返回值 ----
+
+/**
+ * Hook 处理器的返回值
+ * 仅 before_tool 和 after_tool 的返回值有实际效果
+ */
+export interface HookResult {
+  /** before_tool: 阻止工具执行 */
+  block?: boolean;
+  /** block 时的原因（返回给 LLM） */
+  reason?: string;
+  /** before_tool: 修改工具参数（与原始 args 合并） */
+  modify?: Record<string, unknown>;
+  /** after_tool: 追加到工具结果末尾 */
+  inject?: string;
+}
+
+// ---- Hook 定义 ----
+
+export interface Hook {
+  /** Hook 名称（用于日志和调试） */
+  name: string;
+  /** 监听的事件类型 */
+  event: HookEvent;
+  /** 处理器函数 */
+  handler: (ctx: HookContext) => Promise<HookResult | void>;
+}

package/src/index.ts

@@ -0,0 +1,178 @@
+// ============================================================
+// Core 统一导出
+// ============================================================
+
+// ---- 全局类型 ----
+export type {
+  Message,
+  MessageRole,
+  ToolCall,
+  AgentEvent,
+  BaseEvent,
+  ThinkingEvent,
+  ToolCallEvent,
+  ToolResultEvent,
+  MessageEvent,
+  DoneEvent,
+  ErrorEvent,
+  SteeringEvent,
+  RetryEvent,
+  AgentResult,
+  AgentStatus,
+  SessionContext,
+  TokenUsage,
+  ToolCallRecord,
+} from './types.ts';
+
+// ---- Agent Engine ----
+export { AgentEngine } from './agent/engine.ts';
+export {
+  DEFAULT_COMPLEX_WORKFLOW_TEMPLATE,
+  buildDebateInstructions,
+  buildStructuredOutputInstruction,
+  buildWorkflowDecisionMemory,
+  formatDebateOutput,
+  formatStructuredAgentOutput,
+  formatWorkflowTemplateForPrompt,
+  getWorkflowRoleStage,
+  getWorkflowTemplate,
+  parseDebateOutput,
+  parseStructuredAgentOutput,
+  wrapTaskWithWorkflowInstructions,
+} from './agent/workflow.ts';
+export type { StructuredAgentOutput, WorkflowCheckpoint, WorkflowDecisionLog, WorkflowRole, WorkflowStageTemplate, WorkflowTemplate, DebateOutput } from './agent/workflow.ts';
+export { HistoryManager } from './agent/history-manager.ts';
+export { LLMCaller } from './agent/llm-caller.ts';
+export { AgentToolExecutor } from './agent/tool-executor.ts';
+export type { AgentConfig, RunOptions, RetryPolicy, ToolResultStore, OffloadEntry } from './agent/types.ts';
+
+// ---- LLM ----
+export type {
+  LLMProvider,
+  ModelConfig,
+  ModelInfo,
+  ChatParams,
+  ChatResponse,
+  ChatChunk,
+} from './llm/types.ts';
+export { OpenAIProvider } from './llm/openai-provider.ts';
+export { AnthropicProvider } from './llm/anthropic-provider.ts';
+export { OllamaProvider } from './llm/ollama-provider.ts';
+export { createLLMProvider, BUILTIN_PROVIDERS } from './llm/factory.ts';
+export type { BuiltinProvider } from './llm/factory.ts';
+
+// ---- Context ----
+export { ContextManager } from './context/manager.ts';
+export { LocalEnvCollector } from './context/collector.ts';
+export type {
+  BuildContextOptions,
+  EnvInfo,
+  EnvCollector,
+} from './context/types.ts';
+
+// ---- Skill ----
+export { SkillManager } from './skill/manager.ts';
+export { SkillRouter } from './skill/router.ts';
+export type {
+  Skill,
+  SkillManifest,
+  SkillSource,
+  RouteResult,
+  RouteStrategy,
+  MatchType,
+} from './skill/types.ts';
+
+// ---- Tool ----
+export { ToolRegistry } from './tool/registry.ts';
+export { createDelegateTool } from './tool/delegate.ts';
+export type { SubAgentRunner } from './tool/delegate.ts';
+export type {
+  ToolDefinition,
+  ToolExecutor,
+  ToolContext,
+  SubAgentEventEmitter,
+  WidgetEventEmitter,
+  ArtifactEventEmitter,
+  ArtifactData,
+  RegisteredTool,
+  ToolCategory,
+  ShellExecutor,
+  FileSystemExecutor,
+} from './tool/types.ts';
+
+// ---- MCP ----
+export { registerMCPTools, MCP_TOOL_PREFIX, buildMCPToolName, sanitizeForToolName } from './mcp/client.ts';
+export { createMCPClient, registerTransport } from './mcp/factory.ts';
+export type { TransportFactory } from './mcp/factory.ts';
+export { MCPClientBase } from './mcp/base-client.ts';
+export { StdioMCPClient } from './mcp/stdio-client.ts';
+export { HttpMCPClient } from './mcp/http-client.ts';
+export {
+  resolveProxyAgentForCategory,
+  resolveProxyUrlForCategory,
+  getSystemProxyUrl,
+  clearSystemProxyCache,
+  getWindowsSystemProxy,
+  DEFAULT_PROXY_SETTINGS,
+} from './mcp/proxy-agent.ts';
+export type {
+  ProxyMode,
+  ProxyCategoryConfig,
+  ProxySettings,
+} from './mcp/proxy-agent.ts';
+export type {
+  MCPClient,
+  MCPServerConfig,
+  MCPTransport,
+} from './mcp/types.ts';
+
+// ---- Security ----
+export { SecurityGuard } from './security/guard.ts';
+export type {
+  SanitizeResult,
+  SecurityRule,
+  SecurityPolicy,
+  Severity,
+} from './security/types.ts';
+
+// ---- Sandbox ----
+export type {
+  Sandbox,
+  SandboxConfig,
+  SandboxManager,
+  ScriptLanguage,
+} from './sandbox/types.ts';
+export { SANDBOX_BLOCKED_COMMANDS, SANDBOX_SAFE_ENV_KEYS, DEFAULT_SANDBOX_CONFIG } from './sandbox/types.ts';
+
+// ---- Hooks ----
+export type {
+  Hook,
+  HookEvent,
+  HookContext,
+  HookResult,
+} from './hooks/types.ts';
+
+// ---- Middleware ----
+export type {
+  Middleware,
+  MiddlewareContext,
+} from './middleware/types.ts';
+
+// ---- Memory ----
+export type {
+  MemoryEntry,
+  MemoryLayer,
+  MemoryServiceLike,
+} from './memory/types.ts';
+export { MemoryExtractor } from './memory/extractor.ts';
+export type { AtomFact, ExtractorOptions } from './memory/extractor.ts';
+export { SceneAggregator } from './memory/scene.ts';
+export type { SceneBlock, SceneAggregatorOptions } from './memory/scene.ts';
+export { PersonaGenerator } from './memory/persona.ts';
+export type { PersonaFacet, PersonaGeneratorOptions } from './memory/persona.ts';
+export { MemoryCheckpoint, getMemoryCheckpoint, resetMemoryCheckpoint } from './memory/checkpoint.ts';
+export type { CheckpointData } from './memory/checkpoint.ts';
+export { MemoryRecallEngine, formatRecallForPrompt } from './memory/recall.ts';
+export type { RecallResult, ScoredMemoryEntry, RecallOptions } from './memory/recall.ts';
+export { MemoryPipeline } from './memory/pipeline.ts';
+export type { PipelineOptions, PipelineResult } from './memory/pipeline.ts';

package/src/llm/anthropic-provider.ts

@@ -0,0 +1,412 @@
+/**
+ * @file Anthropic Claude LLM Provider
+ * @description 实现 Anthropic Messages API，支持 Claude 系列模型，
+ *              内部自动完成 OpenAI 格式 ↔ Anthropic 格式的双向转换
+ */
+
+import type { LLMProvider, ModelConfig, ModelInfo, ChatParams, ChatResponse, ChatChunk } from './types.ts';
+import type { Message, ToolCall } from '../types.ts';
+
+// ---- Anthropic API 内部类型 ----
+
+interface AnthropicContentBlock {
+  type: 'text' | 'tool_use' | 'tool_result';
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  content?: string;
+}
+
+interface AnthropicMessage {
+  role: 'user' | 'assistant';
+  content: string | AnthropicContentBlock[];
+}
+
+interface AnthropicTool {
+  name: string;
+  description?: string;
+  input_schema: Record<string, unknown>;
+}
+
+// ---- 上下文窗口映射 ----
+
+const CONTEXT_WINDOWS: Record<string, number> = {
+  'claude-sonnet-4': 200000,
+  'claude-opus-4': 200000,
+  'claude-3-5-sonnet': 200000,
+  'claude-3-5-haiku': 200000,
+  'claude-3-opus': 200000,
+  'claude-3-sonnet': 200000,
+  'claude-3-haiku': 200000,
+};
+
+function getContextWindow(model: string): number {
+  for (const [prefix, ctx] of Object.entries(CONTEXT_WINDOWS)) {
+    if (model.startsWith(prefix)) return ctx;
+  }
+  return 200000; // 默认 200k
+}
+
+// ---- Provider 实现 ----
+
+export class AnthropicProvider implements LLMProvider {
+  private config: Required<Pick<ModelConfig, 'provider' | 'model'>> & ModelConfig;
+
+  constructor(config: ModelConfig) {
+    this.config = {
+      ...config,
+      provider: 'anthropic',
+      model: config.model || 'claude-sonnet-4-20250514',
+      baseUrl: config.baseUrl || 'https://api.anthropic.com',
+      temperature: config.temperature ?? 0.7,
+      maxTokens: (typeof config.maxTokens === 'number' && config.maxTokens > 0) ? config.maxTokens : 4096,
+      timeout: config.timeout ?? 120000,
+    };
+  }
+
+  getModel(): ModelInfo {
+    return {
+      provider: this.config.provider,
+      model: this.config.model,
+      contextWindow: getContextWindow(this.config.model),
+      supportsTools: true,
+      supportsStreaming: true,
+    };
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await this.doRequest(
+        {
+          model: this.config.model,
+          max_tokens: 5,
+          messages: [{ role: 'user', content: 'ping' }],
+        },
+      );
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async chat(params: ChatParams): Promise<ChatResponse> {
+    const body = this.buildRequestBody(params);
+    const res = await this.doRequest(body, params.abortSignal);
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => 'Unknown error');
+      throw new Error(`Anthropic API error ${res.status}: ${errText}`);
+    }
+
+    const data = await res.json();
+    return this.parseResponse(data);
+  }
+
+  async *chatStream(params: ChatParams): AsyncGenerator<ChatChunk> {
+    const body = this.buildRequestBody(params);
+    body.stream = true;
+
+    const res = await this.doRequest(body, params.abortSignal);
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => 'Unknown error');
+      throw new Error(`Anthropic API error ${res.status}: ${errText}`);
+    }
+
+    const reader = res.body?.getReader();
+    if (!reader) throw new Error('No response body');
+
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    // 流式状态
+    let currentToolCallId = '';
+    let currentToolCallName = '';
+    let toolCallArgsBuffer = '';
+    let toolCallIndex = 0;         // 全局递增计数器，为每个 tool_use block 分配唯一 index
+    let currentToolCallIndex = 0;  // 当前正在处理的 tool_use block 的 index
+    // Usage 跟踪
+    let inputTokens = 0;
+    let outputTokens = 0;
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || !trimmed.startsWith('data: ')) continue;
+
+          try {
+            const json = JSON.parse(trimmed.slice(6));
+
+            switch (json.type) {
+              case 'message_start': {
+                // 提取 input tokens
+                const usage = json.message?.usage;
+                if (usage) {
+                  inputTokens = usage.input_tokens || 0;
+                }
+                break;
+              }
+
+              case 'content_block_start': {
+                const block = json.content_block;
+                if (block?.type === 'tool_use') {
+                  currentToolCallId = block.id || '';
+                  currentToolCallName = block.name || '';
+                  currentToolCallIndex = toolCallIndex++;
+                  toolCallArgsBuffer = '';
+                }
+                break;
+              }
+
+              case 'content_block_delta': {
+                const delta = json.delta;
+                if (delta?.type === 'text_delta') {
+                  yield {
+                    delta: { content: delta.text, role: 'assistant' },
+                  };
+                } else if (delta?.type === 'input_json_delta') {
+                  toolCallArgsBuffer += delta.partial_json || '';
+                }
+                break;
+              }
+
+              case 'content_block_stop': {
+                if (currentToolCallId) {
+                  // 工具调用完成，输出完整的 tool_call（必须携带 index，否则 LLMCaller 会将多个 tool_call 合并到 index=0）
+                  const toolCalls: (ToolCall & { index: number })[] = [{
+                    index: currentToolCallIndex,
+                    id: currentToolCallId,
+                    type: 'function',
+                    function: {
+                      name: currentToolCallName,
+                      arguments: toolCallArgsBuffer || '{}',
+                    },
+                  }];
+                  yield {
+                    delta: { role: 'assistant', tool_calls: toolCalls },
+                    finish_reason: 'tool_calls',
+                  };
+                  currentToolCallId = '';
+                  currentToolCallName = '';
+                  toolCallArgsBuffer = '';
+                }
+                break;
+              }
+
+              case 'message_delta': {
+                const stopReason = json.delta?.stop_reason;
+                // 提取 output tokens
+                const usage = json.usage;
+                if (usage) {
+                  outputTokens = usage.output_tokens || 0;
+                }
+                if (stopReason) {
+                  yield {
+                    delta: {},
+                    finish_reason: stopReason === 'tool_use' ? 'tool_calls' : stopReason,
+                    usage: {
+                      promptTokens: inputTokens,
+                      completionTokens: outputTokens,
+                      totalTokens: inputTokens + outputTokens,
+                    },
+                  };
+                }
+                break;
+              }
+            }
+          } catch {
+            // skip malformed chunks
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /** 更新配置 */
+  updateConfig(updates: Partial<ModelConfig>): void {
+    Object.assign(this.config, updates);
+  }
+
+  // ---- 内部方法 ----
+
+  /**
+   * 将 OpenAI 格式消息转换为 Anthropic 格式
+   * - system 消息提取为单独的 system 字段
+   * - tool 消息转换为 user 消息中的 tool_result 块
+   * - assistant 的 tool_calls 转换为 tool_use 块
+   */
+  private convertMessages(messages: Message[]): {
+    system?: string;
+    messages: AnthropicMessage[];
+  } {
+    let system: string | undefined;
+    const result: AnthropicMessage[] = [];
+
+    for (const msg of messages) {
+      switch (msg.role) {
+        case 'system':
+          system = (system ? system + '\n\n' : '') + (msg.content || '');
+          break;
+
+        case 'user':
+          result.push({ role: 'user', content: msg.content || '' });
+          break;
+
+        case 'assistant': {
+          if (msg.tool_calls?.length) {
+            // assistant 带 tool_calls → text + tool_use blocks
+            const blocks: AnthropicContentBlock[] = [];
+            if (msg.content) {
+              blocks.push({ type: 'text', text: msg.content });
+            }
+            for (const tc of msg.tool_calls) {
+              let input: Record<string, unknown>;
+              try {
+                input = JSON.parse(tc.function.arguments || '{}');
+              } catch {
+                // tool_call 参数 JSON 截断或格式错误时降级为空对象，避免整次 LLM 调用失败
+                console.warn(`[AnthropicProvider] Failed to parse tool_call arguments for '${tc.function.name}', using empty object. Raw: ${(tc.function.arguments || '').slice(0, 100)}`);
+                input = { _raw_arguments: tc.function.arguments || '' };
+              }
+              blocks.push({
+                type: 'tool_use',
+                id: tc.id,
+                name: tc.function.name,
+                input,
+              });
+            }
+            result.push({ role: 'assistant', content: blocks });
+          } else {
+            result.push({ role: 'assistant', content: msg.content || '' });
+          }
+          break;
+        }
+
+        case 'tool': {
+          // tool 消息 → user 消息中的 tool_result 块
+          result.push({
+            role: 'user',
+            content: [{
+              type: 'tool_result',
+              tool_use_id: msg.tool_call_id,
+              content: msg.content || '',
+            }],
+          });
+          break;
+        }
+      }
+    }
+
+    return { system, messages: result };
+  }
+
+  private convertTools(params: ChatParams): AnthropicTool[] | undefined {
+    if (!params.tools?.length) return undefined;
+    return params.tools.map(t => ({
+      name: t.function.name,
+      description: t.function.description,
+      input_schema: t.function.parameters || { type: 'object', properties: {} },
+    }));
+  }
+
+  private buildRequestBody(params: ChatParams): Record<string, any> {
+    const { system, messages } = this.convertMessages(params.messages);
+    const tools = this.convertTools(params);
+
+    const body: Record<string, any> = {
+      model: this.config.model,
+      max_tokens: (typeof params.maxTokens === 'number' && params.maxTokens > 0)
+        ? params.maxTokens
+        : (typeof this.config.maxTokens === 'number' && this.config.maxTokens > 0)
+          ? this.config.maxTokens
+          : 4096,
+      messages,
+      temperature: params.temperature ?? this.config.temperature,
+    };
+
+    if (system) body.system = system;
+    if (tools?.length) body.tools = tools;
+
+    return body;
+  }
+
+  private parseResponse(data: any): ChatResponse {
+    const content: string[] = [];
+    const toolCalls: ToolCall[] = [];
+
+    for (const block of data.content || []) {
+      if (block.type === 'text') {
+        content.push(block.text || '');
+      } else if (block.type === 'tool_use') {
+        toolCalls.push({
+          id: block.id,
+          type: 'function',
+          function: {
+            name: block.name,
+            arguments: JSON.stringify(block.input || {}),
+          },
+        });
+      }
+    }
+
+    const message: Message = {
+      role: 'assistant',
+      content: content.join('') || null,
+      ...(toolCalls.length ? { tool_calls: toolCalls } : {}),
+    };
+
+    return {
+      choices: [{
+        message,
+        finish_reason: data.stop_reason === 'tool_use' ? 'tool_calls' : (data.stop_reason || 'stop'),
+      }],
+      usage: data.usage
+        ? {
+            promptTokens: data.usage.input_tokens || 0,
+            completionTokens: data.usage.output_tokens || 0,
+            totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+          }
+        : undefined,
+    };
+  }
+
+  private async doRequest(body: Record<string, any>, signal?: AbortSignal): Promise<Response> {
+    const url = `${this.config.baseUrl!.replace(/\/$/, '')}/v1/messages`;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeout);
+
+    if (signal) {
+      if (signal.aborted) controller.abort();
+      else signal.addEventListener('abort', () => controller.abort(), { once: true });
+    }
+
+    try {
+      return await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'anthropic-version': '2023-06-01',
+          ...(this.config.apiKey ? { 'x-api-key': this.config.apiKey } : {}),
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+        ...(this.config.proxy ? { dispatcher: this.config.proxy } : {}),
+      } as RequestInit);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}

package/src/llm/factory.ts

@@ -0,0 +1,34 @@
+/**
+ * @file LLM Provider 工厂
+ * @description 根据 ModelConfig.provider 自动创建对应的 LLMProvider 实例
+ *              支持 'openai' | 'anthropic' | 'ollama' 及任意 OpenAI 兼容供应商
+ */
+
+import type { ModelConfig, LLMProvider } from './types.ts';
+import { OpenAIProvider } from './openai-provider.ts';
+import { AnthropicProvider } from './anthropic-provider.ts';
+import { OllamaProvider } from './ollama-provider.ts';
+
+/** 已注册的供应商名称集合 */
+export const BUILTIN_PROVIDERS = ['openai', 'anthropic', 'ollama'] as const;
+export type BuiltinProvider = (typeof BUILTIN_PROVIDERS)[number];
+
+/**
+ * 根据 config.provider 创建对应的 LLMProvider
+ *
+ * - 'openai'        → OpenAIProvider
+ * - 'anthropic'     → AnthropicProvider
+ * - 'ollama'        → OllamaProvider
+ * - 其他任意字符串   → OpenAIProvider（OpenAI 兼容端点，如 DeepSeek / vLLM / Together 等）
+ */
+export function createLLMProvider(config: ModelConfig): LLMProvider {
+  switch (config.provider?.toLowerCase()) {
+    case 'anthropic':
+      return new AnthropicProvider(config);
+    case 'ollama':
+      return new OllamaProvider(config);
+    case 'openai':
+    default:
+      return new OpenAIProvider(config);
+  }
+}