Cursor Cloud 专用说明

这些说明只针对 Cursor Cloud 智能体（因为 T3 Code 在很多地方开发，所以没有放进共享的 AGENTS.md）。内容包括预先配好的虚拟机环境，以及不那么显而易见的运行注意点。

工具链

已经预装，并接进登录 shell（~/.bashrc/~/.profile）：通过 nvm 安装的 Node 24、全局的 vp（Vite+）CLI，以及它自带的 pnpm。vp 是这个仓库的包管理器，也是任务运行器（vp i、vp check、vp run typecheck、vp test、vp run --filter <pkg> <script>）。

• Node 的易错点：基础镜像还在 /exec-daemon 自带一个更旧的 Node，非登录 shell 里它会在 PATH 上抢先被找到。在登录 shell（bash -lc '...'）里跑命令，或者在前面加上 $HOME/.nvm/versions/node/v24.13.1/bin，这样才会用到 Node 24（engines.node: ^24.13.1）。
• vp check 也会跑格式化，不只是 lint；Markdown 改动必须经得起格式化。提交前先跑 vp check --fix。

运行 Web 应用

• 在仓库根目录运行 npm run dev，会同时拉起 contracts（watch）、web（Vite，端口 5733）和服务器（node --watch，端口 13773），并自动接上 VITE_HTTP_URL/VITE_WS_URL。只跑一边时用 npm run dev:server / npm run dev:web。基础端口已被占用时，它会自动错开到下一对空闲端口，所以实际端口要看标准输出。开发时不要跑生产用的 build/start。
• 认证与配对：服务器默认不做认证，启动时把配对 URL 打到标准输出（例如 http://localhost:5733/pair#token=XXXX）。先在浏览器里打开这个 URL 完成配对，Web 界面才能和服务器通信。服务器状态（SQLite、认证、项目（project））放在 ~/.t3（T3CODE_HOME）；多个 npm run dev 实例绑定的端口不同，但共用这同一个数据库。
• 智能体的提供方（provider）是外部 CLI（codex、claude、cursor-agent、opencode），在 PATH 上探测。一个都没装时，界面能打开，但没有智能体可以运行。Claude Code（npm i -g @anthropic-ai/claude-code）可以用环境里的 ANTHROPIC_API_KEY 无头运行（服务器会把 process.env 转给子进程；不需要交互式的 claude auth login）。提供方探测在启动时进行，大约每 5 分钟刷新一次——想立刻识别新安装的提供方 CLI，就重启开发服务器。

Android 原生构建（apps/mobile）

Android 工具链已经预装，并接进登录 shell：OpenJDK 17（JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64；基础镜像默认的 java 是 21，所以构建必须使用 JAVA_HOME），以及位于 $HOME/Android/Sdk 的 Android SDK（ANDROID_HOME/ANDROID_SDK_ROOT），其中有 platform-tools、platforms;android-36、build-tools;36.0.0、ndk;27.1.12297006 和 cmake;3.22.1。其余钉住版本的 SDK 包，Gradle 会在需要时自动下载。

• 先生成原生工程：在 apps/mobile 下执行 EXPO_NO_GIT_STATUS=1 APP_VARIANT=development npx expo prebuild --clean --platform android（android/ 目录是生成出来的，不提交）。RN 0.85 的默认值：compileSdk/targetSdk 36，minSdk 24，NDK 为 27.1.12297006（见 react-native/gradle/libs.versions.toml）。
• 在 apps/mobile/android 下用 Gradle 构建，例如 ./gradlew :app:assembleDebug。第一次构建比较慢（Kotlin 以及 C++/NDK 的代码生成）。限制 ABI 可以加快速度，例如 -PreactNativeArchitectures=arm64-v8a。已在一个原生模块上做过端到端验证：./gradlew :react-native-worklets:assembleDebug 会编译 Kotlin 和 C++，并产出一个 AAR 和若干 .so。
• 没有模拟器：这台虚拟机没有 /dev/kvm（嵌套虚拟化），硬件加速的 Android 模拟器跑不起来。要真正把应用跑起来，用物理设备（adb）或 EAS 云构建（vp run eas:android:*）。这里不需要完整的 IDE 图形界面——装上的是 Android Studio 所带的 SDK、NDK 和 Gradle 工具链。
• 完整应用的 :app:assembleDebug 有一个已知的阻塞（原先就有，出在应用层，不是环境的问题）：:react-native-screens:compileDebugKotlin 会失败，因为 patches/react-native-screens@4.25.2.patch 给 JS spec 和 iOS 原生代码加了新的代码生成 props（subtitle、largeSubtitle、navigationItemStyle、headerCenterBarButtonItems、headerToolbarItems），却没有 Android 的 Kotlin setter，所以生成出来的 ScreenStackHeaderConfigManagerInterface 没有实现。移动端 README 只写了本地构建的 iOS，Android 则走 EAS。要在本地修好 Android 应用的构建，需要改应用或补丁（补上 Android 的 Kotlin setter），这不属于环境搭建的范围。

已知的不稳定测试（与环境搭建无关）

• apps/server/src/git/GitManager.test.ts（跨仓库的 PR 元数据，可能在 12 秒时超时）。
• apps/server/src/provider/ProviderRegistry.test.ts（codex 的 binaryPath 重新探测的顺序）。