Agents SDK 常见陷阱

# 常见问题与最佳实践 ## 常见错误 ### "setState() 未同步" **原因:** 直接修改状态或在修改后未调用 `setState()` **解决方案:** 始终使用 `setState()` 进行不可变更新： ts // ❌ this.state.count++ // ✅ this.setState({...this.state, count: this.state.count + 1}) ### "消息历史无限增长 (AIChatAgent)" **原因:** `AIChatAgent` 中的 `this.messages` 会无限累积所有消息 **解决方案:** 定期手动修剪旧消息： ts export class ChatAgent extends AIChatAgent { async onChatMessage(onFinish) { // 仅保留最后 50 条消息 if (this.messages.length > 50) { this.messages = this.messages.slice(-50); } return this.streamText({ model: openai("gpt-4"), messages: this.messages, onFinish }); } } ### "SQL 注入漏洞" **原因:** SQL 查询中直接进行字符串插值 **解决方案:** 使用参数化查询： ts // ❌ this.sql`...WHERE id = '${userId}'` // ✅ this.sql`...WHERE id = ${userId}` ### "WebSocket 连接超时" **原因:** 在 `onConnect` 中未调用 `conn.accept()` **解决方案:** 始终接受连接： ts async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: "123"}); } ### "超出调度限制" **原因:** 每个智能体超过 1000 个调度任务 **解决方案:** 清理旧调度并限制创建速率： ts async checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn("Near limit!"); } ### "AI 网关不可用" **原因:** AI 服务超时或配额超出 **解决方案:** 添加错误处理和回退机制： ts try { return await this.env.AI.run(model, {prompt}); } catch (e) { console.error("AI error:", e); return {error: "Unavailable"}; } ### "@callable 方法返回 undefined" **原因:** 方法未返回 JSON 可序列化的值，或包含不可序列化的类型 **解决方案:** 确保返回值是纯对象/数组/原始类型： ts // ❌ 返回类实例 @callable() async getData() { return new Date(); } // ✅ 返回可序列化对象 @callable() async getData() { return { timestamp: Date.now() }; } ### "可恢复流无法恢复" **原因:** 流 ID 必须是确定性的才能使恢复工作 **解决方案:** 使用 AIChatAgent (自动) 或确保流 ID 一致： ts // AIChatAgent 自动处理此问题 export class ChatAgent extends