Drawbridge - 针对 Claude Code 和 Cursor 的可视化标注工具

在浏览器中添加注释（类似于 Figma），并将这些注释发送到 Claude Code 和 Cursor。这款 Chrome 插件与 Cursor 规则集结合，可将您的浏览器连接到本地开发项目。前端页面上的注释会批量汇总到一个 Markdown 文件中，运行 bridge 命令即可在 Cursor 中处理这些注释。通过为 Cursor 中的视觉编辑添加更多上下文，简化您的工作流程。

🚀 1. 设置

1. 下载或克隆 Drawbridge 到您的桌面或其他位置。

2. 打开 Chrome 扩展程序管理页面，切换到开发者模式，并解压扩展程序 drawbridge/chrome-extension。

3. 激活插件。

4. 将其固定以便于访问。

💬 2. 连接您的项目

1. 点击图标以打开 Drawbridge。

2. 点击“Connect”以打开文件浏览器。

3. 选择您想要工作的本地项目文件夹。

4. 授予 Drawbridge 编辑文件的权限。

5. 现在，Drawbridge 可以写入 moat-tasks.mdc 和 moat-task-detail.json 文件。

💬 3. 添加注释

1. 在浏览器中按下 C 键（或点击“Tools”下拉菜单 → “Comment”），将光标变为指针。

2. 将鼠标悬停在页面上，查看可选的 DOM 元素，您可以在这些元素上留下注释。

3. 单击某个元素以添加注释，输入内容后按 Submit 或 Enter 键。

4. 任务将显示在页面底部的“Moat”区域。

5. 任务也会同步到 Cursor。

📐 4. 绘制矩形（自由形式标注）

1. 在浏览器中按下 R 键（或点击“Tools”下拉菜单 → “Rectangle”），进入矩形绘制模式。

2. 光标将变为十字准线，表示您正处于绘制模式。

3. 在页面上单击并拖动，围绕您想要标注的区域绘制矩形。

4. 松开鼠标按钮以完成矩形绘制——此时会在光标位置出现一个注释框。

5. 输入您的注释并按 Submit 或 Enter 键。

6. 矩形的坐标和截图将与您的任务一同保存。

快捷键：

• 按 C 切换到评论模式（指针光标）。
• 按 R 切换到矩形模式（十字准线光标）。
• 按 Esc 退出任一模式。
• 您可以在开始交互之前使用 C 和 R 在两种模式之间切换。

🤖 5. 使用 AI 处理

Drawbridge 可与 Cursor 和 Claude Code 配合使用：

在 Cursor 中

1. 运行 Drawbridge：在编辑器中，只需运行以下命令：

   bridge
   

2. Drawbridge 将分析您的任务、理解依赖关系，并开始进行编辑。

3. 批准：默认情况下，Drawbridge 以“Step”模式逐个处理任务。系统可能会要求您进行批准：

   1. 开始执行任务。
   2. 完成任务（更新 moat-tasks.md 和 moat-tasks-detail.json 中的状态）。

4. 等待：您可以观察任务在 moat-tasks.md 中被更新的情况。

5. 如果在使用“bridge”命令时遇到问题，只需更明确地说明：“使用 @drawbridge-workflow.mdc 处理 @moat-tasks.mdc”。

在 Claude Code 中

1. 运行斜杠命令（在终端或 Cursor 中使用 Claude Code 时均可）：

   /bridge
   

2. 选择模式：Claude 会询问您偏好的处理模式：

   • step：一次处理一项任务，需经批准
   • batch：将相关任务分组一起处理
   • yolo：自主处理所有任务

3. 自动设置：当您连接项目时，/bridge 命令会自动部署到 .claude/commands/ 目录中。

Claude Code 功能：

• ✅ 智能错误提示 - 如果未找到任务，会提供有用的指导
• ✅ 文件引用 - 任务包含文件路径，方便导航
• ✅ 截图支持 - 通过浏览器标注提供视觉上下文
• ✅ Git 安全 - 自动将 .claude/ 和 .moat/ 添加到 .gitignore
• ✅ 状态跟踪 - 按照“待办”→“进行中”→“已完成”的生命周期管理任务

👩🏼‍🎨 6. 查看您的更改

1. 返回浏览器查看您的更改

   1. 如果您使用的是 React 或 Next.js，通常会自动更新

   2. 如果您使用的是 HTML/CSS/JS，请手动刷新页面

2. 继续编辑以完善您的作品！

📁 核心文件

• drawbridge-workflow.mdc：AI 的主要规则集。这是 Drawbridge 的“大脑”所在。

• moat-tasks.md：一份人类可读的待处理任务列表。

• moat-tasks-detail.json：每项任务的原始详细数据，包括选择器和截图路径。

• /screenshots：每个标注的视觉上下文，供 AI 理解您的意图。

🎯 示例工作流程

1. 标注：

   • 点击一个按钮 → “把这个变成绿色”。

   • 再次点击同一个按钮 → “再加点内边距”。

2. 处理：在编辑器中运行 bridge。

3. AI 分析：

   🤖 检测到依赖关系。正在先处理“把这个变成绿色”，再处理“再加点内边距”。
   

4. 审查：AI 会查看您的 moat-tasks-detail.json，了解评论的具体内容。

5. 批准：您回复 yes。

6. 重复：AI 接着处理下一项依赖任务。

🛠️ 高级用法与处理模式

您可以通过指定模式来控制 Drawbridge 处理任务的方式。

• step bridge（默认：安全且逐步推进）

  • 逐个处理任务，每一步都需要您的批准。非常适合复杂的更改。

• batch bridge（高效且分组处理）

  • 智能地将相关任务（例如所有按钮样式）分组在一起，并一次性请求批准。

• yolo bridge（自主且快速）

  • 请谨慎使用。 按照正确的依赖顺序自动处理所有待处理任务，无需中途等待批准。最后会提供一份完整的总结。

🎨 标注最佳实践

• 尽量具体：“把字体改为无衬线体”比“改变字体”更好。

• 逻辑清晰：对于多步骤的更改，应创建相互关联但独立的标注。AI 能够理解操作顺序。

  • 好例子：1. “把按钮变成蓝色” → 2. “给蓝色按钮加上阴影”

  • 坏例子：1. “把按钮变成蓝色并加上阴影”

• 一次只做一件事：每个标注应代表一个明确的变化。

🐛 故障排除

• “依赖错误”：这意味着任务可能没有按照正确的顺序执行。请查看 AI 的分析，确认正确的执行顺序。

• 任务状态为“失败”：如果任务失败（尤其是在 yolo 模式下），请检查 moat-tasks.md。您可以在 .json 文件中将其状态重置为“待处理”，以便重新尝试。

• 连接问题：如果 Drawbridge 找不到任务，请在浏览器中按 Cmd/Ctrl+Shift+P，然后重新选择您的项目目录以重新连接。

祝您使用 Drawbridge 构建愉快！ 🎯

📄 许可证

本项目采用自定义许可证授权。详情请参阅 LICENSE 文件。

要点：

• ✅ 可免费用于任何合法目的，可复制和修改
• ❌ 不得再分发、转授权或出售
• ❌ 不得作为商业服务提供

如需商业授权，请联系：breschicreative@gmail.com

Drawbridge 快速上手指南

Drawbridge 是一款浏览器插件，支持在网页上像 Figma 一样进行视觉标注（评论或绘制矩形），并将这些注释同步到本地项目，通过 AI 助手（Cursor 或 Claude Code）自动执行代码修改。

环境准备

• 操作系统：Windows, macOS, Linux
• 浏览器：Google Chrome 或基于 Chromium 的浏览器（如 Edge）
• 开发工具：
  • Cursor 编辑器（推荐）或终端中的 Claude Code
  • Node.js 环境（用于运行本地项目）
• 前置依赖：无需额外安装 npm 包，核心逻辑通过 .mdc 规则文件集成。

安装步骤

1. 获取源码

下载或克隆 Drawbridge 仓库到本地任意位置：

git clone https://github.com/breschio/drawbridge.git
# 或者手动下载 ZIP 包并解压

2. 加载浏览器插件

1. 打开 Chrome 浏览器，地址栏输入 chrome://extensions/ 进入扩展管理页面。
2. 右上角开启 “开发者模式” (Developer mode)。
3. 点击 “加载已解压的扩展程序” (Load unpacked)。
4. 选择刚才下载的 drawbridge/chrome-extension 文件夹。
5. 插件激活后，建议点击图钉图标将其固定在工具栏以便访问。

3. 连接本地项目

1. 在浏览器中点击 Drawbridge 插件图标。
2. 点击 "Connect" 按钮，在弹出的文件选择器中找到你的本地前端项目根目录。
3. 授予 Drawbridge 写入权限。
4. 连接成功后，插件将在项目根目录生成 moat-tasks.mdc 和 moat-task-detail.json 文件。

基本使用

第一步：在浏览器中添加注释

打开你的本地开发服务器页面（如 localhost:3000）：

1. 添加评论：按下键盘 C 键（或点击插件菜单 → Comment），鼠标变为指针。悬停选中页面上的 DOM 元素，点击后输入指令（例如："make this button green"），按 Enter 提交。
2. 绘制区域：按下键盘 R 键（或点击插件菜单 → Rectangle），鼠标变为十字准星。拖拽绘制矩形框选区域，输入指令并提交。
3. 所有任务将显示在页面底部的 Moat 区域，并同步至本地文件。

第二步：在编辑器中处理任务

方案 A：使用 Cursor（推荐）

1. 打开你的项目文件夹。
2. 在 Chat 面板或命令行中输入以下命令：

   bridge
   

3. AI 将分析任务依赖关系。默认采用 Step 模式，每步需确认：
   • 确认开始任务。
   • 确认任务完成（状态将更新为 "done"）。
4. 若命令未识别，可显式调用：

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

方案 B：使用 Claude Code

1. 在终端或 Cursor 的 Claude 模式中运行：

   /bridge
   

2. 选择处理模式：
   • step: 逐个处理，需人工确认（安全）。
   • batch: 智能分组处理。
   • yolo: 全自动处理所有任务（慎用）。

第三步：查看结果

• React/Next.js 项目：修改通常会自动热重载，直接在浏览器查看效果。
• 传统 HTML/CSS 项目：刷新浏览器页面即可看到变更。
• 如需调整，可继续在浏览器中添加新注释并重复上述流程。