前言¶
在 DeepSeek Harness（DSH）里做需要「真机界面」的任务时，常见做法是本机另开模拟器、手工 adb，再让 Agent 间接描述步骤。人和模型都看不到同一块屏幕，截图与点击也往往要额外脚本衔接。dsh-phone 把 Android 实例跑在 DSH 后端，在浏览器右侧栏用面板呈现画面，并向 Agent 注册一组 phone_* 工具，使状态查询、截图、点击、输入等与 Harness 会话在同一套插件体系里完成。下面介绍插件定位、能力边界、安装方式与典型用法。
这是什么¶
dsh-phone 由维护者 Thatgfsj 发布，分类为客户端插件（面向 web profile）。仓库说明中的定位是：给 DeepSeek Harness 提供一台运行在后端、经浏览器右侧栏呈现的 Android 实例，并注册 9 个 phone_* 工具供 Agent 直接操作。当前 README 标注的已发布版本为 v0.4.1（MIT 许可证）；与 DSH 的集成校准文档针对 DSH 0.2.1-rc.2。
插件本身不代替你在宿主机安装 Docker、Android SDK Emulator 或 adb 环境；前置条件不满足时，文档说明只会给出安装指引，而不会静默改系统。
核心功能¶
运行时与平台¶
插件支持三种运行时，以及 auto 按序探测：redroid（Docker）、Android SDK Emulator（Linux KVM / Windows WHPX / macOS HVF，可无头 AVD）、attach（连接已在运行的模拟器或真机，adb TCP 可达即可）。runtime: auto 的探测顺序为 redroid → emulator → attach；显式配置 runtime 时跳过探测。
| 平台 | 首选运行时 | 前置条件（摘要） |
|---|---|---|
| Linux | redroid | Docker Engine；/dev/binder 存在（binder_linux） |
| Windows | Android SDK Emulator | SDK Emulator；虚拟机平台 / Hyper-V 与 BIOS 虚拟化 |
| macOS | Android SDK Emulator | Android Studio / SDK Emulator（HVF） |
| 任意 | attach | 实例已运行，adb 端口可达（如 127.0.0.1:5555） |
若本机已有一台运行中的模拟器或真机，文档建议优先 attach 复用，避免再起第二台实例。
一键准备运行环境¶
首次使用或设置页可触发 Provisioning API：一键安装 Android SDK Emulator、system image 并创建 AVD，带进度与日志，幂等完成后自动启用。该流程仅在用户点击、浏览器同源下触发；Agent token 不能自动安装软件。
九个 phone_* 工具¶
工具出现在 Agent 工具列表，表示插件开关已打开。任何任务建议先调用 phone_status；实例处于 booting 时可能返回可重试的 E_BOOTING（含 bootMs），不宜当作硬失败中断。
| 工具 | 说明 |
|---|---|
phone_status |
返回 state、runtime、platform、bootMs、phase、endpoint 等 |
phone_screenshot |
单帧截图（约 100–300ms 量级，按需、无持续流开销） |
phone_tap |
坐标须来自最近截图或控件树 |
phone_swipe |
滚动、解锁、切页 |
phone_key |
HOME / BACK / RECENTS / ENTER / DEL 等 |
phone_input_text |
支持中文（scrcpy INJECT_TEXT） |
phone_app_launch |
按包名启动 |
phone_uiautomator_dump |
控件树 XML，可与截图交叉校验 |
phone_shell |
默认需 ask 审批；部分只读子集可免确认 |
懒启动、休眠与双链路¶
实例在首次工具调用或首次打开面板时才拉起。约 20 分钟无交互进入 paused，30 分钟或资源紧张时 stopped；attach 模式不会被插件停止。可选 lifecycle.prewarm（默认 false）可在插件加载后预热。
Agent 侧以按需单帧截图为主；人在面板里看 scrcpy H.264 视频流（默认 720p / 15fps / 2Mbps，仅面板可见时传输）。Host 不转码；浏览器优先 WebCodecs 硬解，不支持时回退 TinyH264 WASM 软解。
面板、设置与生命周期¶
右侧栏面板是独立 tab，可从会话头部手机按钮或设置页打开；底部提供 HOME / BACK / RECENTS / ENTER / DEL，v0.4.1 起还有「应用」按钮（宽屏带文字、窄屏仅图标），可打开 4 列应用抽屉；空白桌面也可从底部上滑打开抽屉（搜索、中文名、点击启动）。
面板 header 与设置页均可启动 / 停止 / 重启手机。外部 kill -9 后约 2 秒内状态会对账为「已停止 / 被外部关闭」。插件拉起的实例为 owned（关闭会保存快照后退出）；用户自有实例为 adopted（停止只断开、不杀进程）。stop 只能由用户在浏览器触发；Agent token 仅允许 start / restart。
可选「肥鱼手机」定制在 system/ 目录（中文、空白桌面、双壁纸轮换等）；一键 Provisioning 在 step=customize 可自动应用，插件核心不依赖该目录。
首次接入「一句话」¶
用户在「设置 → 手机」填写一句话描述现有模拟器位置（原文保留）。操作 Agent 读取配置中的 attach.userHint，在宿主机做只读探测与连通验证，再通过本地 token 通道写入 attach.endpoint 与 attach.resolved（含 revision CAS）。Agent 不能写 attach.userHint 或 onboarding.*；attach.resolved == true 后直接连 endpoint，不再重写探测。
安装与启用¶
要求：DSH >=0.2.1-rc.2 <0.3.0、Node >=20；宿主浏览器建议支持 WebCodecs（Chrome / Edge 等）。
README 不推荐执行 dsh plugin add dsh-phone：npm 上同名包属于另一项目（PonyDevAI/dsh-phone），本仓库未发布到 registry。推荐从 GitHub Release 安装预构建 tgz（包内已有 lib/，无需本地 npm run build）：
# 1) 从 Releases 的 Assets 下载 dsh-phone-<version>.tgz（或 gh CLI）
gh release download v0.4.1 -R Thatgfsj/dsh-phone -p 'dsh-phone-*.tgz'
# 2) 安装到 web profile
dsh plugin --profile web add ./dsh-phone-0.4.1.tgz
# 3) 必需：确认 bundle 真的被选中，再重启 DSH + 刷新页面（F5）
dsh --profile web --dump-config | grep -n -A 8 'dsh-phone'
若 dump-config 中没有 dsh-phone 行，属于「半安装」：需在 Plugins 页启用 / 重载，或将 dsh-phone 加入 profile 的 dsh.profile.bundles 后重启。安装、更新或启用后必须重启 DSH 并刷新页面（F5）；只做其一可能出现工具可用但无入口，或页面有 UI 但 API 404。更完整的对齐检查见仓库 docs/install.md。
典型用法¶
Agent 操作手机¶
- 调用
phone_status确认state与runtime。 - 需要界面时调用
phone_screenshot或phone_uiautomator_dump，再基于坐标调用phone_tap/phone_swipe。 - 输入文字用
phone_input_text；导航用phone_key或phone_app_launch。 - 涉及
phone_shell时留意默认审批策略；支付、发送、删除等敏感操作前应先提示用户，面板可随时人工接管。
attach 定点配置（Agent 本地通道）¶
插件加载时在 storages/dsh-phone/agent.json 生成本地凭据（权限 0600）。验证 endpoint 并写入配置的流程见 README；核心步骤包括先 POST .../attach/verify，再经 GET .../config 取 revision，用 POST .../agent/config 写入 attach.endpoint 与 attach.resolved，最后 GET .../status 复验。
Provisioning、临时 profile 验证、升级与卸载见仓库 docs/install.md。
适用场景与注意¶
适合：需要在 DSH 会话里让 Agent 可操作 Android UI 的自动化、验收、辅助调试；Linux 上倾向 redroid、已有 Emulator 或真机时用 attach；希望人在右侧栏同步看视频流、Agent 用截图 + 控件树双通道。
注意：
- 插件以当前 DSH 进程权限运行；安装前应阅读源码与 MIT 许可证，并理解 Provisioning、adb、Docker 等会触达本机资源。
- 文档明确列出与需求的差异、未验证项（见
docs/host.md、docs/runtime.md等）；Windows 下 WSL2 + redroid 为进阶路径，非默认推荐。 - 社区目录站点（SkillHub）与 DeepSeek / 幻方无官方从属关系；插件来自社区维护者 Thatgfsj，非 Harness 内置组件。
结尾¶
dsh-phone 把后端 Android、浏览器右侧栏面板和 9 个 phone_* 工具收进 DSH 插件模型：懒启动与分级休眠控制资源，attach 与三种运行时覆盖常见部署方式。若要在 web profile 试用，按 Release tgz 安装、确认 bundle 选中并重启 DSH 后，从设置页或会话头打开手机面板即可。
- 目录页：https://www.skillhub.cn/plugins/Thatgfsj/dsh-phone
- 源码与文档：https://github.com/Thatgfsj/dsh-phone
