PocketCode

English

PocketCode 是一个面向 Android 的移动 AI 编程工作台，让 AI Agent 在手机本地完成 code、build 和 run。用户可以选择设备上的项目工作区，创建编程会话，向 Agent 描述任务，并让 Agent 在工作区中阅读和修改文件、调用工具、运行 shell/PTY 命令、编译 Android 应用，再通过系统安装器安装到手机上进行测试。

Android 构建能力由独立的 android-builder 提供；PocketCode 负责把 Agent、项目工作区、设备能力和构建结果连接起来。

简单来说，PocketCode 想实现的是：

不打开电脑，也能在手机上打开一个项目，让 AI Agent 直接完成一轮编码、编译和运行。

当前已实现

当前版本是 Android-only 的开发中版本，已经具备以下主要能力：

• 在 Android 应用内启动本地 Node 运行时，不依赖电脑上的桌面 host；
• 创建、选择、重命名、归档和切换工作区与会话；
• 在移动端进行流式对话，查看会话历史、工具调用、执行轨迹和输出结果；
• 支持 Agent preset、Skill、命令、模型/provider、reasoning effort 和权限 preset；
• 支持工具审批、用户提问、计划、Todo、Goal、Workflow 和运行中任务等交互；
• 通过 Android capability provider 访问工作区文件、附件、凭据、shell、PTY 和受控子进程；
• 支持图片附件、模型能力检查、应用内安全存储和 Android 原生桥接；
• 通过 android-builder 提供的 Android Gradle 构建引擎调用 android_build，在设备侧生成 APK/AAB；
• 通过 android_install 将工作区内的 APK 交给 Android 系统安装器，用户确认后即可在手机上安装和运行本地构建结果。

模型 provider 仍然可以通过 HTTPS 访问远端服务，但 Agent、Session、Tool、事件流和本地持久化都由设备内的运行时负责。

工作方式

┌──────────────────── Android App ────────────────────┐
│ React Native UI                                     │
│   工作区 / 会话 / 对话 / 工具交互 / 设置             │
│                       │                             │
│ Android Native Bridge│                             │
│                       ▼                             │
│ 本地 Node 运行时（sidecar）                          │
│   Agent / Session / Tool / Persistence / Events     │
│                       │                             │
└───────────────────────┼─────────────────────────────┘
                        │ HTTPS
                        ▼
                模型与 provider 服务

编码、构建和运行链路：

Agent → android_build → android-builder / Gradle → APK/AAB
     → android_install → Android 系统安装器 → 手机上的应用

PocketCode 不是一个远程聊天客户端，也不是一个托管平台。它的重点是把 Agent 的运行边界从电脑移到 Android 设备内；网络主要用于访问模型 provider 或其他明确配置的远程服务。

项目结构

packages/app/                 React Native Android 应用
packages/standalone-runtime/  设备内 Agent/Session/Tool 运行时
packages/app/android/          Android 原生服务、JNI/PTY 和 capability bridge
protocol/                     协议类型、事件和 RPC 边界
packages/connection/           远程兼容模式的连接层
packages/runtime/              远程兼容模式的 projection/runtime 原型
scripts/                      Android runtime、校验和 smoke test 脚本
docs/                         架构、移植审计和实现记录

packages/connection 和 packages/runtime 中的远程兼容代码仍保留用于互操作和回归验证，但不是 standalone 模式的默认核心路径。

在手机上构建和运行 Android 应用

PocketCode 不让 Agent 通过普通 shell 随意猜测 Android 工具链，而是调用 android-builder 提供的 android_build 工具。该工具在应用私有目录中准备 SDK、JDK、Gradle 和 ARM64 native toolchain，并执行项目自己的 Gradle Wrapper。

构建完成后，Agent 将生成的 APK 交给 android_install。Android 会使用系统 Package Installer 展示安装确认；PocketCode 不通过 adb、pm 或 am 绕过系统权限。安装完成后，应用即可直接在设备上运行测试。

设备构建需要经过审核的 Android SDK、JDK、Gradle 和 native toolchain staging。相关 staging 目录不提交到 PocketCode 源码仓库，完整接线说明见 android-builder harness 集成文档。

本地开发

环境要求：Node.js 20+、Android SDK、JDK，以及可用的 Android 设备或模拟器。

# 安装 root 和 workspace 依赖
npm install

# 类型检查、静态检查和单元测试
npm run typecheck
npm run lint
npm test

# 协议、Agent preset 和 UI event 校验
npm run verify:protocol
npm run verify:agent-presets
npm run verify:ui-events

启动 Android 应用：

cd packages/app
npm run android

Android sidecar/PTY 的设备验证脚本：

npm run test:android-pty
npm run test:android-sidecar

正式 release 构建通过 GitHub Actions 完成。release keystore 和密码不放在仓库中，而是通过本地未跟踪配置或 GitHub Secrets 注入。

技术基础：DeepSeek Harness

PocketCode 的 Agent、Session、Tool、Cordis plugin 和部分协议语义基于 DeepSeek Harness（dsh）。dsh 是 PocketCode 的上游运行时基础，PocketCode 在其之上增加了：

• React Native 移动界面；
• Android 文件系统、凭据、附件、shell、PTY 和 sandbox provider；
• Node sidecar 与 Android 原生桥；
• 面向触屏交互的会话 projection、工具展示、审批和提问界面。

因此，PocketCode 的产品定位是“Android 上的本地 AI 编程工作台”，而不是 dsh 的桌面或 Web 客户端移植。

当前范围

• 目前只支持 Android，iOS 不在当前范围内；
• 这是开发中版本，部分 Android builder 和设备能力仍在持续完善；
• 使用模型 provider 需要在应用设置中配置相应的 provider 和凭据；
• 仓库当前尚未声明最终的开源许可证。公开使用或再发布前，请确认本项目及上游依赖的许可证和 NOTICE 要求。