120 lines
3.2 KiB
Markdown
120 lines
3.2 KiB
Markdown
# 外部 ACP Endpoint 预配置脚本
|
||
|
||
这个工具是一个**外置 pre 动作**：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart
|
||
```
|
||
|
||
它只负责生成或更新 XWorkmate `settings.yaml` 里的 `externalAcpEndpoints`。
|
||
|
||
它**不**做这些事：
|
||
|
||
- 不修改 Flutter runtime 代码
|
||
- 不往 `.app` bundle、DMG 或打包脚本写任何内容
|
||
- 不启动任何外部 provider、bridge、daemon 或 CLI
|
||
- 不写入 token、password、API key 等 secrets
|
||
|
||
## App Store 对齐边界
|
||
|
||
当前脚本按 App Store 边界收敛为“纯配置助手”：
|
||
|
||
- 脚本在 app 外运行
|
||
- 只写用户态配置文件
|
||
- 不再内置或推荐任何第三方 bridge 依赖
|
||
- Claude / Gemini 在这里只是 endpoint 槽位，不绑定特定实现
|
||
|
||
如果某个 provider 以后要接入，要求是：
|
||
|
||
- 由你自行准备一个兼容的外部 endpoint
|
||
- XWorkmate 只消费 endpoint，不负责拉起依赖
|
||
|
||
## 默认 provider 槽位
|
||
|
||
| Provider | 默认 endpoint |
|
||
| --- | --- |
|
||
| Codex | `ws://127.0.0.1:9001` |
|
||
| OpenCode | `http://127.0.0.1:4096` |
|
||
| Claude | `ws://127.0.0.1:9011` |
|
||
| Gemini | `ws://127.0.0.1:9012` |
|
||
|
||
说明：
|
||
|
||
- 这些值只是默认槽位，不代表脚本会安装或启动任何 provider。
|
||
- `Codex` / `OpenCode` 的本地地址被保留为示例默认值。
|
||
- `Claude` / `Gemini` 仅保留 endpoint 占位，不再绑定第三方桥接包说明。
|
||
|
||
## macOS 路径策略
|
||
|
||
macOS 默认增加了 App Sandbox 感知：
|
||
|
||
- `--settings-scope auto`
|
||
优先写 `~/Library/Containers/plus.svc.xworkmate/Data/Library/Application Support/xworkmate/config/settings.yaml`
|
||
如果容器目录还不存在，再退回 `~/Library/Application Support/xworkmate/config/settings.yaml`
|
||
- `--settings-scope sandbox`
|
||
强制写 App Sandbox 容器路径
|
||
- `--settings-scope user`
|
||
强制写非沙盒用户目录路径
|
||
|
||
这让脚本既能服务 Mac App Store 安装版，也保留非沙盒构建的旧路径。
|
||
|
||
## 前置条件
|
||
|
||
- 在仓库根目录执行
|
||
- 首次在新 clone 上使用前，先跑一次 `flutter pub get`
|
||
|
||
## 常用命令
|
||
|
||
查看将使用哪个配置文件，以及要写入哪些 endpoint：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart print
|
||
```
|
||
|
||
按自动路径策略写入：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart apply
|
||
```
|
||
|
||
强制写入 Mac App Store 容器路径：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart apply --settings-scope sandbox
|
||
```
|
||
|
||
强制写入旧的用户目录路径：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart apply --settings-scope user
|
||
```
|
||
|
||
指定自定义 endpoint：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart apply \
|
||
--codex-endpoint ws://127.0.0.1:9001 \
|
||
--opencode-endpoint http://127.0.0.1:4096 \
|
||
--claude-endpoint ws://127.0.0.1:19111 \
|
||
--gemini-endpoint ws://127.0.0.1:19112
|
||
```
|
||
|
||
只打印结果 YAML，不落盘：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart apply --dry-run
|
||
```
|
||
|
||
禁用某个槽位：
|
||
|
||
```bash
|
||
dart tool/configure_external_acp.dart apply --disable-claude
|
||
```
|
||
|
||
## 兼容性边界
|
||
|
||
- 这个脚本只负责 `externalAcpEndpoints`
|
||
- 它会保留非内置 custom provider 条目
|
||
- 它不会判断某个 endpoint 背后是否真的可用
|
||
- 它不会绕过 XWorkmate 在 App Store 构建里对外部 CLI / 本地 runtime 的禁用策略
|