前言¶

在 DeepSeek Harness（DSH）里做需要真机或模拟器 UI 的任务时，常见做法是本机单独开 adb、截图再贴进会话，或写脚本绕一圈。Agent 拿不到稳定的坐标与状态，人也难以同步看到屏幕。dsh-phone 把 Android 实例跑在 DSH 后端，在浏览器右侧栏呈现画面，并向 Agent 注册一组 phone_* 工具，把「查状态 → 截图/控件树 → 点击滑动输入」收成同一套接口。下面介绍它是什么、能做什么，以及如何安装与使用。

这是什么¶

dsh-phone 由社区维护者 thatgfsj-dsh 发布，在 SkillHub 插件目录 中归类为客户端插件。当前 README 标注的版本为 v0.4.1（MIT 许可证），要求 DSH >=0.2.1-rc.2 <0.3.0、Node >=20。

插件不在 npm 上以同名包代表本仓库（README 明确警告：dsh plugin add dsh-phone 会装到另一个项目 PonyDevAI/dsh-phone）。正确来源是 GitHub 仓库 thatgfsj-dsh/dsh-phone 的 Release 预构建包。

核心功能¶

运行时与平台¶

插件支持三种运行时，以及 runtime: auto 按顺序探测：redroid（Docker）→ Android SDK Emulator → attach（已有模拟器或真机）。显式配置 runtime 时跳过探测。

插件不安装任何软件、不修改模拟器自身配置；前置条件不满足时只给出安装指引。一键准备 Android SDK Emulator + system image + AVD 的 Provisioning API 仅能在用户点击、浏览器同源触发时执行，Agent token 不能自动安装软件。

懒启动、休眠与生命周期¶

首次工具调用或首次打开面板才拉起实例。约 20 分钟无交互进入 paused，30 分钟或资源紧张时 stopped。attach 模式不会被插件停止。面板与设置页提供启动 / 停止 / 重启；外部 kill -9 后约 2 秒内状态会对账为「已停止 / 被外部关闭」。区分 owned（插件拉起，关闭会保存快照后退出）与 adopted（用户自有实例，停止只断开不杀进程）；stop 只能由用户在浏览器触发。

双链路：Agent 截图与人看视频¶

Agent 侧按需单帧截图（README 描述约 100–300ms、无持续流开销）。人在右侧栏面板看 scrcpy H.264 视频流（默认 720p / 15fps / 2Mbps，仅面板可见时传输）。Host 不转码；浏览器优先 WebCodecs 硬解，不支持时回退 TinyH264 WASM 软解。

九个 phone_* 工具¶

工具出现在 Agent 工具列表即表示插件开关已打开。任何任务建议先调用 phone_status；state=booting 时部分工具返回可重试的 E_BOOTING（带 bootMs），不应当作失败中断。

右侧栏面板与「肥鱼手机」定制¶

面板是右侧栏的一个 tab，可从会话头部手机按钮或设置页打开。v0.4.1 起空白桌面从底部上滑可打开 4 列应用抽屉，面板底部另有「应用」按钮。可选的 system/ 换肤工具集提供中文系统、空白桌面、双壁纸轮换等，面向特定 AVD 配置；插件本身不依赖该目录，一键准备在 step=customize 时可自动应用。

安装与启用¶

推荐从 GitHub Release 下载预构建 dsh-phone-<version>.tgz（包内已有 lib/，无需本地 npm run build）。安装后必须重启 DSH 并刷新页面（F5），只做其一可能出现工具可用但无入口，或页面有 UI 但 API 404。

# 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 package.json 的 dsh.profile.bundles 后重启。完整对齐检查见仓库 docs/install.md。

已有一台运行中的 emulator 或真机时，README 建议优先 attach（配置 attach.endpoint），避免再起第二台实例。

典型用法¶

首次接入「一句话」¶

用户在「设置 → 手机」填写一句话描述模拟器位置（原文保留，插件不做规范化）。操作 Agent 读取 dsh --profile <profile> --dump-config 中 dsh-phone 的 config.attach.userHint，在宿主机做只读探测与连通验证，再通过本地 Agent 通道写入 attach.endpoint 与 attach.resolved（须带 revision，且 verify 通过）。凭证位于：

cat "${DSH_HOME:-$HOME/.dsh}/storages/dsh-phone/agent.json"

验证与写入示例（与 README 一致，endpoint 按实际替换）：

BASE=$(node -e "console.log(JSON.parse(require('fs').readFileSync(process.env.HOME+'/.dsh/storages/dsh-phone/agent.json','utf8')).baseUrl)")
TOKEN=$(node -e "console.log(JSON.parse(require('fs').readFileSync(process.env.HOME+'/.dsh/storages/dsh-phone/agent.json','utf8')).token)")

curl -sS -X POST "$BASE/dsh-phone/api/attach/verify" -H 'content-type: application/json' \
  -H "x-dsh-phone-token: $TOKEN" -d '{"endpoint":"127.0.0.1:5555"}'

Agent 通道只允许写 attach.endpoint / attach.resolved；attach.resolved == true 后直接连接现有 endpoint，禁止重新探测。敏感操作（支付、发送/删除消息等）前 Agent 应先提示用户，面板可随时由人接管。

Agent 任务中的工具顺序¶

1. phone_status 确认 state 与 runtime。
2. phone_screenshot 和/或 phone_uiautomator_dump 获取界面信息。
3. 根据坐标或包名调用 phone_tap、phone_swipe、phone_input_text、phone_app_launch 等。
4. 需要只读系统信息时再考虑 phone_shell（注意默认审批策略）。

适用场景与注意¶

适合谁：需要在 DSH 会话里让 Agent 操作 Android UI、同时希望在浏览器右侧栏实时查看同一实例的开发者；Linux 上可走 redroid，Windows/macOS 可走 SDK Emulator，或 attach 已有雷电等模拟器/真机。

权限与安全：插件以当前 DSH 进程权限在宿主机运行，可执行 adb、可选 Docker/redroid、Provisioning 安装 SDK 组件（仅用户浏览器触发）。安装前应阅读仓库源码与 MIT 许可证，自行评估是否接受在主机上暴露 Android 控制面与 Agent 本地 token API。

生态说明：DSH 社区插件目录（如 SkillHub）与 DeepSeek / 幻方无官方从属关系；本文事实均来自上述仓库 README 与 package.json，实现差异与未验证项见仓库内 docs/host.md、docs/runtime.md 等文档。

结尾¶

dsh-phone 把后端 Android 实例、浏览器右侧栏 scrcpy 面板和九项 phone_* Agent 工具绑在同一插件里，并区分 attach 与自管实例的生命周期。若要进一步核对安装项与协议细节，请以仓库文档为准。

• 插件目录：https://www.skillhub.cn/plugins/thatgfsj-dsh/dsh-phone
• GitHub：https://github.com/thatgfsj-dsh/dsh-phone