dsh_ai1net_server/交付物/Android访问WorkBuddy-最小方案-20260928.md

Android app 访问 WorkBuddy · 最小方案（2026-09-28）

用户口径（原话）：「e盘应该已经安装了，还有只需要基于现有架构 加androidapp 访问workbuddy 不要带来其他东西」 本文件范围：据此把此前两版方案收窄到最小 —— 只加一个 Android app 去访问 WorkBuddy，⛔ 不带别的。 与前两版关系：前两版（手机回复 WorkBuddy 会话 / Android 壳联动）里的 PWA · M6 模块 · 决策库联动 · 通知原生 · TUN · 自研设备桥 全部⚠️ 本次不采用。

---

0 先更正一件事（我上一轮判断错了）

E 盘的工具链确实装好了，是我漏看。

项	实测读数
位置	E:\Android（约 9.7 GB，2026-09-17 装，刻意不写系统 PATH、不写注册表）
JDK	jdk-21（默认，21.0.12.1 LTS）＋ jdk-17（备用，17.0.20.1）
SDK	E:\Android\sdk：platform android-36 · build-tools 35.0.0 / 36.0.0 · platform-tools adb 1.0.41 (37.0.1) · emulator · system-images android-36
Gradle	E:\Android\gradle-home（含 init.gradle 八源分流 ＋ gradle.properties 按域名分流代理）
入口	source "/e/Android/env.sh" ⇒ 设 JAVA_HOME=E:\Android\jdk-21、ANDROID_HOME=E:\Android\sdk、GRADLE_USER_HOME、ANDROID_USER_HOME
本机验证	我实跑：java -version → 21.0.12.1 LTS ✅ ｜ adb version → 37.0.1 ✅
已有产物	apps/android/.../app-debug.apk（com.dsh.client，4.1 MB）｜README 记：BUILD SUCCESSFUL in 1m 19s
装机说明	E:\Android\README-AGENT-ANDROID.md（面向 agent 写的，含构建命令与三个已踩的坑）

🔴 我错在哪：上一轮我只查了 which java、$ANDROID_HOME 和默认 SDK 路径（%LOCALAPPDATA%\Android\Sdk），而这个工具链故意不在 PATH、也不在默认位 ⇒ 我据此写了"环境未装"，属未穷尽取证就下结论，已纠正。

⚠️ 一条必读的坑（README §1 明写）：@capacitor/[email protected] 要求 Java 21；用 JDK 17 会报 Java compilation initialization error，极易误判成工程问题 ⇒ 构建一律用 JDK 21。

---

1 关键发现：「访问 WorkBuddy」有官方现成通道 —— 这正是"不带其他东西"成立的前提

WorkBuddy（内核 @genie/agent-cli）自带一个远程控制网关（gateway），本机实测在位：

实测项	读数
监听	127.0.0.1:50753 / :53305 / :57900 = WorkBuddy.exe 起的 Express 服务，页标题「CodeBuddy Remote Control」
端点（服务自报）	POST /api/v1/runs（起一次 Agent run）· GET /api/v1/runs/:runId/stream（SSE 结果流）· GET/POST /api/v1/acp（ACP 协议端点）· POST /api/v1/webhooks/:platform · GET /api/v1/health · GET /api/v1/status
鉴权	要有 —— 实测未带凭据一律 401 {"error":{"code":"AUTH_REQUIRED"}}（不是裸奔）
配置键（从 CLI 内提取）	CODEBUDDY_GATEWAY_AUTH · CODEBUDDY_GATEWAY_PASSWORD · CODEBUDDY_GATEWAY_BASE_PATH · CODEBUDDY_GATEWAY_DISABLE_API_DOCS · CODEBUDDY_GATEWAY_FORCE_TUNNEL · CODEBUDDY_GATEWAY_ACK_*
启动方式	CLI --serve；运行期有 /gateway start / /gateway stop
附带通道	CODEBUDDY_GATEWAY_WECHAT_KF_*（微信客服）· CODEBUDDY_GATEWAY_WECOM_*（企业微信）；本机 settings.json 的 claw 段里 wechatmp 通道已 enabled
⚠️ 手机端界面	dist/web-ui 未构建（服务首页原文：「Web UI is not built. Use the API endpoints directly, or build the Web UI: cd src/node/remote-gateway/web-ui && npm run build」），构建产物来源是 packages/agent-cli/src/node/remote-gateway/web-ui/dist/**

⇒ 结论：WorkBuddy 官方架构本身就支持"被外部客户端访问并驱动会话"（runs ＋ SSE ＋ ACP），⛔ 不需要自研设备桥、不需要新协议、不需要新配对。这就是"不要带来其他东西"能落地的原因。

---

2 最小方案（只加 Android app，一处改动）

Android 手机
  └ 现有 Capacitor 壳（E:\github\dsh-client\apps\android，已产出过 APK）
        └ WebView 指向 → WorkBuddy 自带 gateway（--serve）
              └ WorkBuddy 会话（起 run / 看 SSE / 回复）
        ┈ 承载二选一 ┈
          ① 同机 / 同局域网：直连 http://<电脑IP>:<gateway端口>   （零基础设施）
          ② 需要外网：走**既有**覆盖网络（设备声明端口 + 中继 + 门户）
             —— 即那条线已跑通 28 条判据的通道，**只把声明的端口换掉**

2.1 与既有架构的对接点（只有这些）

件	处置	说明
Android 壳	只改一处：WebView 目标地址	壳现行 capacitor.config.ts 未设 server.url ⇒ 需改并重打包一次（E 盘工具链已就绪）
WorkBuddy gateway	启用即可（--serve ＋ 配 CODEBUDDY_GATEWAY_AUTH/PASSWORD）	官方自带，⛔ 不自研
承载（如需外网）	复用覆盖网络中继 ＋ 设备声明端口	那条线的取址/台账/四道闸全部复用；本方案只换端口号
平台 47 / ai1net 插件	零改动	⛔ 不加模块、不加路由、不加表
设备侧桥 / M6 / PWA / 通知 / TUN	⛔ 全部不做	这是相对前两版砍掉的部分

2.2 判据（可机器验）

#	判据	期望
1	source /e/Android/env.sh && java -version	21.0.12.1 LTS ✅（已验）
2	E:\Android\README-AGENT-ANDROID.md §4 的构建命令	BUILD SUCCESSFUL，出 app-debug.apk
3	壳内 WebView 打开 gateway 首页	不再是内置骨架页
4	curl -H "<凭据>" .../api/v1/health	200（对照：无凭据 401 AUTH_REQUIRED）
5	手机上一次「起 run ＋ 看流 ＋ 回复」	桌面 WorkBuddy 会话体现该动作
6	既有线零回归	配对 28 条 · 设备接入 26 条判据不变

---

3 唯一需要你拍板的一点（其余我自决）

问题：手机端的界面从哪来？

为什么需要你定：WorkBuddy 官方那个手机友好的 Web UI（remote-gateway/web-ui）在本机装好的版本里没构建，而它的源码不在本机任何目录（只在构建配置里被引用）⇒ 我无法自行构建官方界面。所以手机壳指过去，只能看到那张"Web UI is not built"的说明页 —— 功能在、界面缺。三条路各有取舍：

• 候选 1 · 只做壳 ＋ 直连，界面先用官方 API 原始响应（暂不做界面）
  • 优点：完全不加任何东西，最贴合你的口径；今天就能验证"手机能访问到 WorkBuddy"。
  • 缺点：手机上看不到像样的会话界面，只能验证链路通。
• 候选 2 · 自研一个极简手机页（调 /api/v1/runs ＋ SSE）
  • 优点：手机上真正能"看会话 ＋ 回复"，体验完整。
  • 缺点：这就是"带来其他东西"（一个新页面，虽小）；且需跟着 gateway 的 API 版本走。
• 候选 3 · 拿到官方 remote-gateway/web-ui 源码自行构建
  • 优点：界面即官方版，最省后续维护。
  • 缺点：源码不在本机，需先从 CodeBuddy 侧取得，依赖外部条件、何时能做不可控。

倾向：候选 1 先走（零新增、当天验证"手机能访问 WorkBuddy"这条主链），跑通后再按你的口径决定要不要候选 2。

---

4 未验证项（⛔ 不得当成已定）

1. gateway 的端口规律（观察到 3 个随机口）—— 是"每会话一个"还是"一实例多口"？未定 ⇒ 决定"设备要声明哪个端口"。
2. 鉴权凭据怎么给手机 —— CODEBUDDY_GATEWAY_PASSWORD / AUTH 本机 settings.json 里未见配置 ⇒ 需确认开启方式与凭据下发路径（这是把它暴露到局域网/中继之前必须解决的）。
3. 壳是否必须重打包 —— 现行配置未设 server.url；若壳支持运行时注入则可免（待核实）。
4. gateway 暴露到中继的权限影响 —— 该网关能起 Agent run（＝能在你电脑上执行任务）⇒ 一旦经中继可达，权限面显著大于此前那条线的"只读 DSH Web"。按 R5 须先出「权限影响评估」再开。
5. 前两版方案里的两个阻断仍在：E:\ProgramDSH 已消失（那条线写死的垫片挂载点不存在）· dsh-client 仓 0 commit（无版本历史）。
6. E:\Android 的模拟器加速驱动未装（README §3）—— 不影响出 APK，只影响起模拟器；真机可直接用 adb install。

---

5 交付边界（⛔ 逐条自查）

1. ⛔ 不新增平台模块 / 路由 / 数据表（M6 已砍）。
2. ⛔ 不自研设备桥、不新协议、不新配对（gateway 与既有中继已覆盖）。
3. ⛔ 不装 PWA、不写通知原生、不碰 TUN。
4. ⛔ 不引入第三方隧道（CODEBUDDY_GATEWAY_FORCE_TUNNEL 暂不用，承载走既有覆盖网络）。
5. ✅ 只做：Android 壳指向 gateway ＋（如需外网）把设备声明端口换成 gateway 端口。

---

附：本次取证命令与读数

#	取证点	读数
1	ls E:/Android	env.sh jdk-17 jdk-21 sdk gradle-home user-home README-AGENT-ANDROID.md
2	source /e/Android/env.sh && java -version	openjdk 21.0.12.1 2026-08-18 LTS
3	adb version（env 后）	Android Debug Bridge 1.0.41 / 37.0.1-15733141
4	netstat -ano ＋ tasklist	WorkBuddy.exe（PID 30256）监听 127.0.0.1:18488；另有 3 个 Express 口
5	curl 127.0.0.1:18488/	404 {"ok":false,"error":"Not Found"}（JSON API 面）
6	curl 127.0.0.1:50753/	200，<title>CodeBuddy Remote Control</title>、<h1>CodeBuddy Gateway</h1>，正文列 7 个端点
7	curl 127.0.0.1:50753/api/v1/health（无凭据）	401 {"error":{"code":"AUTH_REQUIRED",...}}
8	grep -oE 'CODEBUDDY_GATEWAY_[A-Z_]*'（cli/dist）	AUTH PASSWORD BASE_PATH FORCE_TUNNEL DISABLE_API_DOCS ACK_* WECHAT_KF_* WECOM_*
9	ls cli/dist/web-ui	不存在 ⇒ 官方手机 Web UI 未构建
10	settings.json → claw	users[<uid>].channels.wechatmp.enabled = true（微信通道已开）