foliko 1.0.73 → 1.0.74

package/docs/ai-sdk-optimization.md

@@ -43,118 +43,50 @@
 
 ### 🔴 【高优先级】
 
-#### 2.1 结构化输出 - `generateObject` / `streamObject`
+#### ✅ 2.1 结构化输出 - `generateObject` / `streamObject` **[已完成]**
 
 **现状**：项目使用 `generateText` 进行总结，但未使用结构化输出
 
 **优化位置**：`src/core/agent-chat.js`
 
-**建议新增**：
-
-```javascript
-// 2.1.1 意图识别
-async _classifyIntent(message) {
-  const { generateObject } = require('ai')
-  
-  const { object } = await generateObject({
-    model: this._aiClient,
-    schema: z.object({
-      intent: z.enum([
-        'create', 'read', 'update', 'delete', 
-        'query', 'execute', 'explain', 'unknown'
-      ]),
-      confidence: z.number().min(0).max(1),
-      entities: z.array(z.object({
-        name: z.string(),
-        type: z.string(),
-        value: z.any()
-      })).optional(),
-      suggestedTools: z.array(z.string()).optional()
-    }),
-    prompt: `分析用户消息的意图：${message}`
-  })
-  
-  return object
-}
-
-// 2.1.2 结构化任务解析
-async _parseStructuredTask(message) {
-  const { generateObject } = require('ai')
-  
-  const { object } = await generateObject({
-    model: this._aiClient,
-    schema: z.object({
-      taskType: z.enum(['simple', 'multi-step', 'parallel', 'conditional']),
-      steps: z.array(z.object({
-        action: z.string(),
-        tool: z.string().optional(),
-        parameters: z.record(z.any()).optional(),
-        dependsOn: z.array(z.number()).optional()
-      })),
-      estimatedComplexity: z.number().min(1).max(10)
-    }),
-    prompt: `将任务分解为结构化步骤：${message}`
-  })
-  
-  return object
-}
-```
+**已实现功能**：
+- ✅ `IntentClassificationSchema` - 意图识别 Zod Schema
+- ✅ `TaskStructuredSchema` - 任务结构化解析 Schema  
+- ✅ `SummarySchema` - 摘要生成 Schema
+- ✅ `_classifyIntent()` - 意图分类方法
+- ✅ `_parseStructuredTask()` - 任务结构化解析方法
+- ✅ `_summarizeMessages()` - 智能摘要方法（使用结构化输出）
+- ✅ `configureIntentClassification()` - 意图识别配置方法
+- ✅ `getLastIntent()` - 获取上次意图识别结果
+- ✅ `getCacheStatus()` - 缓存状态查询
 
 **收益**：
 - 输出类型安全，减少解析错误
 - 支持智能意图路由
 - 为任务分解提供结构化基础
+- 可根据意图自动调整 `maxSteps`
 
 ---
 
-#### 2.2 Prompt Caching 集成
+#### ✅ 2.2 Prompt Caching 集成 **[已完成]**
 
 **现状**：使用 tiktoken 手动计算 token，未利用 AI SDK 原生缓存
 
 **优化位置**：`src/core/agent-chat.js`
 
-**建议修改**：
-
-```javascript
-// 2.2.1 新增导入
-const { cachePrompt, smoothStream } = require('ai')
-
-// 2.2.2 修改 _buildSystemPrompt - 添加缓存标记
-_buildSystemPrompt() {
-  const parts = []
-  parts.push(this._originalPrompt)
-  // ... 其他部分
-  
-  // 使用 cachePrompt 标记可缓存内容
-  const cacheableContent = parts.join('\n\n')
-  this._cachedSystemPrompt = cachePrompt(cacheableContent, {
-    cachePrefix: `system-${this.agent.name}`,
-    maxAgeMs: 1000 * 60 * 60  // 1小时
-  })
-  
-  return this._cachedSystemPrompt
-}
-
-// 2.2.3 在 chat() 中使用缓存
-async chat(message, options = {}) {
-  // ...
-  
-  // 使用缓存的 system prompt
-  const cachedSystem = this._cachedSystemPrompt || this._systemPrompt
-  
-  const agent = new ToolLoopAgent({
-    model: this._aiClient,
-    instructions: cachedSystem,  // 使用缓存版本
-    tools: tools,
-    stopWhen: (step) => step.stepCount >= maxSteps
-  })
-}
-```
+**已实现功能**：
+- ✅ `_supportsPromptCache()` - 检测模型是否支持 Prompt Caching
+- ✅ `_buildSystemPrompt()` - 构建可缓存的系统提示
+- ✅ `_applyPromptCacheToMessages()` - 应用缓存标记到消息
+- ✅ `_getSystemPrompt()` - 获取缓存的系统提示
+- ✅ `configurePromptCache()` - Prompt Cache 配置方法
+- ✅ `getCacheStatus()` - 缓存状态查询
 
 **收益**：
 - 降低 30-50% token 消耗
 - 加快响应速度
 - 减少 API 调用成本
+- 支持模型自动检测
 
 ---
 
@@ -557,29 +489,33 @@ async executeToolWithConfirmation(toolName, args) {
 
 ## 三、优化优先级汇总
 
-| 优先级 | 优化项 | 收益 | 影响范围 | 工作量 |
-|--------|--------|------|----------|--------|
-| 🔴 高 | `generateObject` 意图识别 | 类型安全、智能路由 | `agent-chat.js` | 1天 |
-| 🔴 高 | Prompt Caching | 降低30% token消耗 | `agent-chat.js` | 0.5天 |
-| 🟡 中 | `smoothStream` 流式增强 | 更流畅体验 | `agent-chat.js` | 0.5天 |
-| 🟡 中 | 推理模型支持 | o1/R1 优化 | `provider.js`, `agent-chat.js` | 1天 |
-| 🟡 中 | 中间件系统 | 统一监控/日志 | 新建 `middleware/` | 2天 |
-| 🟡 中 | Embeddings | RAG 基础 | `ai-plugin.js` | 1天 |
-| 🟢 低 | 错误处理增强 | 更健壮 | `agent-chat.js` | 0.5天 |
-| 🟢 低 | MCP Elicitation | 用户控制 | `mcp-executor.js` | 1天 |
+| 优先级 | 优化项 | 状态 | 收益 | 影响范围 |
+|--------|--------|------|------|----------|
+| 🔴 高 | `generateObject` 意图识别 | ✅ 已完成 | 类型安全、智能路由 | `agent-chat.js` |
+| 🔴 高 | Prompt Caching | ✅ 已完成 | 降低30% token消耗 | `agent-chat.js` |
+| 🟡 中 | `smoothStream` 流式增强 | 待做 | 更流畅体验 | `agent-chat.js` |
+| 🟡 中 | 推理模型支持 | 待做 | o1/R1 优化 | `provider.js`, `agent-chat.js` |
+| 🟡 中 | 中间件系统 | 待做 | 统一监控/日志 | 新建 `middleware/` |
+| 🟡 中 | Embeddings | 待做 | RAG 基础 | `ai-plugin.js` |
+| 🟢 低 | 错误处理增强 | 待做 | 更健壮 | `agent-chat.js` |
+| 🟢 低 | MCP Elicitation | 待做 | 用户控制 | `mcp-executor.js` |
 
 ---
 
 ## 四、实施路线图
 
-### 第一阶段（立即可做）
+### 第一阶段（立即可做）- ✅ 已完成
 
 ```
 ✅ generateObject 意图识别
    └── 在 agent-chat.js 新增 _classifyIntent() 方法
+   └── 新增 IntentClassificationSchema, TaskStructuredSchema, SummarySchema
+   └── 新增 configureIntentClassification(), getLastIntent(), getCacheStatus()
    
 ✅ Prompt Caching 集成
-   └── 在 _buildSystemPrompt() 中使用 cachePrompt()
+   └── 在 _buildSystemPrompt() 中使用缓存机制
+   └── 新增 _supportsPromptCache(), _applyPromptCacheToMessages()
+   └── 新增 configurePromptCache() 配置方法
 ```
 
 ### 第二阶段（1周内）
@@ -610,7 +546,77 @@ async executeToolWithConfirmation(toolName, args) {
 
 ---
 
-## 五、需要安装的包
+## 五、新增配置选项
+
+### 意图识别配置
+
+```javascript
+const agent = new AgentChatHandler(agent, {
+  // 意图识别（默认开启）
+  enableIntentClassification: true,
+  // 可选：用于意图识别的专用模型
+  intentModel: openai('gpt-4o-mini')
+})
+
+// 运行时配置
+agent.configureIntentClassification({
+  enabled: true,
+  model: openai('gpt-4o-mini')
+})
+
+// 获取上次意图识别结果
+const intent = agent.getLastIntent()
+// { intent: 'create', confidence: 0.95, entities: [...], suggestedTools: [...] }
+```
+
+### Prompt Caching 配置
+
+```javascript
+const agent = new AgentChatHandler(agent, {
+  // Prompt Caching（默认开启）
+  enablePromptCache: true,
+  // 缓存有效期（默认 1 小时）
+  cacheMaxAgeMs: 1000 * 60 * 60
+})
+
+// 运行时配置
+agent.configurePromptCache({
+  enabled: true,
+  maxAgeMs: 1000 * 60 * 30  // 30 分钟
+})
+
+// 查看缓存状态
+const status = agent.getCacheStatus()
+// { promptCache: { enabled: true, supported: true, ... }, intentClassification: {...} }
+```
+
+### chat() / chatStream() 返回值变化
+
+```javascript
+// chat() 返回值新增 intent 字段
+const result = await agent.chat("帮我创建一个文件")
+// { success: true, message: "...", stepCount: 3, intent: { intent: 'create', confidence: 0.9, ... } }
+
+// chatStream() 支持接收 intent 事件
+for await (const chunk of agent.chatStream("查询天气")) {
+  if (chunk.type === 'intent') {
+    console.log('意图:', chunk.intent)  // { intent: 'query', confidence: 0.95, ... }
+  }
+}
+
+// 监听意图识别事件
+agent.on('intent-classified', ({ message, intent }) => {
+  console.log(`消息 "${message}" 被识别为: ${intent.intent}`)
+})
+
+agent.on('intent-detected', ({ message, intent }) => {
+  console.log(`流式模式检测到意图: ${intent.intent}`)
+})
+```
+
+---
+
+## 六、需要安装的包
 
 ```bash
 # 基础已安装
@@ -624,7 +630,7 @@ npm install @ai-sdk/amazon-bedrock # AWS Bedrock 支持
 
 ---
 
-## 六、参考资料
+## 七、参考资料
 
 - [AI SDK 官方文档](https://ai-sdk.dev/docs/getting-started)
 - [AI SDK Cookbook](https://ai-sdk.dev/cookbook)
@@ -634,3 +640,4 @@ npm install @ai-sdk/amazon-bedrock # AWS Bedrock 支持
 
 *文档生成时间：2025-01-25*
 *基于 AI SDK v6 版本分析*
+*高优先级优化完成时间：2025-01-26*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "1.0.73",
+  "version": "1.0.74",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "bin": {

package/plugins/file-system-plugin.js

@@ -85,17 +85,16 @@ class FileSystemPlugin extends Plugin {
     // 读取文件
     framework.registerTool({
       name: 'read_file',
-      description: '读取文件内容',
+      description: '读取文件内容。path 是必填参数。',
       inputSchema: z.object({
-        path: z.string().optional().describe('文件路径'),
-        filePath: z.string().optional().describe('文件路径(同path)'),
-        encoding: z.enum(['utf8', 'base64', 'binary']).optional().describe('文件编码，默认 utf8'),
+        path: z.string().describe('文件路径（必须）'),
         lines: z.number().optional().describe('只读取前 N 行')
       }),
       execute: async (args, framework) => {
-        const filePath = args.path || args.filePath
-        const encoding = args.encoding || 'utf8'
-        const lines = args.lines
+        const { path: filePath, lines } = args
+        if (!filePath) {
+          return { success: false, error: 'path 是必填参数' }
+        }
         try {
           if (!fs.existsSync(filePath)) {
             return { success: false, error: '文件不存在' }
@@ -110,7 +109,7 @@ class FileSystemPlugin extends Plugin {
             const allLines = fileContent.split('\n')
             content = allLines.slice(0, lines).join('\n')
           } else {
-            content = fs.readFileSync(filePath, encoding)
+            content = fs.readFileSync(filePath, 'utf8')
           }
           return {
             success: true,
@@ -128,22 +127,22 @@ class FileSystemPlugin extends Plugin {
     // 写入文件
     framework.registerTool({
       name: 'write_file',
-      description: '创建或写入文件内容',
+      description: '创建或写入文件内容。content 是要写入的文本内容。',
       inputSchema: z.object({
-        path: z.string().optional().describe('文件路径'),
-        filePath: z.string().optional().describe('文件路径(同path)'),
-        content: z.string().describe('文件内容')
+        path: z.string().describe('文件路径（必须）'),
+        content: z.string().describe('文件内容（必须）')
       }),
       execute: async (args, framework) => {
-        const filePath = args.path || args.filePath
-        const content = args.content
-        const encoding = args.encoding || 'utf8'
+        const { path: filePath, content } = args
+        if (!filePath || !content) {
+          return { success: false, error: 'path 和 content 都是必填参数' }
+        }
         try {
           const dir = path.dirname(filePath)
           if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true })
           }
-          fs.writeFileSync(filePath, content, encoding)
+          fs.writeFileSync(filePath, content, 'utf8')
           return { success: true, message: `文件已写入: ${filePath}`, filePath, size: content.length }
         } catch (error) {
           return { success: false, error: error.message }

package/src/core/agent-chat.js

@@ -44,7 +44,7 @@ class AgentChatHandler extends EventEmitter {
     this._systemPrompt = config.systemPrompt || 'You are a helpful assistant.'
     this._messages = []
     this._tools = new Map()
-    this._maxSteps = 10
+    this._maxSteps = 5  // 降低默认步骤数，减少上下文消耗
 
     // 上下文压缩配置：根据模型自动设置限制
     const modelKey = Object.keys(MODEL_CONTEXT_LIMITS).find(k =>

package/src/core/agent.js

@@ -29,7 +29,8 @@ class Agent extends EventEmitter {
     this.baseURL = config.baseURL
     this.provider = config.provider || 'deepseek'
     this.providerOptions = config.providerOptions || {}
-    this.providerOptions.maxOutputTokens=8192
+    this.providerOptions.maxOutputTokens = 8192
+    this.providerOptions.temperature = 0.3  // 降低 temperature 减少生成错误 JSON 的概率
     // 原始 system prompt
     this._originalPrompt = config.systemPrompt || '你是一个智能助手。当用户提出问题或任务时，你会主动分析需求，选择合适的工具来获取信息或执行操作。你善于将复杂任务拆解为多个步骤，通过工具协作完成。'