AIClaw 3.7.7：文件预览与变更审查分离设计解析

在 AI Agent 与开发者协作的日常中，一个常见的痛点：对话里说「SQL 已更新」或「报告已保存」，但验证结果需要切换到另一个应用，而且打开当前文件并不等于看到 Agent 究竟改了什么。AIClaw v3.7.7 在桌面端引入了一套明确区分的双模式方案——在会话侧边即时读取文件，同时单独维护工具修改时记录的快照审查视图。

在对话旁边直接打开结果

点击受支持的文件卡片，会在聊天窗口旁打开一个只读面板。文本、SQL、Markdown 以及常见源代码格式均支持行号、内容复制，并在加载了对应语法时提供高亮。Markdown 可在渲染视图与源码视图之间切换。当窗口较窄时，预览以覆盖层形式呈现，避免两个面板被持续挤压。

例如，Agent 可能返回如下查询：

SELECT id, email FROM users WHERE active = 1;

你无需启动外部编辑器即可在上下文里阅读这条查询。这是检查，不是编辑：面板不会保存任何修改。包括 Office 文档在内的不支持格式，仍保留系统默认打开方式。

格式映射通过显式扩展名和一小部分可识别文件名来确定语言，高亮器使用显式指定的语言而非自动检测。当语法不可用或输入过大时，回退为转义纯文本。这种保守策略牺牲了一点便利性，换来的是行为可预测——对于需要审计的工程场景，这种取舍是合理的。

记录的 Diff 不是 Git Diff

工作面板中的文件变更条目会以比较模式打开同一个预览面板。你可以选择并排或统一视图，或直接阅读记录的前后快照，删除行与新增行分别标注行号。

假设某个工具把查询从「只选 ID」改为「选 ID 和 email」，比较视图会展示这一被记录的转变过程，即使之后有人在磁盘上再次编辑了该文件。

这同时也是它的边界：记录中的 after 快照并不代表当前磁盘内容。面板会显示这一区别的提示，它不与 Git HEAD 比较，不检查暂存区变更，也不提供通用仓库审查视图。

Diff 辅助模块执行逐行比较。当两个行数的乘积超过 250,000 时，改用替换块方式而非分配巨大的比较矩阵。面板将显示的差异限制在 3,000 行内，因此超大变更可能需要借助外部编辑器完成完整审查。这些限制说明该功能面向的是「快速判断 Agent 改了什么」，而非替代代码审查工具。

读取本地文件需要宿主边界

渲染进程通过 Electron IPC 请求预览，同时携带路径和所属会话 ID。宿主使用该会话的工作目录解析相对路径，而不是之后碰巧被选中的某个工作区——避免了跨会话路径混淆的问题。

读取器对请求路径及其规范化目标都检查受保护位置，验证打开的描述符指向常规文件，限制读取大小，并拒绝 NUL 字节或无效 UTF-8。磁盘文本预览上限为 512 KiB，显示的源码内容同样受大小和行数约束。

这些检查保护的是预览路径本身，并非所有文件系统操作的通用沙箱。比较视图使用记录的快照，不回读文件，所以审查过程不受磁盘后续变化影响。

另有一个 UI 竞态需要处理：如果读取在用户切换聊天或打开另一个文件之后才完成，状态存储会忽略过期结果，避免延迟响应导致意外打开另一个会话的预览。

Electron 的进程模型是理解这段设计的前提。它把应用拆成主进程（Node.js 环境，可访问文件系统与操作系统能力）和渲染进程（Chromium 环境，负责界面），两者不共享内存，只能通过 IPC（进程间通信）交换消息。渲染进程出于安全考虑默认被隔离，不能直接调用 fs 模块，所以任何文件读取都必须向主进程发起请求，由主进程执行后把结果回传。preload 脚本则是二者之间的受控桥接层：它在渲染进程里暴露一组经白名单约束的接口，让页面能调用 IPC 而不直接接触 Node API。AIClaw 在预览请求中要求同时携带路径和会话 ID，正是把这种桥接机制用作权限校验点——宿主拿到请求后先确认该请求属于哪个会话，再在对应工作目录内解析路径，从而避免渲染层被利用来读取任意文件。

Markdown 是文档，不是执行面

本地 Markdown 预览复用既有的解析器与净化器，预览渲染器中禁止图片标签和内联样式属性，嵌入图片不会被自动获取，相对文件引用从文档所在目录解析。

它不是一个用于任意 HTML 应用的浏览器，识别 MDX 扩展名也不会执行 MDX 组件。这种设计把 Markdown 严格限定为文档查看场景，堵住了通过预览触发的潜在信息泄露与代码执行路径。

测试覆盖了什么

读取器测试覆盖受支持格式、受保护路径与符号链接别名、超大与无效文本、特殊文件拒绝；Diff 测试检查行号与成对替换行；桌面工作流冒烟测试在真实 Vue/preload 接口上以固定响应运行，覆盖 Markdown/源码切换、SQL 比较以及晚读隔离。这些测试验证了 UI 与桥接层的关键案例，但并不能证明每一种语言语法或每个操作系统的文件打开行为。

v3.7.7 发布说明记录 259 项渲染/辅助测试与 86 项工作面板 UI 检查通过，这是整套本地检查的总数，而非仅预览相关计数。发布 CI 同样成功。需要注意的是，说明中也记录了一个无关的实时转录超时以及一次针对性重试成功；基于固定响应的预览检查不应与真实模型验证混为一谈。

分离设计的实际意义

把「当前文件检查」与「记录变更审查」在界面上明确分开，让用户在评估结果时更清晰：既能看到 Agent 做了什么，又不会误把历史快照当作工作区的当前状态。AIClaw 在这一版中展现的思路——为检查与编辑划清界限、为快照与实时状态标注差异、在读取路径上设置纵深防御——对构建可信 AI 编程工具的团队而言，比单纯增加功能数量更值得参考。