xworkmate-app/docs/feature/2026-04-11-go-acp-stdio-bridge-local-cli-discovery.md

GoAcpStdioBridge 本地 CLI 发现能力规划

日期：2026-04-11

当前定位

GoAcpStdioBridge 在当前版本中不再作为桌面端主运行链路的活跃依赖。现行 assistant / gateway / ACP 调度主路径统一走 agent / gateway 双路径语义，并由 xworkmate-bridge 统一路由；不再从线程恢复、页面默认值、启动流程或运行时路由中复活 127.0.0.1:18789 本地 Go core 路径。

当前仓库只保留这份规划文档，不再保留对应实现文件。

本文件将 GoAcpStdioBridge 的后续用途重新定义为：

• 未来可选的“本地 CLI 发现”能力预留；
• 非当前默认执行路径；
• 非隐式兼容兜底；
• 非启动即自动连接能力。

问题边界

本地 stdio bridge 在历史实现中承担了过多职责：

• 本地 Go core 会话桥接；
• ACP 请求转发；
• 本地 gateway 路径复活；
• 线程/页面/设置中的 local 目标含义承载。

这会让当前 bridge-first 架构继续被旧的本地路径牵制，也会让遗留的 local 状态穿透到当前执行决策中。

未来特性目标

未来如果重新启用 GoAcpStdioBridge，目标应当限定为“显式触发的本地 CLI 发现与接入”：

• 用户主动触发，而不是应用启动自动探测。
• 发现本机可用 CLI / agent runtime，而不是假定固定 127.0.0.1:18789。
• 作为单独能力面挂接到桌面端，不反向污染 remote bridge 主链路。
• 发现结果需要明确展示来源、权限边界、工作目录范围和失败状态。

明确非目标

未来版本在没有单独设计与实现前，不应恢复以下行为：

• 用 GoAcpStdioBridge 作为当前桌面 runtime 会话主桥。
• 在页面默认值、线程恢复、settings sanitize 中恢复 local -> 127.0.0.1:18789。
• 将 local 模式作为 remote bridge 的隐式 fallback。
• 把“也许用户本机还在跑旧服务”当作兼容保留理由。

建议设计约束

如果后续立项，本能力应满足：

1. 明确入口 只允许从显式 UI 操作或显式命令入口触发，不允许启动自动恢复。

2. 单独状态面 使用独立 discovery/session 状态，不复用当前 remote bridge 主链路状态。

3. 零默认地址 不内置 127.0.0.1:18789 作为默认真值来源；地址只能来自显式发现结果或用户确认。

4. 最小权限 工作目录、附件、凭据、CLI 调用都必须延续当前安全规则中的显式授权原则。

5. 可移除 本地 CLI 发现能力必须作为独立 closure / adapter 落地，避免再次进入当前 remote orchestration 主流程。

落地前置条件

后续真正实现前，至少需要补齐：

• 单独的 feature design / ADR；
• UI 入口与状态模型；
• 安全评审：本地进程启动、路径发现、凭据与工作目录边界；
• 回归用例：显式发现、显式连接、显式断开、无自动复活。

本次清理结论

当前阶段的结论是：

• 删除 GoAcpStdioBridge 及其旧本地 session bridge 实现文件；
• 清理它在当前桌面主链路中的活跃依赖；
• 只在 docs/feature/ 中保留未来能力规划；
• 保持 UI 主体不变，但当前执行路径继续以 remote / bridge 为唯一网关主路径。