lll-web-agent 0.1.0 → 0.5.0

package/README.md

@@ -1,8 +1,8 @@
 # lll-web-agent
 
-开箱即用的 LLM Agent SDK。配个 API Key，定义几个工具，就能跑起一个完整的 AI Agent。
+开箱即用的 LLM Agent SDK — 配个 API Key 就能跑。
 
-零依赖。支持 OpenAI / DeepSeek / 通义千问 / X-GROK / Moonshot / 智谱 等所有 OpenAI 兼容供应商。
+内置完整 Runtime 管线：意图识别 → 工具过滤 → 上下文管理（token 预算） → ReAct 循环。
 
 ## 安装
 
@@ -10,386 +10,393 @@
 npm install lll-web-agent
 ```
 
-要求 Node.js >= 18（使用内置 fetch API）。
+## 快速开始
 
-## 30 秒上手
+### 基础用法（10 行代码）
 
-```javascript
-import { Agent } from 'lll-web-agent'
+```js
+import { Agent, defineTool } from 'lll-web-agent'
+
+const readFile = defineTool({
+  name: 'read_file',
+  description: '读取文件内容',
+  parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+  execute: async ({ path }) => (await import('fs/promises')).readFile(path, 'utf-8'),
+})
 
 const agent = new Agent({
   provider: 'openai',
   apiKey: process.env.OPENAI_API_KEY,
   model: 'gpt-4',
+  tools: [readFile],
 })
 
-const reply = await agent.chat('你好，介绍一下你自己')
+const reply = await agent.chat('读取 package.json 并告诉我项目名称')
 console.log(reply)
 ```
 
-就这么多。不需要配置 HTTP 客户端、不需要处理 SSE 解析、不需要理解 ReAct 循环。
-
----
+### Runtime 模式（完整管线）
 
-## 注册工具
+```js
+import { Agent, KnowledgeBase, createKnowledgeEntry } from 'lll-web-agent'
 
-工具是 Agent 与外部世界交互的方式。LLM 会根据工具描述自主决定何时调用哪个工具。
+// 1. 构建知识库
+const kb = new KnowledgeBase()
+kb.addEntry(createKnowledgeEntry('ARCHITECTURE', '项目架构', '本项目使用 monorepo 结构...'))
+kb.addEntry(createKnowledgeEntry('ERROR_PATTERN', '常见错误', '避免在循环中使用 await...'))
 
-### 基本用法
-
-```javascript
-import { Agent, defineTool } from 'lll-web-agent'
-
-// 1. 用 defineTool 定义工具
-const getCurrentTime = defineTool({
-  name: 'get_current_time',          // 工具唯一名称
-  description: '获取当前时间',         // 告诉 LLM 这个工具能做什么
-  parameters: {                       // JSON Schema 格式的参数定义
-    type: 'object',
-    properties: {},                   // 无参数
-  },
-  execute: async () => {              // 执行函数，返回字符串
-    return new Date().toISOString()
+// 2. 创建 Agent（启用 Runtime 管线）
+const agent = new Agent({
+  provider: 'deepseek',
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  model: 'deepseek-chat',
+  tools: [readFile, shellExec],
+  enableIntentRecognition: true,   // 启用意图识别（sidecar LLM 调用）
+  knowledgeBase: kb,               // 注入知识库
+  tokenBudget: {                   // 自定义 token 预算
+    totalTokens: 60000,
+    systemPromptRatio: 0.15,
+    knowledgeRatio: 0.20,
+    historyRatio: 0.45,
+    toolsRatio: 0.20,
   },
 })
 
-// 2. 传给 Agent
-const agent = new Agent({
-  provider: 'openai',
-  apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-4',
-  tools: [getCurrentTime],
-})
+const reply = await agent.chat('分析项目架构并找出潜在问题')
+```
 
-// 3. Agent 会自动决定是否调用工具
-const reply = await agent.chat('现在几点了？')
-// Agent 内部流程：
-//   LLM 思考 -> 决定调用 get_current_time -> 执行 -> 拿到时间 -> 继续思考 -> 返回最终回答
+## 流式对话
+
+```js
+for await (const event of agent.stream('帮我重构这个函数')) {
+  switch (event.type) {
+    case 'intent':     console.log('意图:', event.intent); break
+    case 'delta':      process.stdout.write(event.content); break
+    case 'tool_start': console.log(`\n🔧 ${event.name}(${JSON.stringify(event.arguments)})`); break
+    case 'tool_end':   console.log(`✅ ${event.name} → ${event.result}`); break
+    case 'done':       console.log('\n完成'); break
+  }
+}
 ```
 
-### 带参数的工具
+## 架构
 
-```javascript
-const readFile = defineTool({
-  name: 'read_file',
-  description: '读取指定路径的文件内容',
-  parameters: {
-    type: 'object',
-    properties: {
-      path: {
-        type: 'string',
-        description: '文件路径，相对于当前工作目录',
-      },
-    },
-    required: ['path'],  // 必填参数
-  },
-  execute: async ({ path }) => {
-    const fs = await import('fs/promises')
-    try {
-      return await fs.readFile(path, 'utf-8')
-    } catch (err) {
-      return `读取失败: ${err.message}`  // 返回错误信息，LLM 会看到并处理
-    }
-  },
-})
+```
+用户消息
+  │
+  ├─ enableIntentRecognition=true?
+  │   └─ IntentRecognizer (sidecar LLM 调用)
+  │       → { clarity, complexity, recommendedStrategy, filteredToolNames }
+  │
+  ├─ ToolFilter
+  │   → 根据 intent 过滤工具（BaseTool 始终保留）
+  │
+  ├─ ContextManager (如果配置了 tokenBudget 或 knowledgeBase)
+  │   → 组装 prompt: systemPrompt + knowledge + history + tools
+  │   → 超预算时按优先级裁剪: TOOLS → HISTORY → KNOWLEDGE
+  │
+  └─ 执行策略（strategy）
+      ├─ react（默认）
+      │   → LLM 调用 → 工具执行 → 观察结果 → 继续/完成
+      │
+      └─ plan_and_execute
+          → Phase 1: Planning（LLM 生成结构化计划）
+          → Phase 2: Execution（逐步执行，每步内部 ReAct 循环）
+          → Phase 3: Synthesis（汇总结果，生成最终回答）
+          → 支持自适应重规划（步骤失败时自动修订计划）
 ```
 
-### 多个工具协作
+## 核心模块
 
-Agent 可以在一次对话中调用多个工具，自主决定调用顺序：
+### Agent
 
-```javascript
-const listFiles = defineTool({
-  name: 'list_files',
-  description: '列出目录下的文件',
-  parameters: {
-    type: 'object',
-    properties: {
-      dir: { type: 'string', description: '目录路径' },
-    },
-    required: ['dir'],
-  },
-  execute: async ({ dir }) => {
-    const fs = await import('fs/promises')
-    const files = await fs.readdir(dir)
-    return files.join('\n')
-  },
-})
+主入口，支持两种模式：
 
-const agent = new Agent({
-  provider: 'deepseek',
-  apiKey: process.env.DEEPSEEK_API_KEY,
-  model: 'deepseek-chat',
-  tools: [listFiles, readFile],  // 注册多个工具
-})
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `provider` | (必需) | 供应商: openai, deepseek, qwen, moonshot, zhipu, x-grok |
+| `apiKey` | (必需) | API Key |
+| `model` | `'gpt-4'` | 模型名称 |
+| `tools` | `[]` | 工具列表 |
+| `maxRounds` | `300` | 最大 ReAct 轮次 |
+| `enableIntentRecognition` | `false` | 启用意图识别 |
+| `knowledgeBase` | `null` | 知识库实例 |
+| `tokenBudget` | `null` | token 预算配置 |
+| `memory` | `SlidingWindowMemory(40)` | 自定义记忆实例 |
+| `strategy` | `'react'` | 执行策略: `'react'` 或 `'plan_and_execute'` |
+| `planAndExecuteOpts` | `{}` | PlanAndExecute 策略配置（见下方） |
 
-// Agent 会先调用 list_files 看有哪些文件，再调用 read_file 读取感兴趣的文件
-const reply = await agent.chat('看看当前目录有什么文件，读一下 package.json 的内容')
-```
+### IntentRecognizer
 
-### 工具的 execute 函数规范
-
-```javascript
-defineTool({
-  name: 'my_tool',
-  description: '...',
-  parameters: { ... },
-  execute: async (params) => {
-    // params 是 LLM 传入的参数对象，结构与 parameters 定义一致
-    // 必须返回字符串（LLM 只能理解文本）
-    // 如果返回对象，会被自动 JSON.stringify
-    // 抛出异常时，错误信息会被发送给 LLM，LLM 可能会重试或换一种方式
-    return '执行结果'
-  },
-})
-```
+Sidecar 方式独立 LLM 调用，分析用户请求：
 
-### 实用工具示例
-
-```javascript
-// Shell 命令执行
-const shellExec = defineTool({
-  name: 'shell_exec',
-  description: '执行 shell 命令并返回输出',
-  parameters: {
-    type: 'object',
-    properties: {
-      command: { type: 'string', description: 'shell 命令' },
-    },
-    required: ['command'],
-  },
-  execute: async ({ command }) => {
-    const { execSync } = await import('child_process')
-    try {
-      return execSync(command, { encoding: 'utf-8', timeout: 10000 })
-    } catch (err) {
-      return `命令执行失败: ${err.message}`
-    }
-  },
-})
+```js
+import { IntentRecognizer } from 'lll-web-agent'
 
-// HTTP 请求
-const httpGet = defineTool({
-  name: 'http_get',
-  description: '发送 HTTP GET 请求',
-  parameters: {
-    type: 'object',
-    properties: {
-      url: { type: 'string', description: 'URL 地址' },
-    },
-    required: ['url'],
-  },
-  execute: async ({ url }) => {
-    const res = await fetch(url)
-    return await res.text()
-  },
+const ir = new IntentRecognizer({
+  url: 'https://api.openai.com/v1/chat/completions',
+  apiKey: 'sk-xxx',
+  model: 'gpt-4',
 })
 
-// 数学计算
-const calculate = defineTool({
-  name: 'calculate',
-  description: '计算数学表达式',
-  parameters: {
-    type: 'object',
-    properties: {
-      expression: { type: 'string', description: '数学表达式' },
-    },
-    required: ['expression'],
-  },
-  execute: async ({ expression }) => {
-    return String(Function(`"use strict"; return (${expression})`)())
-  },
-})
+const intent = await ir.analyze('帮我重构整个项目的错误处理', ['read_file', 'write_file', 'shell_exec'])
+// → { clarity: 'CLEAR', complexity: 'COMPLEX', recommendedStrategy: 'plan_and_execute', ... }
 ```
 
----
+### KnowledgeBase
 
-## 流式输出
+项目知识管理，注入到 prompt 中：
 
-通过 async generator 实时获取 Agent 的执行过程：
+```js
+import { KnowledgeBase, createKnowledgeEntry } from 'lll-web-agent'
 
-```javascript
-for await (const event of agent.stream('帮我分析这个项目')) {
-  switch (event.type) {
-    case 'delta':       // LLM 文本增量
-      process.stdout.write(event.content)
-      break
-    case 'tool_start':  // 开始调用工具
-      console.log(`\n[调用工具: ${event.name}]`)
-      break
-    case 'tool_end':    // 工具执行完成
-      console.log(`[结果: ${event.result}]`)
-      break
-    case 'done':        // 对话完成
-      console.log('\n--- 完成 ---')
-      break
-  }
-}
+const kb = new KnowledgeBase()
+kb.addEntry(createKnowledgeEntry('ARCHITECTURE', '技术栈', 'React + TypeScript + Vite'))
+kb.addEntry(createKnowledgeEntry('ERROR_PATTERN', 'API 调用', '所有 API 调用必须有超时设置'))
+
+console.log(kb.buildKnowledgePrompt())
+// → ## 项目架构\n### 技术栈\nReact + TypeScript + Vite\n\n## 错误避免模式\n...
 ```
 
----
+### ContextManager
 
-## 多轮对话
+Token 预算管理和 prompt 组装：
 
-Agent 自动维护对话历史，支持多轮上下文：
+```js
+import { ContextManager, defaultTokenBudget } from 'lll-web-agent'
 
-```javascript
-const agent = new Agent({
-  provider: 'openai',
-  apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-4',
-  tools: [readFile],
+const cm = new ContextManager()
+const result = cm.assemblePrompt({
+  systemPrompt: '你是一个编程助手',
+  userMessage: '帮我写排序',
+  history: [{ role: 'user', content: '你好' }, { role: 'assistant', content: '你好！' }],
+  filteredTools: myTools,
+  tokenBudget: { ...defaultTokenBudget(), totalTokens: 8000 },
 })
-
-await agent.chat('读一下 package.json')
-// Agent 记住了上一轮的内容
-await agent.chat('这个项目用了什么依赖？')
-
-// 开始新会话
-agent.reset()
-await agent.chat('你好')  // 不记得之前的对话了
+// result.messages → 组装好的 messages 数组
+// result.trimmed → 是否发生了裁剪
 ```
 
----
+### Memory 策略
 
-## 取消请求
+```js
+import { SlidingWindowMemory, SummarizingMemory, TokenAwareMemory } from 'lll-web-agent'
 
-```javascript
-const controller = new AbortController()
+// 滑动窗口（默认）
+const sw = new SlidingWindowMemory(40)
 
-// 5 秒后取消
-setTimeout(() => controller.abort(), 5000)
+// 摘要记忆（超阈值时 LLM 压缩）
+const sm = new SummarizingMemory({
+  threshold: 20,
+  keepRecent: 5,
+  summarizer: async (text) => await myLlmSummarize(text),
+})
 
-try {
-  const reply = await agent.chat('做一个很复杂的分析', {
-    signal: controller.signal,
-  })
-} catch (err) {
-  if (err.name === 'AbortError') {
-    console.log('请求已取消')
-  }
-}
+// Token 感知记忆
+const ta = new TokenAwareMemory(50000)
+
+// 注入到 Agent
+const agent = new Agent({ ..., memory: sm })
 ```
 
----
+### ToolFilter
 
-## 多供应商支持
+```js
+import { ToolFilter, BASE_TOOLS } from 'lll-web-agent'
 
-所有使用 OpenAI 兼容 API 的供应商都可以直接使用：
+const filter = new ToolFilter()
+const filtered = filter.filter(intentResult, allTools)
+// BASE_TOOLS (keyword_search, read_file, write_file, shell_exec, project_tree) 始终保留
+```
 
-```javascript
-// OpenAI
-new Agent({ provider: 'openai', apiKey: '...', model: 'gpt-4' })
+### PlanAndExecute 执行策略
 
-// DeepSeek
-new Agent({ provider: 'deepseek', apiKey: '...', model: 'deepseek-chat' })
+对应 Java 框架的 `PlanAndExecuteStrategy`。适用于复杂多步骤任务，相比 ReAct 的"边思考边行动"，PlanAndExecute 先让 LLM 站在全局视角制定完整计划，然后逐步执行。
 
-// 通义千问
-new Agent({ provider: 'qwen', apiKey: '...', model: 'qwen-turbo' })
+三阶段流程：
+1. **Planning** — 调用 LLM 生成结构化执行计划（JSON 步骤列表）
+2. **Execution** — 对每个步骤使用内部 ReAct 循环执行（支持工具调用）
+3. **Synthesis** — 汇总所有步骤结果，生成最终回答
 
-// X-GROK
-new Agent({ provider: 'x-grok', apiKey: '...', model: 'grok-2' })
+#### 通过 Agent 切换策略
 
-// Moonshot (月之暗面)
-new Agent({ provider: 'moonshot', apiKey: '...', model: 'moonshot-v1-8k' })
+```js
+import { Agent, defineTool } from 'lll-web-agent'
 
-// 智谱 AI
-new Agent({ provider: 'zhipu', apiKey: '...', model: 'glm-4' })
+const readFile = defineTool({ name: 'read_file', description: '读取文件', /* ... */ })
+const writeFile = defineTool({ name: 'write_file', description: '写入文件', /* ... */ })
+const shellExec = defineTool({ name: 'shell_exec', description: '执行命令', /* ... */ })
 
-// 任意 OpenAI 兼容供应商（自定义 URL）
-new Agent({
+// 使用 PlanAndExecute 策略
+const agent = new Agent({
   provider: 'openai',
-  url: 'https://my-proxy.com/v1/chat/completions',
-  apiKey: '...',
-  model: 'my-model',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+  tools: [readFile, writeFile, shellExec],
+  strategy: 'plan_and_execute',          // ← 切换策略
+  planAndExecuteOpts: {                   // ← 可选配置
+    maxPlanSteps: 10,
+    stepMaxRounds: 20,
+    maxReplanAttempts: 2,
+  },
 })
-```
-
-### 注册自定义供应商
 
-```javascript
-import { registerProvider } from 'lll-web-agent/src/providers.js'
-
-registerProvider('my-llm', {
-  url: 'https://api.my-llm.com/v1/chat/completions',
-})
+// 同步对话 — 用法与 ReAct 完全一致
+const reply = await agent.chat('重构项目中所有废弃的 API 调用')
+console.log(reply)
 
-const agent = new Agent({ provider: 'my-llm', apiKey: '...', model: '...' })
+// 流式对话 — 额外推送计划和步骤进度事件
+for await (const event of agent.stream('分析项目架构并生成文档')) {
+  switch (event.type) {
+    case 'phase':         console.log(`[${event.phase}] ${event.message}`); break
+    case 'plan_generated': console.log('计划:', event.plan); break
+    case 'step_start':    console.log(`▶ Step ${event.index + 1}: ${event.description}`); break
+    case 'step_complete':
+      console.log(`${event.success ? '✅' : '❌'} Step ${event.index + 1} (${event.duration}ms)`)
+      break
+    case 'plan_revised':  console.log('计划已修订:', event.plan); break
+    case 'done':          console.log('最终结果:', event.content); break
+  }
+}
 ```
 
----
+#### 动态切换策略
 
-## 全部配置项
-
-```javascript
-new Agent({
-  // 必填
-  provider: 'openai',           // 供应商名称
-  apiKey: 'sk-xxx',             // API Key
+```js
+// 根据任务复杂度动态选择策略
+function chooseStrategy(message) {
+  const complexKeywords = ['重构', '迁移', '分析整个', '批量修改', '全面检查']
+  return complexKeywords.some(k => message.includes(k)) ? 'plan_and_execute' : 'react'
+}
 
-  // 可选
-  model: 'gpt-4',              // 模型名称，默认 'gpt-4'
-  systemPrompt: '你是一个助手',  // 系统提示词，默认 'You are a helpful assistant.'
-  url: 'https://...',           // 自定义 API URL，覆盖供应商默认值
-  tools: [],                    // 工具列表
-  maxRounds: 30,                // 最大 ReAct 轮次，默认 30
-  maxMessages: 40,              // 记忆窗口大小（保留最近 N 条消息），默认 40
-  temperature: 1,               // 温度，默认 1
+const agent = new Agent({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+  tools: [readFile, writeFile, shellExec],
+  strategy: chooseStrategy(userMessage),
 })
 ```
 
----
-
-## 工作原理
+#### 结合意图识别自动选择策略
 
-Agent 内部运行 ReAct（Reasoning + Acting）循环：
+```js
+import { Agent, IntentRecognizer } from 'lll-web-agent'
 
-```
-用户消息 + 工具描述 -> LLM
-                        |
-                  LLM 返回文本？ -> 作为最终回答返回
-                        |
-                  LLM 返回工具调用？
-                        |
-                  执行工具 -> 将结果加入对话历史
-                        |
-                  回到顶部，再次调用 LLM
-```
+// 先用 IntentRecognizer 分析任务复杂度
+const ir = new IntentRecognizer({
+  url: 'https://api.openai.com/v1/chat/completions',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+})
 
-对话历史通过 SlidingWindowMemory 管理，超出窗口大小时自动丢弃最旧的消息（system prompt 始终保留）。
+const intent = await ir.analyze(userMessage, toolNames)
+// intent.recommendedStrategy → 'react' | 'plan_and_execute'
 
----
+const agent = new Agent({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+  tools: myTools,
+  strategy: intent.recommendedStrategy,  // ← 根据意图识别结果选择
+})
 
-## API 参考
+const reply = await agent.chat(userMessage)
+```
 
-### `Agent`
+#### 独立使用 PlanAndExecuteStrategy
 
-| 方法 | 说明 |
-|------|------|
-| `new Agent(opts)` | 创建 Agent 实例 |
-| `agent.chat(message, opts?)` | 同步对话，返回 `Promise<string>` |
-| `agent.stream(message, opts?)` | 流式对话，返回 `AsyncGenerator<Event>` |
-| `agent.reset()` | 清空对话历史，开始新会话 |
+不通过 Agent，直接使用策略类：
 
-### `defineTool(def)`
+```js
+import { PlanAndExecuteStrategy } from 'lll-web-agent'
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `name` | string | 是 | 工具唯一名称 |
-| `description` | string | 是 | 工具描述（供 LLM 理解） |
-| `parameters` | object | 否 | JSON Schema 格式的参数定义 |
-| `execute` | async function | 是 | 执行函数，接收参数对象，返回字符串 |
+const strategy = new PlanAndExecuteStrategy({
+  url: 'https://api.openai.com/v1/chat/completions',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+  tools: [readFile, writeFile, shellExec],
+  maxPlanSteps: 10,
+  stepMaxRounds: 20,
+  maxReplanAttempts: 2,
+
+  // 进度回调
+  onPhase: (phase, msg) => console.log(`[${phase}] ${msg}`),
+  onPlanGenerated: (steps) => {
+    console.log('执行计划:')
+    steps.forEach(s => console.log(`  ${s.index + 1}. ${s.description}`))
+  },
+  onStepStart: (i, desc) => console.log(`▶ 开始步骤 ${i + 1}: ${desc}`),
+  onStepComplete: (i, ok, result) => console.log(`${ok ? '✅' : '❌'} 步骤 ${i + 1}: ${result}`),
+  onPlanRevised: (steps) => console.log('计划已修订，剩余步骤:', steps.length),
+})
 
-### 流式事件类型
+// 同步执行
+const { content, plan } = await strategy.execute('将项目从 CommonJS 迁移到 ESM')
+console.log('最终结果:', content)
+console.log('计划步骤:', plan.map(s => `${s.status} - ${s.description}`))
 
-| type | 字段 | 说明 |
-|------|------|------|
-| `delta` | `content` | LLM 文本增量 |
-| `tool_start` | `name`, `arguments` | 开始调用工具 |
-| `tool_end` | `name`, `result` | 工具执行完成 |
-| `done` | `content` | 对话完成，包含完整回复 |
+// 流式执行
+for await (const event of strategy.stream('批量修复所有 lint 错误')) {
+  console.log(event)
+}
+```
 
----
+#### PlanAndExecute 配置参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `maxPlanSteps` | `35` | 计划步骤上限 |
+| `stepMaxRounds` | `300` | 单个步骤内 ReAct 循环最大轮次 |
+| `maxReplanAttempts` | `2` | 步骤失败时最大重规划次数 |
+| `planningTimeoutMs` | `120000` | 规划阶段 LLM 调用超时（毫秒） |
+| `synthesisTimeoutMs` | `120000` | 合成阶段 LLM 调用超时（毫秒） |
+| `onPhase` | - | 阶段变更回调 `(phase, message) => void` |
+| `onPlanGenerated` | - | 计划生成回调 `(steps) => void` |
+| `onStepStart` | - | 步骤开始回调 `(index, description) => void` |
+| `onStepComplete` | - | 步骤完成回调 `(index, success, result) => void` |
+| `onPlanRevised` | - | 计划修订回调 `(steps) => void` |
+
+#### 流式事件类型
+
+| 事件 type | 字段 | 说明 |
+|-----------|------|------|
+| `phase` | `phase`, `message` | 阶段变更（planning / executing / synthesizing / completed / fallback） |
+| `plan_generated` | `plan` | 计划生成完成 |
+| `step_start` | `index`, `description` | 步骤开始执行 |
+| `step_complete` | `index`, `success`, `result`, `duration` | 步骤执行完成 |
+| `plan_revised` | `plan` | 计划被修订（步骤失败后重规划） |
+| `done` | `content`, `plan` | 全部完成，包含最终结果和计划快照 |
+
+## 与 Java Runtime 的对应关系
+
+| JS SDK | Java Runtime | 说明 |
+|--------|-------------|------|
+| `Agent` | `Agent + AgentBuilder + AgentRuntime` | 高层 API |
+| `Agent({ strategy: 'react' })` | `ReActStrategy` | ReAct 执行策略（默认） |
+| `Agent({ strategy: 'plan_and_execute' })` | `PlanAndExecuteStrategy` | Plan & Execute 执行策略 |
+| `PlanAndExecuteStrategy` | `PlanAndExecuteStrategy` | 独立使用的策略类 |
+| `PlanStep` / `StepStatus` | `PlanStep` / `PlanStep.Status` | 计划步骤模型 |
+| `IntentRecognizer` | `fc.runtime.IntentRecognizer` | sidecar 意图识别 |
+| `ToolFilter` | `fc.runtime.ToolFilter` | 工具过滤 |
+| `ContextManager` | `fc.state.ContextManager` | prompt 组装 + token 预算 |
+| `KnowledgeBase` | `fc.runtime.KnowledgeBase` | 知识库管理 |
+| `SlidingWindowMemory` | `fc.memory.SlidingWindowMemory` | 滑动窗口记忆 |
+| `SummarizingMemory` | `fc.memory.SummarizingMemory` | 摘要记忆 |
+| `TokenAwareMemory` | `fc.memory.AdaptiveMemory` | token 感知记忆 |
+| `streamChat / syncChat` | `LlmClient` | LLM 通信 |
+| `defineTool` | `Tool` 接口 | 工具定义 |
+| `resolveProviderUrl` | `LlmProviderAdapterRegistry` | 供应商适配 |
+
+## 浏览器使用
+
+```html
+<script src="https://unpkg.com/lll-web-agent/dist/lll-web-agent.min.js"></script>
+<script>
+  const { Agent, defineTool, KnowledgeBase } = LllWebAgent
+  // ...
+</script>
+```
 
 ## License