docs(agents): add Cursor Cloud environment setup notes

[jh0904]

Summary

搭建并验证了本仓库在 Cursor 云端环境下的开发环境(Bun / Go 两个主要工作区),并把安装过程中发现的非显而易见坑记录进 AGENTS.md 的 ## Cursor Cloud specific instructions,供后续云端代理复用。除文档外没有改动任何产品代码。

Refs: dev environment setup

Type of change

• docs — documentation only

Affected components

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

Implementation notes

• 启动脚本(update script)设为最小依赖刷新:bun install + go -C chrome-native-host mod download。
• 其余工具链(新版 Bun、Go 1.25、golangci-lint、Playwright + Chromium 及系统依赖)固化在 VM 快照,不进 update script。
• AGENTS.md 新增云端小节,记录的关键坑:
  • 仓库根 bun.lock 是较新 lockfile 格式,devcontainer pin 的 bun@1.1.42 无法解析,需用新版 Bun。
  • 扩展无本地 dev server(bun run dev 是 vite watch → dist/)。
  • bun run test:e2e 用 Playwright 把 dist/ 加载进完整版 Chromium 做端到端验证;SKIP_BUILD=1 复用已有 dist/;个别 p0-*/06-browser-batch 用例并行下 flaky,单独重跑必过。
  • superduck CLI 的真实 native-messaging 链路在云端未接好,端到端验证用 Playwright e2e。

Screenshots / recordings

在真实 Chromium 中加载构建好的扩展、打开 side panel 并完成一次「你好」对话(mock LLM)。

Verification

# chrome-crx
cd chrome-crx
bun run typecheck      # tsc --noEmit
bun run lint:ci        # eslint --max-warnings=0
bun run format:check   # prettier --check
bun run test           # vitest: 487 passed
bun run build          # 构建成功 → dist/
SKIP_BUILD=1 bun run test:e2e  # Playwright: 加载真实扩展, 30 passed (flaky 用例单独复跑通过)

# chrome-native-host
cd chrome-native-host
make                   # 构建 native-host / mcp-server / superduck
make test              # go test ./... 全绿
make lint              # golangci-lint: 0 issues

Tests added / updated

• No tests needed because: docs-only(仅新增 AGENTS.md 说明)

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.
• 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: 73bf46e1-8a94-47c2-aa01-6353514c02b4

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-1569

---

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 "Cursor Cloud specific instructions" section to AGENTS.md, detailing VM environment configurations, toolchain behaviors (such as Bun versions), and testing guidelines. The review feedback suggests improving these instructions by recommending a future Dev Container configuration update to resolve Bun version conflicts, advising developers to limit Playwright workers to mitigate flaky tests in resource-constrained environments, and refining the phrasing regarding superduck CLI limitations to be more professional and technically precise.

[gemini-code-assist]

虽然在文档中记录此问题对后续开发者很有帮助，但根本的解决办法是更新 Dev Container 配置文件（如 .devcontainer/devcontainer.json 或相关初始化脚本）中固定的 Bun 版本（例如升级到 1.2.0 或更高版本），以确保新拉取环境的用户不会遇到此问题。建议在后续 PR 中彻底修复该配置，并在本文档中补充说明。

Suggested change

	- **Bun 版本**:仓库根 `bun.lock` 用的是较新的 lockfile 格式,devcontainer 里 pin 的 `bun@1.1.42` 无法解析(报 `Unknown lockfile version`)。快照里装的是新版 Bun(`bun --version` 应 ≥ 1.3);不要降级到 1.1.42。
	- **Bun 版本**: 仓库根目录的 bun.lock 采用了较新的 lockfile 格式（Bun 1.2+），而 Dev Container 中固定的 bun@1.1.42 无法解析该格式（会报错 Unknown lockfile version）。云端快照中已预装新版 Bun（bun --version 应 ≥ 1.3），请勿降级至 1.1.42。*（注：建议后续直接更新 Dev Container 配置文件以彻底解决此版本冲突）*

[gemini-code-assist]

在云端 VM 等资源受限的环境中，并行运行测试极易因 CPU/内存争抢导致 flaky 失败。建议在此处补充说明：如果遇到此类偶发失败，可以通过限制 Playwright 的 worker 数量（例如追加 -- --workers=1）来降低并发，从而提高测试运行的稳定性。

Suggested change

	- **端到端验证扩展**:`cd chrome-crx && bun run test:e2e` 会用 Playwright 把真实的 `dist/` 加载进**完整版 Chromium**(不是 `chrome-headless-shell`,后者会静默禁用 `--load-extension`)。用 `SKIP_BUILD=1 bun run test:e2e` 复用已有 `dist/` 跳过重复构建。少数 `p0-*` / `06-browser-batch` 用例在并行满载下偶发失败,但单独重跑必过——属已知 flaky,非环境问题。
	- **端到端验证扩展**: cd chrome-crx && bun run test:e2e 会用 Playwright 把真实的 dist/ 加载进完整版 Chromium（不是 chrome-headless-shell，后者会静默禁用 --load-extension）。用 SKIP_BUILD=1 bun run test:e2e 复用已有 dist/ 跳过重复构建。少数 p0-* / 06-browser-batch 用例在并行满载下偶发失败（属已知 flaky，非环境问题），在云端资源受限时，可尝试通过限制并发（如 bun run test:e2e -- --workers=1）来稳定运行。

[gemini-code-assist]

“在云端 VM 里没有接好” 表述较为口语化。建议修改为更专业、准确的描述，并简要说明原因（如云端环境缺少 GUI 桌面及已登录的 Chrome 实例），以便后续开发者或 AI 代理更清晰地理解技术限制。

Suggested change

	- **superduck CLI 的完整链路**(CLI → native host → 已登录的真实 Chrome + 扩展 native messaging)在云端 VM 里没有接好;要端到端验证浏览器自动化,用上面的 Playwright e2e 套件,而不是 `chrome-native-host/testdata/` 里那些需要真实 Chrome 的冒烟脚本。
	- **superduck CLI 的完整链路**（CLI → native host → 已登录的真实 Chrome + 扩展 native messaging）在云端无 GUI 的 VM 环境中无法直接运行（缺少真实的 Chrome 实例及登录态）；若需端到端验证浏览器自动化，请使用上述 Playwright e2e 测试套件，而非 chrome-native-host/testdata/ 下依赖真实 Chrome 的本地冒烟脚本。