@cicctencent/agent-core 0.1.3 → 0.1.5

package/README.md

@@ -1,952 +1,39 @@
 # @cicctencent/agent-core
 
-> Core engine for AI agent — LLM orchestration, ReAct loop, tool execution, MCP integration, skill routing, security guard, and memory pipeline.
+> **内部库，仅供项目内部使用，不对外发布。**
 
-一个框架无关的 AI Agent 核心引擎库。提供完整的 ReAct 循环编排、多 LLM 供应商抽象、工具注册与执行、MCP 协议集成、Skill 路由、安全守卫和渐进式记忆管道。不绑定任何特定框架或运行时，通过接口注入实现上层适配。
+AI Agent 核心引擎，提供 ReAct 循环编排、多 LLM 供应商抽象、工具注册与执行、MCP 协议集成、Skill 路由、安全守卫和渐进式记忆管道。
 
----
+## 文档
 
-## 目录
-
-- [架构概览](#架构概览)
-- [快速开始](#快速开始)
-- [模块详解](#模块详解)
-  - [AgentEngine — ReAct 循环引擎](#agentengine--react-循环引擎)
-  - [LLM Provider — 多供应商抽象](#llm-provider--多供应商抽象)
-  - [Tool Registry — 工具注册与执行](#tool-registry--工具注册与执行)
-  - [MCP — 模型上下文协议](#mcp--模型上下文协议)
-  - [Skill — 技能管理与路由](#skill--技能管理与路由)
-  - [Security — 安全守卫](#security--安全守卫)
-  - [Sandbox — 沙箱类型定义](#sandbox--沙箱类型定义)
-  - [Context — 上下文构建](#context--上下文构建)
-  - [Hooks — 生命周期钩子](#hooks--生命周期钩子)
-  - [Middleware — 中间件管道](#middleware--中间件管道)
-  - [Memory — 渐进式记忆管道](#memory--渐进式记忆管道)
-  - [Workflow — 复杂工作流模板](#workflow--复杂工作流模板)
-- [TypeScript 配置](#typescript-配置)
-- [依赖说明](#依赖说明)
-
----
-
-## 架构概览
-
-```
-┌──────────────────────────────────────────────────────────┐
-│                    上层应用 (Server/App)                    │
-│  提供：ShellExecutor, FileSystemExecutor, MemoryService,  │
-│        SubAgentRunner, SSE 事件流, 沙箱实现                 │
-└────────────────────────┬─────────────────────────────────┘
-                         │ 接口注入
-┌────────────────────────▼─────────────────────────────────┐
-│                    @cicctencent/agent-core                    │
-│                                                          │
-│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐ │
-│  │ AgentEngine  │  │ ToolRegistry  │  │  SecurityGuard   │ │
-│  │  (ReAct 循环) │←→│  (工具注册表)  │  │  (安全守卫)      │ │
-│  └──────┬──────┘  └──────┬───────┘  └──────────────────┘ │
-│         │                │                                │
-│  ┌──────▼──────┐  ┌──────▼───────┐  ┌──────────────────┐ │
-│  │ LLMCaller   │  │ MCP Clients   │  │  SkillRouter     │ │
-│  │ (LLM 调用)  │  │ (远程工具)     │  │  (技能路由)       │ │
-│  └──────┬──────┘  └──────────────┘  └──────────────────┘ │
-│         │                                                │
-│  ┌──────▼──────────────────────────────────────────────┐ │
-│  │  LLM Provider (OpenAI / Anthropic / Ollama / Custom) │ │
-│  └─────────────────────────────────────────────────────┘ │
-│                                                          │
-│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐ │
-│  │ MemoryPipe   │  │ Hooks/MW     │  │  ContextManager  │ │
-│  │ (L1→L2→L3)  │  │ (生命周期)    │  │  (消息构建)       │ │
-│  └─────────────┘  └──────────────┘  └──────────────────┘ │
-└──────────────────────────────────────────────────────────┘
-```
-
-**核心设计原则**：
-- **接口隔离**：Core 不实现 Shell、文件系统、沙箱、持久化等能力，由上层通过 `ShellExecutor`、`FileSystemExecutor`、`Sandbox` 等接口注入
-- **ESM 原生**：所有内部导入使用显式 `.ts` 扩展名，兼容 Node.js ESM 和 TypeScript bundler
-- **流式优先**：Agent 执行通过 `AsyncGenerator<AgentEvent>` 逐事件推送，支持 SSE 实时流
-
----
+完整 API 文档请查阅 [docs/API.md](./docs/API.md)。
 
 ## 快速开始
 
-### 安装
-
 ```bash
 pnpm add @cicctencent/agent-core
 ```
 
-### 最小示例
-
 ```typescript
-import {
-  AgentEngine,
-  createLLMProvider,
-  ToolRegistry,
-  ContextManager,
-} from '@cicctencent/agent-core';
+import { AgentEngine, createLLMProvider, ToolRegistry, ContextManager } from '@cicctencent/agent-core';
 
-// 1. 创建 LLM Provider
-const llm = createLLMProvider({
-  provider: 'openai',
-  model: 'gpt-4o',
-  apiKey: process.env.OPENAI_API_KEY!,
-});
-
-// 2. 创建工具注册表并注册工具
+const llm = createLLMProvider({ provider: 'openai', model: 'gpt-4o', apiKey: process.env.OPENAI_API_KEY! });
 const toolRegistry = new ToolRegistry();
-toolRegistry.register({
-  definition: {
-    type: 'function',
-    function: {
-      name: 'get_time',
-      description: 'Get current time',
-      parameters: { type: 'object', properties: {}, required: [] },
-    },
-  },
-  executor: async () => new Date().toISOString(),
-  category: 'builtin',
-});
-
-// 3. 创建引擎
-const engine = new AgentEngine({
-  llmProvider: llm,
-  toolRegistry,
-  contextManager: new ContextManager(),
-  maxIterations: 10,
-});
-
-// 4. 运行（流式事件推送）
-const events = engine.run({
-  sessionId: 'session-001',
-  message: 'What time is it?',
-});
+const engine = new AgentEngine({ llmProvider: llm, toolRegistry, contextManager: new ContextManager(), maxIterations: 10 });
 
-for await (const event of events) {
+for await (const event of engine.run({ sessionId: 'session-001', message: 'Hello' })) {
   if (event.type === 'message') process.stdout.write(event.content);
   if (event.type === 'done') console.log('\nDone:', event.content);
-  if (event.type === 'error') console.error('Error:', event.error);
-}
-```
-
----
-
-## 模块详解
-
-### AgentEngine — ReAct 循环引擎
-
-**文件**：`agent/engine.ts` | **导出**：`AgentEngine`
-
-核心编排层，实现 Reasoning + Acting 循环：
-
-```
-用户消息 → [构建上下文] → [LLM 推理] → [解析响应]
-                                             │
-                   ┌─────────────────────────┤
-                   ▼                         ▼
-           tool_calls 存在?           纯文本响应
-                   │                         │
-          [执行工具] → [结果回注]          [done 事件]
-                   │
-              回到 LLM 推理（下一轮迭代）
-```
-
-#### 构造参数 `AgentConfig`
-
-| 参数 | 类型 | 默认值 | 说明 |
-|---|---|---|---|
-| `llmProvider` | `LLMProvider` | **必填** | LLM 供应商实例 |
-| `toolRegistry` | `ToolRegistry` | **必填** | 工具注册表实例 |
-| `contextManager` | `ContextManager` | **必填** | 上下文构建器 |
-| `maxIterations` | `number` | `15` | 单次任务最大迭代轮次 |
-| `maxMessages` | `number` | `50` | 消息历史滑动窗口大小 |
-| `toolTimeout` | `number` | `30000` | 单工具执行超时（ms） |
-| `llmTimeout` | `number` | `120000` | LLM 推理超时（ms） |
-| `basePrompt` | `string` | 内置默认 | Agent 系统提示词基础模板 |
-| `skillManager` | `SkillManager` | — | Skill 管理器（可选） |
-| `skillRouter` | `SkillRouter` | — | Skill 路由器（可选） |
-| `securityGuard` | `SecurityGuard` | — | 安全守卫（可选） |
-| `hooks` | `Hook[]` | — | 生命周期钩子列表 |
-| `middleware` | `Middleware[]` | — | 中间件管道 |
-| `retryPolicy` | `RetryPolicy` | — | LLM 调用重试策略 |
-| `fallbackProvider` | `LLMProvider` | — | 降级 LLM Provider |
-| `toolResultStore` | `ToolResultStore` | — | 大结果存储（写文件，按需读取） |
-| `contextBudget` | `object` | — | 上下文压缩配置 |
-| `contextBudget.maxToolOutput` | `number` | `8000` | 单工具输出最大字符数 |
-| `contextBudget.compactThreshold` | `number` | `maxMessages*0.8` | 触发压缩的消息数阈值 |
-| `contextBudget.maxContextTokens` | `number` | `100000` | 上下文总 token 预算 |
-| `toolDiscovery` | `'full' \| 'summary'` | `'full'` | 工具发现模式 |
-| `deniedTools` | `string[]` | — | 全局禁止的工具名 |
-| `defaultTools` | `string[]` | — | 默认工具列表 |
-| `dataFetchTools` | `string[]` | 内置列表 | 数据获取类工具（循环检测用） |
-| `outputTools` | `string[]` | 内置列表 | 产出型工具（免循环检测） |
-
-#### 运行方法 `engine.run(options)`
-
-```typescript
-const events = engine.run({
-  sessionId: string;           // 会话 ID
-  message: string;             // 用户输入
-  skillId?: string;            // 指定 Skill（跳过路由）
-  extraTools?: string[];       // 动态注入额外工具名
-  context?: SessionContext;    // 会话上下文
-  abortSignal?: AbortSignal;   // 取消信号
-  systemPromptOverride?: string; // 覆盖 system prompt 片段
-});
-
-// 返回 AsyncGenerator<AgentEvent>
-for await (const event of events) { /* 处理事件 */ }
-```
-
-#### 事件流 `AgentEvent`（discriminated union）
-
-```typescript
-type AgentEvent =
-  | ThinkingEvent     // { type: 'thinking', content?: string }        LLM 推理
-  | ToolCallEvent     // { type: 'tool_call', tool, args, callId }     请求工具
-  | ToolResultEvent   // { type: 'tool_result', tool, result, isError, duration, callId }
-  | MessageEvent      // { type: 'message', content, delta }           流式文本
-  | DoneEvent         // { type: 'done', content, iterations, usage }  完成
-  | ErrorEvent        // { type: 'error', error, recoverable }         出错
-  | SteeringEvent     // { type: 'steering', messages, count }         实时转向
-  | RetryEvent;       // { type: 'retry', attempt, maxRetries, delay, error, provider }
-```
-
-所有事件都继承 `BaseEvent`：`{ timestamp, sessionId, metadata? }`
-
----
-
-### LLM Provider — 多供应商抽象
-
-**文件**：`llm/types.ts`, `llm/factory.ts`, `llm/openai-provider.ts`, `llm/anthropic-provider.ts`, `llm/ollama-provider.ts`
-
-#### 接口 `LLMProvider`
-
-```typescript
-interface LLMProvider {
-  chat(params: ChatParams): Promise<ChatResponse>;          // 非流式推理
-  chatStream(params: ChatParams): AsyncGenerator<ChatChunk>; // 流式推理
-  getModel(): ModelInfo;                                     // 模型信息
-  ping(): Promise<boolean>;                                  // 连接测试
-}
-```
-
-#### 工厂 `createLLMProvider(config)`
-
-```typescript
-import { createLLMProvider } from '@cicctencent/agent-core';
-
-const llm = createLLMProvider({
-  provider: 'openai',     // 'openai' | 'anthropic' | 'ollama' | 任意 OpenAI 兼容供应商
-  model: 'gpt-4o',
-  apiKey: 'sk-...',
-  baseUrl: 'https://api.openai.com/v1', // 可选，自定义端点
-  temperature: 0.7,
-  maxTokens: 4096,
-  timeout: 60000,
-  extra: {},              // 供应商特定参数透传
-  proxy: dispatcher,      // undici Dispatcher（运行时注入）
-});
-```
-
-内置供应商：`'openai'` → `OpenAIProvider`、`'anthropic'` → `AnthropicProvider`、`'ollama'` → `OllamaProvider`。其他任意字符串均使用 `OpenAIProvider`（兼容 DeepSeek/vLLM/Together 等）。
-
-#### 请求参数 `ChatParams`
-
-```typescript
-interface ChatParams {
-  messages: Message[];
-  tools?: ToolDefinition[];
-  toolChoice?: 'auto' | 'none' | { type: 'function'; function: { name: string } };
-  temperature?: number;
-  maxTokens?: number;
-  abortSignal?: AbortSignal;
-}
-```
-
-#### 消息格式 `Message`
-
-兼容 OpenAI Chat Completion 格式：
-
-```typescript
-interface Message {
-  role: 'system' | 'user' | 'assistant' | 'tool';
-  content: string | null;
-  tool_calls?: ToolCall[];        // assistant 的工具调用请求
-  tool_call_id?: string;          // tool 消息对应的 call id
-  name?: string;
-  reasoning_content?: string | null;  // DeepSeek R1 推理内容
-  metadata?: Record<string, unknown>;
-}
-```
-
----
-
-### Tool Registry — 工具注册与执行
-
-**文件**：`tool/registry.ts`, `tool/types.ts`, `tool/delegate.ts`
-
-#### `ToolRegistry` 类
-
-```typescript
-import { ToolRegistry } from '@cicctencent/agent-core';
-
-const registry = new ToolRegistry();
-
-// 注册单个工具
-registry.register({
-  definition: { /* OpenAI Function Calling schema */ },
-  executor: async (args, ctx) => { /* 执行逻辑 */ return 'result'; },
-  category: 'builtin',       // 'builtin' | 'skill' | 'mcp' | 'custom'
-  concurrent: false,          // 是否支持并行执行
-  metadata: {},
-});
-
-// 批量注册
-registry.registerAll(tools);
-
-// 查询
-registry.has('get_time');           // boolean
-registry.get('get_time');           // RegisteredTool | undefined
-registry.listNames();               // string[]
-registry.getDefinitions({           // ToolDefinition[]（传给 LLM）
-  category: 'builtin',
-  names: ['get_time', 'calc'],
-});
-
-// 执行（内部调用）
-await registry.execute('get_time', {}, ctx);
-
-// 注销
-registry.unregister('get_time');
-```
-
-#### 工具定义格式 `ToolDefinition`
-
-遵循 OpenAI Function Calling 规范：
-
-```typescript
-interface ToolDefinition {
-  type: 'function';
-  function: {
-    name: string;
-    description: string;
-    parameters: {
-      type: 'object';
-      properties: Record<string, { type: string; description: string; enum?: string[]; /* ... */ }>;
-      required?: string[];
-    };
-  };
-}
-```
-
-#### 工具执行上下文 `ToolContext`
-
-由 `AgentEngine` 自动注入到每个 executor：
-
-```typescript
-interface ToolContext {
-  sessionId: string;
-  shell: ShellExecutor;          // Shell 执行能力（上层注入）
-  fs?: FileSystemExecutor;       // 文件系统操作（上层注入）
-  env?: EnvInfo;                 // 环境信息
-  abortSignal: AbortSignal;      // 取消信号
-  custom?: Record<string, unknown>; // 上层自定义能力
-  emitSubEvent?: SubAgentEventEmitter;  // 子 Agent 事件转发
-  emitWidget?: WidgetEventEmitter;      // Widget 事件发射
-  emitArtifact?: ArtifactEventEmitter;  // Artifact 事件发射
-  currentToolCallId?: string;
-}
-```
-
-#### 上层需实现的接口
-
-```typescript
-// Shell 执行器
-interface ShellExecutor {
-  exec(command: string, timeout?: number): Promise<string>;
-  write(data: string): void;
-  read(lines?: number): string;
-}
-
-// 文件系统执行器
-interface FileSystemExecutor {
-  readFile(path: string): Promise<string>;
-  readFileBuffer?(path: string): Promise<Buffer>;
-  writeFile(path: string, content: string): Promise<void>;
-  appendFile?(path: string, content: string): Promise<void>;
-  listDir(path: string): Promise<string[]>;
-}
-```
-
-#### DelegateTool — 任务分发
-
-```typescript
-import { createDelegateTool } from '@cicctencent/agent-core';
-
-const delegateTool = createDelegateTool([
-  { name: 'researcher', description: 'Deep research and analysis', run: async (task, ctx) => '...' },
-  { name: 'coder', description: 'Code generation and review', run: async (task, ctx) => '...' },
-]);
-
-if (delegateTool) registry.register(delegateTool);
-```
-
-生成 `delegate_task` 工具，LLM 可根据 agent name/description 智能分发子任务。
-
----
-
-### MCP — 模型上下文协议
-
-**文件**：`mcp/types.ts`, `mcp/factory.ts`, `mcp/client.ts`, `mcp/stdio-client.ts`, `mcp/http-client.ts`
-
-#### MCP 客户端接口
-
-```typescript
-interface MCPClient {
-  connect(config: MCPServerConfig): Promise<void>;
-  listTools(): Promise<ToolDefinition[]>;
-  callTool(name: string, args: Record<string, unknown>): Promise<string>;
-  listResources?(): Promise<Array<{ uri: string; name: string; description?: string }>>;
-  readResource?(uri: string): Promise<string>;
-  disconnect(): void;
-  isConnected(): boolean;
-}
-```
-
-#### 工厂 `createMCPClient(config)`
-
-```typescript
-import { createMCPClient, registerTransport } from '@cicctencent/agent-core';
-
-// 内置 transport：stdio / http / sse / streamableHttp
-const client = createMCPClient({
-  name: 'my-server',
-  transport: 'stdio',
-  command: 'node',
-  args: ['server.js'],
-  env: { API_KEY: '...' },
-});
-
-// HTTP/SSE transport
-const httpClient = createMCPClient({
-  name: 'remote-server',
-  transport: 'http',
-  endpoint: 'https://mcp.example.com',
-  headers: { Authorization: 'Bearer ...' },
-  auth: { type: 'bearer', value: 'token123' },
-  proxy: 'socks5://proxy:1080', // 支持 HTTP/HTTPS/SOCKS 代理
-});
-
-// 注册自定义 transport
-registerTransport('api-bridge', () => new MyCustomClient());
-const customClient = createMCPClient({ name: 'custom', transport: 'api-bridge' });
-```
-
-#### 服务器配置 `MCPServerConfig`
-
-```typescript
-interface MCPServerConfig {
-  name: string;
-  transport: 'stdio' | 'http' | 'sse' | 'streamableHttp' | string;
-  command?: string;          // stdio: 启动命令
-  args?: string[];           // stdio: 命令参数
-  env?: Record<string, string>; // stdio: 环境变量
-  endpoint?: string;         // HTTP/SSE: 服务端点
-  headers?: Record<string, string>; // HTTP/SSE: 自定义请求头
-  auth?: { type: 'bearer' | 'basic' | 'apiKey' | 'custom'; value: string; name?: string };
-  timeout?: number;
-  autoReconnect?: boolean | { maxRetries?: number; interval?: number };
-  proxy?: string;            // 代理 URL（HTTP/HTTPS/SOCKS4/SOCKS5）
-  extra?: Record<string, unknown>; // 扩展配置
-}
-```
-
-#### 工具注册辅助
-
-```typescript
-import { registerMCPTools, buildMCPToolName, MCP_TOOL_PREFIX } from '@cicctencent/agent-core';
-
-// 自动发现并注册 MCP 远程工具到 ToolRegistry
-await registerMCPTools(toolRegistry, mcpClient, {
-  serverName: 'my-server',
-  connectorId: 'my-connector', // 可选，用于命名空间隔离
-});
-
-// 工具名格式：mcp_{connectorId}_{serverName}_{toolName} 或 mcp_{serverName}_{toolName}
-const name = buildMCPToolName('search', 'brave', 'my-connector');
-// → "mcp_my_connector_brave_search"
-```
-
----
-
-### Skill — 技能管理与路由
-
-**文件**：`skill/types.ts`, `skill/manager.ts`, `skill/router.ts`
-
-#### SkillManager — 懒加载技能管理
-
-```typescript
-import { SkillManager } from '@cicctencent/agent-core';
-
-const skillManager = new SkillManager({
-  skills: [],       // 初始 Skill 列表
-  lazy: true,       // 启用懒加载（仅加载 manifest，content 按需读取）
-  cacheSize: 50,    // LRU 缓存大小
-});
-
-// 注册 Skill
-skillManager.register(skill);
-
-// 获取（懒加载时自动从 filePath 读取 content）
-const skill = skillManager.get('stock-analysis');
-
-// 获取所有 manifest（轻量，不含 content）
-const manifests = skillManager.getAllManifests();
-
-// 获取所有完整 Skill
-const allSkills = skillManager.getAll();
-```
-
-#### Skill 数据结构
-
-```typescript
-interface SkillManifest {
-  id: string;
-  name: string;
-  description: string;
-  tags: string[];          // 关键词（路由匹配用）
-  aliases: string[];       // 同义词
-  source: 'system' | 'user' | 'remote';
-  version?: string;
-  requires?: string[];     // 依赖的 MCP 工具名
-  referencedSkills?: string[]; // 引用的其他 Skill ID
-  filePath?: string;       // 懒加载路径
-  contentSize?: number;
-  metadata?: Record<string, unknown>;
-}
-
-interface Skill extends SkillManifest {
-  content: string;         // Skill 正文（懒加载时可能为空）
-}
-```
-
-#### SkillRouter — 三级路由
-
-```typescript
-import { SkillRouter } from '@cicctencent/agent-core';
-
-const router = new SkillRouter(skillManager);
-
-// 添加自定义路由策略
-router.addStrategy({
-  name: 'priority',
-  match: async (message, skills) => {
-    if (message.includes('urgent')) return { skill: skills[0], message, matchType: 'custom', confidence: 1 };
-    return null;
-  },
-});
-
-// 路由（三级：自定义策略 → 显式 /command → 关键词匹配）
-const result = await router.route('/stock-analysis AAPL');
-// → { skill: Skill, message: 'AAPL', matchType: 'explicit', confidence: 1 }
-
-// 未命中时返回 { skill: null }，Engine 会在 system prompt 注入 skill catalog
-```
-
----
-
-### Security — 安全守卫
-
-**文件**：`security/guard.ts`, `security/types.ts`
-
-#### SecurityGuard
-
-```typescript
-import { SecurityGuard } from '@cicctencent/agent-core';
-
-const guard = new SecurityGuard({
-  deleteProtection: true,         // rm → mv 到回收站
-  trashDir: '~/.workagent/.trash',
-  blacklistEnabled: true,
-  rules: [
-    {
-      name: 'block-format',
-      pattern: /^mkfs\b/,
-      severity: 'blocked',
-      action: 'block',
-      description: 'Block disk format',
-    },
-    {
-      name: 'rewrite-rm',
-      pattern: /^rm\s+-rf\s+(?!\/)/,
-      severity: 'danger',
-      action: 'rewrite',
-      rewriter: (cmd) => cmd.replace('rm -rf', 'mv'),
-    },
-  ],
-});
-
-// 检查命令
-const result = guard.sanitize('rm -rf /tmp/test');
-// → { safe: false, severity: 'blocked', reason: '...' }
-
-// 检查凭证泄露
-const leaked = guard.detectCredentials('export API_KEY=sk-abc123...');
-// → [{ name: 'openai-key', match: 'sk-abc123...' }]
-```
-
-#### SanitizeResult
-
-```typescript
-interface SanitizeResult {
-  safe: boolean;
-  rewritten?: string;       // 改写后的命令
-  reason?: string;          // 拒绝/警告原因
-  severity: 'safe' | 'warn' | 'danger' | 'blocked';
-}
-```
-
----
-
-### Sandbox — 沙箱类型定义
-
-**文件**：`sandbox/types.ts`
-
-Core 层仅定义沙箱接口和安全规则常量，**不提供实现**（由上层实现）。
-
-```typescript
-interface Sandbox {
-  readonly id: string;
-  readonly rootDir: string;
-  getShellExecutor(): ShellExecutor;
-  getFileSystemExecutor(): FileSystemExecutor;
-  runScript(language: 'python' | 'nodejs' | 'shell', code: string, timeout?: number): Promise<string>;
-  destroy(): Promise<void>;
-}
-
-interface SandboxManager {
-  create(id: string, config?: Partial<SandboxConfig>): Promise<Sandbox>;
-  get(id: string): Sandbox | undefined;
-  destroy(id: string): Promise<void>;
-  destroyAll(): Promise<void>;
-}
-```
-
-内置安全常量（上层实现沙箱时可直接使用）：
-
-```typescript
-import { SANDBOX_BLOCKED_COMMANDS, SANDBOX_SAFE_ENV_KEYS, DEFAULT_SANDBOX_CONFIG } from '@cicctencent/agent-core';
-```
-
----
-
-### Context — 上下文构建
-
-**文件**：`context/manager.ts`, `context/types.ts`, `context/collector.ts`
-
-#### ContextManager（纯函数式，无状态）
-
-```typescript
-import { ContextManager } from '@cicctencent/agent-core';
-
-const ctx = new ContextManager();
-const messages = ctx.buildMessages({
-  systemPrompt: 'You are a helpful assistant...',
-  extraSystemPrompt: 'Current time: 2025-01-01',
-  history: previousMessages,
-  userMessage: 'Hello',
-});
-// → [{ role: 'system', content: '...' }, ...history, { role: 'user', content: 'Hello' }]
-```
-
-#### EnvCollector — 环境采集接口
-
-```typescript
-interface EnvCollector {
-  collect(): Promise<EnvInfo>;
-  format(info: EnvInfo): string;
-}
-
-interface EnvInfo {
-  os: string;
-  platform: 'linux' | 'darwin' | 'win32';
-  cpuCores: number;
-  memory: string;
-  disk: string;
-  shell: string;
-  hostname?: string;
-  user?: string;
-  custom?: Record<string, string>;
-}
-```
-
-`LocalEnvCollector` 提供本地环境采集的默认实现。
-
----
-
-### Hooks — 生命周期钩子
-
-**文件**：`hooks/types.ts`
-
-7 个事件点，支持拦截、修改、注入：
-
-```typescript
-import type { Hook } from '@cicctencent/agent-core';
-
-const auditHook: Hook = {
-  name: 'audit-tool-calls',
-  event: 'before_tool',
-  handler: async (ctx) => {
-    console.log(`Tool: ${ctx.tool}, Args:`, ctx.args);
-    // 阻止危险操作
-    if (ctx.tool === 'rm_file') return { block: true, reason: 'File deletion not allowed' };
-    // 修改参数
-    if (ctx.tool === 'write_file') return { modify: { backup: true } };
-  },
-};
-
-const logHook: Hook = {
-  name: 'log-completion',
-  event: 'on_complete',
-  handler: async (ctx) => {
-    console.log(`Completed in ${ctx.totalIterations} iterations, tokens:`, ctx.usage);
-  },
-};
-
-// 注入到引擎
-new AgentEngine({ ..., hooks: [auditHook, logHook] });
-```
-
-**事件类型**：
-
-| 事件 | 时机 | 可用上下文 | 有效返回值 |
-|---|---|---|---|
-| `before_tool` | 工具执行前 | `tool`, `args` | `{ block, reason, modify }` |
-| `after_tool` | 工具执行后 | `tool`, `args`, `result`, `isError`, `duration` | `{ inject }` |
-| `before_ll_call` | LLM 调用前 | `messages`, `tools` | — |
-| `after_ll_call` | LLM 调用后 | `response` | — |
-| `on_iteration_start` | 每轮开始 | `iteration` | — |
-| `on_error` | 出错时 | `error`, `recoverable` | — |
-| `on_complete` | 完成时 | `totalIterations`, `usage` | — |
-
----
-
-### Middleware — 中间件管道
-
-**文件**：`middleware/types.ts`
-
-与 Hook 共存的结构化增强层，提供更清晰的 before/after 生命周期：
-
-```typescript
-import type { Middleware } from '@cicctencent/agent-core';
-
-const timingMiddleware: Middleware = {
-  name: 'timing',
-  before: async (ctx) => { console.log(`Iteration ${ctx.iteration} start`); },
-  after: async (ctx) => { console.log(`Iteration ${ctx.iteration} end`); },
-  onToolBefore: async (ctx) => { /* 工具执行前，返回 HookResult */ },
-  onToolAfter: async (ctx) => { /* 工具执行后，返回 HookResult */ },
-};
-```
-
-**执行顺序**：
-```
-Middleware.before → Hook.on_iteration_start → ... → Hook.before_tool → Middleware.onToolBefore → [工具执行] → Hook.after_tool → Middleware.onToolAfter → ... → Middleware.after
-```
-
----
-
-### Memory — 渐进式记忆管道
-
-**文件**：`memory/pipeline.ts`, `memory/extractor.ts`, `memory/scene.ts`, `memory/persona.ts`, `memory/recall.ts`, `memory/checkpoint.ts`
-
-四级记忆架构（L0→L1→L2→L3）：
-
-| 层级 | 含义 | 来源 |
-|---|---|---|
-| L0 | 原始对话 | 直接存储 |
-| L1 | 原子事实 | LLM 从对话中提取 |
-| L2 | 场景块 | L1 聚合 |
-| L3 | 用户画像 | L2 提炼 |
-
-#### MemoryPipeline — 管道调度器
-
-```typescript
-import { MemoryPipeline } from '@cicctencent/agent-core/memory/pipeline';
-
-const pipeline = new MemoryPipeline({
-  llmProvider: llm,
-  l2Threshold: 5,  // L1 累积 5 条触发 L2
-  l3Threshold: 3,  // L2 累积 3 条触发 L3
-});
-
-// 对话结束后 fire-and-forget
-const result = await pipeline.run(messages, sessionId, memoryService);
-// → { l1Extracted: 3, l2Triggered: false, l3Triggered: false }
-```
-
-上层需实现 `MemoryServiceLike` 接口：
-
-```typescript
-interface MemoryServiceLike {
-  getKeys(): string[];
-  getAllEntries(layer?: MemoryLayer): MemoryEntry[];
-  save(key, content, category, importance, extras?): MemoryEntry;
-}
-```
-
-#### MemoryExtractor — L1 原子事实提取
-
-```typescript
-import { MemoryExtractor } from '@cicctencent/agent-core/memory/extractor';
-
-const extractor = new MemoryExtractor({ llmProvider, maxFactsPerSession: 5 });
-const facts = await extractor.extract(messages, sessionId, existingKeys);
-// → AtomFact[]: [{ key: 'user_pref_language', content: '用户偏好中文', category: 'user_preference', importance: 4 }]
-```
-
-#### SceneAggregator — L2 场景聚合
-
-```typescript
-import { SceneAggregator } from '@cicctencent/agent-core/memory/scene';
-
-const aggregator = new SceneAggregator({ llmProvider });
-const scenes = await aggregator.aggregate(atoms, existingScenes);
-// → SceneBlock[]: [{ sceneId, title, description, atomIds }]
-```
-
-#### PersonaGenerator — L3 用户画像
-
-```typescript
-import { PersonaGenerator } from '@cicctencent/agent-core/memory/persona';
-
-const generator = new PersonaGenerator({ llmProvider });
-const persona = await generator.generate(scenes, existingPersona);
-// → string: 用户画像文本
-```
-
-#### MemoryRecallEngine — 智能召回
-
-```typescript
-import { MemoryRecallEngine, formatRecallForPrompt } from '@cicctencent/agent-core/memory/recall';
-
-const recall = new MemoryRecallEngine(allEntries);
-const result = await recall.recall('用户偏好', {
-  maxResults: 5,
-  timeoutMs: 3000,
-  layers: ['L1', 'L2', 'L3'],
-});
-
-// 格式化为 prompt 片段
-const promptFragment = formatRecallForPrompt(result);
-```
-
-召回策略：关键词匹配 + 重要性加权 + 时效性衰减。
-
-#### MemoryCheckpoint — 增量检查点
-
-```typescript
-import { getMemoryCheckpoint, resetMemoryCheckpoint } from '@cicctencent/agent-core/memory/checkpoint';
-
-const checkpoint = getMemoryCheckpoint();
-checkpoint.shouldTriggerL2(l1Count, threshold); // boolean
-checkpoint.updateL2(l1Count);
-```
-
----
-
-### Workflow — 复杂工作流模板
-
-**文件**：`agent/workflow.ts`
-
-支持结构化输出、辩论模式、多角色工作流：
-
-```typescript
-import {
-  getWorkflowTemplate,
-  formatWorkflowTemplateForPrompt,
-  parseStructuredAgentOutput,
-  DEFAULT_COMPLEX_WORKFLOW_TEMPLATE,
-} from '@cicctencent/agent-core';
-
-// 获取工作流模板
-const template = getWorkflowTemplate('complex');
-
-// 格式化为 prompt 指令
-const instruction = formatWorkflowTemplateForPrompt(template);
-
-// 解析结构化输出
-const output = parseStructuredAgentOutput(rawText);
-// → { findings: [...], risks: [...], recommendation: '...', confidence: 0.85, next_actions: [...] }
-```
-
-**类型**：
-
-```typescript
-type WorkflowRole = 'researcher' | 'implementer' | 'reviewer' | 'critic' | 'risk_checker' | 'final_approver';
-
-interface StructuredAgentOutput {
-  findings: Array<{ title: string; detail: string; evidence?: string }>;
-  risks: Array<{ description: string; severity: 'low' | 'medium' | 'high' | 'critical'; mitigation?: string }>;
-  recommendation: string;
-  confidence: number;
-  next_actions: string[];
 }
 ```
 
----
-
-## TypeScript 配置
-
-### 使用方 tsconfig
-
-```jsonc
-{
-  "compilerOptions": {
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,  // 必须：agent-core 内部使用 .ts 扩展名
-    "noEmit": true,                       // 或 emitDeclarationOnly
-    "paths": {
-      "@cicctencent/agent-core": ["./node_modules/@cicctencent/agent-core/src"],
-      "@cicctencent/agent-core/*": ["./node_modules/@cicctencent/agent-core/src/*"]
-    }
-  }
-}
-```
-
-### 子路径导入
-
-包支持子路径直接导入：
-
-```typescript
-import { MemoryPipeline } from '@cicctencent/agent-core/memory/pipeline';
-import { MemoryRecallEngine } from '@cicctencent/agent-core/memory/recall';
-import { createMCPClient } from '@cicctencent/agent-core/mcp/factory';
-import { SecurityGuard } from '@cicctencent/agent-core/security/guard';
-import type { ToolContext } from '@cicctencent/agent-core/tool/types';
-```
-
----
-
-## 依赖说明
-
-| 依赖 | 用途 |
-|---|---|
-| `js-tiktoken` | Token 计数（上下文预算管理） |
-| `undici` | HTTP 客户端（LLM API 调用、MCP HTTP transport） |
-| `socks-proxy-agent` | SOCKS 代理支持（MCP proxy 配置） |
-
-**运行时要求**：Node.js >= 18
-
----
-
 ## 构建
 
 ```bash
-# 类型检查
-pnpm typecheck
-
-# 生成类型声明文件（.d.ts）
-pnpm build
+pnpm typecheck   # 类型检查
+pnpm build       # 生成 .d.ts
 ```
+
+## 运行时要求
+
+Node.js >= 18