xworkmate-app/docs/architecture/task-control-plane-unification.md

# Task Control Plane Unification

Last Updated: 2026-04-14

## Background

当前 `xworkmate-app` 的主链已经不是“多模块并列入口”模型，而是：

- shell 只保留 `assistant + settings`
- assistant 负责线程、任务、结果与 bridge task/runtime 主链
- settings 负责 bridge connection、account sync、integration affordance
- app 不再维护本地 provider preset、旧 gateway 直连叙述、模块页矩阵

本文件定义的统一口径是：

- app 内任务入口统一走 `GoTaskService.executeTask`
- bridge capability / routing / gateway runtime 由 `xworkmate-bridge` 提供
- app 只消费 bridge 合同，不重建第二套 provider/gateway 真源

## Canonical Mainline

```mermaid
flowchart TD
    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 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"]
        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"]
        D1["stream events / runtime state"]
        D2["thread/session state update"]
        D3["assistant render / settings status"]
    end

    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
```

## App-Side Truth Sources

### Surface Truth

- `feature_flags.yaml -> UiFeatureManifest / AppCapabilities -> Shell / Registry` 是唯一 surface 事实源
- app 不再把 provider topology、gateway backend、旧模块入口写成 shell 级分类

### Provider Truth

- `acp.capabilities` 是任务对话模式与 provider picker 的唯一上游真源
- 持久化在线程上的 `providerId` 只表示用户历史选择，不负责反向生成 catalog
- provider unavailable 文案与 resolved provider 都来自 `xworkmate.routing.resolve`
- bridge 返回 `availableExecutionTargets` 与 target-scoped provider catalog；app 只做目标切换与展示，不做静态拆分或 canonical 单项硬编码
- app 侧任务对话框 provider 选择主链固定为：
  - `providerCatalogForExecutionTarget(...)`
  - `resolveProviderForExecutionTarget(...)`
  - `setAssistantProvider(...)`
- `agent` catalog 只消费 bridge 广告的 ACP server bridges
- `gateway` catalog 只消费 bridge 返回的 gateway provider 列表；当前为 `openclaw`，未来可扩展 `hermes` 等项
- app 只负责：
  - 展示 `agent` / `gateway` 目标切换
  - 请求 bridge contract
  - 按 bridge 返回结果渲染 provider 菜单与默认项
- 这里不保留旧的 provider matrix、preset fallback 或双真源选择路径

### Gateway Truth

- 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

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 不直接调用 `xworkmate-bridge.svc.plus/*`、`openclaw.svc.plus` 等 upstream 地址。

## Removed From Target

- `TasksPage`、`SkillsPage`、`ModulesPage` 之类独立 surface 叙述
- `local / remote / preset / fallback` 作为 app 一级执行路径心智
- “app 自己维护 provider matrix，再把 bridge 当可选后端”的旧设计
- 通过 alias、compat 分流去保留旧模块入口

## See Also

- [Task Dialog Provider Selection Mainline](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-dialog-provider-selection-mainline.md)
- [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)