63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# XWorkmate Bridge Migration
|
||
|
||
Last Updated: 2026-04-13
|
||
|
||
## Summary
|
||
|
||
`xworkmate-app` 已不再承载内嵌 Go bridge 实现；bridge runtime、ACP forwarding、gateway runtime 与 upstream routing 的主设计都已经迁移到独立 sibling repo：
|
||
|
||
- repo: `/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge`
|
||
|
||
这个迁移不是兼容壳，而是当前真实的 cross-repo runtime contract。
|
||
|
||
## Current Repo Split
|
||
|
||
### xworkmate-app Owns
|
||
|
||
- `assistant + settings` 双端 surface
|
||
- feature flags、shell、registry、navigation
|
||
- app controller、本地状态编排、secure storage 消费
|
||
- bridge contract client：`GoTaskService`、`GatewayAcpClient`、`ExternalCodeAgentAcpDesktopTransport`
|
||
|
||
### xworkmate-bridge Owns
|
||
|
||
- ACP entrypoints 与 forwarding topology
|
||
- provider catalog、routing resolve、gateway runtime
|
||
- upstream ACP adapter / gateway adapter
|
||
- internal service auth injection 与 bridge-owned routing truth
|
||
|
||
## Canonical Cross-Repo Docs
|
||
|
||
建议按下面顺序阅读当前主链文档：
|
||
|
||
1. app surface inventory
|
||
- [XWorkmate Core Module Inventory](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/xworkmate-core-module-inventory-2026-04-13.md)
|
||
2. app control-plane view
|
||
- [Task Control Plane Unification](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md)
|
||
3. bridge forwarding view
|
||
- [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
|
||
4. bridge entrypoint ADR
|
||
- [ADR: Unified Bridge Entry Points](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/adr-unified-bridge-entrypoints.md)
|
||
|
||
## Build Contract
|
||
|
||
`xworkmate-app` 不再构建、嵌入或启动本地 ACP bridge helper。
|
||
|
||
这表示：
|
||
|
||
- macOS 打包不再从 `xworkmate-bridge` sibling repo 构建 `xworkmate-go-core`
|
||
- app bundle 不再携带 `xworkmate-go-core` 或本地 ACP bridge 启动脚本
|
||
- app 端只消费托管 `xworkmate-bridge` capability、routing、gateway runtime 合同
|
||
|
||
## Operational Note
|
||
|
||
- 本地开发默认要求 `xworkmate-app` 与 `xworkmate-bridge` 以 sibling repo 形式存在
|
||
- 若目录布局不同，可通过 `XWORKMATE_BRIDGE_DIR` 显式指定 bridge 仓库位置
|
||
- app 端只消费 bridge capability、routing、gateway runtime 合同，不再在本地恢复旧 provider/module 真源
|
||
|
||
## Communication Protocol
|
||
|
||
- **Standard**: 全面转向 **JSON-RPC 2.0** 作为 APP 与 Bridge 之间的默认通信协议。
|
||
- **Client Implementation**: `GatewayAcpClient` 与 `GatewayRuntime` 已完成健壮性升级，支持自动识别 JSON-RPC 2.0 报文。
|
||
- **Compatibility**: 当前处于混合过渡期，Bridge 响应报文会同时包含 JSON-RPC 2.0 字段（`result`/`error`）与 Legacy 字段（`ok`/`type`/`payload`），确保旧版逻辑不会崩溃。
|