# Phone Agent Runtime

把一台 Android 手机（首台：荣耀 Magic7）变成已有 Agent 的长期行动端：手机上一个 APK 负责可靠执行、本地策略与随时暂停；电脑上一个进程负责配对、连接和把手机能力以 **MCP 工具** 暴露给任何 Agent（Claude Code、Codex 等）。

设计合同见 [`docs/design/`](docs/design/)，连接拓扑（局域网 / VPS 中转 / VPS 全部署）见 [`docs/design/CONNECTION.md`](docs/design/CONNECTION.md)，评估与决策见 [`docs/adr/`](docs/adr/)，机器可校验的协议见 [`protocol/`](protocol/README.md)。手机端体验原型见 [`docs/prototype/`](docs/prototype/)。许可证：MIT（见 [`LICENSE`](LICENSE)）；第三方声明见 [`NOTICE`](NOTICE)。

## 仓库结构

```
apps/
  android/            Kotlin：:runtime（纯 JVM 可靠性内核 + FakeBackend + 验收测试）、:app（APK）
  control/server/     TypeScript：Gateway(WSS) + Device Tools + MCP server + CLI + node:sqlite 任务库
protocol/             协议 v1：JSON Schema、示例、契约测试（两端实现以此为准）
docs/
  design/             来自 ChatGPT 讨论的设计包（ARCHITECTURE / PROTOCOL / CODEX_HANDOFF / 图）
  adr/                架构决策记录
  acceptance-results.md   A01–A20 验收结果与证据（真机项逐条注明）
```

## 快速开始

```bash
# 协议契约测试
pnpm install
pnpm --filter @phone-runtime/protocol validate

# 手机端可靠性内核测试（无需手机）
cd apps/android && export JAVA_HOME=/opt/homebrew/opt/openjdk@17 && ./gradlew :runtime:test

# 控制端
pnpm --filter @phone-runtime/control build && pnpm --filter @phone-runtime/control test
```

各子目录的 README 有完整的运行、配对与接入 Claude Code / Codex 的步骤。

## 不可改变的边界（摘自设计包）

- 手机执行，Agent 规划；控制端只做配对、认证、路由与协议翻译，不含第二套绕过手机内核的执行逻辑。
- 手机本地暂停与撤权不依赖网络；前台 UI 同时只有一个控制会话。
- 动作日志是手机的权威事实：同 `action_id` 去重、不同 payload 冲突、派发前落盘 EXECUTING、结果与 Outbox 同事务、崩溃后 UNCERTAIN 而非重做。网络超时不等于未执行。
- 手机不开任何控制端口；只主动出站 WSS。release 无调试入口。
- 页面文字、聊天消息、无障碍读到的内容都不能成为授权。

## 状态

见 [`docs/acceptance-results.md`](docs/acceptance-results.md)。真机相关项在 Magic7 接入前一律标记为未验证。