Web Canvas (Agent 协作画布)
Web Canvas 是一个基于 Physical-First (物理优先) 架构的 Agent 协作开发环境。它不仅提供了一个内置的代码编辑器和实时预览引擎，更核心的价值在于其深度集成的 LLM Agent 协作能力，允许智能体直接读写项目文件、感知运行时错误并进行迭代修复。
1. 核心设计原理
Web Canvas 的设计围绕着“协作”与“物理真实”展开：
- Physical-First 架构：与传统的内存虚拟文件系统不同，Web Canvas 所有的编辑操作（无论是用户手动输入还是 Agent 调用工具）都直接作用于物理磁盘。
- Git 版本追踪：每个画布项目都是一个独立的 Git 仓库。物理文件的任何变动都会被 Git 实时捕捉，提供可靠的变更追踪（Dirty Files）和回滚能力。
- 独立预览通信：预览引擎运行在独立的系统窗口中，通过
asset://协议加载物理文件，并通过注入脚本捕获所有运行时错误回传给主进程，形成“报错 -> Agent 感知 -> 修复”的闭环。
2. 管理器操作 (Project Lobby)
当你进入 Web Canvas 时，首先看到的是项目大厅，它是所有画布项目的管理中心。
画布生命周期管理
- 新建画布：点击左上角按钮，从模板系统初始化项目。模板决定了初始的文件结构（如 HTML/CSS/JS 组合）和入口文件。
- 健康检查：管理器会定期对比磁盘物理目录与索引文件（
projects.json）。如果发现索引丢失或物理目录被手动删除，会提供“修复”选项。 - 物理删除：删除项目时，系统会将整个 Git 仓库目录移入系统回收站，确保数据安全。
视图与状态
- 卡片/列表切换：支持大卡片预览和紧凑列表模式。
- 实时状态标签：
正在编辑：当前编辑器正打开此项目。待提交：物理文件已变更，但尚未执行 Git Commit。同步中：Agent 正在通过工具接口对该项目执行并发操作。
3. 画布独立窗口 (Preview Window)
预览窗口是 Web Canvas 的“眼睛”，它支持独立于主窗口运行，提供沉浸式的开发体验。
实时预览引擎
- 物理加载：预览窗口不使用
srcdoc字符串，而是通过 Tauri 提供的安全协议直接加载磁盘上的index.html。 - 防抖刷新：当磁盘文件发生变动时，预览引擎会触发 300ms 防抖刷新，既保证了实时性，又避免了因频繁保存导致的白屏闪烁。
运行时错误捕获
预览窗口被注入了特制的监控脚本，能够捕获以下信息并实时回传：
console.error/console.warnwindow.onerror(未捕获的常规错误)unhandledrejection(未捕获的 Promise 异常)
这些错误不仅展示在预览窗口的控制台中，还会被同步到 Agent 上下文中。
4. Agent 配置联动 (Agent Integration)
这是 Web Canvas 最强大的部分——将画布变成 Agent 的“操盘工具”。
绑定与感知
在 智能体 (Agent) 设置 或 画布设置 中，你可以配置联动参数：
- 绑定画布 ID：通过
canvas-bound-id明确告诉 Agent 当前应该操作哪一个项目。 - 自动包含运行时错误：开启后，预览窗口捕获的错误会作为“额外上下文”自动发送给 Agent。Agent 能够根据报错信息定位到具体文件的行号，实现自愈。
Agent 工具集 (Toolbox)
Agent 拥有操作画布的完整权限：
- 读取文件：获取带行号的源码。
- 应用 Diff：使用先进的 Search/Replace 算法进行手术式代码修改。
- 提交/回滚：Agent 可以在完成阶段性任务后自动执行
commit，或在测试失败时discard更改。
审批流联动
当 Agent 发起文件修改请求时，Web Canvas 会采用**“先应用，后确认”**的策略：
- Agent 修改物理文件。
- 预览窗口实时刷新展示修改后的效果。
- 用户在预览窗口中直接观察效果，若满意则批准（保留修改），若不满意则拒绝（系统自动通过 Git 回滚物理文件）。
5. 进阶技巧
- 外部编辑器协作：由于是物理优先架构，你可以同时用 VSCode 打开画布目录进行重构，Web Canvas 会自动同步 Git 状态。
- 自定义模板：你可以将常用的框架结构存放在
AppData/canvases/templates/user/下，实现一键生成专属开发环境。 - 错误过期机制：当你手动修复代码后，预览窗口会自动将之前的错误标记为“过期 (Stale)”，确保 Agent 不会被旧的报错干扰。