@fxz26284407/yuanma-gateway 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +203 -0
  2. package/NOTICE +26 -0
  3. package/README.md +369 -2
  4. package/bin/yuanma-gateway.mjs +212 -0
  5. package/dist/agents.js +5 -0
  6. package/dist/antigravity-acp.js +132 -0
  7. package/dist/antigravity-conversation.js +73 -0
  8. package/dist/antigravity-native.js +150 -0
  9. package/dist/antigravity.js +660 -0
  10. package/dist/approvals.js +52 -0
  11. package/dist/async-questions.js +34 -0
  12. package/dist/auth.js +228 -0
  13. package/dist/browser-extensions.js +60 -0
  14. package/dist/changes.js +65 -0
  15. package/dist/cli.js +116 -0
  16. package/dist/codex.js +636 -0
  17. package/dist/conversation.js +1 -0
  18. package/dist/deepseek-conversation.js +108 -0
  19. package/dist/deepseek-suggestion-runner.mjs +35 -0
  20. package/dist/deepseek-suggestion.js +29 -0
  21. package/dist/deepseek.js +864 -0
  22. package/dist/desktop-sync.js +163 -0
  23. package/dist/domain.js +21 -0
  24. package/dist/execution-summary.js +62 -0
  25. package/dist/extension-icons.js +110 -0
  26. package/dist/extensions.js +40 -0
  27. package/dist/identity.js +29 -0
  28. package/dist/lan.js +44 -0
  29. package/dist/ledger.js +158 -0
  30. package/dist/media.js +75 -0
  31. package/dist/mobile-history.js +36 -0
  32. package/dist/next-suggestion.js +41 -0
  33. package/dist/noise.js +131 -0
  34. package/dist/permissions.js +13 -0
  35. package/dist/progress.js +113 -0
  36. package/dist/project-access.js +75 -0
  37. package/dist/queue.js +127 -0
  38. package/dist/relay-client.js +57 -0
  39. package/dist/relay.js +119 -0
  40. package/dist/rpc.mjs +127 -0
  41. package/dist/secure-ws.js +199 -0
  42. package/dist/server.js +946 -0
  43. package/dist/sidebar.js +41 -0
  44. package/dist/thread-titles.js +44 -0
  45. package/dist/uploads.js +260 -0
  46. package/dist/version.js +2 -0
  47. package/gateway/config.example.json +15 -0
  48. package/package.json +57 -4
  49. package/scripts/approval-ui.html +10 -0
  50. package/scripts/approval-ui.mjs +37 -0
  51. package/scripts/pairing-qr.mjs +63 -0
  52. package/scripts/restart-local-gateway.mjs +97 -0
package/LICENSE ADDED
@@ -0,0 +1,203 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
203
+
package/NOTICE ADDED
@@ -0,0 +1,26 @@
1
+ # Yuanma Gateway NOTICE
2
+
3
+ Copyright 2026 fxz26284407
4
+ Original author: https://github.com/fxz26284407
5
+ Original project: https://github.com/fxz26284407/yuanma-gateway
6
+ Companion HarmonyOS client: https://github.com/fxz26284407/yuanma-harmony
7
+
8
+ Original project attribution is provided for preservation under Apache-2.0, section 4. This notice does not add restrictions to that license.
9
+
10
+ # Third-party dependencies
11
+
12
+ Dependencies are installed through npm; dependency source trees are not vendored here.
13
+
14
+ | Package | Version | License |
15
+ | --- | --- | --- |
16
+ | better-sqlite3 | 12.4.1 | MIT |
17
+ | noise-handshake | 4.2.0 | Apache-2.0 |
18
+ | qrcode-terminal | 0.12.0 | Apache-2.0 |
19
+ | ws | 8.20.0 | MIT |
20
+
21
+ qrcode-terminal includes QRCode for JavaScript, Copyright (c) 2009 Kazuhiko Arase, under its MIT notice; the upstream package LICENSE retains that notice.
22
+
23
+ Development and transitive dependencies retain their respective licenses in the npm packages and package lock metadata. Relay packaging copies the complete ws package, including its license. No third-party copyright notices are removed.
24
+
25
+ Original Yuanma gateway code is licensed under Apache-2.0; dependency licenses remain unchanged.
26
+
package/README.md CHANGED
@@ -1,3 +1,370 @@
1
- # Temporary Holding Version
1
+ # 远码网关(yuanma-gateway)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 远码的 Mac 本地网关与 HTTP/WS 公网密文中继。只包含两端网关,不包含鸿蒙工程、签名文件、个人文档库或运行数据。
4
+
5
+ ## 局域网直连(本地开发版本,尚未发布到 npm)
6
+
7
+ 本地代码已支持手机直接连接 Mac,无需启动 Relay。npm 已发布的 0.1.0 仍沿用原中继流程;使用直连需同时更新本地网关和鸿蒙 App,旧 App 不支持新的直连二维码。
8
+
9
+ 在本仓库使用 Node.js 22 构建后运行:
10
+
11
+ ```sh
12
+ npm run build
13
+ node bin/yuanma-gateway.mjs init
14
+ node bin/yuanma-gateway.mjs pair
15
+ ```
16
+
17
+ 首次初始化的中继地址可以留空。单个常规内网 IPv4 自动选择,多个地址展示网卡与 IP 供选择;虚拟网卡需确认手机可达。默认端口为 `19089`,二维码地址为 `ws://所选内网IP:19089/v1/secure`。仅该加密入口对内网开放,本地管理接口继续使用 Unix socket。仍需准备与桌面共享的 Codex 后端及现有密钥保存模式。
18
+
19
+ 普通 start/restart 沿用已保存模式;pair 默认局域网,多个内网 IP 时交互选择,直接执行:
20
+
21
+ ```sh
22
+ node bin/yuanma-gateway.mjs pair
23
+ ```
24
+
25
+ 非交互或需要指定网卡、端口时:
26
+
27
+ ```sh
28
+ node bin/yuanma-gateway.mjs pair --lan-host 192.168.1.10 --lan-port 19089
29
+ ```
30
+
31
+ 将示例 IP 替换为本机实际内网地址。IP 失效时重新选择并扫码,端口冲突时更换端口;不要将手机的 localhost 当作 Mac。网关保存连接方式,后续启动复用;设备身份与授权保持原样。
32
+
33
+ 保留 Relay 扩展,切换时使用:
34
+
35
+ ```sh
36
+ node bin/yuanma-gateway.mjs pair --relay-url wss://relay.example.com
37
+ ```
38
+
39
+ 局域网和 Relay 首版互斥,不会自动回退公网。以下中继安装与部署说明适用于已有发布版本及需要中继扩展的用户。
40
+
41
+ ## 项目系列
42
+
43
+ [远码 Yuanma · GitHub Project](https://github.com/users/fxz26284407/projects/2)
44
+
45
+ - [远码网关与公网中继](https://github.com/fxz26284407/yuanma-gateway)
46
+ - [远码鸿蒙客户端](https://github.com/fxz26284407/yuanma-harmony)
47
+
48
+ ## 部署架构
49
+
50
+ ![远码部署架构](docs/assets/deployment.svg)
51
+
52
+ 手机和 Mac 主动连接同一个公网 WS 入口;业务内容通过 Noise 在两端加密,中继只负责转发。Codex Desktop 与 Mac 网关连接同一个 app-server,任务、文件操作和审批发生在 Mac。SQLite 消息账本与设备授权也保存在 Mac。
53
+
54
+ 中继默认直接拉取 [Docker Hub 公开镜像](https://hub.docker.com/r/fxz26284407/yuanma-relay),端口映射为 `19088:8080`,支持 amd64 / arm64。既可部署在公网服务器,也可部署在本机 Docker 并通过花生壳 HTTPS 穿透,以 `wss://域名` 连接。
55
+
56
+ 容器内只有 Node HTTP/WS relay,不含 Nginx,也无需配置域名或证书。HTTPS/WSS 的证书和 WebSocket 升级由花生壳或外部反代处理;直接使用 `ws://服务器地址:19088` 时不需要外部反代。
57
+
58
+ [架构图源文件](docs/deployment.archify.json)
59
+
60
+ ## 模块
61
+
62
+ | 目录 | 内容 | 运行位置 |
63
+ | --- | --- | --- |
64
+ | `gateway/` | Codex 适配、鉴权、项目权限、SQLite 消息账本、自有队列、图片和审批路由 | 工作 Mac |
65
+ | `gateway/relay.ts`、`deploy/relay/` | HTTP 健康检查、WebSocket 密文路由、Docker 配置 | 公网服务器或本机 Docker |
66
+ | `scripts/` | 配对二维码、Mac 本地批准页、网关重启和中继打包 | Mac |
67
+
68
+ 手机与 Mac 建立固定公钥的 Noise 加密通道,中继只转发密文。Codex 桌面和网关需要连接同一后端才能共享实时会话。
69
+
70
+ ## 附件与下一步建议
71
+
72
+ - 支持图片、PDF、Office 文档及常见文本文件。文档单个最多 50 MiB,每条消息附件共 4 个、合计最多 100 MiB;图片单张及每条消息图片合计仍为 8 MiB。
73
+ - 文档通过加密分块上传,在 Mac 私有目录暂存并校验 SHA-256,完成后将原文件路径交给智能体。Mac 每个后端附件存储最多 512 MiB、2048 项,满额后需要清理旧附件;上传不代表所有格式都能由模型直接解析。
74
+ - Codex 与 DeepSeek 共用下一步建议开关、预览及采用流程,各自使用自己的模型和额度。建议只填入可编辑草稿,不自动发送。
75
+ - DeepSeek 建议复用 `/Applications/DeepSeek Harness.app` 内置 SDK 和既有登录,独立请求近期会话文本,不加载 Agent、会话持久化或工具。支持 `deepseek-account` 与 `deepseek-official` 路由;其他第三方提供方尚未适配。桌面 SDK 更新不兼容时,建议暂不可用,原会话仍走现有桌面 Host。
76
+
77
+ ## Antigravity 接入进度
78
+
79
+ 支持读取 Antigravity App 的已有工作区、会话、历史分页和全文。手机可切换第三个智能体,文件引用按 Markdown 标签展示。CLI 不可用时保留只读浏览。
80
+
81
+ 控制通道使用官方 Antigravity CLI 1.5.0 的 ACP,默认可执行文件为 `~/.local/bin/agy`;其他路径可在网关配置中设置 `antigravityCli`。目前已接线已有会话发送、实时进度、手机回合取消、原生审批/字符串问题回复、模型与思考档位、执行策略及图片输入。实际用户任务的发送、审批与取消闭环尚未完成验收;新建、引导、会话菜单、文档附件、扩展、Diff 和下一步建议未开放。
82
+
83
+ 进程重启后无法确认的发送会保留未知状态,不自动重发。当前只支持取消手机通过本网关发起的回合,尚不提供桌面独立回合的停止或审批接管,整体使用体验仍未与 Codex 对齐。历史与摘要单文件上限为 32 MiB,超限会明确提示。
84
+
85
+ ## Mac 网关安装(npm)
86
+
87
+ 需要 **macOS、Node.js 22**,以及已登录、与桌面共用的 Codex app-server。当前适配固定为 app-server **0.166.0**;其他版本需要先适配协议。DeepSeek 功能另外依赖本机已有的 DeepSeek Harness 和登录。
88
+
89
+ ### 安装
90
+
91
+ ```sh
92
+ nvm install 22
93
+ nvm use 22
94
+ npm install -g @fxz26284407/yuanma-gateway@0.1.0 --registry=https://registry.npmjs.org
95
+ yuanma-gateway --version
96
+ ```
97
+
98
+ 无需克隆仓库或手动运行 TypeScript 构建。SQLite 使用 npm 原生依赖;若对应平台没有预编译二进制,安装时需要 Xcode Command Line Tools。不要用 `sudo` 启动网关,进程应与 Codex 桌面属于同一 Mac 用户。
99
+
100
+ ### 配置共享后端入口
101
+
102
+ 默认读取 `~/.local/share/yuanma/shared/app-server.sock`。先确认桌面实际使用的同用户私有 Codex socket,再建立该入口,或初始化时通过 `--codex-socket /absolute/path/to/shared/app-server.sock` 指定真实入口。npm 安装不会改写 Codex 桌面的启动方式,也不会自动创建另一套后端。
103
+
104
+ 仅查看真实项目目录,不创建任务:
105
+
106
+ ```sh
107
+ yuanma-gateway projects
108
+ ```
109
+
110
+ ### 初始化
111
+
112
+ ```sh
113
+ yuanma-gateway init --relay-url wss://relay.example.com
114
+ ```
115
+
116
+ 将示例域名替换为实际 relay 地址。初始化读取真实 Codex 项目列表,由你选择初始项目。**现有产品会继续同步发现其他项目;配对后所有发现的项目和工作区默认可执行,初始列表不是权限白名单。** 初始化会明确说明并要求接受这项既有策略;会话中的执行审批仍独立管理。
117
+
118
+ 当前版本的远程连接还需显式启用本机私有文件保存传输密钥的模式;交互界面会说明并征求选择。
119
+
120
+ 在非交互环境中,提供真实项目 ID 和对应选项:
121
+
122
+ ```sh
123
+ yuanma-gateway init \
124
+ --relay-url wss://relay.example.com \
125
+ --projects '真实项目ID1,真实项目ID2' \
126
+ --allow-development-keys \
127
+ --accept-project-access
128
+ ```
129
+
130
+ 默认数据目录为 `~/.local/share/yuanma/gateway/`:
131
+
132
+ | 文件或目录 | 内容 |
133
+ | --- | --- |
134
+ | `installation.json` | 当前配置、状态目录及已保存中继地址的安装记录 |
135
+ | `config.json` | 项目授权、共享后端入口及初始中继配置 |
136
+ | `state/` | 网关身份密钥、设备配对/授权、SQLite 账本和运行状态 |
137
+ | `state/gateway.log`、`state/restart.log` | 启动及重启日志 |
138
+
139
+ 目录使用 700、配置文件使用 600 权限。它们位于 npm 安装目录之外,npm 升级不覆盖、删除或重新生成这些数据。重复执行 `init` 会保留现有安装,不重置身份或覆盖项目配置。
140
+
141
+ ### 启动、状态与重启
142
+
143
+ ```sh
144
+ yuanma-gateway start
145
+ yuanma-gateway status
146
+ yuanma-gateway restart
147
+ ```
148
+
149
+ `start` 在后台启动网关,终端关闭不停止进程;已有就绪实例时复用它,不新建第二套身份。`restart` 只重启经过 PID、私有所有权记录和本地状态接口核验的同一实例,不停止共享 Codex 后端。
150
+
151
+ 更新中继地址并保存,供后续重启/启动复用:
152
+
153
+ ```sh
154
+ yuanma-gateway restart --relay-url wss://new-relay.example.com
155
+ ```
156
+
157
+ 网关尚未运行时使用 `start --relay-url 地址`。URL 支持 `ws://` 和 `wss://`,拒绝内嵌账号密码、查询参数、片段或非法端口。状态输出中的 `relayUrl` 是实际生效地址,末尾 `/` 属正常规范化结果。
158
+
159
+ 后台运行不等于已配置开机自启动;npm 首版不安装 launchd 服务。
160
+
161
+ ### 手机配对
162
+
163
+ ```sh
164
+ yuanma-gateway pair
165
+ ```
166
+
167
+ 命令会确保网关已启动并生成有效二维码,手机证明设备密钥后按现有产品策略自动完成配对,所有发现的项目和工作区默认可执行。不会创建新的会话任务,也不改变会话中的执行审批设置。二维码包含短时凭据,不公开发布。
168
+
169
+ 已有同一 Mac 配对会沿用原设备身份登录;地址变化时重新扫码,手机在登录成功后保存新地址。npm CLI 复用现有配对逻辑,不提供与后端实际授权行为不一致的“手动 / 只读配对”选项。
170
+
171
+ ### 手机版本要求
172
+
173
+ 使用花生壳 HTTPS/WSS 时,手机必须安装包含 WSS 支持的 **0.1.1(versionCode 100003)或后续版本**。原 **0.1.0(100002)** 不支持本次 WSS 地址。更新 relay 镜像或 npm 网关,不会自动升级手机 App。
174
+
175
+ 使用同一签名的新包覆盖安装,保留应用数据与原配对;不要先卸载或清空数据。在手机连接页选择“扫码更新连接地址”,扫描刚生成且未过期的二维码。手机和 Mac 须连接同一套 relay,两套中继之间不共享注册路由。
176
+
177
+ ### 已有源码安装接入 npm
178
+
179
+ **已有配对的用户不要直接初始化另一套空身份。** 用原配置和状态目录原地登记:
180
+
181
+ ```sh
182
+ yuanma-gateway init \
183
+ --config /absolute/path/to/existing/.local/gateway-config.json \
184
+ --state-dir /absolute/path/to/existing/.local/gateway
185
+ yuanma-gateway status
186
+ yuanma-gateway restart
187
+ ```
188
+
189
+ 这只登记原路径,不复制运行中的 SQLite,不删除或重建密钥、设备授权与消息账本;会保留原运行实例的中继地址。第一次重启切换到当前 npm 安装的代码,之后仍使用原数据。**原目录必须保留,不能删除旧项目目录中的数据。** 原网关未运行时,登记后执行 `start`。
190
+
191
+ `--config` 和 `--state-dir` 必须成对给出;也可在具体命令中成对指定,以操作同一套自定义实例。已有安装再次 `init` 不会静默换到另一套身份。
192
+
193
+ ### 升级与停止
194
+
195
+ ```sh
196
+ npm install -g @fxz26284407/yuanma-gateway@latest --registry=https://registry.npmjs.org
197
+ yuanma-gateway restart
198
+ ```
199
+
200
+ 升级不会自动重启服务;上面的显式重启才切换到新代码。当前用户、配置、网关密钥、设备配对及授权、消息账本均保留。换 Node 版本后需在该版本下重新安装此命令,但用户目录中的数据仍保留。
201
+
202
+ ```sh
203
+ yuanma-gateway stop
204
+ ```
205
+
206
+ 停止不删除配置和设备数据,之后可用 `start` 恢复。不要为升级清理用户数据目录,也不要重新生成网关密钥。
207
+
208
+ ### 源码开发方式
209
+
210
+ 需要修改网关时仍可克隆仓库,使用 Node 22 执行 `npm ci`、`npm run build`,再运行原有 `npm run gateway -- start --config 路径 --state-dir 路径 --relay-url 地址`。原源码入口保持兼容;源码与 npm CLI 均沿用现有的默认可执行项目策略。
211
+
212
+ ## 移动端新建项目与自动授权
213
+
214
+ Mac 网关和鸿蒙客户端都需要更新到支持移动端新建项目的版本。先启动网关并完成手机配对,再设置该设备的新项目权限。
215
+
216
+ ### 当前项目权限策略
217
+
218
+ 当前产品固定为:所有发现的项目和工作区默认可执行,新项目自动取得执行权限。配置中的初始项目列表不是设备权限白名单,也不支持通过 `read` 或 `none` 切换到逐项授权。本次 npm 安装只复用这一既有行为,不修改已配对设备、授权版本或消息账本。
219
+
220
+ 在任意目录查看当前设备:
221
+
222
+ ```sh
223
+ yuanma-gateway devices
224
+ ```
225
+
226
+ 项目访问权限与会话执行审批分别管理,默认可执行不等于自动把新会话设为“完整存取权”。
227
+
228
+ ### 在手机设置路径并创建
229
+
230
+ 1. 打开“设置 → 连接 → 默认项目创建路径”,填写 **Mac 上的父目录**,点击“保存路径”。默认是 `~/workspace`,支持 `/` 开头的绝对路径或 `~/` 路径;`~` 指运行网关的 Mac 用户主目录。
231
+ 2. 打开侧栏,在“项目”标题右侧点击“新建项目”,输入项目名称,再点击“创建并授权”。名称最长 80 个字符,不能含 `/`、`\`、控制字符,也不能是 `.` 或 `..`。
232
+ 3. 网关在父目录下创建项目目录并登记 Codex 项目,手机自动取得执行权限并进入新对话,无需再单独批准此项目。
233
+
234
+ 例如,父目录设为 `~/Projects`、项目名为 `my-app`,实际工作目录就是 Mac 上的 `~/Projects/my-app`。路径设置保存在此手机上,按所连接的 Mac 分别记录,重启客户端后仍保留;修改默认路径只影响后续创建,不移动已有项目。目录不存在时由网关创建,运行网关的 Mac 用户须有写入权限。
235
+
236
+ “自动可执行”是项目访问权限;新对话默认仍为“要求批准”,不会自动切换为“完整存取权”。创建失败时先查看手机提示:权限提示需在 Mac 调整该设备策略,目录错误需检查 Mac 路径及写入权限,版本不支持则需更新网关。
237
+
238
+ ## 项目菜单与桌面同步
239
+
240
+ 手机侧栏支持长按项目“重新命名”或调整“分区”,也可选择“不分区”。只读或未授权的项目不能修改。
241
+
242
+ 手机新增、改名或调整分区后,网关会持久保存待同步变更。当前桌面应用不自动读取外部项目状态更新,因此请按以下顺序操作:**完全退出桌面应用 → 稍等并刷新手机侧栏,确认显示“已同步” → 重新打开桌面应用**。仅关闭桌面窗口不算退出。
243
+
244
+ 同步前会在网关私有状态目录保存桌面状态备份;桌面运行时不会写入其状态文件。待同步记录在网关重启后保留,旧版手机分区记录会自动纳入一次补同步。
245
+
246
+ ## 中继部署:直接拉取 Docker Hub 镜像
247
+
248
+ 公开仓库:[fxz26284407/yuanma-relay](https://hub.docker.com/r/fxz26284407/yuanma-relay)。普通部署不再需要在 Mac 打包源码、上传发布目录或在服务器构建镜像;宿主机只需 Docker,不需要安装 Node、Codex 或网关依赖。
249
+
250
+ | 标签 | 说明 |
251
+ | --- | --- |
252
+ | `2026.11.03` | 本次发布的固定版本,推荐部署使用 |
253
+ | `latest` | 最新版本,后续可能变化 |
254
+
255
+ 两个标签均包含 `linux/amd64`、`linux/arm64`,Docker 自动选择宿主机架构。
256
+
257
+ ### 启动与端口
258
+
259
+ 先确认宿主机 `19088` 未被占用,再执行:
260
+
261
+ ```sh
262
+ docker pull fxz26284407/yuanma-relay:2026.11.03
263
+
264
+ docker run -d --name yuanma-relay \
265
+ --restart unless-stopped --init \
266
+ -p 19088:8080 \
267
+ --read-only --tmpfs /tmp:rw,noexec,nosuid,size=16m \
268
+ --cap-drop ALL --security-opt no-new-privileges:true \
269
+ --memory 128m --cpus 0.5 --pids-limit 64 \
270
+ --log-opt max-size=5m --log-opt max-file=3 \
271
+ fxz26284407/yuanma-relay:2026.11.03
272
+ ```
273
+
274
+ `19088:8080` 表示 **宿主机 19088 → 容器 8080**。如需换端口,只改左边并同步修改穿透回源端口。无需给 relay 挂载工作目录、数据库、网关配置或 Mac 私钥。镜像自带 Node 运行时,内部不含 Nginx。
275
+
276
+ ```sh
277
+ curl --max-time 5 -fsS http://127.0.0.1:19088/health
278
+ docker inspect yuanma-relay --format '{{.State.Status}} / {{.State.Health.Status}}'
279
+ docker logs --tail 30 yuanma-relay
280
+ ```
281
+
282
+ 健康接口应返回 `{"ok":true}`;启动后短暂的 `starting` 会在健康检查完成后转为 `healthy`。重启已有容器可执行 `docker restart yuanma-relay`。仅拉取新镜像不会自动替换运行中的容器,升级时按原部署方式重建并保留端口和资源配置;已有 relay 占用端口时不要重复启动。
283
+
284
+ ### 花生壳 HTTPS / WSS
285
+
286
+ 花生壳客户端需上线,并能访问宿主机发布的 relay 端口:
287
+
288
+ ```text
289
+ 手机 / Mac 网关
290
+ → wss://你的花生壳域名:443
291
+ → 花生壳 HTTPS 入口(TLS 与证书)
292
+ → 花生壳客户端
293
+ → 宿主机可达地址:19088
294
+ → relay 容器 8080(HTTP/WS)
295
+ ```
296
+
297
+ | 花生壳配置项 | 填写方式 |
298
+ | --- | --- |
299
+ | 映射协议 | HTTPS |
300
+ | 外网域名 | 花生壳分配或绑定的实际域名 |
301
+ | 外网端口 | 默认 443,或产品实际提供的 HTTPS 外网端口 |
302
+ | 内网主机 | 从花生壳客户端所在环境可达的宿主机地址 |
303
+ | 内网端口 | 19088 |
304
+ | 回源协议(如有此选项) | HTTP,relay 内部不提供 TLS |
305
+
306
+ **公网 HTTPS 不等于内网也要 HTTPS。** 花生壳负责证书和 TLS,relay 继续用 HTTP/WS。外层入口需要支持 WebSocket 升级;若有单独的 WebSocket 开关,应开启。容器内加 Nginx 无法替代外层的 WS 支持。
307
+
308
+ “内网主机”按花生壳实际运行位置选择:
309
+
310
+ - 花生壳直接运行在 relay 宿主机上:可以使用 `127.0.0.1:19088`。
311
+ - 花生壳在 Docker 容器里:`127.0.0.1` 是花生壳容器自身,应改为可达的宿主机地址。
312
+ - Mac Docker Desktop 可查询 `host.docker.internal`;本次环境解析为 `192.168.65.254`,已核对从花生壳容器能访问 `192.168.65.254:19088`。该 IP 不是所有机器的固定值。
313
+ - Linux 或其他环境使用从花生壳客户端可达的宿主机内网 IP,不直接照抄 Mac 示例。
314
+
315
+ 例如花生壳容器名为 `oray`,且内置以下工具:
316
+
317
+ ```sh
318
+ docker exec oray getent hosts host.docker.internal
319
+ docker exec oray wget -qO- -T 5 -t 1 http://192.168.65.254:19088/health
320
+ curl --max-time 10 -fsS https://relay.example.com/health
321
+ ```
322
+
323
+ 容器名、内网 IP 和公网域名均应替换为实际值。两跳健康接口都应返回 `{"ok":true}`,HTTPS 证书应有效。健康检查通过不等于 WebSocket 可用;还需确认 WSS 的 HTTP 101 升级及手机安全登录。
324
+
325
+ 配置完成后,已通过 npm 初始化的 Mac 网关可在任意目录执行:
326
+
327
+ ```sh
328
+ source ~/.nvm/nvm.sh
329
+ nvm use 22
330
+ yuanma-gateway pair --relay-url wss://relay.example.com
331
+ ```
332
+
333
+ 将 `relay.example.com` 换成花生壳实际域名;非 443 外网端口需写入 URL。npm 配对命令会按现有安装启动网关,地址变化时安全重启原实例;已配对手机通过“扫码更新连接地址”沿用原身份登录。使用 HTTPS 穿透时,网关参数写 `wss://`,不能写 `https://`。手机须先升级至上文要求的 WSS 版本。
334
+
335
+ 本机部署依赖 Mac、Docker Desktop 和花生壳持续在线。休眠、退出 Docker 或花生壳离线都会中断连接;中继镜像不会自动配置这些运行条件。
336
+
337
+ ### 公网服务器直连或外部反代
338
+
339
+ 也可在公网服务器运行同一镜像,放行实际端口后使用 `ws://服务器地址:19088`。需要 HTTPS/WSS 域名时,由外部 Nginx 或其他支持 WebSocket 的反代处理 TLS 和升级,再回源 HTTP `19088`;无需修改容器内部域名或证书。
340
+
341
+ ### 常见连接问题
342
+
343
+ | 现象 | 优先核对 |
344
+ | --- | --- |
345
+ | 宿主机健康检查失败 | relay 是否运行、端口映射是否正确或被占用 |
346
+ | 宿主机可达,花生壳容器访问失败 | 是否误用 127.0.0.1、内网 IP 是否从该容器可达 |
347
+ | 内网可达,外网域名失败 | 花生壳是否在线、映射是否保存、回源地址和协议是否正确 |
348
+ | HTTPS 200,但 WSS 失败 | 外层 WebSocket 支持、证书和实际外网端口 |
349
+ | 手机扫码后仍恢复旧连接 | 手机版本是否支持 WSS、二维码是否过期、新地址是否成功登录并保存 |
350
+ | WS 打开后路由立即断开 | Mac 网关是否注册到同一套 relay;“配置了中继”不等于注册成功 |
351
+
352
+ Docker Hub 首页有完整的镜像使用说明。源码构建和 `npm run package:relay` 仍保留给需要自行修改中继的开发者,不作为普通部署的前置步骤。
353
+
354
+ ## 数据与工程约定
355
+
356
+ - `.local/`、真实配置、设备授权、密钥、聊天账本、日志和 `.env` 不提交到 Git。
357
+ - 配置示例只保留占位值。
358
+ - 手机断线后按原消息 ID 核对结果,结果未知时不自动换 ID 重发。
359
+ - 保留项目授权和会话审批边界,中继不开放明文业务 RPC。
360
+ - 不包含项目自有测试用例、临时验收脚本或测试会话数据。
361
+
362
+ 第三方依赖及其许可证见 [NOTICE](NOTICE)。本项目原创代码采用 Apache-2.0。
363
+
364
+ ## 作者与开源许可
365
+
366
+ 原作者:[@fxz26284407](https://github.com/fxz26284407)。
367
+
368
+ **创作不易。二次开发或分发时,请保留原作者署名和原项目链接,并按许可证保留 LICENSE 与 NOTICE。** 也欢迎在你的 README、关于页面或分发说明中介绍项目来源。
369
+
370
+ 本项目原创代码采用 [Apache-2.0](LICENSE)。上述署名倡议不增加 Apache-2.0 之外的授权限制,第三方依赖继续遵循各自许可证。