docs(agents): add Cursor Cloud dev environment setup instructions

[jh0904]

Summary

搭建并验证了 SuperDuck 在 Cursor Cloud 环境下的开发环境(chrome-crx 扩展 + chrome-native-host Go CLI/桥),并把过程中发现的、非显而易见的启动/联调坑记录到 AGENTS.md 的 ## Cursor Cloud specific instructions。本 PR 仅新增文档(15 行),不改任何代码。

Type of change

• docs — documentation only

Affected components

• Root tooling (.github/workflows, scripts/, AGENTS.md, hooks)

Implementation notes

环境搭建要点(依赖刷新已配置为 update script:根 bun install --frozen-lockfile + chrome-native-host 的 go mod download):

• Bun 版本:根 bun.lock 为 lockfileVersion 1,需 Bun ≥ 1.2(本环境用 1.3.14)。.devcontainer/post-create.sh pin 的 Bun 1.1.42 读不了该 lockfile(会降级重写、污染工作区),已在 AGENTS.md 说明。
• 加载扩展:系统 google-chrome 148 会静默忽略 --load-extension(企业策略),需用 Playwright 自带 Chromium(e2e 同款)。
• CLI ↔ 扩展联调:需把 native messaging manifest 也放到 ~/.config/chromium/NativeMessagingHosts/,并直接启动 chromium 二进制(绕开 Playwright 的 CDP,否则 chrome.debugger.attach 超时),软件 GPU 需 --disable-gpu。

Verification

已运行并通过:

# chrome-crx
cd chrome-crx
bun run lint:ci        # ✅
bun run typecheck      # ✅
bun run test           # ✅ 50 files / 487 tests passed
bun run build          # ✅ dist/ 产出
xvfb-run -a bun run test:e2e   # ✅ 30 passed(1 并发抖动用例单独重跑通过)
bun run format:check   # ✅

# chrome-native-host
cd chrome-native-host
make lint              # ✅ 0 issues
make test              # ✅ go test ./... 全通过
make                   # ✅ 构建 native-host / mcp-server / superduck

# AGENTS.md 自验
node scripts/validate-agents-md.mjs   # ✅

端到端 hello-world:用 Playwright Chromium 加载 dist/,注册 native messaging host,superduck CLI 成功创建 tab group、导航实时标签页并通过扩展截图。

CLI 通过扩展对实时浏览器抓取的 example.com 截图:

Tests added / updated

• No tests needed because: 仅文档改动

Security & privacy

• No new secrets / API keys are committed.
• .gitignore still covers any newly produced artifacts.

Reviewer checklist

• Title follows Conventional Commits.
• PR is focused — 仅 AGENTS.md 文档。
• Documentation updated (AGENTS.md).

  

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 483290e7-b975-42f6-bb95-3c37dd33120d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/setup-dev-environment-b58f

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request adds a new section to AGENTS.md detailing specific instructions and troubleshooting steps for Cursor Cloud agents. The reviewer provided valuable feedback to improve the documentation's actionable quality, including suggesting an upgrade to the Bun version in the Dev Container configuration to prevent workspace pollution, and providing concrete shell command examples for copying manifests and launching Chromium with the correct flags.

[gemini-code-assist]

⚠️ Dev Container 自动构建时的 Bun 版本冲突风险

由于 .devcontainer/post-create.sh 在 Dev Container 启动时会自动执行（通过 postCreateCommand），如果其中仍固定（pin）了 Bun 1.1.42，那么任何人在打开 Dev Container 时，工作区中的 bun.lock 都会被自动降级重写为 version 0 并污染工作区。

为了避免这种开箱即用的不良体验，建议在后续的 PR 中（或直接在此 PR 中）将 .devcontainer/post-create.sh 中的 Bun 版本也同步升级到 1.2 或更高版本（例如 1.3.14），而不是仅仅在文档中进行警告。

建议修改：

- **Bun 版本**:根 `bun.lock` 是 lockfileVersion 1,需 **Bun ≥ 1.2**(本环境用 1.3.14)。`.devcontainer/post-create.sh` 里 pin 的 Bun 1.1.42 **读不了**该 lockfile(会把它降级重写成 version 0、污染工作区),不要用它（建议后续将 `.devcontainer/post-create.sh` 中的 Bun 版本同步升级至 ≥ 1.2）。根目录 `bun install` 已通过 workspaces 覆盖 `chrome-crx` 等所有子包(hoist 到根 `node_modules/`),无需再单独进 `chrome-crx` 安装。

[gemini-code-assist]

💡 建议提供具体的复制命令以提高可操作性

为了方便开发者快速配置，建议在此处提供具体的复制命令。这样开发者可以直接复制执行，避免手动创建目录和复制文件时出错。

建议修改：

  2. 用 Playwright 的 Chromium 时,还要把同一 manifest 复制到 **`~/.config/chromium/NativeMessagingHosts/`** 才能被找到(否则扩展报 "Specified native messaging host not found")。可以使用以下命令：
     ```bash
     mkdir -p ~/.config/chromium/NativeMessagingHosts && cp ~/.config/google-chrome/NativeMessagingHosts/com.me.superduck_browser_extension.json ~/.config/chromium/NativeMessagingHosts/
     ```

[gemini-code-assist]

💡 建议提供具体的 Chromium 启动命令示例

在步骤 3 中，列出了许多启动参数（如 --user-data-dir=<dir>、--load-extension=<dist> 等）。为了让开发者更直观、更方便地一键运行，建议提供一个完整的、带占位符替换示例的 shell 命令。

建议修改：

  3. **直接**启动 Playwright 的 chromium 二进制(`~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome`),**不要**经 Playwright 的 CDP 连接启动:Playwright 占用 CDP 会让扩展的 `chrome.debugger.attach` 超时,导致 `screenshot`/`context`/`read_page` 失败。
     启动示例：
     ```bash
     ~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome \\
       --user-data-dir=/tmp/chrome-user-data \\
       --load-extension=$(pwd)/chrome-crx/dist \\
       --disable-extensions-except=$(pwd)/chrome-crx/dist \\
       --silent-debugger-extension-api \\
       --disable-gpu \\
       --no-sandbox
     ```
     *(注：软件 GPU 在重页面(如 Wikipedia)会整个浏览器崩溃,务必 `--disable-gpu`)*