Agent 对话、工具循环、持久化与 MCP 可靠性增强

[cyfung1031]

Checklist / 检查清单

• Fixes Issues [Feature] 建议暴露 AI Agent 最大工具调用限制并优化多轮 Tool Calling 下的 Token 消耗 #1545 / 已修复关联问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

背景

本 PR 关联 Issue #1545，解决内置 Agent 在长时间、高频 Tool Calling、后台任务和会话续接场景中的可靠性与 Token 成本问题。

原始需求包括：

1. 最大工具调用次数固定，复杂任务容易被强制中断；
2. 历史工具结果在后续请求中重复携带，Token 消耗持续增长；
3. 检测到重复或循环调用后，用户无法及时介入；
4. Agent 的取消、压缩、持久化、附件所有权和后台任务生命周期存在竞态边界。

在后续实现和审查中，又确认并处理了跨上下文写入、OPFS 提交确认、会话 ID 复用、任务快照代际隔离、MCP 连接生命周期以及结构化错误传播等问题。分支已同步最新 main，并完成了与官方 MCP SDK 迁移相关的冲突语义合并。

本次改动 / 实现内容

1. 可配置最大工具调用次数，并支持原会话继续执行

• 新增 Agent 配置持久化 chatMaxIterations：
  • 默认值为 50；
  • 有效范围为 1–1000；
  • 设置页输入、直接传参和损坏存储值统一取整、截断并回退。
• 达到迭代上限时：
  • 持久化带 errorCode: "max_iterations" 的错误消息；
  • UI 仅对最后一个有效的 max-iterations 错误组显示“继续对话”；
  • 继续操作在原会话中追加指令，并复用持久化历史。
• 重建发送给 Provider 的上下文时跳过错误占位消息，保留 UI 和 OPFS 中的完整历史。
• 定时任务遇到终态错误时正确记录失败状态、usage 和 duration。

2. 降低长 Tool Loop 的上下文和 Token 成本

• Anthropic 请求在稳定消息前缀和最后一条消息上使用 Prompt Cache 断点。
• execute_script 按最终 JSON envelope 限制结果大小，保留首尾内容并标记截断；截断不会拆分 UTF-16 surrogate pair，也覆盖引号、反斜杠等转义内容。
• Tool Loop 按消息缓存序列化结果估算上下文，避免重复计算造成 O(n²) 开销。
• 图片视觉 Token 按像素尺寸估算，并按 Provider 实际内联行为计算附件预算。
• 请求前执行上下文预算检查；长历史在达到阈值时按滑动窗口裁剪旧 tool result，同时保留可恢复标识。
• 历史裁剪只作用于发送给 LLM 的副本，不改写 OPFS/UI 中的完整消息；普通 ephemeral/direct tool-loop 保持原有内存消息语义。
• 小上下文模型使用实际可用预算，避免预算计算为 0 后所有对话必然失败。
• Provider 的上下文长度拒绝统一分类为 context_too_large，并保留可信的结构化错误码。

3. Loop Guard 与用户介入

• 重复或循环工具调用达到阈值后暂停并询问用户继续或停止。
• 使用稳定的 continue / stop action，拒绝任意自定义输入。
• Continue 会重置本轮累计警告计数，避免后续每次命中都立即暂停。
• 超时、取消、attach、disconnect 和多监听器场景会同步清理 pending 状态并广播终态。
• 定时任务和子代理继续保持无人值守语义：只告警，不等待用户输入。
• Continue 双击、AskUserBlock 选项 key 和实时错误码传播均已修正。

4. 取消、终态和跨上下文生命周期

• 统一处理 UI、后台任务、子代理、用户脚本工具和 compact 的 abort 竞态。
• 取消后不再因连接关闭时序误报成功，也不会遗漏 done / error / tool_call_complete 等终态事件。
• SSE 截断、端口断开、后台任务取消和 reentrant chat 都按实际终态处理。
• 工具后处理、附件保存、任务保存和通知阶段持续观察 AbortSignal。
• 会话队列在排队前注册连接感知回调、入锁后复查；重入 clear 会显式拒绝。

5. OPFS 持久化、会话代际与任务 CAS

• 消息、工具轮和 compact 写入使用跨上下文锁及事务式快照，避免读改写覆盖。
• 对可能已经提交但 close 返回错误的写入执行读回确认；无法确认时不把数据当作已丢失。
• conversation 使用 generation/revision 保护 chat、attach、clear、delete、compact 和后台续接边界。
• 任务快照保存 generation/revision，并使用 CAS 防止 Options、Service Worker 和后台任务互相覆盖。
• 会话 ID 复用时不会读取上一代残留的任务或消息；旧格式裸 Task 数组仅在 legacy 会话中兼容读取。
• 主元数据提交与消息、任务、附件 GC 解耦；清理失败不会伪装成主操作失败。
• 生成附件按本轮租约和消息所有权管理：
  • 失败、取消或未被持久化消息接管时回收；
  • legacy 会话可从 content block 推断旧所有权；
  • GC 会检查工具附件、子代理嵌套附件以及跨会话和同会话借用引用；
  • 无法完整确认引用关系时安全保留附件，避免误删。
• 生成图片保存失败会作为持久化 warning 传播，而不是静默丢失。
• 定时任务的 claim、取消、删除和会话续接边界已统一处理，避免并发执行与元数据生命周期错位。

6. MCP 连接与结果处理

• 分支已同步最新 main 的官方 @modelcontextprotocol/sdk 客户端实现，并保留 request AbortSignal。
• 同一 MCP server ID 的并发连接请求复用同一个连接操作。
• initialize 或 listTools 失败时关闭临时 client，不注册半成品工具。
• 已连接服务器配置更新后会断开并按新 URL、headers、API key 重连。
• 工具名保留可读 server name，同时以原始 server ID 的码点编码避免 a-b / a_b 等碰撞。
• MCP 的 structuredContent 在普通结果、image 附件、ToolRegistry 归一化和结构化错误路径中均得到保留。
• 异步 disconnect 会等待 client.close 完成后再清理注册状态。

7. 用户脚本 API、类型和 UI

• 补齐 Agent Chat、Task、Model provider、warning 和 errorCode 的公开类型声明。
• userscript tool batch 使用 requestId 隔离超时批次，避免迟到结果污染新请求。
• Tool result、子代理详情、warning、usage 和附件 ownership 在流式与非流式路径保持一致。
• ChatInput 和消息编辑附件预览 URL 在取消、保存和卸载时正确释放。
• 设置页、任务页、MCP 页面和 ChatArea 的状态、双击、代际透传和错误展示已补齐回归覆盖。
• Agent 的错误、warning、Loop Guard 和任务相关文案已同步到现有 locale，并通过 i18n key-set 检查。

实现考虑

• 持久化不确定态优先安全保留。 close 报错或确认读失败不能证明写入失败，因此不会删除可能已经被持久化消息引用的附件。
• generation + revision 是会话边界和并发边界。 generation 防止 ID 复用后的旧数据复活，revision/CAS 防止不同上下文用旧快照覆盖新快照。
• LLM 上下文副本与展示历史分离。 裁剪只改变发送前副本，保证继续对话、刷新页面和 UI 展示仍可访问完整工具结果。
• 取消终态只有一个提交责任方。 AbortSignal 会贯穿工具、附件、任务和连接生命周期，避免多个主体重复发布或误报成功。
• 附件 GC 采用 fail-safe 策略。 引用扫描不完整时保留附件；同一附件既可能由消息拥有，也可能被其他消息或会话借用。
• MCP 注册名必须由原始身份决定。 可读名称允许清洗，但唯一性不能依赖清洗后的 server name 或 ID。

兼容性

• 未修改 Agent 配置的用户仍使用默认最大工具调用次数 50。
• execute_script、上下文裁剪和 Anthropic cache 不改变 OPFS 中的原始消息。
• 旧 conversation message、legacy attachment ownership 和 legacy 裸 Task 数组继续兼容；新 generation 不会读取旧会话 ID 残留数据。
• 现有 userscript tool、子代理、后台/定时任务和 Provider 接口保持兼容；新增字段均为可选或向后兼容的结构化字段。
• MCP 服务器配置仍使用原有 URL、headers 和 API key 语义；工具名的 server ID 编码只影响注册到 Agent 的内部工具名。

已知限制

• 未执行真实远程 MCP server 的端到端连接；MCP transport、失败清理、并发连接和结果转换由协议 mock 回归测试覆盖。
• 附件 GC 仍是 best-effort 清理，不引入持久化 GC 重试队列；扫描或删除失败时保留附件，可能留下可回收的存储。
• 未执行真实浏览器安装包手工验证；本次范围没有新增页面视觉设计，验证以完整测试、类型检查、lint 和生产构建为准。
• 构建仍报告仓库已有的 bundle size 和 Monaco 动态 require 警告，不是本 PR 新增的失败。

建议审查重点

• 最大工具调用次数的归一化、继续对话的历史重建和错误占位消息过滤。
• 40%/60% 上下文裁剪阈值、Provider 实际 Token/附件预算和持久化历史不可变性。
• Loop Guard 的 Continue/Stop、超时、取消、attach 和后台任务终态。
• OPFS close 不确定态、跨上下文锁、generation/revision/CAS、附件所有权和 GC fail-safe 行为。
• MCP 并发 connect/disconnect、配置重连、工具名唯一性和 structuredContent 保留。
• 公开 userscript 类型与流式/非流式终态事件的一致性。

关联

• Issue #1545
• 本 PR：scriptscat/scriptcat#1549

验证 / Test plan

• pnpm run test:ci — 完整测试套件通过。
• pnpm run lint:ci — Prettier、TypeScript、i18n、issue-template 检查和 ESLint 全部通过。
• pnpm run build — 生产构建成功；仅有已知 bundle size 与 Monaco 动态 require 警告。
• 相关 Agent、MCP、OPFS、任务和 Chat UI 回归测试均已覆盖本次新增边界。
• 3 个 subagents 完成 fresh review；未声称其等同于 human review。

Screenshots / 截图

N/A — 本 PR 没有新增页面视觉设计或需要截图的 UI 变更。

[cyfung1031]

本轮已完成同步与收尾，当前 PR head 为 de6c4560，并已合入最新 main（解决了 mcp_client.ts / 测试冲突）。

经复现、回归测试和 3 个 subagent 的 fresh review，按 PickInvariant 逐项检查后处理了以下确认有效的问题：

• 修复 compact 产生的结构化 context_too_large 在 ChatService 边界被错误降级为 api_error。
• MCP 连接并发去重；连接初始化或 listTools 失败时关闭临时 client；更新已连接配置时重连。
• MCP 工具名改为基于原始 server ID 的无碰撞编码，避免不同 ID 被清洗成同名工具。
• 保留 MCP 的 structuredContent，包括 image 附件结果和仅由结构化内容携带的错误详情。
• 任务快照加入 generation/revision 的读取与 CAS 写入保护；会话 ID 复用时不会复活旧任务，取消的定时任务不会误记成功。
• 附件 GC 同时检查跨会话借用和同一会话新快照中的引用，避免所有权转移时误删附件。
• ChatArea / task hook 透传正确的 conversation generation；补齐 compact duration 和公开类型声明。

验证结果：

• pnpm run test:ci：完整测试通过
• pnpm run lint:ci：Prettier、TypeScript、i18n、issue-template、ESLint 全部通过
• pnpm run build：构建成功；仅有仓库原有的 bundle 体积和 Monaco 动态 require 警告
• 每个 commit 创建前均完成 PickInvariant Review；每个确认问题都有对应回归测试

本轮 fresh review 中未能以可重复证据确认的风险（例如 GC 失败后的持久化重试债务、跨上下文全局扫描锁竞争、极窄的取消时序窗口）没有扩大改动范围；现有实现对这些情况采取安全保留/失败关闭策略。

[cyfung1031]

@CodFrm 你人手实测吧