# Phtomt

**Repository Path**: lvyuan/Phtomt

## Basic Information

- **Project Name**: Phtomt
- **Description**: Happy Phone Agent - 基于 AI 的 Android 智能体应用，自动操控手机完成复杂任务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-10-21
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Happy Phone Agent (Phtomt)

> 一个基于 AI 的 Android 智能体应用，能够理解用户意图并自动操控手机完成复杂任务。

## 简介

**Happy Phone Agent** 是一款运行在 Android 设备上的 AI 智能体 App（应用名：Happy Agent）。用户只需用自然语言描述一个目标（例如"帮我订一份外卖"、"把微信消息全部标为已读"），应用会自动规划步骤、观察当前页面、做出决策并在授权后执行点击/滑动/输入等操作，协助用户完成日常手机任务。

## 核心特性

- 🤖 **AI 驱动决策** — 集成主流大语言模型，支持流式思考和智能规划
- 👁️ **视觉理解** — 云端视觉模型 + 本地 ML Kit OCR 双引擎，识别页面控件语义和截图文字
- 🔗 **多模型链路聚合** — 主模型（决策）+ 视觉模型（截图描述/坐标定位）+ 思考模型（规划/重规划）可按需组合
- 🖱️ **多通道执行** — 无障碍服务（基础）+ 无线 ADB / Shizuku（高权限）+ Termux（命令行工具链）
- 🔧 **AI 友好命令解析** — ShellCommands 将 AI 短命令（如 `tap 500 800`）翻译为 ADB 命令，支持比例/百分比/像素坐标
- 🛡️ **内置跳广告** — AdSkipperCore 自动识别并关闭青少年模式弹窗、跳过按钮、倒计时广告
- 📍 **常用 App 直达** — AppPageIndex 为系统设置、高德地图等常用 App 提供深链直达
- 🛡️ **安全防护** — 敏感页面自动检测与只读保护；手机号、身份证号、银行卡号自动脱敏
- 📍 **页面指纹验证** — 基于控件特征的页面指纹比对，确保每次操作真正生效
- ⚡ **端侧快速决策** — 内置本地决策引擎，自动处理弹窗/加载等高频场景，减少云端调用
- 🪟 **悬浮窗实时进度** — 液态玻璃悬浮窗 + 系统通知双通道显示任务状态
- 📋 **多任务队列** — 支持顺序执行多个任务，任务可随时取消和重新规划
- 🌐 **中文/英文双语提示词** — 可自由切换，内置自动翻译（AI 缓存去重）
- 📱 **Material 3 设计** — 严格遵循 Material 3 Expressive 视觉标准，支持深色模式
- 💡 **边缘光效** — EdgeLighting 曲面屏边缘光晕效果

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 语言 | Kotlin | 2.0.21 |
| UI | Jetpack Compose | 2024.12.01 |
| 设计 | Material 3 | 1.3.1 |
| 架构 | MVVM + 状态流 | StateFlow / Co-routines |
| 依赖注入 | Koin | 4.0.0 |
| 网络 | OkHttp | 4.12.0 |
| 序列化 | kotlinx-serialization | 1.7.3 |
| 存储 | DataStore | 1.1.1 |
| 本地 OCR | External Vision App（IPC/AIDL） | 外挂端侧 3B 模型 + ML Kit（已从主程序移除以减小包体） |
| ADB 执行 | Shizuku | 高权限 Shell 通道 |
| 最低 SDK | Android 8.0 (API 26) | — |
| 目标 SDK | Android 15 (API 35) | — |

## 项目结构

```
happy_phone agent/
├── app/
│   └── src/main/
│       ├── java/com/phoneagent/
│       │   ├── PhoneAgentApp.kt            # Application 入口（Koin 初始化）
│       │   ├── core/                       # 跨层基础设施（零业务语义）
│       │   │   ├── ai/
│       │   │   │   ├── AiClient.kt         # OpenAI 兼容客户端（流式 + 结构化输出）
│       │   │   │   ├── AiDecision.kt
│       │   │   │   ├── ChatModels.kt
│       │   │   │   └── GlmDefaults.kt
│       │   │   ├── security/
│       │   │   │   └── SensitivePageDetector.kt   # 敏感页检测 + DataSanitizer 脱敏
│       │   │   ├── text/
│       │   │   │   └── HumanTranslator.kt         # 动作 / 错误 / 置信度 → 人话
│       │   │   └── notify/
│       │   │       ├── TaskProgressNotifier.kt    # 任务进度通知
│       │   │       ├── AdbPairingNotifier.kt      # 无线配对通知栏向导
│       │   │       └── ActiveNotifier.kt          # 主动反馈通知（卡顿 / 死循环 / 模板失效等 6 类）
│       │   ├── domain/                     # 纯领域模型与规则
│       │   │   ├── model/
│       │   │   │   ├── AgentAction.kt / AgentIntent.kt / AgentState.kt
│       │   │   │   ├── AppPageIndex.kt            # App 页面直达索引
│       │   │   │   ├── ControlNode.kt / ScreenSnapshot.kt / UiElement.kt
│       │   │   │   └── DebugModels.kt / PhantomModels.kt
│       │   │   └── rules/
│       │   │       ├── EngineRules.kt             # 硬约束规则引擎（拦截危险动作 / 只读横切）
│       │   │       ├── ShellCommands.kt           # AI 友好命令解析器
│       │   │       └── LocalDecisionEngine.kt     # 端侧决策引擎
│       │   ├── data/                       # 持久化与数据源
│       │   │   ├── prefs/
│       │   │   │   └── AppSettings.kt             # DataStore 配置
│       │   │   ├── store/                         # 五处持久化统一收敛
│       │   │   │   ├── MemoryStore.kt
│       │   │   │   ├── TaskStore.kt               # 检查点 + 任务模板库
│       │   │   │   ├── DebugRecordsStore.kt       # 日志 / 轨迹 / 历史 / 对话落盘
│       │   │   │   ├── McpStore.kt
│       │   │   │   └── PromptTemplateStore.kt
│       │   │   └── export/
│       │   │       └── LogExporter.kt             # 日志 / 诊断报告导出
│       │   ├── device/                     # 设备能力接入
│       │   │   ├── a11y/
│       │   │   │   ├── AgentAccessibilityService.kt
│       │   │   │   └── ActionExecutor.kt          # 动作执行 + 语义 ID 定位
│       │   │   ├── shell/                         # 无线 ADB（主）/ Shizuku / Termux（命令行）
│       │   │   │   ├── ShizukuManager.kt / ShizukuBootstrap.kt
│       │   │   │   ├── TermuxBridge.kt            # Termux 通道 + 结果回传接收器
│       │   │   │   ├── AdbProtocol.kt / AdbSocket.kt / AdbTcpSession.kt
│       │   │   │   ├── AdbKeyStore.kt / AdbWirelessTransport.kt
│       │   │   │   ├── AdbBootstrapTransport.kt / MdnsAdbResolver.kt
│       │   │   │   ├── WirelessAdbModels.kt / WirelessAdbStateMachine.kt
│       │   │   │   ├── WirelessAdbPairingFlow.kt
│       │   │   │   └── AdbPairingReceiver.kt      # 通知内联配对码接收
│       │   │   ├── screen/
│       │   │   │   ├── ScreenCapture.kt           # 统一截图入口
│       │   │   │   └── ScreenSharingService.kt    # MediaProjection 回退
│       │   │   └── vision/
│       │   │       ├── ExternalVisionProvider.kt  # 外挂视觉服务 IPC 调用方
│       │   │       └── DetectedControl.kt
│       │   ├── engine/                     # Agent 编排
│       │   │   ├── AgentEngine.kt                 # ReAct 主循环
│       │   │   ├── AgentPrompts.kt                # 系统 / 规划 / 决策提示词
│       │   │   ├── execution/
│       │   │   │   ├── IntentTranslator.kt        # 意图 → 端侧动作转译层
│       │   │   │   ├── IntentResolver.kt
│       │   │   │   ├── AppNameResolver.kt
│       │   │   │   ├── CapabilityManager.kt
│       │   │   │   └── VerifiedClickExecutor.kt   # 带验证的点击执行器
│       │   │   ├── perception/
│       │   │   │   ├── PageAnnotator.kt           # 语义 ID 标注
│       │   │   │   ├── ControlTreeBuilder.kt
│       │   │   │   └── PageFingerprint.kt
│       │   │   ├── network/
│       │   │   │   └── CloudAgent.kt
│       │   │   └── prompt/
│       │   │       └── PromptTemplate.kt          # 模板 + 变量引擎
│       │   ├── overlay/                    # 悬浮窗
│       │   │   ├── FloatingWindowService.kt
│       │   │   ├── FloatingUi.kt
│       │   │   ├── LiquidGlassDrawable.kt         # 液态玻璃绘制
│       │   │   ├── MarqueeView.kt
│       │   │   └── SuccessMarkView.kt            # 任务完成打勾动画
│       │   ├── feature/                    # 功能域
│       │   │   ├── task/
│       │   │   │   └── TemplateMatcher.kt         # 任务模板匹配
│       │   │   ├── skill/
│       │   │   │   ├── SkillModels.kt / SkillCatalog.kt / SkillRegistry.kt
│       │   │   │   ├── SkillExecutionGateway.kt
│       │   │   │   └── SkillCompat.kt
│       │   │   ├── mcp/
│       │   │   │   ├── McpClient.kt / McpManager.kt
│       │   │   │   ├── McpModels.kt / McpRules.kt
│       │   │   │   ├── McpMarketplace.kt
│       │   │   │   └── OkHttpMcpTransportFactory.kt
│       │   │   ├── document/
│       │   │   │   └── DocumentEngine.kt         # 文档结果落盘 + 推给 Agent 页预览
│       │   │   ├── adskip/
│       │   │   │   ├── AdSkipperCore.kt
│       │   │   │   └── AdContentFilter.kt         # 运行时广告过滤
│       │   │   ├── edge/
│       │   │   │   ├── EdgeLightingService.kt
│       │   │   │   └── EdgeLightingView.kt
│       │   │   └── test/
│       │   │       ├── TestEngine.kt / TestModels.kt
│       │   │       ├── TestPresets.kt
│       │   │       └── RealScenes.kt
│       │   ├── ui/                         # 界面层（页面 = 入口 + 单一职责拆分文件）
│       │   │   ├── MainActivity.kt
│       │   │   ├── MainViewModel.kt
│       │   │   ├── model/
│       │   │   │   └── PermissionRadar.kt         # 权限雷达展示模型
│       │   │   ├── theme/                         # Color / Type / Theme / Motion
│       │   │   ├── components/                     # Components / Formatters / Haptic / Markdown
│       │   │   ├── home/                          # HomeScreen + HomeHero / HomeCards / PermissionRadarCard
│       │   │   ├── agent/                         # AgentScreen + 时间线模型/映射 + 列表项 / 计划项 / 步骤 / 实时态 / 输入区
│       │   │   ├── memory/                        # MemoryGraphScreen + Canvas / Stats / Lists
│       │   │   ├── debug/
│       │   │   │   ├── DebugScreen.kt / DebugTabs.kt / CapabilityStrip.kt
│       │   │   │   └── panels/                   # StepShot / Metrics / Chat / Log / History / Steps / Timeline
│       │   │   ├── skill/                         # SkillManagerScreen + Skills / Mcp / WirelessAdb / Prompts Tab
│       │   │   ├── settings/                      # SettingsScreen + 8 个分项设置页
│       │   │   └── test/                          # TestScreen + TestPresetCard / TestResultViews
│       │   └── di/
│       │       └── AppModule.kt                   # Koin 依赖注入
│       └── res/                    # 资源文件
├── gradle/
│   ├── libs.versions.toml          # 版本目录
│   └── wrapper/
├── tests/                          # AI 提示词测试脚本
├── 杂项/                           # 杂项文档
├── build.gradle.kts
├── settings.gradle.kts
└── version.properties
```

## 快速开始

### 1. 环境要求

- Android Studio Hedgehog 或更新版本
- JDK 17
- Android SDK 35
- 一台 Android 手机（需开启开发者选项）
- （可选）安装 Shizuku 以启用 ADB 高权限执行

### 2. 构建步骤

```bash
# 克隆项目
git clone <repository-url>
cd happy_phone-agent

# 清理并构建 Debug APK
./gradlew assembleDebug

# APK 输出路径
# app/build/outputs/apk/debug/app-debug.apk
```

### 3. 安装与配置

1. 安装 APK 到手机
2. 打开 App，授予以下权限：
   - **无障碍服务** — 读取屏幕元素并执行操作
   - **悬浮窗**（可选） — 显示实时进度覆盖层，可在设置里关闭，关闭后不影响任务执行
   - **屏幕录制** — 用于截图视觉模型
   - **通知权限** — 显示前台服务通知
   - **自启动** — 保持后台服务运行
   - **Shizuku** — 启用 ADB 级 Shell 命令（可选，增强执行能力）
3. 在 **设置** 页面配置 AI 模型（API Base URL、API Key、Model Name）
4. 点击 **测试连接** 验证模型可用性
5. 开始使用！

## 核心模块详解

### ShellCommands — AI 友好命令解析器

AI 不再需要记忆复杂的 ADB 语法，只需使用简洁的命名命令：

| 命令 | 参数 | 说明 |
|------|------|------|
| `tap` | `x y` | 点击（支持比例/百分比/像素坐标） |
| `lp` | `x y` | 长按 1500ms |
| `dt` | `x y` | 双击 |
| `sw` | `x1 y1 x2 y2` | 滑动 |
| `key` | `BACK/HOME/ENTER/数字` | 按键 |
| `text` | `"文字"` | 输入文字 |
| `launch` | `包名` | 启动应用 |
| `brightness` | `0~255` | 屏幕亮度 |
| `raw` | `完整ADB命令` | 直接透传（兜底） |

### Shizuku — ADB 高权限通道

当安装了 Shizuku 时，App 可通过 ADB Shell 执行更强大的命令：
- 三态状态管理：`UNAVAILABLE` / `PERMISSION_DENIED` / `READY`
- 支持执行任意 ADB 命令（通过 ShellCommands 转换）
- 未安装 Shizuku 时自动回退到无障碍服务通道

### TermuxBridge — Termux 命令行通道

把 shell 命令交给 Termux 执行并回读输出，为 App 补上一条 **Linux 工具链**通道：

- 目标组件 `com.termux/.app.RunCommandService`（action `com.termux.RUN_COMMAND`）
- 结果经 **PendingIntent 回传**（Termux 官方源码指出：结果目录文件方式在 `allow-external-apps` 未开时会永久挂起）
- 前置条件三项：已安装 Termux / 已授予 `com.termux.permission.RUN_COMMAND` / Termux 侧 `allow-external-apps=true`
- 执行通道四态：`AUTO`（无线 ADB → Shizuku → Termux）/ `ADB` / `SHIZUKU` / `TERMUX`

**能力边界（与 ADB / Shizuku 的本质区别）**

| 通道 | 权限级别 | 能做什么 |
|------|---------|---------|
| 无线 ADB / Shizuku | shell（adb）权限 | `am` / `pm` / `settings` 等系统命令 |
| Termux | **普通应用权限** | curl/wget/python/文本处理/沙箱内文件操作，**不能**执行系统命令 |

**`fetch` 意图**：把 Termux 的命令行能力纳入[意图转译层](file:///d:/xkx/xkx_appproj/happy_phone%20agent/app/src/main/java/com/phoneagent/engine/execution/IntentTranslator.kt)——AI 只给 `uri`，
命令（`curl -sL --max-time 20`）由端侧拼装，走 Termux 执行并把正文回传 AI，用于"图形界面做不到"的取数场景。

### AdSkipperCore — 内置跳广告

独立于 Agent 运行的后台广告拦截引擎：
- 识别优先级：青少年模式弹窗 > 显式"跳过"按钮 > 纯倒计时角标 > 关闭按钮
- 内置冷却机制，防止重复点击和死循环
- 精确匹配 + 位置约束 + 控件类型约束，降低误触

### AppPageIndex — App 页面直达

为常用 App 提供稳定的页面直达方式，避免 AI 自行编造 scheme：
- 系统设置：Wi-Fi、蓝牙、显示、应用管理等
- 高德地图：地图首页、路线规划、附近
- 支持 URI 深链 > Intent Action > 包名直达的降级策略

### LocalVisionEngine — 本地 OCR

基于 Google ML Kit 的端侧文字识别：
- 支持中文 Text Recognition
- 返回归一化坐标（cx, cy）供视觉定位使用
- 离线运行，无网络延迟

### DocumentEngine — 文档结果

承接 AI 的 `write_doc` 能力，只做两件事：
- 把文档正文落盘到应用私有目录（`documents/`）
- 把最近一次结果推成状态流，由 Agent 页任务流内嵌 Markdown 预览（可展开/收起/关闭）

## 杂项文档索引

项目根目录 `杂项/` 存放全部设计/复盘文档，按主题索引如下：

| 文档 | 内容 |
|------|------|
| [项目完整流程说明.md](杂项/项目完整流程说明.md) | 全局架构总览：感知/决策/执行/视觉/持久化/展示六层 + 提示词体系 |
| [HPAv2.0计划文档.md](杂项/HPAv2.0计划文档.md) | v2.0 开发计划与功能清单 |
| [HPA中长线任务优化及agent逻辑优化文档.md](杂项/HPA中长线任务优化及agent逻辑优化文档.md) | 长线任务进度记忆、检查点、防死循环、模板机制设计 |
| [HPA动作执行逻辑优化文档.md](杂项/HPA动作执行逻辑优化文档.md) | 意图 DSL（intent/target{by,value}）与执行层转译规范 |
| [IntentTranslator转译层原理.md](杂项/IntentTranslator转译层原理.md) | 意图→动作矩阵转译、通道选择（Shizuku/无障碍/只读） |
| [IntentTranslator_Bug分析.md](杂项/IntentTranslator_Bug分析.md) | 转译层历史 Bug 复盘与根因分析 |
| [HPA项目提示词文档.md](杂项/HPA项目提示词文档.md) / [HPA提示词文档.md](杂项/HPA提示词文档.md) | AI 系统/规划/决策提示词与参数规范 |
| [HPA项目AI提示词全集.md](杂项/HPA项目AI提示词全集.md) | 全部提示词汇总（中文/英文双版本） |
| [HPA项目ai温度文档.md](杂项/HPA项目ai温度文档.md) | 各提示词 temperature 取值依据 |
| [PHA调试页原始+翻译双语信息展示设计文档.md](杂项/PHA调试页原始 + 翻译双语信息展示设计文档.md) | 调试页人话/原始双语展示、诊断导出、主动通知设计 |
| [HPS ai标准化测试.md](杂项/HPS ai标准化测试.md) / [HPS-agnes测试结果.md](杂项/HPS-agnes测试结果.md) | AI 提示词标准化测试方案与 AGNES 模型实测结果 |

## 配置说明

### 模型配置

支持三类模型独立配置：

| 模型类型 | 用途 | 是否必需 |
|---------|------|---------|
| 主模型 | 决策、规划、意图理解 | ✅ 必需 |
| 视觉模型 | 截图描述、坐标定位 | 可选（默认 glm-4.6v-flash） |
| 思考模型 | 深度思考、重规划 | 可选（链路聚合模式） |

### 链路聚合

默认情况下仅使用主模型 + 可选视觉模型。开启链路聚合后可同时启用思考模型，用于复杂规划和重规划场景。

### 执行通道

- **无障碍通道**（默认）：通过 AccessibilityService 执行，兼容性好但能力有限
- **Shizuku 通道**（可选）：通过 ADB Shell 执行，支持更丰富的命令集

### 提示词语言

支持中文/英文双语提示词，可在设置中切换。

## 架构设计

### Agent 执行循环 (ReAct)

```
观察屏幕 → 页面标注 → 端侧/云端决策 → 双通道执行 → 带验证 → 记录 → 循环
```

1. **观察**：通过无障碍服务获取屏幕所有可交互元素
2. **标注**：自动识别页面类型（弹窗/广告/加载/正常）和上下文
3. **决策**：端侧引擎优先处理高频场景，其余委托给 AI 模型
4. **执行**：Shizuku 通道优先，无障碍通道兜底；前后指纹比对确认生效
5. **记录**：保存执行历史供多轮对话参考

### 安全防护

- **敏感页面检测**：识别支付、个人信息等敏感页面，自动切换为只读模式
- **数据脱敏**：手机号（11位）、身份证号（18位）、银行卡号自动遮蔽
- **用户确认**：关键操作（如支付跳转）强制要求用户确认

## 版本历史

### v0.1.132 (132)

- 🆕 **ShellCommands**：AI 友好命令解析器，支持 tap/swipe/key 等命名命令，三坐标格式
- 🆕 **ShizukuManager**：ADB 高权限 Shell 执行通道，三态状态管理
- 🆕 **AdSkipperCore**：内置跳广告引擎，识别青少年模式弹窗/跳过按钮/倒计时角标
- 🆕 **AppPageIndex**：常用 App 页面直达索引库（系统设置/高德地图/抖音等深链）
- 🆕 **LocalVisionEngine**：基于 ML Kit 的本地中文 OCR，离线识别文字区域
- 🆕 **WorkAreaEngine**：工作区文件管理引擎
- 🆕 **TaskProgressNotifier**：独立系统通知进度（与悬浮窗互补）
- 🆕 **EdgeLighting**：曲面边缘光晕效果
- 🆕 **LiquidGlassDrawable**：液态玻璃悬浮窗绘制
- 🆕 **SuccessMarkView**：成功标记视图
- 🆕 **MemoryGraphScreen**：记忆图谱 UI
- 🔧 设置页面拆分为独立组件（6 个 Settings* 文件）
- 🔧 新增工作区界面（WorkAreaScreen/FileListScreen/FileEditorScreen）
- 🔧 AgentEngine 核心逻辑大幅扩展（+783 行）
- 🔧 FloatingWindowService 增强（+837 行）
- 🔧 新增 3 个测试脚本（adb_priority_test/all_prompts_test/retry_rate_limited）

### v0.1.30 (30)

- UI 全面优化：Material 3 Expressive 视觉标准落地
- 运动系统：新增 Motion.kt / MotionHelpers.kt，缓动曲线与弹簧动画
- 触觉反馈：全局 rememberHapticClick() 组件
- 页面转场：AnimatedContent 对称路径过渡
- 视觉层次：Color 语义化 token，深色模式全面适配
- 代码结构：HomeScreen 状态提升、Composable 复用
- 权限雷达：优化位置与视觉对比

### v0.1.6 (6)

- 自动递增版本号机制
- 新增真实环境场景库（10+ 移动端页面快照）
- 测试引擎支持 AGNES 模型 prompt 验证
- 修复步骤描述解析逻辑（字段优先级：description > action > text > step）

### v0.1.4 (4)

- 新增自启动与电池优化权限
- 实现厂商自启动管理页面跳转（小米/华为/OPPO/VIVO/三星/魅族）
- 权限雷达 UI 优化

### v0.1.0 (Initial)

- 核心 Agent 引擎：观察-决策-执行循环
- 无障碍服务集成
- 多模型链路聚合
- 数据脱敏与敏感页检测
- 悬浮窗实时进度
- 测试引擎框架

## 贡献指南

欢迎贡献代码！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: 添加新功能'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 代码规范

- 遵循 [Kotlin 官方编码规范](https://developer.android.com/kotlin/style-guide)
- 使用 4 空格缩进
- 提交信息遵循 Conventional Commits 格式
- UI 变更需遵循 Material 3 设计标准

## 许可协议

本项目基于 [MIT License](LICENSE) 开源。

## 联系方式

- 创建 Issue 讨论技术问题
- 提交 Pull Request 贡献代码

## 致谢

- Material Design 设计团队
- Jetpack Compose 社区
- Google ML Kit OCR
- Shizuku 项目
- 所有开源贡献者