企业官网建设流程全解析

使用 Drawbridge（浏览器视觉标注工具）时，最常见的三类故障是：连接断开、任务丢失、AI 找不到文件。Drawbridge 会把你在浏览器里像 Figma 批注一样留下的评论，批量写入项目的.moat/目录，再由 Cursor 或 Claude Code 通过bridge命令处理成代码修改。理解了这条「浏览器 → 任务文件 → AI」的链路，90% 的常见问题都能快速定位。本文用排查清单的方式，带你逐一解决这三类问题，并给出预防建议。

一、先搞懂 Drawbridge 的数据流，才能对号入座

Drawbridge 由三部分组成，排查时先确认问题出在哪个环节：

核心文件一览（连接项目后自动生成）：

• moat-tasks.md：勾选框形式的任务清单
• moat-tasks-detail.json：包含选择器、截图路径、状态的机器可读数据
• drawbridge-workflow.md：AI 的「大脑」，规则模板
• screenshots/：每条批注的截图，帮 AI 理解你的意图

💡 记住：扩展只负责写文件，AI 只负责读文件。两边「见不到对方」的所有现象，基本都是连接或目录问题。

二、症状 1：Drawbridge 连接断开怎么办？

2.1 为什么每次重启浏览器都要重连？

这是浏览器安全机制的正常限制，不是 Bug。File System Access API 的目录句柄不能跨浏览器会话持久保存，以下情况都会导致连接失效：

• ✅ 浏览器重启（最常见）
• ✅ 项目目录被重命名或移动
• ✅ 浏览器数据被清除
• ✅ 扩展更新

而页面刷新、切换标签页不会断开连接。

2.2 三种重新连接方式

1. 快捷键重连：在浏览器中按Cmd+Shift+P（Mac）或Ctrl+Shift+P（Windows），重新选择项目目录
2. 扩展图标重连：点击 Drawbridge 扩展图标，或点侧边栏设置图标（⚙️）再连接
3. 控制台重连：在浏览器控制台执行setupProject()

重连后扩展会自动重新部署规则模板（见 ARCHITECTURE.md 连接生命周期），无需手动操作。

2.3 一键检查连接状态

在浏览器控制台执行：

window.directoryHandle ? "✅ Connected" : "❌ Not Connected"

如果显示 Not Connected，批注就不会落盘——这就是「任务不保存」的根本原因。

2.4 疑难杂症？用内置诊断命令

扩展提供了调试接口（详见 content_script.js）：

window.moatDebug.diagnoseConnection() // 完整连接诊断 window.moatDebug.checkSystemStatus() // 系统状态检查 window.moatDebug.verifyFiles() // 验证任务文件健康度

三、症状 2：任务丢失怎么找回？

「任务消失」通常不是真丢了，而是没写进去或状态没同步。按下面顺序排查：

3.1 确认.moat/目录是否真的生成了

打开项目根目录，看是否有.moat/文件夹。如果没有，说明扩展从未成功连接，按第二节重连即可。

3.2 任务状态不同步？以 JSON 为准

Drawbridge 采用双文件设计（见 taskStore.js）：moat-tasks.md给人看，moat-tasks-detail.json给 AI 看。两者不一致时：

1. 以 JSON 文件为准
2. 点击侧边栏的🔄 Refresh按钮，从 JSON 重新生成 markdown
3. 旧版本升级时，扩展会自动迁移老文件（.moat-stream.jsonl等）并打上.backup-时间戳后缀，原数据不会删除（见 migrateLegacyFiles.js）

3.3 任务 failed 了怎么重试？

任务在yolo模式下执行失败时，打开.moat/moat-tasks-detail.json，把对应任务的"status"改回"to do"，再跑一次bridge即可重试。状态生命周期严格为："to do" → "doing" → "done"（见 bridge.md）。

四、症状 3：AI 说「找不到文件」怎么办？

AI 报 "No Drawbridge tasks found" 时，按它的查找优先级逐项核对（定义在 bridge.md）：

1. .moat/moat-tasks-detail.json（项目根目录）
2. moat-tasks-detail.json（根目录，旧版位置）
3. ../.moat/moat-tasks-detail.json（上一级目录）

4.1 目录不对？先确认工作目录

最常见的原因：你在src/子目录里打开了编辑器。先cd到项目根目录，确认.moat/就在那里。

4.2 规则模板没部署？重连一次就好

扩展连接项目时会自动把 rules-templates/ 里的模板部署进.moat/。如果模板缺失，AI 不知道去哪读任务——重新连接项目即会自动修复。

4.3 Cursor 里bridge命令不灵？用显式指令

如果bridge命令跑不起来，换成更明确的说法（来自 README.md 官方建议）：

use @drawbridge-workflow.mdc to process @moat-tasks.mdc

4.4 提示「空任务列表」怎么办？

如果显示 "No pending tasks found"，说明文件存在但全是done或还没创建批注——回到浏览器按f（或C）进入标注模式，点选元素写评论，任务会自动出现在.moat/moat-tasks.md。

五、其他高频问题速查表

📌 小贴士：截图报错 "Attempting to parse an unsupported color function 'lab'" 是旧版本问题，已在 1.0.1 修复，升级到 CHANGELOG.md 中的新版本即可。

六、预防清单：把问题挡在发生之前

• 📌每个浏览器会话连接一次：重启浏览器后先重连，再开始标注
• 📌别改名、别移动项目目录：目录句柄会因此失效
• 📌一个标签页对应一个项目：多标签多项目时逐一连接
• 📌标注要具体：「字体改成 sans-serif」优于「改字体」，AI 更不容易跑偏
• 📌收藏本地开发地址：减少重新寻找项目的成本

相关文档

• 官方说明与故障排查：README.md、chrome-extension/README.md
• 架构与连接生命周期：chrome-extension/ARCHITECTURE.md
• 连接后自动生成的项目内指南：chrome-extension/rules-templates/README.md
• AI 命令规则：chrome-extension/rules-templates/bridge.md

按上面的顺序排查：先确认连接 → 再核对任务文件 → 最后检查 AI 的目录与指令，绝大多数 Drawbridge 问题都能在三分钟内解决。