From 68d2a3f4d72087fe4182fe48fec492e8c8d86157 Mon Sep 17 00:00:00 2001 From: Haitao Pan Date: Mon, 13 Apr 2026 15:28:15 +0800 Subject: [PATCH] docs: align app architecture to bridge mainline --- ...ettings-integration-configuration-model.md | 129 +++++----- .../task-control-plane-unification.md | 237 ++++++------------ .../xworkmate-bridge-migration.md | 74 +++--- .../xworkmate-layered-architecture.md | 166 ++++++------ 4 files changed, 260 insertions(+), 346 deletions(-) diff --git a/docs/architecture/settings-integration-configuration-model.md b/docs/architecture/settings-integration-configuration-model.md index b7aa4659..8fff4fc5 100644 --- a/docs/architecture/settings-integration-configuration-model.md +++ b/docs/architecture/settings-integration-configuration-model.md @@ -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
account sync metadata
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 只保留消费与展示 diff --git a/docs/architecture/task-control-plane-unification.md b/docs/architecture/task-control-plane-unification.md index 2c0aaa56..0d458bab 100644 --- a/docs/architecture/task-control-plane-unification.md +++ b/docs/architecture/task-control-plane-unification.md @@ -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
Task Envelope"] - C["GoTaskService.executeTask
唯一公开入口"] - 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
dynamic discovery / policy / auth injection"] - M["Provider adapters
codex / opencode / claude / gemini"] - N["Gateway adapters
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
仅管理 bridge 连接参数
与账号同步元数据"] - B["acp.capabilities"] - C["bridge capability snapshot
providerCatalog / agent / gateway
dynamic upstream discovery"] - A --> B --> C - end +### Provider Truth - subgraph APPSTATE["App-side truth sources"] - D["refreshSingleAgentCapabilitiesRuntimeInternal()"] - E["bridgeProviderCatalogInternal
App 内唯一 provider 名单源"] - F["singleAgentCapabilitiesByProviderInternal
App 内唯一 provider 可用性源"] - G["refreshAcpCapabilitiesRuntimeInternal()"] - H["GatewayAcpCapabilities"] - I["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"] - J["ManagedMountTargetState
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
Composer / Thread Picker provider source"] - L["availableSingleAgentProviders
agent path visibility"] - M["visible gateway affordances
只看 bridge capabilities / discovery"] - E --> K - F --> L - J --> M - end +### Gateway Truth - subgraph EXEC["Execution resolution"] - N["setSingleAgentProvider(providerId)
仅写入 thread executionBinding.providerId"] - O["singleAgentProviderForSession()"] - P["buildExternalAcpRoutingForSessionInternal()"] - Q["xworkmate.routing.resolve"] - R["resolvedProviderId / unavailableMessage"] - S{"unavailable?"} - T["executeTask(... resolved routing ...)"] - U["provider unavailable UX
直接使用 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) diff --git a/docs/architecture/xworkmate-bridge-migration.md b/docs/architecture/xworkmate-bridge-migration.md index 53859776..8ba2b9f1 100644 --- a/docs/architecture/xworkmate-bridge-migration.md +++ b/docs/architecture/xworkmate-bridge-migration.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 真源 diff --git a/docs/architecture/xworkmate-layered-architecture.md b/docs/architecture/xworkmate-layered-architecture.md index f528c942..0d79d6c8 100644 --- a/docs/architecture/xworkmate-layered-architecture.md +++ b/docs/architecture/xworkmate-layered-architecture.md @@ -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
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 一级模块心智