docs: align app architecture to bridge mainline
This commit is contained in:
Haitao Pan
parent
76d19e3186
commit
68d2a3f4d7
@ -1,79 +1,84 @@
|
||||
# Settings Integration Configuration Model
|
||||
|
||||
This document records the current logical model behind Settings -> Integrations,
|
||||
with the provider catalog aligned to the bridge-only design.
|
||||
Last Updated: 2026-04-13
|
||||
|
||||
本文件记录当前 `Settings -> Integrations` 在主链中的职责边界。
|
||||
|
||||
## Current Rule
|
||||
|
||||
- Settings only manages bridge connection parameters and account sync metadata.
|
||||
- The provider picker is not derived from local endpoint presets.
|
||||
- `xworkmate-bridge` is the only source of truth for the provider catalog.
|
||||
- Settings 只管理 bridge connection 参数与 account sync 元数据
|
||||
- app 不从本地 endpoint preset、旧 module 配置、历史 fallback 恢复 provider catalog
|
||||
- `xworkmate-bridge` 是 provider catalog、gateway capability、routing resolve 的唯一真源
|
||||
|
||||
## Bridge-Only Provider Source Of Truth
|
||||
## Bridge-Owned Source Of Truth
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Settings UI
|
||||
仅管理 Bridge 连接参数
|
||||
与账号同步元数据"] --> G["acp.capabilities"]
|
||||
G --> H["providerCatalog[]
|
||||
singleAgent / multiAgent"]
|
||||
subgraph SETTINGS["Settings surface"]
|
||||
A["SettingsPage / SettingsAccountPanel"]
|
||||
B["bridge connection params<br/>account sync metadata<br/>secure refs"]
|
||||
A --> B
|
||||
end
|
||||
|
||||
H --> I["refreshSingleAgentCapabilitiesRuntimeInternal()"]
|
||||
I --> J["bridgeProviderCatalogInternal
|
||||
App 内唯一 provider 名单源"]
|
||||
I --> K["singleAgentCapabilitiesByProviderInternal
|
||||
App 内唯一 provider 可用性源"]
|
||||
subgraph BRIDGE["Bridge contract"]
|
||||
C["acp.capabilities"]
|
||||
D["xworkmate.routing.resolve"]
|
||||
E["xworkmate.gateway.*"]
|
||||
B --> C
|
||||
end
|
||||
|
||||
G --> L["refreshAcpCapabilitiesRuntimeInternal()"]
|
||||
L --> M["GatewayAcpCapabilities
|
||||
providerCatalog / singleAgent / multiAgent"]
|
||||
M --> N["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"]
|
||||
N --> O["ManagedMountTargetState
|
||||
codex / opencode / claude / gemini / aris / openclaw
|
||||
available / discoveryState"]
|
||||
subgraph APPSTATE["App-side derived state"]
|
||||
F["refreshSingleAgentCapabilitiesRuntimeInternal()"]
|
||||
G["bridgeProviderCatalogInternal"]
|
||||
H["singleAgentCapabilitiesByProviderInternal"]
|
||||
I["refreshAcpCapabilitiesRuntimeInternal()"]
|
||||
J["GatewayAcpCapabilities"]
|
||||
K["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"]
|
||||
L["ManagedMountTargetState"]
|
||||
C --> F --> G
|
||||
F --> H
|
||||
C --> I --> J --> K --> L
|
||||
end
|
||||
|
||||
J --> P["bridgeProviderCatalog
|
||||
= bridgeProviderCatalogInternal"]
|
||||
P --> Q["singleAgentProviderOptions
|
||||
Composer / Thread Picker 唯一数据源"]
|
||||
subgraph UI["Visible affordances"]
|
||||
M["assistant provider picker"]
|
||||
N["available assistant targets"]
|
||||
O["settings gateway connection affordances"]
|
||||
G --> M
|
||||
H --> N
|
||||
L --> O
|
||||
end
|
||||
|
||||
K --> R["availableSingleAgentProviders
|
||||
= bridge 当前可用 provider"]
|
||||
R --> S["visibleAssistantExecutionTargets(...)
|
||||
agent / gateway 是否显示
|
||||
只看 bridge runtime capabilities"]
|
||||
|
||||
O --> T["visible gateway affordances
|
||||
gateway discovery 只看 bridge capabilities"]
|
||||
|
||||
Q --> U["setSingleAgentProvider(providerId)
|
||||
仅写入 thread executionBinding.providerId"]
|
||||
|
||||
U --> V["singleAgentProviderForSession()
|
||||
恢复线程已选 providerId"]
|
||||
|
||||
V --> W["sendSingleAgentMessageDesktopGoTaskFlowInternal()"]
|
||||
W --> X["xworkmate.routing.resolve"]
|
||||
X --> Y["bridge 返回 resolvedExecutionTarget /
|
||||
resolvedProviderId /
|
||||
unavailableCode /
|
||||
unavailableMessage"]
|
||||
|
||||
Y --> Z{"unavailable?"}
|
||||
Z -->|"no"| AA["executeTask(... resolved routing ...)"]
|
||||
Z -->|"yes"| AB["provider unavailable UX
|
||||
直接使用 bridge unavailable message"]
|
||||
subgraph EXEC["Execution"]
|
||||
P["setSingleAgentProvider(providerId)"]
|
||||
Q["singleAgentProviderForSession()"]
|
||||
R["executeTask(...)"]
|
||||
S["resolved provider / unavailable message"]
|
||||
T["provider unavailable UX"]
|
||||
M --> P --> Q --> R
|
||||
R --> D --> S
|
||||
S --> T
|
||||
O --> E
|
||||
end
|
||||
```
|
||||
|
||||
## What Settings Owns
|
||||
|
||||
- bridge host / transport / auth input
|
||||
- account-linked bridge configuration metadata
|
||||
- secure secret references
|
||||
- gateway connection test / connect / disconnect affordance
|
||||
|
||||
## What Settings Does Not Own
|
||||
|
||||
- 独立 provider catalog
|
||||
- 独立 module matrix
|
||||
- app-side gateway preset backfill
|
||||
- 旧 `ai_gateway` / `secrets` / `account` 页面壳
|
||||
|
||||
## Notes
|
||||
|
||||
- Production cloud mode does not use app-side provider sync.
|
||||
- Provider visibility and picker contents come from
|
||||
`acp.capabilities.providerCatalog`.
|
||||
- Auto-provider resolution and unavailable messaging come from
|
||||
`xworkmate.routing.resolve`.
|
||||
- `openclaw` and other mount-target discovery states are also bridge-owned and
|
||||
come from ACP capabilities merged into `ManagedMountTargetState`.
|
||||
- Persisted thread `providerId` restores the user's previous selection, but it
|
||||
does not repopulate the provider catalog.
|
||||
- `providerCatalog` 只负责 assistant provider picker；不会因为线程里保存过 `providerId` 就被 app 反向重建
|
||||
- gateway runtime 可见性来自 bridge capability snapshot 与 `xworkmate.gateway.*` 返回，不来自旧设置页枚举
|
||||
- bridge 若返回额外 capability flag，这些 flag 只属于合同元数据，不会自动生成新的 settings tab 或 module page
|
||||
- production provider / gateway 选择继续由 bridge 拥有，app 只保留消费与展示
|
||||
|
||||
@ -1,197 +1,108 @@
|
||||
# 任务执行链路统一收敛
|
||||
# Task Control Plane Unification
|
||||
|
||||
Last Updated: 2026-04-11
|
||||
Last Updated: 2026-04-13
|
||||
|
||||
## 背景
|
||||
## Background
|
||||
|
||||
当前仓库里已经存在 `GoTaskService`、Go ACP `Router.Resolve`、`Skills.Resolve`、
|
||||
`Memory` 与 `buildResolvedExecutionParams`，说明统一控制面已经具备核心骨架。
|
||||
当前 `xworkmate-app` 的主链已经不是“多模块并列入口”模型，而是：
|
||||
|
||||
但旧设计文档长期把不同实现通道写成并列主链，导致：
|
||||
- shell 只保留 `assistant + settings`
|
||||
- assistant 负责线程、任务、结果与 bridge task/runtime 主链
|
||||
- settings 负责 bridge connection、account sync、integration affordance
|
||||
- app 不再维护本地 provider preset、旧 gateway 直连叙述、模块页矩阵
|
||||
|
||||
- Desktop / Web / Mobile 的现状与目标混在一起
|
||||
- controller 层的历史分流被误认为长期规范
|
||||
- `local / remote / multi-agent` 被描述成 app 侧一级执行路径
|
||||
本文件定义的统一口径是：
|
||||
|
||||
本文件把官方口径统一为：
|
||||
- app 内任务入口统一走 `GoTaskService.executeTask`
|
||||
- bridge capability / routing / gateway runtime 由 `xworkmate-bridge` 提供
|
||||
- app 只消费 bridge 合同，不重建第二套 provider/gateway 真源
|
||||
|
||||
- UI 不变
|
||||
- `GoTaskService.executeTask` 是唯一公开入口
|
||||
- ACP 是统一控制面
|
||||
- `bridge` 是 app 客户端的发现 / 配置 / 连接 / 对话枢纽
|
||||
- app 当前只保留 `agent / gateway` 两条路径
|
||||
- ACP Server list / gateway upstream 由 `xworkmate-bridge` 动态发现与维护
|
||||
- `$INTERNAL_SERVICE_TOKEN` 仅属于 bridge / internal service 注入责任
|
||||
- 账户同步只同步 bridge 相关配置属性与安全引用，不做自动连接
|
||||
## Canonical Mainline
|
||||
|
||||
|
||||
## 目标态
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph APP["App surfaces"]
|
||||
A["Desktop / Web / Mobile UI"]
|
||||
B["sendMessage<br/>Task Envelope"]
|
||||
C["GoTaskService.executeTask<br/>唯一公开入口"]
|
||||
A --> B --> C
|
||||
subgraph APP["xworkmate-app"]
|
||||
A1["AssistantPage"]
|
||||
A2["SettingsPage"]
|
||||
A3["AppControllerDesktop*"]
|
||||
A4["GoTaskService.executeTask"]
|
||||
A5["GatewayAcpClient / ExternalCodeAgentAcpDesktopTransport"]
|
||||
A1 --> A3
|
||||
A2 --> A3
|
||||
A3 --> A4
|
||||
A3 --> A5
|
||||
end
|
||||
|
||||
subgraph ACP["ACP control plane"]
|
||||
D["ACP.session.start / session.message"]
|
||||
E["Router.Resolve"]
|
||||
F["Skills.Resolve"]
|
||||
G["Memory.Inject"]
|
||||
H["buildResolvedExecutionParams"]
|
||||
I{"resolvedExecutionPath"}
|
||||
D --> E --> F --> G --> H --> I
|
||||
subgraph CONTRACT["Bridge-facing contract"]
|
||||
B1["acp.capabilities"]
|
||||
B2["xworkmate.routing.resolve"]
|
||||
B3["session.start / session.message / session.cancel / session.close"]
|
||||
B4["xworkmate.gateway.connect / request / disconnect"]
|
||||
end
|
||||
|
||||
subgraph BRIDGE["xworkmate-bridge"]
|
||||
J["agent route"]
|
||||
K["gateway route"]
|
||||
L["bridge routing hub<br/>dynamic discovery / policy / auth injection"]
|
||||
M["Provider adapters<br/>codex / opencode / claude / gemini"]
|
||||
N["Gateway adapters<br/>openclaw / aris / hosted gateway capability"]
|
||||
J --> L
|
||||
K --> L
|
||||
L --> M
|
||||
L --> N
|
||||
C1["bridge-owned provider catalog"]
|
||||
C2["bridge-owned routing"]
|
||||
C3["bridge-owned gateway runtime"]
|
||||
C4["upstream ACP and gateway adapters"]
|
||||
end
|
||||
|
||||
subgraph RETURN["Return path"]
|
||||
O["stream events / result"]
|
||||
P["Memory.Record"]
|
||||
Q["Update Thread State"]
|
||||
R["UI stream render"]
|
||||
O --> P --> Q --> R
|
||||
D1["stream events / runtime state"]
|
||||
D2["thread/session state update"]
|
||||
D3["assistant render / settings status"]
|
||||
end
|
||||
|
||||
C --> D
|
||||
I -->|"agent"| J
|
||||
I -->|"gateway"| K
|
||||
M --> O
|
||||
N --> O
|
||||
A4 --> B2
|
||||
A4 --> B3
|
||||
A5 --> B1
|
||||
A5 --> B4
|
||||
B1 --> C1
|
||||
B2 --> C2
|
||||
B3 --> C2
|
||||
B4 --> C3
|
||||
C1 --> C4
|
||||
C2 --> C4
|
||||
C3 --> C4
|
||||
C4 --> D1 --> D2 --> D3
|
||||
```
|
||||
|
||||
## Provider 真源
|
||||
## App-Side Truth Sources
|
||||
|
||||
Single-agent provider catalog and availability are owned by
|
||||
`xworkmate-bridge`, not by local endpoint presets inside the app.
|
||||
### Surface Truth
|
||||
|
||||
ACP server addresses and gateway upstreams are also bridge-owned dynamic
|
||||
discovery data. The app must not treat concrete endpoints such as
|
||||
`https://acp-server.svc.plus/*` or `wss://openclaw.svc.plus` as app-side
|
||||
hardcoded truth sources.
|
||||
- `feature_flags.yaml -> UiFeatureManifest / AppCapabilities -> Shell / Registry` 是唯一 surface 事实源
|
||||
- app 不再把 provider topology、gateway backend、旧模块入口写成 shell 级分类
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph INPUT["Config / discovery input"]
|
||||
A["Settings UI<br/>仅管理 bridge 连接参数<br/>与账号同步元数据"]
|
||||
B["acp.capabilities"]
|
||||
C["bridge capability snapshot<br/>providerCatalog / agent / gateway<br/>dynamic upstream discovery"]
|
||||
A --> B --> C
|
||||
end
|
||||
### Provider Truth
|
||||
|
||||
subgraph APPSTATE["App-side truth sources"]
|
||||
D["refreshSingleAgentCapabilitiesRuntimeInternal()"]
|
||||
E["bridgeProviderCatalogInternal<br/>App 内唯一 provider 名单源"]
|
||||
F["singleAgentCapabilitiesByProviderInternal<br/>App 内唯一 provider 可用性源"]
|
||||
G["refreshAcpCapabilitiesRuntimeInternal()"]
|
||||
H["GatewayAcpCapabilities"]
|
||||
I["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"]
|
||||
J["ManagedMountTargetState<br/>gateway capability / discovery state"]
|
||||
C --> D --> E
|
||||
D --> F
|
||||
C --> G --> H --> I --> J
|
||||
end
|
||||
- `acp.capabilities.providerCatalog` 是 assistant provider picker 的唯一上游真源
|
||||
- 持久化在线程上的 `providerId` 只表示用户历史选择，不负责反向生成 catalog
|
||||
- provider unavailable 文案与 resolved provider 都来自 `xworkmate.routing.resolve`
|
||||
|
||||
subgraph UISTATE["UI affordances"]
|
||||
K["bridgeProviderCatalog<br/>Composer / Thread Picker provider source"]
|
||||
L["availableSingleAgentProviders<br/>agent path visibility"]
|
||||
M["visible gateway affordances<br/>只看 bridge capabilities / discovery"]
|
||||
E --> K
|
||||
F --> L
|
||||
J --> M
|
||||
end
|
||||
### Gateway Truth
|
||||
|
||||
subgraph EXEC["Execution resolution"]
|
||||
N["setSingleAgentProvider(providerId)<br/>仅写入 thread executionBinding.providerId"]
|
||||
O["singleAgentProviderForSession()"]
|
||||
P["buildExternalAcpRoutingForSessionInternal()"]
|
||||
Q["xworkmate.routing.resolve"]
|
||||
R["resolvedProviderId / unavailableMessage"]
|
||||
S{"unavailable?"}
|
||||
T["executeTask(... resolved routing ...)"]
|
||||
U["provider unavailable UX<br/>直接使用 bridge unavailable message"]
|
||||
K --> N --> O --> P --> Q --> R --> S
|
||||
S -->|"no"| T
|
||||
S -->|"yes"| U
|
||||
```
|
||||
- gateway runtime 可见性、连接状态、mount target discovery 都由 bridge capability / runtime snapshot 驱动
|
||||
- `xworkmate.gateway.*` 是 gateway runtime 的稳定 app-facing 方法族
|
||||
- app 不再把 production gateway endpoint、fallback endpoint、local preset 当真源
|
||||
|
||||
## 端侧桥接规则
|
||||
## Mainline Rules
|
||||
|
||||
### Desktop App
|
||||
1. Assistant 所有正常任务都先进入 `GoTaskService.executeTask`。
|
||||
2. Settings 只管理 bridge connection 参数、account sync 元数据与 gateway/integration affordance。
|
||||
3. provider catalog、routing resolve、gateway runtime state 都由 bridge 提供。
|
||||
4. bridge 若暴露额外 capability flag 或协作模式，它们属于合同元数据，不自动抬升为 app shell / module taxonomy。
|
||||
5. app 不直接调用 `acp-server.svc.plus/*`、`openclaw.svc.plus` 等 upstream 地址。
|
||||
|
||||
- Desktop App 直接桥接 Go 代码
|
||||
- Desktop 正常执行链路不以“先启动一个本地 HTTP server，再由 Desktop 自己回连”作为目标架构
|
||||
- Desktop 的 `sendMessage -> GoTaskService.executeTask -> ACP` 应理解为进程内或直接桥接语义
|
||||
- Production cloud mode does not call `xworkmate.providers.sync`
|
||||
- Production provider upstreams are bridge-owned, not app-owned
|
||||
- Production ACP server list / gateway upstreams are bridge-owned, not app-owned
|
||||
- `$INTERNAL_SERVICE_TOKEN` 只允许在 bridge / internal service 层使用，app 不持有
|
||||
- 对 app 来说，bridge 是 discovery / config / connect / dialogue 的统一枢纽
|
||||
## Removed From Target
|
||||
|
||||
### Web / Mobile
|
||||
- `TasksPage`、`SkillsPage`、`ModulesPage` 之类独立 surface 叙述
|
||||
- `local / remote / preset / fallback` 作为 app 一级执行路径心智
|
||||
- “app 自己维护 provider matrix，再把 bridge 当可选后端”的旧设计
|
||||
- 通过 alias、compat 分流去保留旧模块入口
|
||||
|
||||
- Web / Mobile UI 连接的是 Go 代码启动出来的 server
|
||||
- Web / Mobile 通过标准 ACP contract 与该 server 通信
|
||||
- 对 Web / Mobile 来说，`/acp` 与 `/acp/rpc` 是稳定的网络协议入口
|
||||
## See Also
|
||||
|
||||
## 协议约束
|
||||
|
||||
### 传输协议
|
||||
|
||||
- app 侧当前不再把 `local / remote` 作为执行路径语义
|
||||
- Desktop 只区分 `agent / gateway` 两条路径，二者都经由 `xworkmate-bridge` 路由
|
||||
- 如果 bridge endpoint 是网络地址，则必须遵守 TLS 要求
|
||||
- loopback / non-TLS 只允许作为底层 adapter / 开发态传输细节，不能重新上升为产品执行路径语义
|
||||
- app 不直接持有 ACP server upstream 或 gateway upstream 的授权头
|
||||
- `Authorization: Bearer $INTERNAL_SERVICE_TOKEN` 属于 bridge / internal service 注入责任
|
||||
|
||||
### ACP contract
|
||||
|
||||
- websocket endpoint 规范路径：`/acp`
|
||||
- RPC endpoint 规范路径：`/acp/rpc`
|
||||
- base URL 派生时必须避免重复拼接 `/acp`
|
||||
- 以上 endpoint contract 主要适用于 Web / Mobile 与外部 ACP server 的通信语义
|
||||
- Desktop 目标态不要求为自身 UI 再额外启动一层本地 HTTP ACP server
|
||||
|
||||
## 收敛原则
|
||||
|
||||
### Current implementation note
|
||||
|
||||
- 当前实现可能仍残留历史分流代码
|
||||
- 这些实现痕迹不再代表规范
|
||||
|
||||
### Target architecture rule
|
||||
|
||||
- 所有正常发送请求都先进入 `GoTaskService.executeTask`
|
||||
- 所有任务都先进入 ACP 控制面，再解析到 executor
|
||||
- Desktop 采用直接桥接 Go 代码的控制面接入方式
|
||||
- Web / Mobile 采用连接 Go server 的控制面接入方式
|
||||
- app 侧一级执行路径只保留 `agent / gateway`
|
||||
- `multi-agent` 是 bridge / gateway 内部能力，不再作为 app 侧一级路径
|
||||
- app 不直接调用 `acp-server.svc.plus/*` 或 `openclaw.svc.plus`
|
||||
- 如果需要补全或变更 ACP / gateway upstream，优先在 `xworkmate-bridge` 仓库实现动态发现能力
|
||||
|
||||
### Compatibility route (removed from target)
|
||||
|
||||
- `openClawTask` 不再属于目标架构
|
||||
- `GatewayRuntime`、`Web relay`、`GatewayAcpClient` 只作为 adapter/executor 能力存在
|
||||
|
||||
## 分阶段方向
|
||||
|
||||
1. 文档口径收敛
|
||||
2. Dart 请求模型统一
|
||||
3. route 决策内收到 `GoTaskService` / ACP
|
||||
4. app 侧 bridge 枢纽与 provider / gateway 适配关系收敛
|
||||
5. `multi-agent` 下沉为 bridge 内部能力，而不是 app 一级路径
|
||||
- [XWorkmate Core Module Inventory](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/xworkmate-core-module-inventory-2026-04-13.md)
|
||||
- [Settings Integration Configuration Model](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/settings-integration-configuration-model.md)
|
||||
- [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
|
||||
|
||||
@ -1,60 +1,56 @@
|
||||
# XWorkmate Bridge Migration
|
||||
|
||||
Last Updated: 2026-04-13
|
||||
|
||||
## Summary
|
||||
|
||||
The ACP Bridge Server implementation was migrated out of `xworkmate-app` into the standalone sibling repository `xworkmate-bridge`.
|
||||
`xworkmate-app` 已不再承载内嵌 Go bridge 实现；bridge runtime、ACP forwarding、gateway runtime 与 upstream routing 的主设计都已经迁移到独立 sibling repo：
|
||||
|
||||
This migration separates the embedded Go bridge/server from the Flutter application repository. The app now depends on the sibling `xworkmate-bridge` repo for the helper/runtime contract instead of carrying an in-repo Go bridge copy.
|
||||
- repo: `/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge`
|
||||
|
||||
## New Repository
|
||||
这个迁移不是兼容壳，而是当前真实的 cross-repo runtime contract。
|
||||
|
||||
- Repository path: `/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge`
|
||||
- Go module: `xworkmate-bridge`
|
||||
- Helper binary output name: `xworkmate-go-core`
|
||||
## Current Repo Split
|
||||
|
||||
## What Moved
|
||||
### xworkmate-app Owns
|
||||
|
||||
The previous `xworkmate-app/go/go_core` implementation was migrated to `xworkmate-bridge`, including:
|
||||
- `assistant + settings` 双端 surface
|
||||
- feature flags、shell、registry、navigation
|
||||
- app controller、本地状态编排、secure storage 消费
|
||||
- bridge contract client：`GoTaskService`、`GatewayAcpClient`、`ExternalCodeAgentAcpDesktopTransport`
|
||||
|
||||
- ACP Bridge HTTP/WebSocket server
|
||||
- ACP stdio entrypoint
|
||||
- internal routing, dispatch, mounts, shared RPC helpers, gateway runtime support, memory, skills, and toolbridge packages
|
||||
- Go tests for ACP routing/contracts and bridge helper behavior
|
||||
- legacy static token auth helper code previously stored under `xworkmate-app/go_service`
|
||||
### xworkmate-bridge Owns
|
||||
|
||||
## What Stayed In xworkmate-app
|
||||
- ACP entrypoints 与 forwarding topology
|
||||
- provider catalog、routing resolve、gateway runtime
|
||||
- upstream ACP adapter / gateway adapter
|
||||
- internal service auth injection 与 bridge-owned routing truth
|
||||
|
||||
The following app-side concerns remain in `xworkmate-app`:
|
||||
## Canonical Cross-Repo Docs
|
||||
|
||||
- Flutter UI and settings pages
|
||||
- ACP Bridge client-side configuration and secure-storage handling
|
||||
- Dart runtime launch/locator logic for the helper binary
|
||||
建议按下面顺序阅读当前主链文档：
|
||||
|
||||
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` expects the helper artifact named `xworkmate-go-core`.
|
||||
`xworkmate-app` 仍然消费名为 `xworkmate-go-core` 的 helper artifact。
|
||||
|
||||
This is the current cross-repo runtime contract for local development flows, not a legacy compatibility shim. The helper is built from `xworkmate-bridge` and consumed by `xworkmate-app` outside the shipped app bundle.
|
||||
这表示：
|
||||
|
||||
## App Repository Changes
|
||||
|
||||
In `xworkmate-app`:
|
||||
|
||||
- `go/go_core` was removed
|
||||
- `scripts/build-go-core.sh` now resolves and builds from sibling repo `xworkmate-bridge`
|
||||
- the script supports both normal workspace layout and worktree layout
|
||||
- release notes references were updated to point at the new repository
|
||||
|
||||
## Validation
|
||||
|
||||
Validated during migration:
|
||||
|
||||
- `cd xworkmate-bridge && go test ./...`
|
||||
- `cd xworkmate-bridge && bash scripts/build-helper.sh`
|
||||
- `cd xworkmate-app && bash scripts/build-go-core.sh`
|
||||
- helper 从 `xworkmate-bridge` 构建
|
||||
- app 负责定位与调用 helper
|
||||
- helper 内部的 bridge/runtime 行为以 bridge repo 为准，不再在 app repo 内保留并列设计文档
|
||||
|
||||
## Operational Note
|
||||
|
||||
For local development and packaging, `xworkmate-bridge` must exist as a sibling repository next to `xworkmate-app`, unless `XWORKMATE_BRIDGE_DIR` is set explicitly.
|
||||
|
||||
At runtime, the app treats bridge-related discovery, provider sync, connection metadata, and ACP conversation forwarding as bridge-owned concerns. Account sync only updates bridge-linked configuration attributes and secure secret references; it does not auto-connect the bridge.
|
||||
- 本地开发默认要求 `xworkmate-app` 与 `xworkmate-bridge` 以 sibling repo 形式存在
|
||||
- 若目录布局不同，可通过 `XWORKMATE_BRIDGE_DIR` 显式指定 bridge 仓库位置
|
||||
- app 端只消费 bridge capability、routing、gateway runtime 合同，不再在本地恢复旧 provider/module 真源
|
||||
|
||||
@ -1,113 +1,115 @@
|
||||
# XWorkmate 整体分层架构
|
||||
# XWorkmate Layered Architecture
|
||||
|
||||
Last Updated: 2026-04-08
|
||||
Last Updated: 2026-04-13
|
||||
|
||||
## 目的
|
||||
## Purpose
|
||||
|
||||
本文件只保留整体分层总览与目录作用，不再把当前兼容旁路写成长期规范。
|
||||
本文件只保留当前 `xworkmate-app <-> xworkmate-bridge` 主链的分层总览。
|
||||
|
||||
统一口径如下：
|
||||
当前仓库已经收敛到：
|
||||
|
||||
- `TaskThread` 是线程控制面
|
||||
- `GoTaskService.executeTask` 是唯一公开执行入口
|
||||
- ACP 是统一控制面
|
||||
- `bridge` 是 app 客户端侧的发现 / 配置 / 连接 / 对话枢纽
|
||||
- 账户同步只同步 bridge 相关配置属性与安全引用，不负责自动连接
|
||||
- 历史旁路与旧的直连叙述不再作为目标架构
|
||||
- 顶层 surface 只有 `assistant`、`settings`
|
||||
- app 只保留消费 bridge 合同所需的 surface、gate、controller、runtime
|
||||
- provider catalog、routing、gateway runtime 能力都由 `xworkmate-bridge` 拥有真源
|
||||
- 已删除独立 `tasks / skills / modules / mcp / claw_hub / secrets / ai_gateway / account` 页面壳与 alias 心智
|
||||
|
||||
## 总览图
|
||||
## Layered View
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph L1["访问与归属层"]
|
||||
A1["Local user / device"]
|
||||
A2["Web user / browser session"]
|
||||
A3["Remote owner realm"]
|
||||
flowchart TD
|
||||
subgraph L1["Surface Visibility"]
|
||||
A1["config/feature_flags.yaml"]
|
||||
A2["UiFeatureManifest / UiFeatureAccess / AppCapabilities"]
|
||||
A3["AppShell / MobileShell / workspace_page_registry.dart"]
|
||||
A4["AssistantPage / SettingsPage"]
|
||||
end
|
||||
|
||||
subgraph L2["多端 UI 层"]
|
||||
B1["Desktop / Mobile / Web UI"]
|
||||
B2["AssistantPage / Settings / Tasks"]
|
||||
subgraph L2["App Orchestration"]
|
||||
B1["AppControllerDesktop*"]
|
||||
B2["SettingsController"]
|
||||
B3["GatewaySessionsController"]
|
||||
B4["GatewayChatController"]
|
||||
B5["GatewayAgentsController"]
|
||||
B6["DerivedTasksController"]
|
||||
B7["SkillsController"]
|
||||
end
|
||||
|
||||
subgraph L3["线程控制面"]
|
||||
C1["TaskThread"]
|
||||
C2["ownerScope"]
|
||||
C3["workspaceBinding"]
|
||||
C4["executionBinding"]
|
||||
C5["contextState"]
|
||||
C6["lifecycleState"]
|
||||
subgraph L3["Bridge Contract"]
|
||||
C1["GoTaskService.executeTask"]
|
||||
C2["GatewayAcpClient"]
|
||||
C3["ExternalCodeAgentAcpDesktopTransport"]
|
||||
C4["acp.capabilities / xworkmate.routing.resolve / session.* / xworkmate.gateway.*"]
|
||||
C5["managed bridge/account sync contract"]
|
||||
end
|
||||
|
||||
subgraph L4["统一任务入口"]
|
||||
D1["AppController*"]
|
||||
D2["GoTaskService.executeTask"]
|
||||
subgraph L4["Bridge And Upstreams"]
|
||||
D1["xworkmate-bridge"]
|
||||
D2["ACP adapters / gateway runtime adapters / upstream services"]
|
||||
end
|
||||
|
||||
subgraph L5["ACP Control Plane"]
|
||||
E1["session.start / session.message"]
|
||||
E2["Router.Resolve"]
|
||||
E3["Skills.Resolve"]
|
||||
E4["Memory.Inject / Record"]
|
||||
E5["buildResolvedExecutionParams"]
|
||||
end
|
||||
|
||||
subgraph L6["Bridge / Executors / Adapters"]
|
||||
F1["agent ACP request"]
|
||||
F2["gateway ACP request"]
|
||||
F3["bridge hub<br/>dynamic discovery / config / connect / dialogue / auth injection"]
|
||||
F4["gateway / provider adapters"]
|
||||
end
|
||||
|
||||
A1 --> B1
|
||||
A2 --> B1
|
||||
A3 --> B1
|
||||
A1 --> A2 --> A3 --> A4
|
||||
A4 --> B1
|
||||
B1 --> B2
|
||||
B2 --> C1
|
||||
C1 --> C2
|
||||
C1 --> C3
|
||||
B1 --> B3
|
||||
B1 --> B4
|
||||
B1 --> B5
|
||||
B1 --> B6
|
||||
B1 --> B7
|
||||
B1 --> C1
|
||||
B1 --> C2
|
||||
B1 --> C3
|
||||
B2 --> C5
|
||||
C1 --> C4
|
||||
C1 --> C5
|
||||
C1 --> C6
|
||||
C1 --> D1
|
||||
D1 --> D2
|
||||
D2 --> E1
|
||||
E1 --> E2
|
||||
E2 --> E3
|
||||
E3 --> E4
|
||||
E4 --> E5
|
||||
E5 --> F1
|
||||
E5 --> F2
|
||||
F1 --> F3
|
||||
F2 --> F3
|
||||
F3 --> F4
|
||||
C2 --> C4
|
||||
C3 --> C4
|
||||
C4 --> D1 --> D2
|
||||
```
|
||||
|
||||
## 核心规则
|
||||
## Layer Responsibilities
|
||||
|
||||
1. UI 不直接决定执行 lane。
|
||||
2. `TaskThread` 承载线程级事实，不由页面局部状态拼装。
|
||||
3. `GoTaskService.executeTask` 是唯一公开任务入口。
|
||||
4. ACP 是统一控制面，负责 routing / skills / memory / resolved execution。
|
||||
5. `bridge` 是 app 侧统一枢纽；gateway/provider 适配能力挂在 bridge 后面，不再把历史直连路径写成长期主链。
|
||||
### 1. Surface Visibility
|
||||
|
||||
## 文档目录
|
||||
- `feature_flags.yaml` 是 surface 可见性的唯一声明源
|
||||
- `UiFeatureManifest / AppCapabilities` 负责把声明变成当前平台允许能力
|
||||
- `AppShell / MobileShell / workspace_page_registry.dart` 只承载已声明且真实存在的 `assistant`、`settings`
|
||||
- 不再允许“manifest 已删但 shell/registry 还留旧入口”的双重真源
|
||||
|
||||
### 目标规范
|
||||
### 2. App Orchestration
|
||||
|
||||
- [任务执行链路统一收敛](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md)
|
||||
- [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
|
||||
- `AssistantPage` 承载当前线程、任务、技能、结果与 bridge 主链交互
|
||||
- `SettingsPage` 承载 bridge connection、account sync、integration affordance
|
||||
- app controller 只做最小本地编排，不再维护独立模块壳、假矩阵、旧 alias 分流
|
||||
- 任务与技能仍可作为 assistant 内部数据面存在，但不再拥有独立页面地位
|
||||
|
||||
### 当前实现观察
|
||||
### 3. Bridge Contract
|
||||
|
||||
- 当前实现观察不再保留独立主设计文档
|
||||
- 如需判断规范，以 [任务执行链路统一收敛](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md) 为准
|
||||
- `GoTaskService.executeTask` 是 app 任务链的统一公开入口
|
||||
- `acp.capabilities` 提供 bridge-owned capability snapshot
|
||||
- `xworkmate.routing.resolve` 返回执行解析结果与 unavailable 信息
|
||||
- `session.*` 承载 ACP 会话流
|
||||
- `xworkmate.gateway.*` 承载 gateway runtime 连接与请求流
|
||||
- 账户同步只同步 bridge 相关配置属性与安全引用，不负责恢复旧模块心智或自动造 catalog
|
||||
|
||||
### 边界与适配器说明
|
||||
### 4. Bridge And Upstreams
|
||||
|
||||
- 适配器边界统一收敛到本文件与主文档，不再保留旧的并列设计稿
|
||||
- `xworkmate-bridge` 是 app 唯一公共集成面
|
||||
- upstream ACP service、gateway runtime、provider adapter 都是 bridge 内部关注点
|
||||
- app 不直接把 upstream URL、provider topology、gateway backend 细节当成自己的 surface taxonomy
|
||||
|
||||
## Canonical Cross-Repo Reading Order
|
||||
|
||||
建议按下面顺序理解当前主链：
|
||||
|
||||
1. [XWorkmate Core Module Inventory](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/xworkmate-core-module-inventory-2026-04-13.md)
|
||||
2. [Task Control Plane Unification](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md)
|
||||
3. [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
|
||||
4. [ADR: Unified Bridge Entry Points](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/adr-unified-bridge-entrypoints.md)
|
||||
|
||||
## Removed From Target
|
||||
|
||||
- 旧的 `openClawTask` 公开语义不再是目标架构的一部分
|
||||
- 不再把“客户端直接围绕旧 gateway 默认值运转”写成长期主设计
|
||||
以下内容都不再作为当前目标架构的一部分：
|
||||
|
||||
- `Tasks / Skills / Modules / MCP / ClawHub / Secrets / AiGateway / Account` 独立 surface
|
||||
- 旧 alias destination 与 dormant registry
|
||||
- app-side provider preset/backfill/fallback 真源
|
||||
- 把 upstream URL、gateway backend 或 provider 拓扑直接暴露成 app 一级模块心智
|
||||
|
||||
Loading…
Reference in New Issue
Block a user