3FUI Agent 模块审计实录：进程超时、SSE 协议、会话恢复与回归验证的完整加固

• 桌面应用
• 音视频
• 视频处理

本文基于仓库内 doc/Agent-audit.md 的审计记录展开，系统梳理 3FUI（FFmpegFreeUI）Agent 智能体模块在 2026-09-17 审计中定位并修复的问题：进程工具的超时与取消、SSE 流式协议的严格校验、中断会话的恢复策略、按端点隔离的推理能力缓存，以及参数面板与编码队列的校验加固。读完你可以掌握一套“工具执行层—端点传输层—会话存储层—回归测试层”四层视角下审视 LLM Agent 桌面应用可靠性的方法，并能在 tests/FFmpegFreeUI.RegressionTests 中复现全部验证。

审计范围与保留特性

审计文档开篇即给出范围声明：范围覆盖Agent 页面、会话与草稿存储、历史升级、上下文压缩、端点传输与模型能力、工具定义与执行、参数面板和队列桥接、内置技能与提示词。同时明确本次审计保留的设计：多对话并发、工具摘要展示、完整结果存档，以及 200 的工具展开高度。这个“保留清单”很重要——它界定了审计的边界：不是推倒重来，而是在既有交互模型之上修复可靠性缺陷。

代码入口：分部页面 + 独立工具层

审计文档给出的代码结构如下表，页面分部类位于FFmpegFreeUI/界面 v6 主页面，工具实现位于FFmpegFreeUI/功能/Agent 智能体：

分部类维持原有接口和 WinForms Designer 绑定；工具目录中的独立会话存储（Agent会话存储_v6.vb）、升级器（Agent会话Json升级器_v6.vb）、端点客户端（Agent端点客户端_v6.vb）、能力表（Agent推理级别能力表_v6.vb）和上下文投影（Agent上下文投影_v6.vb）继续各司其职。

已修复问题与源码印证

进程超时与取消：先解决“EOF 阻塞”，再谈超时

审计文档指出，原先等待进程和两路输出的WhenAll可能被 EOF 阻塞，导致取消分支无法执行；stdin 写入也没有纳入超时。修复后：写入、刷新、退出和输出读取都受超时控制，输出持续排空但限制缓存长度；PowerShell 清理不再无限同步等待输出。

源码可以印证这一设计。在 Agent本地工具_进程_v6.vb 中，run_windows_executable的等待被重构为对整个任务设超时，而不是先等读到 EOF：

Dim work = Task.WhenAll(stdoutTask, stderrTask, inputTask, process.WaitForExitAsync(timeout.Token)) ' 对整个任务设置超时，不能先等待读到 EOF 再处理进程取消。

即 stdin 写入任务（inputTask）与两路输出读取、进程退出统一纳入同一个WhenAll，并整体受timeout.Token控制。回归测试 AgentAuditChecks.cs 用三个用例锁定该行为：

1. 超时覆盖阻塞 stdin：向--wait-fixture进程（挂起 30 秒）传入 512KB stdin 并设timeout_seconds = 1，断言返回timed_out = true且总耗时小于 8 秒；
2. 用户取消语义保持：150ms 后取消，断言任务以IsCanceled结束而不是“工具成功”；
3. 输出持续排空但有界：max_output_chars = 128时，进程仍能正常退出（exit_code = 0），且stdout/stderr缓冲均被截断在 160 字符以内。

参数保真是同类修复的一部分。测试 AgentAuditChecks.cs L17-L33 验证空参数、含空格的参数、重复参数（["", " spaced ", "x", "x"]）逐位精确传递——工具定义中也明确要求“参数使用数组逐项传递，不经过 shell 拼接”（见 Agent本地工具_v6.vb L226-L233）。

PowerShell 会话同样经过审计加固：AgentAuditChecks.cs L55-L69 验证了同一会话内变量持久（$agentAuditValue第二轮读出 42）、跨会话隔离（第二个 shell 中agentAuditValue不存在）、超时杀进程不阻塞 UI 清理，以及“超时一个 shell 不会连带杀死另一个 shell”。这与工具定义中的约定一致：同一次用户消息触发的 Agent 运行复用同一个 PowerShell 进程，优先 pwsh.exe 并回退 powershell.exe，强制 stdin/stdout/stderr 使用 UTF-8（Agent本地工具_v6.vb L221）。

文件操作：保留参数形态，防御危险路径

审计文档记录的修复包括：保留空参数、重复参数和参数首尾空格；去除 UTF-16 BOM 对文本的污染；目录移动拒绝相同及父子路径；覆盖目标目录时先备份，移动失败恢复目标；目录枚举先限制数量再排序并跳过重解析点；HTTP 工具限制响应缓冲大小和完整读取时间。

对应测试证据：

• BOM 剥离：对Unicode、BigEndianUnicode、UTF8三种编码的 BOM 前缀解码后均得到纯文本“你好”（AgentAuditChecks.cs L20-L21）；
• 危险移动拒绝：把源目录移动到自身、父目录或子目录三种情形全部返回“拒绝移动”，且源内文件完好（AgentAuditChecks.cs L71-L78）；
• 取消不落盘：已取消的 token 调用write_local_text_file，任务必须IsCanceled且目标文件不存在（AgentAuditChecks.cs L79-L85）。

工具层的配套防线在 Agent本地工具_v6.vb 中可见：copy_local_file/move_local_path目标已存在时默认拒绝覆盖；delete_local_path必须显式传confirm=true，否则直接返回“拒绝删除：必须传 confirm=true”，且文件优先移入回收站。

端点协议：SSE 流“宁缺毋假”

这是本次审计中改动面最大的一块。审计文档的结论：HTTP 请求与 JSON 文档显式释放；流式读取覆盖响应体超时；缺少完成标志、空流和错误事件不会当成成功；工具调用因输出长度截断时不执行工具；HTTP 超时与用户取消分别处理；错误 JSON 不再伪装成成功响应。

在 Agent端点客户端_v6.vb 中可以看到具体实现：

• 响应体超时：流式请求用CancellationTokenSource.CreateLinkedTokenSource叠加CancelAfter(Http.Timeout)（基础HttpClient超时为 90 秒），整个逐行读取循环受其约束（Agent端点客户端_v6.vb L153-L167）；
• 空流/非流式响应识别：循环结束时若未见到任何data:事件，先检测 Cloudflare 质询文本与 HTML 响应，再归为“端点没有返回有效的流式 JSON”（L197-L206）；
• 完成标志校验：合法完成依赖[DONE]或finish_reason，读取后调用ValidateStreamCompletion兜底（L178-L213）；
• 取消与超时分离：OperationCanceledException在cancellationToken.IsCancellationRequested条件下重新抛出，与流超时导致的失败路径区分开（L220-L227）；
• 原始响应捕获有界：MaxStreamingRawCaptureLength = 65536，防止超长流撑爆内存（L12）。

AgentAuditChecks.cs L87-L109 对这组行为做了双向验证：截断 chunk、夹带 error 事件后[DONE]、以及只有[DONE]的空流三种输入均必须被拒绝；data: [DONE]与finish_reason: "stop"两条完成路径均必须被接受；再用本地 SSE 模拟端点（AgentStreamFixture）构造“中途 EOF”的真实 HTTP 流，断言结果Success = false且ToolCalls.Count == 0——没有完成标志的流不允许触发任何工具执行。这直接对应审计文档中“工具调用因输出长度截断时不执行工具”一条。

另一个易被忽略的防线：run_powershell的参数如果是损坏的 JSON（如{"command":），不得被“重新解释”为裸命令文本执行。AgentAuditChecks.cs L107-L109 断言其以“工具参数 JSON 解析失败”开头。而合法的裸字符串命令会由 Agent本地工具_v6.vb 的 ParseToolArguments/NormalizeToolArguments 规范化为{"command": "..."}单字段 JSON——只针对白名单中的原始参数属性（目前仅run_powershell的command），其余工具参数解析失败一律报错。

会话恢复：保存不干扰运行，加载即修复

审计文档对会话层的修复描述为：加载时把上次中断的运行标成取消，并为缺失的工具返回补充“结果未知”记录；保存时不改变仍在运行的任务；工具批次开始及返回后保存进度；索引拒绝跨目录文件名，非法 ID 生成无碰撞文件名；旧记录中的空集合成员被规范化。

Agent会话存储_v6.vb 中可见加载侧的修复逻辑：将残留的运行态轮次与活动标记为canceled，并对缺失结果的未完成任务补一条 tool 消息，内容为“上次运行中断，工具结果未知；请先核实实际状态，不要假设操作未执行”——这句话本身就是写给模型看的提示词，防止模型在恢复后的对话里臆断工具没有执行。

AgentAuditChecks.cs L119-L143 把整条恢复链路做成可复现断言：

• 保存一个处于running状态、且带未完成工具调用的会话，Save()后轮次状态仍是running（保存不能取消活着的对话）；
• 重新Load后轮次与活动变为canceled，消息列表末尾自动补上Role = tool、ToolCallId = "unfinished"的收尾消息；
• 未发送的草稿DraftText原样保留；再次 Load 结果幂等；
• 非法会话 ID（a:b、a?b等含文件名非法字符）不会造成存储文件碰撞，旧数据中的null集合被规范化；
• 当前 schema 的“调整方向：这是用户原文”消息经升级器处理后原文不被改写——对应审计文档中“当前版本的用户原文不再被旧版迁移逻辑删去‘调整方向：’前缀”。

上下文：每轮重查压缩预算，方向调整按 ID 去重

审计文档指出：每一轮工具循环都重新检查压缩预算，避免长任务只检查首次请求；调整方向按消息 ID 去重；取消时刷新尚未展示的流式缓冲。

压缩预算所依赖的模型选择在 Agent上下文能力表_v6.vb 中维护：内置一张按优先级排列的“上下文压缩专用模型”表，选择上下文压缩模型按优先级在端点可用模型列表中匹配。配合 Form_v6_Agent_上下文.vb 分部的上下文投影与检查点逻辑，长工具循环中每一轮都重新评估预算，而不是一次性决策。从源码结构看，这意味着即使一个任务连续调用数十次工具，上下文长度增长也不会只依赖首轮请求时的判断。

模型与交互：推理能力按端点隔离

审计文档的修复点：推理能力按端点和模型隔离，显式返回的能力优先于兜底表；新建、删除和切换对话保留底部下拉框选项；推理期间下拉框保持可操作，修改只影响后续提交；只附带文件的发送不被误判成空消息。

能力缓存的实现位于 Agent能力缓存_v6.vb：

• 缓存键由BuildEndpointSignature生成，包含端点地址、API Key、附加请求头和附加 Body（L52-L60），因此同一模型挂在不同端点下的能力互不继承；
• GetReasoningEfforts的优先级是：模型显式返回的ReasoningEfforts> 缓存条目 > 兜底表low/medium/high（L34-L50），显式能力还会回写缓存；
• 缓存版本号为 6（ReasoningEffortCacheVersion As Integer = 6，L8），缓存文件为Agent/ReasoningEfforts.cache.json。版本升级意味着旧缓存整体失效重新生成，正如审计文档所述，目的是“避免复用此前未按端点隔离的数据”。

对应测试 AgentAuditChecks.cs L111-L117 用同一模型 ID 分别注册在两个不同端点客户端上，断言：显式能力覆盖兜底表；模型查找大小写不敏感；换端点后缓存限制不串用（能取到含high的默认能力）。

参数与队列：拒绝“悄悄执行”

审计文档对参数与队列桥接的修复是：无效枚举值和非有限数字在应用参数前被拒绝；队列修改存在未匹配目标或同时指定all与具体目标时，不再悄悄执行部分任务或扩大到全部任务。

参数侧的实现证据在 AgentAuditChecks.cs L144-L151：向DeserializeJsonElement分别传入"NaN"（目标是double）和99（目标是DayOfWeek枚举），两者都必须抛InvalidOperationException，即校验失败发生在改动 UI 之前。工具定义也强调“填写不熟悉的参数前优先调用get_parameter_field_info查询字段的类型、当前值、候选值和格式规则”（Agent本地工具_v6.vb L25），从提示词层面降低模型猜值概率。

队列侧的目标解析统一收敛到 Agent本地工具_队列_v6.vb 的 ResolveQueueTarget，被get_queue_summary、get_queue_task_logs、control_queue_tasks等工具复用。冲突用例的断言在 AgentAuditChecks.cs L152-L154：{"target":"all","id":"one"}必须返回非空Errors，既不部分执行也不静默扩大到全部任务。工具描述同样写明“停止或移除全部只应在用户明确要求时使用”（Agent本地工具_v6.vb L61）。

清理与维护约定

审计的另一半工作是“做减法”，文档列出的约定与源码现状一致：

• 删除ToolRunLog、ToolRoundLog两层重复状态，直接使用AgentTurnActivityData：以ToolCallId对应协议调用，以活动 ID 找回控件；
• 清理无用状态：页面总用量累加器、压缩计划字段、不可达的空 SSE 二次请求逻辑和空壳异步方法被移除；
• 复用既有基座：聊天请求构造、响应根对象验证及原子 JSON 写入（后者与 原子文件写入_v6.vb 一致）；
• 草稿边界：草稿不属于Messages，不能进入端点请求或上下文压缩；只有当前对话可以更新 AgentRoom；
• 结果分层：完整返回保存在活动记录中，界面和复制内容只使用摘要；模型上下文保留原有工具文本长度限制（对应max_output_chars默认 12000 等上限）；
• 并发与共享边界：多对话拥有独立的取消源、流式解析器和 PowerShell 进程；而参数面板、编码队列及集成工具仍是共享的应用状态；
• 兼容承诺：会话格式保持兼容；推理级别缓存版本更新为 6，旧缓存重新生成。

验证：本地 SSE 模拟端点驱动的回归测试

审计文档给出的验证入口是tests/FFmpegFreeUI.RegressionTests中的AgentConversationChecks.cs与AgentAuditChecks.cs，使用本地 SSE 模拟端点、临时目录和测试进程本身：

dotnet build FFmpegFreeUI/FFmpegFreeUI.vbproj --no-restore dotnet run --project tests/FFmpegFreeUI.RegressionTests --no-restore -- --agent-only dotnet run --project tests/FFmpegFreeUI.RegressionTests --no-restore

三条命令分别对应：构建主程序、只跑 Agent 检查、跑完整回归套件（Agent 检查之外的部分覆盖队列、预设、主题、VMAF 模型选择等，说明见 tests/FFmpegFreeUI.RegressionTests/README.md）。

Agent 检查（--agent-only）覆盖：并发输出与取消隔离、工具归属、草稿恢复与下拉框保持、排序、撤销隔离、存档恢复、流式 EOF/错误、真实进程参数与超时、PowerShell 会话隔离、文件移动保护及能力缓存隔离。测试工程无需测试框架包，被测可执行文件自身充当短生命周期的 stdout/stderr fixture（如--agent-args-fixture、--wait-fixture、--output-fixture三种参数桩，见 AgentAuditChecks.cs 中的用例构造）。

适用前提需要说明：这些检查不依赖真实模型服务或 API Key；但供应商兼容性与桌面 GPU 呈现仍需在相应实际环境中另行验证（审计文档的明确边界声明）。

小结

从这份审计记录与对应源码看，3FUI Agent 模块的加固遵循一条清晰的主线：任何“看起来像成功”的路径都必须能被测试证伪——超时必须覆盖 stdin 与 EOF、取消必须保持取消语义、无完成标志的流必须失败且不得触发工具、中断的工具结果必须以“结果未知”显式落库、all与具体目标并存必须报错。对维护 LLM Agent 工具层的开发者而言，这套“权限分级（Safe/Environment/System）+ 目标解析集中化 + 端点签名缓存 + 恢复即修复”的组合，以及用本地 SSE fixture 和自引用进程桩做回归的验证方式，是可以直接借鉴的工程实践。

• 桌面应用
• 音视频
• 视频处理