前言¶

在 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