Web Canvas (进阶指南)
Web Canvas 的核心价值在于其 Physical-First 架构下的深度协作能力。本指南将深入探讨 Agent 联动、预览引擎原理、版本控制及自定义模板等进阶功能。
Agent 协作工作流
绑定画布
在 LLM 聊天设置中找到 "绑定画布 ID" 配置项，输入项目大厅中显示的画布 ID 即可完成绑定。绑定后，Agent 在生成代码时会直接操作画布文件，而非仅输出文本建议。
Agent 可操作的能力
| 方法 | 功能 | 典型使用场景 |
|---|---|---|
read_canvas_file | 读取文件（带行号） | Agent 审查现有代码 |
apply_canvas_diff | 应用 Search/Replace Diff | Agent 精准修改指定代码块 |
write_canvas_file | 全量写入文件 | Agent 创建新文件或重写整个文件 |
commit_changes | 提交所有更改 | Agent 完成一轮修改后创建 Git 快照 |
discard_changes | 丢弃未提交变更 | 回退 Agent 的修改 |
list_canvas_files | 获取文件树 | Agent 了解项目结构 |
create_canvas | 创建新画布 | Agent 主动新建项目 |
clear_runtime_errors | 清空运行时错误 | 修复问题后清理错误记录 |
open_window | 打开预览窗口 | 为指定画布开启独立预览 |
Agent 驱动的代码生成工作流
- 在 LLM 聊天中绑定 Web Canvas（设置中填入画布 ID）
- 用自然语言描述需求，如"帮我创建一个带有交互式折线图的数据仪表盘"
- Agent 会自动创建文件、写入代码
- 你可以在预览窗口中实时查看效果
- 不满意时直接告诉 Agent 修改，它会使用
apply_canvas_diff精确调整指定代码块 - 满意后 Agent 调用
commit_changes提交版本
审批系统（Preview → Approve/Reject）
Agent 的操作会经过审批系统：
- 预览阶段：Agent 调用的
apply_canvas_diff或write_canvas_file会直接执行到磁盘，让你在预览中实时看到效果 - 用户确认：你确认修改是否正确，选择批准或拒绝
- 拒绝回滚：如果拒绝，系统自动回滚——新文件被物理删除，已有文件通过 Git checkout 恢复
运行时错误自动注入
开启"自动包含运行时错误"设置后，预览中的运行时错误会自动注入到 Agent 上下文中。Agent 获取上下文时能看到类似以下信息：
--- RUNTIME ERRORS ---
TypeError: Cannot read property 'data' of undefined
at Line 24:12 (index.js)
---这样 Agent 可以"看见"自己代码的问题并自动修复。你可以在设置中调整最大错误数量（0–50）来控制 token 消耗。
隐式创建
如果当前没有打开的画布，Agent 执行文件操作时会自动创建一个新画布，确保协作流程不会中断。
模板系统
内置模板
系统内置了多分类模板，在创建画布时可选：
| 分类 | 说明 | 示例模板 ID |
|---|---|---|
| 基础 | 干净的空 HTML 模板 | blank-html |
| 动效 | CSS 动画、Canvas 渲染模板 | canvas-animation |
| 数据可视化 | 集成 ECharts 等图表库的模板 | echarts-dashboard |
| 游戏 | 轻量游戏开发模板 | snake-game |
| 作品集 | 个人展示页模板 | portfolio-page |
| 工具 | 实用工具类模板 | json-pretty-viewer |
| 用户自定义 | 用户自己创建的模板 | 自定义存储路径 |
模板版本管理
模板通过 template.json 中的 version 字段管理版本。应用启动时，内置模板会同步到 AppData/canvases/templates/builtin/ 目录下，仅在版本更新时覆盖旧文件。
自定义模板
你可以将自己的项目目录结构创建为模板。用户自定义模板存放在 {appDataDir}/canvases/templates/user/{templateId}/ 目录下。
创建自定义模板的步骤：
- 在
{appDataDir}/canvases/templates/user/下创建一个以模板 ID 命名的目录 - 在该目录下创建
template.json，定义模板元数据（名称、描述、入口文件、版本） - 在该目录下创建
files/子目录，放入所有项目文件 - 重启 Web Canvas 或重新加载，在新建画布时就能看到自定义模板选项
TODO: 截图 - 自定义模板目录结构示例
设置默认模板
你可以在 Web Canvas 设置页面的项目管理中配置"默认项目模板"的 ID。创建新项目时会自动预选该模板。
版本控制
每个画布项目内置一个独立的 Git 仓库。当你创建画布时，系统自动执行：
git init → git add <all files> → git commit -m "Initial commit from template: {name}"提交更改
在编辑器左侧的待更改面板中点击 Commit All，输入提交信息即可。提交操作：
- 通过 Git 内部服务检查所有文件的状态矩阵
- 添加未跟踪文件（new）和修改过的文件（modified）
- 执行 Git commit
- 更新元数据文件的
updatedAt时间戳 - 更新项目索引
- 刷新状态栏
TODO: 截图 - 待更改面板上的 Commit 按钮和提交信息输入
丢弃更改
点击 Discard 按钮会通过 git checkout 恢复到最近一次提交的状态。这是一个不可逆操作——所有未提交的修改都会丢失，请谨慎操作。
查看变更
左侧文件树中的每个文件都会显示 Git 状态标识：
new（绿色）：新创建但未提交的文件modified（橙色）：已有文件被修改deleted（红色）：文件被删除
预览引擎深入
架构原理
预览引擎使用 iframe 通过 srcdoc 属性渲染入口文件。它会自动在 HTML 中注入：
<base>标签：确保相对路径资源（图片、CSS、JS 文件）正确加载- 错误捕获脚本：劫持
console方法（warn/error）和全局错误事件（window.onerror、unhandledrejection）
预览通信机制：预览 iframe 通过 window.parent.postMessage() 将运行时错误回传到主窗口，主窗口的去重和限流机制确保不会淹没日志。
预览配置
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 自动打开预览 | 创建或打开项目后自动开启独立预览窗口 | 开启 |
| 预览刷新延迟 | 文件保存后等待多久刷新预览 | 500ms |
独立预览窗口
预览窗口是一个由 Rust 后端创建的系统级 WebviewWindow，独立于主应用运行。这意味着：
- 预览窗口关闭后不会影响编辑器状态
- 可以同时打开多个画布的预览窗口
- 预览窗口独立于主应用窗口，不会被遮挡
外部编辑器协同
你可以在 Web Canvas 中配置 VSCode 路径，然后在项目操作菜单中选择 在 VSCode 中打开。
配置 VSCode 路径
进入 Web Canvas 设置，在外部编辑器配置项中填入 code.exe 或 code.cmd 的完整路径。系统会自动扫描常见的 VSCode 安装目录（点击扫描按钮）。
协同工作流
- VSCode 中编辑：享受完整的 IDE 体验（代码补全、调试、Git 历史）
- Web Canvas 中预览：回到 Web Canvas 查看实时预览效果
- Web Canvas 感知变更：Physical-First 架构通过 Git 状态自动感知 VSCode 中的修改，打开项目时自动刷新
TODO: 截图 - 在 VSCode 中编辑画布项目
健康检查与项目修复
Web Canvas 会定期对所有项目执行健康检查，对比磁盘目录和索引文件。可能的状态：
| 状态 | 含义 | 修复方式 |
|---|---|---|
| 健康 | 索引与磁盘一致 | 无需操作 |
| 索引异常 | 索引存在但磁盘缺失 | 移除孤儿索引 |
| 未索引 | 磁盘存在但索引缺失 | 重新建立索引 |
| 元数据损坏 | .canvas.json 文件不可读 | 尝试从索引恢复元数据 |
鼠标悬停在异常状态标签上会显示修复选项。你也可以在项目大厅中点击刷新按钮手动触发全量健康检查。
Diff 引擎的智能匹配
当 Agent 使用 apply_canvas_diff 时，底层的 Diff 引擎采用降级匹配策略：
精确匹配 → 忽略末尾空格 → 完全忽略缩进 → 模糊匹配（≥85% 相似度）这意味着 Agent 可以容忍代码中的缩进差异和空格变化，有效提高修改成功率。模糊匹配基于 Bigram Dice 系数，对行级别的相似度进行计算，首尾行还有额外加权。
Diff 操作会返回匹配策略和范围信息，让你了解匹配的准确度：
Applied diff to index.html [fuzzy matched (confidence: 92%)] at lines 15-22常见高级问题
Q：Agent 操作被拒绝后文件会怎样？
Agent 的操作被拒绝后：
- 修改已有文件：通过 Git checkout 恢复到修改前的状态
- 新建文件：从磁盘物理删除
- 多个连续操作：被拒绝的操作会尝试回滚，但建议在审批前仔细确认预览效果
如果误拒绝了正确修改，可通过编辑器重新手动修改。
Q：如何强制刷新健康检查？
在项目大厅中点击右上角的刷新按钮，触发全量健康检查。系统会重新扫描 AppData/canvases/projects/ 目录下的所有项目，更新索引和元数据。
Q：预览窗口能展示非 HTML 文件吗？
预览引擎默认加载入口文件（通常为 index.html）。如果需要预览其他类型的文件（如 SVG 或服务端渲染页面），你需要创建一个包装 HTML 文件来引用它们。