@fxz26284407/yuanma-gateway 0.1.4 → 0.1.6

package/README.md

@@ -1,23 +1,59 @@
 # 远码网关（yuanma-gateway）
 
-远码的 Mac 本地网关与 HTTP/WS 局域网密文中继。只包含两端网关，不包含鸿蒙工程、签名文件、个人文档库或运行数据。
+远码的 Mac 本地网关与 HTTP/WS 公网密文中继。只包含两端网关，不包含鸿蒙工程、签名文件、个人文档库或运行数据。
+
+## 局域网直连（本地开发版本，尚未发布到 npm）
+
+本地代码已支持手机直接连接 Mac，无需启动 Relay。npm 已发布的 0.1.0 仍沿用原中继流程；使用直连需同时更新本地网关和鸿蒙 App，旧 App 不支持新的直连二维码。
+
+在本仓库使用 Node.js 22 构建后运行：
+
+```sh
+npm run build
+node bin/yuanma-gateway.mjs init
+node bin/yuanma-gateway.mjs pair
+```
+
+首次初始化的中继地址可以留空。单个常规内网 IPv4 自动选择，多个地址展示网卡与 IP 供选择；虚拟网卡需确认手机可达。默认端口为 `19089`，二维码地址为 `ws://所选内网IP:19089/v1/secure`。仅该加密入口对内网开放，本地管理接口继续使用 Unix socket。仍需准备与桌面共享的 Codex 后端及现有密钥保存模式。
+
+普通 start/restart 沿用已保存模式；pair 默认局域网，多个内网 IP 时交互选择，直接执行：
+
+```sh
+node bin/yuanma-gateway.mjs pair
+```
+
+非交互或需要指定网卡、端口时：
+
+```sh
+node bin/yuanma-gateway.mjs pair --lan-host 192.168.1.10 --lan-port 19089
+```
+
+将示例 IP 替换为本机实际内网地址。IP 失效时重新选择并扫码，端口冲突时更换端口；不要将手机的 localhost 当作 Mac。网关保存连接方式，后续启动复用；设备身份与授权保持原样。
+
+保留 Relay 扩展，切换时使用：
+
+```sh
+node bin/yuanma-gateway.mjs pair --relay-url wss://relay.example.com
+```
+
+局域网和 Relay 首版互斥，不会自动回退公网。以下中继安装与部署说明适用于已有发布版本及需要中继扩展的用户。
 
 ## 项目系列
 
 [远码 Yuanma · GitHub Project](https://github.com/users/fxz26284407/projects/2)
 
-- [远码网关与局域网中继](https://github.com/fxz26284407/yuanma-gateway)
+- [远码网关与公网中继](https://github.com/fxz26284407/yuanma-gateway)
 - [远码鸿蒙客户端](https://github.com/fxz26284407/yuanma-harmony)
 
 ## 部署架构
 
 ![远码部署架构](docs/assets/deployment.svg)
 
-手机与 Mac 位于同一局域网，主动连接用户自行部署的内网 WS 中继，例如 `ws://192.168.1.10:19088`。业务内容通过 Noise 在两端加密，中继只负责转发。Codex Desktop 与 Mac 网关连接同一个 app-server，任务、文件操作和审批发生在 Mac。SQLite 消息账本与设备授权也保存在 Mac。
+手机和 Mac 主动连接同一个公网 WS 入口；业务内容通过 Noise 在两端加密，中继只负责转发。Codex Desktop 与 Mac 网关连接同一个 app-server，任务、文件操作和审批发生在 Mac。SQLite 消息账本与设备授权也保存在 Mac。
 
-中继部署在 Mac 的 Docker 或同一局域网内的主机，端口映射为 `19088:8080`，支持 amd64 / arm64。示例使用私有 IP，不需要公网域名、内网穿透或外部反向代理；不要在路由器上配置公网端口转发。按下文将服务绑定到宿主机实际的局域网 IP，并由防火墙仅允许可信内网设备访问。
+中继默认直接拉取 [Docker Hub 公开镜像](https://hub.docker.com/r/fxz26284407/yuanma-relay)，端口映射为 `19088:8080`，支持 amd64 / arm64。既可部署在公网服务器，也可部署在本机 Docker 并通过花生壳 HTTPS 穿透，以 `wss://域名` 连接。
 
-这里的“局域网”指手机、网关与中继之间的连接范围，不表示模型在本地离线运行。Mac 上的 Codex、DeepSeek 及所选模型服务仍按各自配置联网；安装依赖和拉取镜像也需要访问相应软件源。
+容器内只有 Node HTTP/WS relay，不含 Nginx，也无需配置域名或证书。HTTPS/WSS 的证书和 WebSocket 升级由花生壳或外部反代处理；直接使用 `ws://服务器地址:19088` 时不需要外部反代。
 
 [架构图源文件](docs/deployment.archify.json)
 
@@ -26,7 +62,7 @@
 | 目录 | 内容 | 运行位置 |
 | --- | --- | --- |
 | `gateway/` | Codex 适配、鉴权、项目权限、SQLite 消息账本、自有队列、图片和审批路由 | 工作 Mac |
-| `gateway/relay.ts`、`deploy/relay/` | HTTP 健康检查、WebSocket 密文路由、Docker 配置 | 局域网主机或 Mac Docker |
+| `gateway/relay.ts`、`deploy/relay/` | HTTP 健康检查、WebSocket 密文路由、Docker 配置 | 公网服务器或本机 Docker |
 | `scripts/` | 配对二维码、Mac 本地批准页、网关重启和中继打包 | Mac |
 
 手机与 Mac 建立固定公钥的 Noise 加密通道，中继只转发密文。Codex 桌面和网关需要连接同一后端才能共享实时会话。
@@ -38,6 +74,14 @@
 - Codex 与 DeepSeek 共用下一步建议开关、预览及采用流程，各自使用自己的模型和额度。建议只填入可编辑草稿，不自动发送。
 - DeepSeek 建议复用 `/Applications/DeepSeek Harness.app` 内置 SDK 和既有登录，独立请求近期会话文本，不加载 Agent、会话持久化或工具。支持 `deepseek-account` 与 `deepseek-official` 路由；其他第三方提供方尚未适配。桌面 SDK 更新不兼容时，建议暂不可用，原会话仍走现有桌面 Host。
 
+## Antigravity 接入进度
+
+支持读取 Antigravity App 的已有工作区、会话、历史分页和全文。手机可切换第三个智能体，文件引用按 Markdown 标签展示。CLI 不可用时保留只读浏览。
+
+控制通道使用官方 Antigravity CLI 1.5.0 的 ACP，默认可执行文件为 `~/.local/bin/agy`；其他路径可在网关配置中设置 `antigravityCli`。目前已接线已有会话发送、实时进度、手机回合取消、原生审批／字符串问题回复、模型与思考档位、执行策略及图片输入。实际用户任务的发送、审批与取消闭环尚未完成验收；新建、引导、会话菜单、文档附件、扩展、Diff 和下一步建议未开放。
+
+进程重启后无法确认的发送会保留未知状态，不自动重发。当前只支持取消手机通过本网关发起的回合，尚不提供桌面独立回合的停止或审批接管，整体使用体验仍未与 Codex 对齐。历史与摘要单文件上限为 32 MiB，超限会明确提示。
+
 ## Mac 网关安装（npm）
 
 需要 **macOS、Node.js 22**，以及已登录、与桌面共用的 Codex app-server。当前适配固定为 app-server **0.166.0**；其他版本需要先适配协议。DeepSeek 功能另外依赖本机已有的 DeepSeek Harness 和登录。
@@ -66,18 +110,18 @@ yuanma-gateway projects
 ### 初始化
 
 ```sh
-yuanma-gateway init --relay-url ws://192.168.1.10:19088
+yuanma-gateway init --relay-url wss://relay.example.com
 ```
 
-将示例 IP 替换为运行中继的主机局域网 IP，并先按下文启动中继。初始化读取真实 Codex 项目列表，由你选择初始项目。**现有产品会继续同步发现其他项目；配对后所有发现的项目和工作区默认可执行，初始列表不是权限白名单。** 初始化会明确说明并要求接受这项既有策略；会话中的执行审批仍独立管理。
+将示例域名替换为实际 relay 地址。初始化读取真实 Codex 项目列表，由你选择初始项目。**现有产品会继续同步发现其他项目；配对后所有发现的项目和工作区默认可执行，初始列表不是权限白名单。** 初始化会明确说明并要求接受这项既有策略；会话中的执行审批仍独立管理。
 
-当前版本的跨设备连接还需显式启用本机私有文件保存传输密钥的模式；交互界面会说明并征求选择。
+当前版本的远程连接还需显式启用本机私有文件保存传输密钥的模式；交互界面会说明并征求选择。
 
 在非交互环境中，提供真实项目 ID 和对应选项：
 
 ```sh
 yuanma-gateway init \
-  --relay-url ws://192.168.1.10:19088 \
+  --relay-url wss://relay.example.com \
   --projects '真实项目ID1,真实项目ID2' \
   --allow-development-keys \
   --accept-project-access
@@ -107,7 +151,7 @@ yuanma-gateway restart
 更新中继地址并保存，供后续重启/启动复用：
 
 ```sh
-yuanma-gateway restart --relay-url ws://192.168.1.20:19088
+yuanma-gateway restart --relay-url wss://new-relay.example.com
 ```
 
 网关尚未运行时使用 `start --relay-url 地址`。URL 支持 `ws://` 和 `wss://`，拒绝内嵌账号密码、查询参数、片段或非法端口。状态输出中的 `relayUrl` 是实际生效地址，末尾 `/` 属正常规范化结果。
@@ -126,7 +170,7 @@ yuanma-gateway pair
 
 ### 手机版本要求
 
-局域网连接使用 `ws://内网IP:19088`。建议手机与 Mac 网关保持兼容版本；更新 relay 镜像或 npm 网关，不会自动升级手机 App。
+使用花生壳 HTTPS/WSS 时，手机必须安装包含 WSS 支持的 **0.1.1（versionCode 100003）或后续版本**。原 **0.1.0（100002）** 不支持本次 WSS 地址。更新 relay 镜像或 npm 网关，不会自动升级手机 App。
 
 使用同一签名的新包覆盖安装，保留应用数据与原配对；不要先卸载或清空数据。在手机连接页选择“扫码更新连接地址”，扫描刚生成且未过期的二维码。手机和 Mac 须连接同一套 relay，两套中继之间不共享注册路由。
 
@@ -199,7 +243,7 @@ yuanma-gateway devices
 
 同步前会在网关私有状态目录保存桌面状态备份；桌面运行时不会写入其状态文件。待同步记录在网关重启后保留，旧版手机分区记录会自动纳入一次补同步。
 
-## 局域网中继部署：直接拉取 Docker Hub 镜像
+## 中继部署：直接拉取 Docker Hub 镜像
 
 公开仓库：[fxz26284407/yuanma-relay](https://hub.docker.com/r/fxz26284407/yuanma-relay)。普通部署不再需要在 Mac 打包源码、上传发布目录或在服务器构建镜像；宿主机只需 Docker，不需要安装 Node、Codex 或网关依赖。
 
@@ -212,14 +256,14 @@ yuanma-gateway devices
 
 ### 启动与端口
 
-以下假设中继宿主机的局域网 IP 为 `192.168.1.10`。先替换为本机实际 IP，确认 `19088` 未被占用，再执行：
+先确认宿主机 `19088` 未被占用，再执行：
 
 ```sh
 docker pull fxz26284407/yuanma-relay:2026.11.03
 
 docker run -d --name yuanma-relay \
   --restart unless-stopped --init \
-  -p 192.168.1.10:19088:8080 \
+  -p 19088:8080 \
   --read-only --tmpfs /tmp:rw,noexec,nosuid,size=16m \
   --cap-drop ALL --security-opt no-new-privileges:true \
   --memory 128m --cpus 0.5 --pids-limit 64 \
@@ -227,38 +271,82 @@ docker run -d --name yuanma-relay \
   fxz26284407/yuanma-relay:2026.11.03
 ```
 
-`192.168.1.10:19088:8080` 表示 **宿主机局域网 IP 的 19088 → 容器 8080**，仅绑定指定内网接口。如需换端口，同步修改两端连接地址。无需给 relay 挂载工作目录、数据库、网关配置或 Mac 私钥。镜像自带 Node 运行时，内部不含 Nginx。
+`19088:8080` 表示 **宿主机 19088 → 容器 8080**。如需换端口，只改左边并同步修改穿透回源端口。无需给 relay 挂载工作目录、数据库、网关配置或 Mac 私钥。镜像自带 Node 运行时，内部不含 Nginx。
 
 ```sh
-curl --max-time 5 -fsS http://192.168.1.10:19088/health
+curl --max-time 5 -fsS http://127.0.0.1:19088/health
 docker inspect yuanma-relay --format '{{.State.Status}} / {{.State.Health.Status}}'
 docker logs --tail 30 yuanma-relay
 ```
 
 健康接口应返回 `{"ok":true}`；启动后短暂的 `starting` 会在健康检查完成后转为 `healthy`。重启已有容器可执行 `docker restart yuanma-relay`。仅拉取新镜像不会自动替换运行中的容器，升级时按原部署方式重建并保留端口和资源配置；已有 relay 占用端口时不要重复启动。
 
-### 手机与 Mac 连接同一局域网
+### 花生壳 HTTPS / WSS
+
+花生壳客户端需上线，并能访问宿主机发布的 relay 端口：
+
+```text
+手机 / Mac 网关
+    → wss://你的花生壳域名:443
+    → 花生壳 HTTPS 入口（TLS 与证书）
+    → 花生壳客户端
+    → 宿主机可达地址:19088
+    → relay 容器 8080（HTTP/WS）
+```
+
+| 花生壳配置项 | 填写方式 |
+| --- | --- |
+| 映射协议 | HTTPS |
+| 外网域名 | 花生壳分配或绑定的实际域名 |
+| 外网端口 | 默认 443，或产品实际提供的 HTTPS 外网端口 |
+| 内网主机 | 从花生壳客户端所在环境可达的宿主机地址 |
+| 内网端口 | 19088 |
+| 回源协议（如有此选项） | HTTP，relay 内部不提供 TLS |
+
+**公网 HTTPS 不等于内网也要 HTTPS。** 花生壳负责证书和 TLS，relay 继续用 HTTP/WS。外层入口需要支持 WebSocket 升级；若有单独的 WebSocket 开关，应开启。容器内加 Nginx 无法替代外层的 WS 支持。
 
-1. 将手机连接到与 Mac、中继互通的 Wi-Fi；Mac 或中继主机可使用同一路由器下的有线网络。不要使用隔离设备的访客网络。
-2. 为中继主机配置 DHCP 地址保留或固定内网 IP，允许可信内网设备访问 TCP `19088`，关闭路由器端口转发、穿透及其他对外入口。
-3. 在 Mac 检查 `http://192.168.1.10:19088/health`，返回 `{"ok":true}` 后更新网关并配对：
+“内网主机”按花生壳实际运行位置选择：
+
+- 花生壳直接运行在 relay 宿主机上：可以使用 `127.0.0.1:19088`。
+- 花生壳在 Docker 容器里：`127.0.0.1` 是花生壳容器自身，应改为可达的宿主机地址。
+- Mac Docker Desktop 可查询 `host.docker.internal`；本次环境解析为 `192.168.65.254`，已核对从花生壳容器能访问 `192.168.65.254:19088`。该 IP 不是所有机器的固定值。
+- Linux 或其他环境使用从花生壳客户端可达的宿主机内网 IP，不直接照抄 Mac 示例。
+
+例如花生壳容器名为 `oray`，且内置以下工具：
+
+```sh
+docker exec oray getent hosts host.docker.internal
+docker exec oray wget -qO- -T 5 -t 1 http://192.168.65.254:19088/health
+curl --max-time 10 -fsS https://relay.example.com/health
+```
+
+容器名、内网 IP 和公网域名均应替换为实际值。两跳健康接口都应返回 `{"ok":true}`，HTTPS 证书应有效。健康检查通过不等于 WebSocket 可用；还需确认 WSS 的 HTTP 101 升级及手机安全登录。
+
+配置完成后，已通过 npm 初始化的 Mac 网关可在任意目录执行：
 
 ```sh
-yuanma-gateway pair --relay-url ws://192.168.1.10:19088
+source ~/.nvm/nvm.sh
+nvm use 22
+yuanma-gateway pair --relay-url wss://relay.example.com
 ```
 
-将示例 IP 替换为中继主机实际的内网 IP。手机扫描 Mac 生成的二维码；已有配对通过“扫码更新连接地址”沿用原身份。手机和 Mac 须使用同一个中继地址，手机不能将 `127.0.0.1` 或 `localhost` 作为 Mac 地址。
+将 `relay.example.com` 换成花生壳实际域名；非 443 外网端口需写入 URL。npm 配对命令会按现有安装启动网关，地址变化时安全重启原实例；已配对手机通过“扫码更新连接地址”沿用原身份登录。使用 HTTPS 穿透时，网关参数写 `wss://`，不能写 `https://`。手机须先升级至上文要求的 WSS 版本。
+
+本机部署依赖 Mac、Docker Desktop 和花生壳持续在线。休眠、退出 Docker 或花生壳离线都会中断连接；中继镜像不会自动配置这些运行条件。
+
+### 公网服务器直连或外部反代
 
-离开该局域网后，此部署方式无法连接 Mac；回到互通网络后可重新连接。更换局域网或中继 IP 后，更新网关地址并重新扫码。部署在 Mac Docker 上时，Mac 与 Docker 必须持续运行；休眠或退出 Docker 会中断连接。
+也可在公网服务器运行同一镜像，放行实际端口后使用 `ws://服务器地址:19088`。需要 HTTPS/WSS 域名时，由外部 Nginx 或其他支持 WebSocket 的反代处理 TLS 和升级，再回源 HTTP `19088`；无需修改容器内部域名或证书。
 
 ### 常见连接问题
 
 | 现象 | 优先核对 |
 | --- | --- |
-| 宿主机健康检查失败 | relay 是否运行、绑定的内网 IP 是否属于本机、端口是否被占用 |
-| Mac 可达，手机不可达 | 手机是否连接同一局域网、是否启用访客隔离、防火墙是否允许内网端口 |
-| 手机扫码后仍恢复旧连接 | 二维码是否过期、新地址是否成功登录并保存 |
-| 更换网络后无法连接 | 是否仍能访问中继内网 IP；地址变化后需更新网关并重新扫码 |
+| 宿主机健康检查失败 | relay 是否运行、端口映射是否正确或被占用 |
+| 宿主机可达，花生壳容器访问失败 | 是否误用 127.0.0.1、内网 IP 是否从该容器可达 |
+| 内网可达，外网域名失败 | 花生壳是否在线、映射是否保存、回源地址和协议是否正确 |
+| HTTPS 200，但 WSS 失败 | 外层 WebSocket 支持、证书和实际外网端口 |
+| 手机扫码后仍恢复旧连接 | 手机版本是否支持 WSS、二维码是否过期、新地址是否成功登录并保存 |
 | WS 打开后路由立即断开 | Mac 网关是否注册到同一套 relay；“配置了中继”不等于注册成功 |
 
 Docker Hub 首页有完整的镜像使用说明。源码构建和 `npm run package:relay` 仍保留给需要自行修改中继的开发者，不作为普通部署的前置步骤。

package/bin/yuanma-gateway.mjs

@@ -9,8 +9,9 @@ import {parseArgs} from 'node:util';
 import {createInterface} from 'node:readline/promises';
 import {setTimeout as delay} from 'node:timers/promises';
 import {Rpc} from '../dist/rpc.mjs';
-import {relayEndpoint} from '../dist/relay.js';
-import {gatewayLaunch, restartGateway, gatewayStatus, stopGateway, openGatewayLog} from '../scripts/restart-local-gateway.mjs';
+import {lanAddresses, lanConfig, DEFAULT_LAN_PORT} from '../dist/lan.js';
+import {relayEndpoint} from '../dist/relay-client.js';
+import {connectionArgs, gatewayLaunch, restartGateway, gatewayStatus, stopGateway, openGatewayLog} from '../scripts/restart-local-gateway.mjs';
 
 process.umask(0o077);
 const root=fileURLToPath(new URL('../',import.meta.url));
@@ -22,7 +23,10 @@ const help=`远码网关（需要 Node.js 22 和与桌面共享的 Codex 后端
   yuanma-gateway init --config 原配置绝对路径 --state-dir 原状态目录绝对路径
   yuanma-gateway start [--relay-url wss://域名]
   yuanma-gateway restart [--relay-url wss://域名]
-  yuanma-gateway pair [--relay-url wss://域名]
+  yuanma-gateway pair（默认局域网，交互选择内网 IP）
+  yuanma-gateway pair --relay-url ws[s]://中继地址
+  局域网选项：--connection-mode lan [--lan-host 内网IP] [--lan-port 19089]
+  中继选项：--relay-url ws[s]://中继地址（start/restart 沿用原模式，pair 默认局域网）
   yuanma-gateway status | stop | projects | devices | security
   yuanma-gateway device-project-policy --device-id 设备ID --capability control
 默认配置与状态位于 ~/.local/share/yuanma/gateway/，npm 升级不会覆盖。
@@ -44,6 +48,7 @@ async function createJson(path,value){
 }
 function validateConfig(config){
  if(!Array.isArray(config.projects)||!config.projects.length||config.projects.some(p=>typeof p.id!=='string'||!p.id||!Array.isArray(p.roots)||!p.roots.length||p.roots.some(r=>typeof r!=='string'||!r.startsWith('/'))))throw Error('配置需要明确的项目 ID 和绝对根目录');
+ if(config.connectionMode!==undefined&&!['lan','relay'].includes(config.connectionMode))throw Error('配置中的连接模式无效');
  if(config.relayUrl!=null)relayEndpoint(config.relayUrl);
 }
 async function installation(values){
@@ -53,16 +58,46 @@ async function installation(values){
  if(typeof info.config!=='string'||!info.config.startsWith('/')||typeof info.stateDir!=='string'||!info.stateDir.startsWith('/'))throw Error('安装记录中的路径无效');
  const config=await privateJson(info.config);validateConfig(config);
  await lstat(info.stateDir);await privateDirectory(info.stateDir);
- if(info.relayUrl!==undefined)relayEndpoint(info.relayUrl);
+ if(info.relayUrl!=null)relayEndpoint(info.relayUrl);
  return {...info,configData:config};
 }
-async function rememberRelay(info,relayUrl){
+async function rememberConnection(info,connection){
  const current=await privateJson(settingsPath).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
- if(!current||current.config!==info.config||current.stateDir!==info.stateDir||current.relayUrl===relayUrl)return;
+ if(!current||current.config!==info.config||current.stateDir!==info.stateDir){
+  const config=await privateJson(info.config);
+  const temporary=join(dirname(info.config),'connection-'+randomUUID()+'.tmp');
+  try{await createJson(temporary,{...config,...connection,relayUrl:connection.connectionMode==='relay'?connection.relayUrl:null});await rename(temporary,info.config);}
+  finally{await unlink(temporary).catch(e=>{if(e.code!=='ENOENT')throw e;});}
+  return;
+ }
  const temporary=join(home,'installation-'+randomUUID()+'.tmp');
- try{await createJson(temporary,{...current,relayUrl});await rename(temporary,settingsPath);}
+ try{await createJson(temporary,{...current,...connection,relayUrl:connection.connectionMode==='relay'?connection.relayUrl:null});await rename(temporary,settingsPath);}
  finally{await unlink(temporary).catch(e=>{if(e.code!=='ENOENT')throw e;});}
 }
+async function selectConnection(values,saved={},choose=false){
+ if(values['relay-url']!==undefined&&values['connection-mode']==='lan')throw Error('--relay-url 与局域网模式冲突');
+ if(values['lan-host']!==undefined&&(values['relay-url']!==undefined||values['connection-mode']==='relay'))throw Error('--lan-host 与 Relay 模式冲突');
+ const mode=values['connection-mode']??(values['relay-url']!==undefined?'relay':values['lan-host']!==undefined?'lan':saved.connectionMode??(saved.relayUrl?'relay':'lan'));
+ if(mode==='relay')return {connectionMode:'relay',relayUrl:relayEndpoint(values['relay-url']??saved.relayUrl)};
+ if(mode!=='lan')throw Error('--connection-mode 只能是 lan 或 relay');
+ let host=values['lan-host']??saved.lanHost;
+ const addresses=lanAddresses();
+ if(values['lan-host']!==undefined)lanConfig(host,values['lan-port']??saved.lanPort??DEFAULT_LAN_PORT);
+ if(!addresses.some(a=>a.address===host)||(choose&&values['lan-host']===undefined&&new Set(addresses.map(a=>a.address)).size>1)){
+  if(host&&!addresses.some(a=>a.address===host))console.log('原局域网 IP 已不可用，请重新选择。');
+  const unique=addresses.filter((a,i)=>addresses.findIndex(b=>a.address===b.address)===i);
+  if(!unique.length)throw Error('未发现局域网 IPv4，请连接 Wi-Fi 或有线网络');
+  unique.forEach((a,i)=>console.log(`${i+1}. ${a.name}: ${a.address}${a.virtual?'（虚拟网卡/VPN，请确认手机可达）':''}`));
+  if(unique.length===1&&!unique[0].virtual)host=unique[0].address;
+  else{
+   if(!process.stdin.isTTY)throw Error('请显式提供 --lan-host 选择局域网 IP');
+   const prompt=createInterface({input:process.stdin,output:process.stdout});
+   try{const previous=unique.findIndex(a=>a.address===host)+1;const answer=(await prompt.question('选择手机可达的局域网 IP 序号'+(previous?'（回车沿用 '+previous+'）':'')+'：')).trim()||(previous?String(previous):'');const index=Number(answer);if(!/^\d+$/.test(answer)||index<1||index>unique.length)throw Error('网卡序号无效');host=unique[index-1].address;}finally{prompt.close();}
+  }
+ }
+ const lan=lanConfig(host,values['lan-port']??saved.lanPort??DEFAULT_LAN_PORT);
+ return {connectionMode:'lan',lanHost:lan.host,lanPort:lan.port,relayUrl:null};
+}
 async function catalog(socket){
  const rpc=new Rpc(socket,'yuanma_gateway_setup',{retainMessages:false});
  try{await rpc.initialize();const result=await rpc.call('project/list',{limit:100});return result.data;}finally{rpc.close();}
@@ -80,16 +115,18 @@ async function init(values){
   const active=await gatewayStatus(info.stateDir).catch(e=>{if(['ENOENT','ECONNREFUSED'].includes(e.code))return null;throw e;});
   if(active)await gatewayLaunch(info.stateDir);
   // ponytail: 原地登记既有目录，不复制正在使用的 SQLite 或身份文件。
-  await createJson(settingsPath,{config:info.config,stateDir:info.stateDir,...(active?.relayUrl||info.configData.relayUrl?{relayUrl:relayEndpoint(active?.relayUrl??info.configData.relayUrl)}:{})});
+  await createJson(settingsPath,{config:info.config,stateDir:info.stateDir,...(active?.connectionMode==='lan'?{connectionMode:'lan',lanHost:active.lanHost,lanPort:active.lanPort,relayUrl:null}:info.configData.connectionMode==='lan'?{connectionMode:'lan',lanHost:info.configData.lanHost,lanPort:info.configData.lanPort,relayUrl:null}:active?.relayUrl||info.configData.relayUrl?{relayUrl:relayEndpoint(active?.relayUrl??info.configData.relayUrl)}:{})});
   console.log('已沿用原配置、密钥、设备授权和消息账本；请保留原目录。');return;
  }
  const configPath=join(home,'config.json'),stateDir=join(home,'state');
  const saved=await privateJson(configPath).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
- if(saved){validateConfig(saved);await lstat(stateDir);await privateDirectory(stateDir);await createJson(settingsPath,{config:configPath,stateDir,...(saved.relayUrl?{relayUrl:relayEndpoint(saved.relayUrl)}:{})});console.log('已保留原配置并恢复安装记录。');return;}
+ if(saved){validateConfig(saved);await lstat(stateDir);await privateDirectory(stateDir);await createJson(settingsPath,{config:configPath,stateDir,...(saved.connectionMode==='lan'?{connectionMode:'lan',lanHost:saved.lanHost,lanPort:saved.lanPort,relayUrl:null}:saved.relayUrl?{relayUrl:relayEndpoint(saved.relayUrl)}:{})});console.log('已保留原配置并恢复安装记录。');return;}
  let prompt;
- const ask=async question=>{if(!process.stdin.isTTY)throw Error('非交互初始化需提供 --relay-url、--projects、--allow-development-keys 和 --accept-project-access');prompt??=createInterface({input:process.stdin,output:process.stdout});return prompt.question(question);};
+ const ask=async question=>{if(!process.stdin.isTTY)throw Error('非交互初始化需提供 --projects、--allow-development-keys 和 --accept-project-access；多网卡时还需 --lan-host');prompt??=createInterface({input:process.stdin,output:process.stdout});return prompt.question(question);};
  try{
-  const relay=relayEndpoint(values['relay-url']??await ask('中继地址（ws:// 或 wss://）：'));
+  const entered=values['relay-url']??(values['connection-mode']||values['lan-host']||!process.stdin.isTTY?'':await ask('中继地址（可留空使用局域网直连）：'));
+  prompt?.close();prompt=undefined;
+  const connection=await selectConnection({...values,...(entered.trim()?{'relay-url':entered.trim()}:{})});
   const socket=resolve(values['codex-socket']??join(homedir(),'.local/share/yuanma/shared/app-server.sock'));
   const projects=await catalog(socket);
   if(!Array.isArray(projects)||!projects.length)throw Error('共享 Codex 后端没有可选择的项目');
@@ -105,23 +142,23 @@ async function init(values){
   if(!allow)throw Error('未启用当前版本所需的密钥模式，未创建配置或网关身份');
   const accepted=values['accept-project-access']||(await ask('配对后所有发现的项目和工作区默认可执行，初始项目列表不是权限白名单。接受此策略？[y/N]：')).trim().toLowerCase()==='y';
   if(!accepted)throw Error('未接受现有项目访问策略，未创建配置或网关身份');
-  const config={codexSocket:socket,relayUrl:relay,allowDevelopmentKeys:true,projects:selected.map(p=>({id:p.id,...(p.name?{name:p.name}:{}),roots:p.roots}))};validateConfig(config);
+  const config={codexSocket:socket,...connection,allowDevelopmentKeys:true,projects:selected.map(p=>({id:p.id,...(p.name?{name:p.name}:{}),roots:p.roots}))};validateConfig(config);
   await privateDirectory(stateDir);
   await createJson(configPath,config);
-  await createJson(settingsPath,{config:configPath,stateDir,relayUrl:relay});
+  await createJson(settingsPath,{config:configPath,stateDir,...connection});
   console.log('初始化完成；配置：'+configPath+'\n状态：'+stateDir+'\n接下来运行 yuanma-gateway start 和 yuanma-gateway pair。');
  }finally{prompt?.close();}
 }
-async function start(info,relay){
- const value=relay??info.relayUrl??info.configData.relayUrl??undefined;
- const wanted=value===undefined?undefined:relayEndpoint(value);
+async function start(info,connection){
+ const flags=connectionArgs(connection);
+ const endpoint=connection.connectionMode==='relay'?relayEndpoint(connection.relayUrl):`ws://${connection.lanHost}:${connection.lanPort}/v1/secure`;
  const current=await gatewayStatus(info.stateDir).catch(e=>{if(['ENOENT','ECONNREFUSED'].includes(e.code))return null;throw e;});
- if(current){await gatewayLaunch(info.stateDir);if(wanted&&current.relayUrl!==wanted)return restartGateway(info.stateDir,wanted);if(!current.backendReady)throw Error('已有网关尚未就绪，请查看状态和日志');return current;}
+ if(current){await gatewayLaunch(info.stateDir);if((current.endpoint??current.relayUrl)!==endpoint||current.connectionMode!==connection.connectionMode)return restartGateway(info.stateDir,connection);if(!current.backendReady)throw Error('已有网关尚未就绪，请查看状态和日志');return current;}
  await privateDirectory(info.stateDir);
  const logPath=join(info.stateDir,'gateway.log');
  const log=await openGatewayLog(logPath);
  try{
-  const args=[cli,'start','--config',info.config,'--state-dir',info.stateDir];if(wanted)args.push('--relay-url',wanted);
+  const args=[cli,'start','--config',info.config,'--state-dir',info.stateDir];args.push(...flags);
   const child=spawn(process.execPath,args,{cwd:dirname(info.config),detached:true,stdio:['ignore',log.fd,log.fd]});child.unref();
   let error,exited=false;child.on('error',e=>{error=e;});child.on('exit',()=>{exited=true;});
   for(let n=0;n<150;n++){
@@ -129,7 +166,7 @@ async function start(info,relay){
    if(exited)throw Error('网关启动失败，请查看 '+logPath);
    const state=await gatewayStatus(info.stateDir).catch(e=>{if(['ENOENT','ECONNREFUSED'].includes(e.code))return null;throw e;});
    if(state?.processId&&state.processId!==child.pid)throw Error('另一实例取得了网关状态目录，未启动第二套身份');
-   if(state?.backendReady)return state;
+   if(state?.backendReady&&state.endpoint===endpoint&&state.connectionMode===connection.connectionMode)return state;
    await delay(100);
   }
   throw Error('启动尚未完成，请检查 yuanma-gateway status 和 '+logPath+'；不要重复初始化');
@@ -146,7 +183,7 @@ try{
  if(['help','--help','-h'].includes(action)||args.includes('--help'))console.log(help);
  else if(['--version','version'].includes(action))console.log(JSON.parse(await readFile(join(root,'package.json'),'utf8')).version);
  else{
-  const {values}=parseArgs({args,options:{config:{type:'string'},'state-dir':{type:'string'},'relay-url':{type:'string'},'codex-socket':{type:'string'},projects:{type:'string'},'allow-development-keys':{type:'boolean'},'accept-project-access':{type:'boolean'},backend:{type:'string'},'device-id':{type:'string'},capability:{type:'string'},'claim-id':{type:'string'},'grants-json':{type:'string'}}});
+  const {values}=parseArgs({args,options:{config:{type:'string'},'state-dir':{type:'string'},'relay-url':{type:'string'},'connection-mode':{type:'string'},'lan-host':{type:'string'},'lan-port':{type:'string'},'codex-socket':{type:'string'},projects:{type:'string'},'allow-development-keys':{type:'boolean'},'accept-project-access':{type:'boolean'},backend:{type:'string'},'device-id':{type:'string'},capability:{type:'string'},'claim-id':{type:'string'},'grants-json':{type:'string'}}});
   if(action==='init')await init(values);
   else if(action==='projects'){
    if(values.backend&&values.backend!=='codex')await run(cli,['projects','--backend',values.backend]);
@@ -154,15 +191,17 @@ try{
   }else if(['start','restart','stop','status','pair','devices','security','device-project-policy','pairing-pending','pairing-approve','pairing-reject','device-revoke'].includes(action)){
    const info=await installation(values);
    if(action==='start'||action==='restart'){
-    const state=action==='start'?await start(info,values['relay-url']):await restartGateway(info.stateDir,values['relay-url']??info.relayUrl);
-    if(state.relayUrl)await rememberRelay(info,state.relayUrl);
+    const connection=await selectConnection(values,{...info.configData,...info});
+    const state=action==='start'?await start(info,connection):await restartGateway(info.stateDir,connection);
+    await rememberConnection(info,connection);
     console.log(JSON.stringify(state,null,2));
    }
    else if(action==='stop'){await stopGateway(info.stateDir);console.log('网关已停止，配置和设备数据保留。');}
    else if(action==='status')console.log(JSON.stringify(await gatewayStatus(info.stateDir),null,2));
    else if(action==='pair'){
-    const state=await start(info,values['relay-url']);if(state.relayUrl)await rememberRelay(info,state.relayUrl);
-    await run(join(root,'scripts/pairing-qr.mjs'),['--state-dir',info.stateDir,'--auto-approve','--no-ui',...(values['relay-url']?['--relay-url',values['relay-url']]:[])]);
+    const connection=await selectConnection({...values,'connection-mode':values['connection-mode']??(values['relay-url']!==undefined?'relay':'lan')},{...info.configData,...info},process.stdin.isTTY);
+    await start(info,connection);await rememberConnection(info,connection);
+    await run(join(root,'scripts/pairing-qr.mjs'),['--state-dir',info.stateDir,'--auto-approve','--no-ui',...connectionArgs(connection)]);
    }else{
     const forwarded=[action,'--state-dir',info.stateDir];
     for(const key of ['backend','device-id','capability','claim-id','grants-json'])if(values[key]!==undefined)forwarded.push('--'+key,values[key]);

package/dist/agent-commands.js

@@ -0,0 +1,15 @@
+import { digest, requireValue } from './domain.js';
+export const agentCommands = [
+    { name: 'goal', description: '设置长期目标并持续推进' },
+    { name: 'plan', description: '先研究并制定计划' },
+    { name: 'compact', description: '精简当前会话上下文' }
+];
+export function checkGoal(goal, version) {
+    requireValue(goal && version === goal.version, 'GOAL_CHANGED', '目标已变化，请刷新后重试');
+    return goal;
+}
+export function goalView(value) {
+    if (!value)
+        return null;
+    return { objective: value.objective, status: value.status, version: digest({ objective: value.objective, status: value.status, createdAt: value.createdAt }), ...(Number.isFinite(value.tokensUsed) ? { tokensUsed: value.tokensUsed } : {}), ...(Number.isFinite(value.tokenBudget) ? { tokenBudget: value.tokenBudget } : {}) };
+}

package/dist/antigravity-native.js

@@ -95,6 +95,9 @@ export class AntigravityNative {
     async state() {
         return this.readState('JetboxSubscribeToState', {});
     }
+    async agentState(conversationId) {
+        return this.readState('StreamAgentStateUpdates', { conversationId, subscriberId: 'yuanma-runtime', disableRehydration: true });
+    }
     async subscribeAgentState(conversationId, startIndex, onValue, onEnd) {
         return this.stream('StreamAgentStateUpdates', { conversationId, subscriberId: 'yuanma-live:' + randomUUID(), disableRehydration: true, trajectoryVerbosity: 'CLIENT_TRAJECTORY_VERBOSITY_PROD_UI', initialStepsPageBounds: { startIndex } }, onValue, onEnd);
     }