lll-web-agent 0.1.0

package/README.md

@@ -0,0 +1,396 @@
+# lll-web-agent
+
+开箱即用的 LLM Agent SDK。配个 API Key，定义几个工具，就能跑起一个完整的 AI Agent。
+
+零依赖。支持 OpenAI / DeepSeek / 通义千问 / X-GROK / Moonshot / 智谱 等所有 OpenAI 兼容供应商。
+
+## 安装
+
+```bash
+npm install lll-web-agent
+```
+
+要求 Node.js >= 18（使用内置 fetch API）。
+
+## 30 秒上手
+
+```javascript
+import { Agent } from 'lll-web-agent'
+
+const agent = new Agent({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+})
+
+const reply = await agent.chat('你好，介绍一下你自己')
+console.log(reply)
+```
+
+就这么多。不需要配置 HTTP 客户端、不需要处理 SSE 解析、不需要理解 ReAct 循环。
+
+---
+
+## 注册工具
+
+工具是 Agent 与外部世界交互的方式。LLM 会根据工具描述自主决定何时调用哪个工具。
+
+### 基本用法
+
+```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
+const agent = new Agent({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+  tools: [getCurrentTime],
+})
+
+// 3. Agent 会自动决定是否调用工具
+const reply = await agent.chat('现在几点了？')
+// Agent 内部流程：
+//   LLM 思考 -> 决定调用 get_current_time -> 执行 -> 拿到时间 -> 继续思考 -> 返回最终回答
+```
+
+### 带参数的工具
+
+```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 会看到并处理
+    }
+  },
+})
+```
+
+### 多个工具协作
+
+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],  // 注册多个工具
+})
+
+// Agent 会先调用 list_files 看有哪些文件，再调用 read_file 读取感兴趣的文件
+const reply = await agent.chat('看看当前目录有什么文件，读一下 package.json 的内容')
+```
+
+### 工具的 execute 函数规范
+
+```javascript
+defineTool({
+  name: 'my_tool',
+  description: '...',
+  parameters: { ... },
+  execute: async (params) => {
+    // params 是 LLM 传入的参数对象，结构与 parameters 定义一致
+    // 必须返回字符串（LLM 只能理解文本）
+    // 如果返回对象，会被自动 JSON.stringify
+    // 抛出异常时，错误信息会被发送给 LLM，LLM 可能会重试或换一种方式
+    return '执行结果'
+  },
+})
+```
+
+### 实用工具示例
+
+```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}`
+    }
+  },
+})
+
+// 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 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})`)())
+  },
+})
+```
+
+---
+
+## 流式输出
+
+通过 async generator 实时获取 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
+  }
+}
+```
+
+---
+
+## 多轮对话
+
+Agent 自动维护对话历史，支持多轮上下文：
+
+```javascript
+const agent = new Agent({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+  tools: [readFile],
+})
+
+await agent.chat('读一下 package.json')
+// Agent 记住了上一轮的内容
+await agent.chat('这个项目用了什么依赖？')
+
+// 开始新会话
+agent.reset()
+await agent.chat('你好')  // 不记得之前的对话了
+```
+
+---
+
+## 取消请求
+
+```javascript
+const controller = new AbortController()
+
+// 5 秒后取消
+setTimeout(() => controller.abort(), 5000)
+
+try {
+  const reply = await agent.chat('做一个很复杂的分析', {
+    signal: controller.signal,
+  })
+} catch (err) {
+  if (err.name === 'AbortError') {
+    console.log('请求已取消')
+  }
+}
+```
+
+---
+
+## 多供应商支持
+
+所有使用 OpenAI 兼容 API 的供应商都可以直接使用：
+
+```javascript
+// OpenAI
+new Agent({ provider: 'openai', apiKey: '...', model: 'gpt-4' })
+
+// DeepSeek
+new Agent({ provider: 'deepseek', apiKey: '...', model: 'deepseek-chat' })
+
+// 通义千问
+new Agent({ provider: 'qwen', apiKey: '...', model: 'qwen-turbo' })
+
+// X-GROK
+new Agent({ provider: 'x-grok', apiKey: '...', model: 'grok-2' })
+
+// Moonshot (月之暗面)
+new Agent({ provider: 'moonshot', apiKey: '...', model: 'moonshot-v1-8k' })
+
+// 智谱 AI
+new Agent({ provider: 'zhipu', apiKey: '...', model: 'glm-4' })
+
+// 任意 OpenAI 兼容供应商（自定义 URL）
+new Agent({
+  provider: 'openai',
+  url: 'https://my-proxy.com/v1/chat/completions',
+  apiKey: '...',
+  model: 'my-model',
+})
+```
+
+### 注册自定义供应商
+
+```javascript
+import { registerProvider } from 'lll-web-agent/src/providers.js'
+
+registerProvider('my-llm', {
+  url: 'https://api.my-llm.com/v1/chat/completions',
+})
+
+const agent = new Agent({ provider: 'my-llm', apiKey: '...', model: '...' })
+```
+
+---
+
+## 全部配置项
+
+```javascript
+new Agent({
+  // 必填
+  provider: 'openai',           // 供应商名称
+  apiKey: 'sk-xxx',             // API Key
+
+  // 可选
+  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
+})
+```
+
+---
+
+## 工作原理
+
+Agent 内部运行 ReAct（Reasoning + Acting）循环：
+
+```
+用户消息 + 工具描述 -> LLM
+                        |
+                  LLM 返回文本？ -> 作为最终回答返回
+                        |
+                  LLM 返回工具调用？
+                        |
+                  执行工具 -> 将结果加入对话历史
+                        |
+                  回到顶部，再次调用 LLM
+```
+
+对话历史通过 SlidingWindowMemory 管理，超出窗口大小时自动丢弃最旧的消息（system prompt 始终保留）。
+
+---
+
+## API 参考
+
+### `Agent`
+
+| 方法 | 说明 |
+|------|------|
+| `new Agent(opts)` | 创建 Agent 实例 |
+| `agent.chat(message, opts?)` | 同步对话，返回 `Promise<string>` |
+| `agent.stream(message, opts?)` | 流式对话，返回 `AsyncGenerator<Event>` |
+| `agent.reset()` | 清空对话历史，开始新会话 |
+
+### `defineTool(def)`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 工具唯一名称 |
+| `description` | string | 是 | 工具描述（供 LLM 理解） |
+| `parameters` | object | 否 | JSON Schema 格式的参数定义 |
+| `execute` | async function | 是 | 执行函数，接收参数对象，返回字符串 |
+
+### 流式事件类型
+
+| type | 字段 | 说明 |
+|------|------|------|
+| `delta` | `content` | LLM 文本增量 |
+| `tool_start` | `name`, `arguments` | 开始调用工具 |
+| `tool_end` | `name`, `result` | 工具执行完成 |
+| `done` | `content` | 对话完成，包含完整回复 |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "lll-web-agent",
+  "version": "0.1.0",
+  "description": "开箱即用的 LLM Agent SDK — 配个 API Key 就能跑",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "example": "node examples/basic.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["agent", "llm", "openai", "deepseek", "anthropic", "qwen", "function-calling", "react-loop", "tool-use"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/src/agent.js

@@ -0,0 +1,213 @@
+/**
+ * Agent — 开箱即用的 LLM Agent
+ * 对应 Java 框架的 Agent + AgentBuilder + ReActStrategy
+ *
+ * 用法：
+ *   const agent = new Agent({
+ *     provider: 'openai',
+ *     apiKey: 'sk-xxx',
+ *     model: 'gpt-4',
+ *     tools: [readFile, shellExec],
+ *   })
+ *   const reply = await agent.chat('帮我分析项目架构')
+ */
+
+import { streamChat, syncChat } from './llm-client.js'
+import { formatToolsForOpenAI, parseToolCalls, formatToolResult } from './tool.js'
+import { SlidingWindowMemory } from './memory.js'
+import { resolveProviderUrl } from './providers.js'
+
+export class Agent {
+  /**
+   * @param {object} opts
+   * @param {string} opts.provider - 供应商名称 ('openai', 'deepseek', 'qwen', ...)
+   * @param {string} opts.apiKey - API Key
+   * @param {string} [opts.model='gpt-4'] - 模型名称
+   * @param {string} [opts.systemPrompt='You are a helpful assistant.'] - 系统提示词
+   * @param {string} [opts.url] - 自定义 API URL（覆盖供应商默认值）
+   * @param {import('./tool.js').ToolDef[]} [opts.tools=[]] - 工具列表
+   * @param {number} [opts.maxRounds=30] - 最大 ReAct 轮次
+   * @param {number} [opts.maxMessages=40] - 记忆窗口大小
+   * @param {number} [opts.temperature=1] - 温度
+   */
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error('apiKey is required')
+    if (!opts.provider) throw new Error('provider is required')
+
+    this.apiKey = opts.apiKey
+    this.model = opts.model ?? 'gpt-4'
+    this.systemPrompt = opts.systemPrompt ?? 'You are a helpful assistant.'
+    this.url = resolveProviderUrl(opts.provider, opts.url)
+    this.tools = opts.tools ?? []
+    this.maxRounds = opts.maxRounds ?? 30
+    this.temperature = opts.temperature ?? 1
+    this.memory = new SlidingWindowMemory(opts.maxMessages ?? 40)
+
+    // 初始化 system prompt
+    this.memory.add({ role: 'system', content: this.systemPrompt })
+  }
+
+  /**
+   * 同步对话 — 发送消息，返回最终回复文本
+   * 内部执行完整的 ReAct 循环（LLM 思考 -> 调用工具 -> 观察结果 -> 继续）
+   * @param {string} message - 用户消息
+   * @param {object} [opts]
+   * @param {AbortSignal} [opts.signal] - 取消信号
+   * @returns {Promise<string>} Agent 最终回复
+   */
+  async chat(message, opts = {}) {
+    this.memory.add({ role: 'user', content: message })
+    return this._reactLoop(opts)
+  }
+
+  /**
+   * 流式对话 — 通过 async generator 实时推送内容
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {AbortSignal} [opts.signal]
+   * @yields {{ type: 'delta'|'tool_start'|'tool_end'|'done', ... }}
+   */
+  async *stream(message, opts = {}) {
+    this.memory.add({ role: 'user', content: message })
+    yield* this._reactLoopStream(opts)
+  }
+
+  /** 清空对话历史，开始新会话 */
+  reset() {
+    this.memory.clear()
+    this.memory.add({ role: 'system', content: this.systemPrompt })
+  }
+
+  // ---- ReAct 循环（非流式） ----
+
+  async _reactLoop({ signal } = {}) {
+    const toolMap = Object.fromEntries(this.tools.map(t => [t.name, t]))
+    const openaiTools = this.tools.length > 0 ? formatToolsForOpenAI(this.tools) : undefined
+
+    for (let round = 0; round < this.maxRounds; round++) {
+      signal?.throwIfAborted()
+
+      const body = {
+        model: this.model,
+        messages: this.memory.getMessages(),
+        temperature: this.temperature,
+      }
+      if (openaiTools) body.tools = openaiTools
+
+      // 调用 LLM
+      const response = await syncChat({ url: this.url, apiKey: this.apiKey, body, signal })
+
+      const message = response.choices?.[0]?.message
+      if (!message) throw new Error('Empty LLM response')
+
+      const textContent = message.content ?? ''
+      const toolCalls = parseToolCalls(response)
+
+      // 没有工具调用 = LLM 给出了最终回答
+      if (toolCalls.length === 0) {
+        this.memory.add({ role: 'assistant', content: textContent })
+        return textContent
+      }
+
+      // 将 assistant 消息（含 tool_calls）加入历史
+      this.memory.add({
+        role: 'assistant',
+        content: textContent || null,
+        tool_calls: message.tool_calls,
+      })
+
+      // 执行所有工具调用
+      for (const call of toolCalls) {
+        const tool = toolMap[call.name]
+        let result
+        if (!tool) {
+          result = `Error: Tool "${call.name}" not found. Available: ${this.tools.map(t => t.name).join(', ')}`
+        } else {
+          try {
+            result = await tool.execute(call.arguments)
+          } catch (err) {
+            result = `Error executing ${call.name}: ${err.message}`
+          }
+        }
+        this.memory.add(formatToolResult(call.id, call.name, result))
+      }
+    }
+
+    return '[max rounds exceeded]'
+  }
+
+  // ---- ReAct 循环（流式） ----
+
+  async *_reactLoopStream({ signal } = {}) {
+    const toolMap = Object.fromEntries(this.tools.map(t => [t.name, t]))
+    const openaiTools = this.tools.length > 0 ? formatToolsForOpenAI(this.tools) : undefined
+
+    for (let round = 0; round < this.maxRounds; round++) {
+      signal?.throwIfAborted()
+
+      const body = {
+        model: this.model,
+        messages: this.memory.getMessages(),
+        temperature: this.temperature,
+      }
+      if (openaiTools) body.tools = openaiTools
+
+      // 流式调用 LLM
+      let fullText = ''
+      const response = await streamChat({
+        url: this.url,
+        apiKey: this.apiKey,
+        body,
+        signal,
+        onDelta: (delta) => {
+          fullText += delta
+          // 不在这里 yield，因为 onDelta 不是 generator 上下文
+        },
+      })
+
+      const textContent = response.choices?.[0]?.message?.content ?? ''
+      const toolCalls = parseToolCalls(response)
+
+      // 推送文本内容
+      if (textContent) {
+        yield { type: 'delta', content: textContent }
+      }
+
+      // 没有工具调用 = 最终回答
+      if (toolCalls.length === 0) {
+        this.memory.add({ role: 'assistant', content: textContent })
+        yield { type: 'done', content: textContent }
+        return
+      }
+
+      // 将 assistant 消息加入历史
+      this.memory.add({
+        role: 'assistant',
+        content: textContent || null,
+        tool_calls: response.choices[0].message.tool_calls,
+      })
+
+      // 执行工具
+      for (const call of toolCalls) {
+        yield { type: 'tool_start', name: call.name, arguments: call.arguments }
+
+        const tool = toolMap[call.name]
+        let result
+        if (!tool) {
+          result = `Error: Tool "${call.name}" not found`
+        } else {
+          try {
+            result = await tool.execute(call.arguments)
+          } catch (err) {
+            result = `Error: ${err.message}`
+          }
+        }
+
+        this.memory.add(formatToolResult(call.id, call.name, result))
+        yield { type: 'tool_end', name: call.name, result }
+      }
+    }
+
+    yield { type: 'done', content: '[max rounds exceeded]' }
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { Agent } from './agent.js'
+export { defineTool } from './tool.js'

package/src/llm-client.js

@@ -0,0 +1,138 @@
+/**
+ * LLM 通信层 — SSE 流式请求 + 工具调用增量拼接
+ * 对应 Java 框架的 LlmClient + SseStreamProcessor + StreamingFcCollector
+ */
+
+/**
+ * 发送 SSE 流式请求，返回完整的非流式等价响应 JSON
+ * @param {object} opts
+ * @param {string} opts.url - API endpoint
+ * @param {string} opts.apiKey - Bearer token
+ * @param {object} opts.body - 请求体（含 messages, model, tools 等）
+ * @param {AbortSignal} [opts.signal] - 取消信号
+ * @param {function} [opts.onDelta] - 文本增量回调 (delta: string) => void
+ * @param {function} [opts.onReasoning] - 思考过程增量回调
+ * @param {function} [opts.onToolCall] - 工具调用增量回调 (index, toolCall) => void
+ * @returns {Promise<object>} 重构后的非流式响应 JSON
+ */
+export async function streamChat({ url, apiKey, body, signal, onDelta, onReasoning, onToolCall }) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ ...body, stream: true }),
+    signal,
+  })
+
+  if (!response.ok) {
+    const errorBody = await response.text().catch(() => '')
+    throw new LlmApiError(response.status, errorBody)
+  }
+
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  // StreamingFcCollector 等价物
+  const collected = { content: '', reasoning: '', toolCalls: new Map() }
+
+  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) {
+      if (!line.startsWith('data:')) continue
+      const data = line.slice(5).trim()
+      if (data === '[DONE]' || !data) continue
+
+      try {
+        const json = JSON.parse(data)
+        processSSEChunk(json, collected, { onDelta, onReasoning, onToolCall })
+      } catch { /* 忽略解析失败的行 */ }
+    }
+  }
+
+  return reconstructResponse(collected)
+}
+
+/**
+ * 同步请求（非流式）
+ */
+export async function syncChat({ url, apiKey, body, signal }) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ ...body, stream: false }),
+    signal,
+  })
+
+  if (!response.ok) {
+    const errorBody = await response.text().catch(() => '')
+    throw new LlmApiError(response.status, errorBody)
+  }
+
+  return response.json()
+}
+
+/** 处理单个 SSE chunk — 对应 SseStreamProcessor.processOpenAiLine */
+function processSSEChunk(json, collected, callbacks) {
+  const delta = json.choices?.[0]?.delta
+  if (!delta) return
+
+  if (delta.reasoning_content) {
+    collected.reasoning += delta.reasoning_content
+    callbacks.onReasoning?.(delta.reasoning_content)
+  }
+
+  if (delta.content) {
+    collected.content += delta.content
+    callbacks.onDelta?.(delta.content)
+  }
+
+  if (delta.tool_calls) {
+    for (const tc of delta.tool_calls) {
+      const idx = tc.index ?? 0
+      if (!collected.toolCalls.has(idx)) {
+        collected.toolCalls.set(idx, { id: '', type: 'function', name: '', arguments: '' })
+      }
+      const acc = collected.toolCalls.get(idx)
+      if (tc.id) acc.id = tc.id
+      if (tc.type) acc.type = tc.type
+      if (tc.function?.name) acc.name = tc.function.name
+      if (tc.function?.arguments) acc.arguments += tc.function.arguments
+      callbacks.onToolCall?.(idx, acc)
+    }
+  }
+}
+
+/** 重构为非流式等价响应 — 对应 StreamingFcCollector.reconstructResponse */
+function reconstructResponse(collected) {
+  const message = {}
+  if (collected.content) message.content = collected.content
+  if (collected.reasoning) message.reasoning_content = collected.reasoning
+  if (collected.toolCalls.size > 0) {
+    message.tool_calls = [...collected.toolCalls.values()].map(tc => ({
+      id: tc.id,
+      type: tc.type,
+      function: { name: tc.name, arguments: tc.arguments },
+    }))
+  }
+  return { choices: [{ message }] }
+}
+
+export class LlmApiError extends Error {
+  constructor(status, body) {
+    super(`LLM API error ${status}: ${body.slice(0, 200)}`)
+    this.status = status
+    this.body = body
+  }
+}

package/src/memory.js

@@ -0,0 +1,40 @@
+/**
+ * 对话记忆 — 对应 Java 框架的 SlidingWindowMemory
+ * 保留 system prompt + 最近 N 条消息，超出时丢弃最旧的
+ */
+export class SlidingWindowMemory {
+  /** @param {number} maxMessages 最大消息数（不含 system prompt） */
+  constructor(maxMessages = 40) {
+    this.maxMessages = maxMessages
+    this.messages = []
+  }
+
+  add(message) {
+    this.messages.push(message)
+    this._trim()
+  }
+
+  addAll(messages) {
+    this.messages.push(...messages)
+    this._trim()
+  }
+
+  /** 返回当前应发送给 LLM 的消息列表 */
+  getMessages() {
+    return [...this.messages]
+  }
+
+  clear() {
+    this.messages = []
+  }
+
+  _trim() {
+    // 保留 system 消息 + 最近 maxMessages 条非 system 消息
+    const system = this.messages.filter(m => m.role === 'system')
+    const nonSystem = this.messages.filter(m => m.role !== 'system')
+    if (nonSystem.length > this.maxMessages) {
+      const trimmed = nonSystem.slice(-this.maxMessages)
+      this.messages = [...system, ...trimmed]
+    }
+  }
+}

package/src/providers.js

@@ -0,0 +1,54 @@
+/**
+ * 供应商适配 — 对应 Java 框架的 LlmProviderAdapterRegistry
+ * 处理不同供应商的 API URL 差异
+ */
+
+const PROVIDERS = {
+  openai: {
+    url: 'https://api.openai.com/v1/chat/completions',
+  },
+  deepseek: {
+    url: 'https://api.deepseek.com/chat/completions',
+  },
+  anthropic: {
+    url: 'https://api.anthropic.com/v1/messages',
+    // Anthropic 使用不同的认证头和消息格式，暂不在 MVP 中支持
+    // 后续版本添加 AnthropicProtocolAdapter
+  },
+  qwen: {
+    url: 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
+  },
+  'x-grok': {
+    url: 'https://api.x.ai/v1/chat/completions',
+  },
+  moonshot: {
+    url: 'https://api.moonshot.cn/v1/chat/completions',
+  },
+  zhipu: {
+    url: 'https://open.bigmodel.cn/api/paas/v4/chat/completions',
+  },
+}
+
+/**
+ * 解析供应商配置，返回 API URL
+ * @param {string} provider - 供应商名称（不区分大小写）
+ * @param {string} [customUrl] - 自定义 URL（优先级最高）
+ * @returns {string} API URL
+ */
+export function resolveProviderUrl(provider, customUrl) {
+  if (customUrl) return customUrl
+  const key = provider.toLowerCase()
+  const config = PROVIDERS[key]
+  if (!config) {
+    // 未知供应商，假设是 OpenAI 兼容格式，用户必须提供 url
+    throw new Error(
+      `Unknown provider "${provider}". Either use a known provider (${Object.keys(PROVIDERS).join(', ')}) or provide a custom url.`
+    )
+  }
+  return config.url
+}
+
+/** 注册自定义供应商 */
+export function registerProvider(name, config) {
+  PROVIDERS[name.toLowerCase()] = config
+}

package/src/tool.js

@@ -0,0 +1,80 @@
+/**
+ * Tool 定义 — 对应 Java 框架的 Tool 接口
+ *
+ * 用法：
+ *   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')
+ *       return await fs.readFile(path, 'utf-8')
+ *     },
+ *   })
+ */
+
+/**
+ * @typedef {object} ToolDef
+ * @property {string} name - 工具唯一名称
+ * @property {string} description - 工具描述（供 LLM 理解）
+ * @property {object} parameters - JSON Schema 格式的参数定义
+ * @property {(params: object, context?: object) => Promise<string>} execute - 执行函数
+ */
+
+/**
+ * 定义一个工具
+ * @param {ToolDef} def
+ * @returns {ToolDef}
+ */
+export function defineTool(def) {
+  if (!def.name) throw new Error('Tool name is required')
+  if (!def.description) throw new Error('Tool description is required')
+  if (!def.execute) throw new Error('Tool execute function is required')
+  return {
+    name: def.name,
+    description: def.description,
+    parameters: def.parameters ?? { type: 'object', properties: {} },
+    execute: def.execute,
+  }
+}
+
+/** 将 Tool 列表转换为 OpenAI tools 格式 */
+export function formatToolsForOpenAI(tools) {
+  return tools.map(t => ({
+    type: 'function',
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  }))
+}
+
+/** 从 LLM 响应中解析工具调用 */
+export function parseToolCalls(response) {
+  const message = response.choices?.[0]?.message
+  if (!message?.tool_calls?.length) return []
+  return message.tool_calls.map(tc => ({
+    id: tc.id,
+    name: tc.function.name,
+    arguments: safeParseJSON(tc.function.arguments),
+  }))
+}
+
+/** 将工具执行结果格式化为对话消息 */
+export function formatToolResult(callId, toolName, result) {
+  return {
+    role: 'tool',
+    tool_call_id: callId,
+    name: toolName,
+    content: typeof result === 'string' ? result : JSON.stringify(result),
+  }
+}
+
+function safeParseJSON(str) {
+  try { return JSON.parse(str) } catch { return {} }
+}