# 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/android@8.5.2` 要求 **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`（微信通道已开） |