Skip to content

docs(agents): add Cursor Cloud environment setup notes #296

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jh0904 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(agents): add Cursor Cloud environment setup notes #296

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,3 +247,13 @@ go run ./testdata/server -addr :8765 & # 本地测试服
- Label 命名使用 `<group>: <slug>`,例如 `type: bug`、`area: chrome-crx`、`priority: P1`、`status: ready`。
- 新建 issue 至少添加一个 `type:` 和一个 `area:`;bug / agent-task 还应添加 `priority:`。
- 代理挑任务时优先看 `agent: ready` + `status: ready`,再按 `priority:` 和 `area:` 过滤。

## Cursor Cloud specific instructions

面向在已跑过启动脚本(`bun install` + `go -C chrome-native-host mod download`)的云端环境里工作的后续代理。工具链(Bun、Go 1.25、golangci-lint、Playwright + Chromium 及其系统依赖)已固化在 VM 快照里,常规构建 / lint / test / run 命令见上文「构建命令」小节,这里只补充非显而易见的坑:

- **Bun 版本**:仓库根 `bun.lock` 用的是较新的 lockfile 格式,devcontainer 里 pin 的 `bun@1.1.42` 无法解析(报 `Unknown lockfile version`)。快照里装的是新版 Bun(`bun --version` 应 ≥ 1.3);不要降级到 1.1.42。

@gemini-code-assist gemini-code-assist Bot Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

虽然在文档中记录此问题对后续开发者很有帮助，但根本的解决办法是更新 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 配置文件以彻底解决此版本冲突）*

- **扩展没有本地 dev server**:`bun run dev` 只是 `vite build --watch`,产物写进 `chrome-crx/dist/`。要在真实浏览器里验证得把 `dist/` 作为「加载已解压的扩展」载入 Chrome。
- **端到端验证扩展**:`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,非环境问题。

@gemini-code-assist gemini-code-assist Bot Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

在云端 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）来稳定运行。

- **Go 侧 lint**:`golangci-lint` 由 `make lint-install` 装到 `~/go/bin`(已在快照内),不在 PATH 时 `make lint` 会自动回退到该路径。
- **superduck CLI 的完整链路**(CLI → native host → 已登录的真实 Chrome + 扩展 native messaging)在云端 VM 里没有接好;要端到端验证浏览器自动化,用上面的 Playwright e2e 套件,而不是 `chrome-native-host/testdata/` 里那些需要真实 Chrome 的冒烟脚本。

@gemini-code-assist gemini-code-assist Bot Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

“在云端 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 的本地冒烟脚本。