feat(cli): add app server to cli - #2034
Conversation
limityan
left a comment
There was a problem hiding this comment.
总体判断
同意引入 TuiBackend,用统一端口解除 TUI 对 Core/Runtime 具体实现的直接依赖;但不建议把“Embedded 与 Shared 都必须经过 App Server”作为目标架构。当前 PR 实际上只有 Embedded 运行 BitfunAppServer,Shared 仍通过 agent-runtime-ipc v17,SharedTuiBackend 只是兼容翻译层。因此本次变更主要获得了源码边界统一,并没有获得新的共享后端能力。
建议调整为以下方向后再合并:
TUI -> TuiBackend
Embedded -> 进程内强类型 Runtime port
Shared -> 现有 Runtime IPC
Web/外部 Rich Client -> App Server
这里统一的是 TUI 可依赖的行为契约,不要求所有部署模式使用同一 wire protocol。行为一致性应由 adapter contract tests 保证。
主要风险
-
Shared 功能回退
当前 Shared IPC 已负责实例发现和 token 校验、session controller lease、single-active-turn、断连取消、
outcome_unknown、帧限制及空闲退出。App Server 当前没有这些进程和会话控制语义。Phase 5 如果仅把 Pipe/UDS wire 替换为 App Server,会造成并发控制、异常恢复和生命周期回退;在这些能力有明确 owner、协议和等价测试前,不应替换现有 Shared IPC。 -
默认 Embedded 路径增加了缺乏收益证明的复杂度
Embedded 原本可以通过强类型 port 直接调用同进程 Runtime;当前实现增加专用线程、独立 Tokio runtime、request/response 分派以及 client/server 生命周期,却没有新增跨进程或共享能力,也没有启动时间、延迟或资源开销数据。这同时与
product-architecture.md和agent-runtime-deployment-design.md中 Embedded 直连、默认 CLI 不承担 App Server 成本的现行约束冲突。 -
capability 与 transport limits 不是 Host 的真实能力
App Server/Shared adapter 宣称约 16 MiB,但 Shared IPC 实际为 128 KiB 请求、8 MiB 响应,WebSocket Host 实际约 256 KiB;Server Host 未注入
context_reload时仍会宣称相关方法可用。客户端会据此作出错误决策。capability、限制及 unsupported reason 应由具体 Host/transport 构造,不能由通用协议层写死。 -
WebSocket 能力面被隐式扩大
通用
BitfunAppServer注册 TUI handlers 后,Web Host 也可能暴露 shell、diff、context reload 等本地控制能力。现有 WebSocket 主要依赖 loopback/origin allowlist,缺少完整的连接身份、workspace/user/execution binding。应按 Host 显式注册允许的 handler,并在扩大能力前完成相应威胁模型和认证边界。 -
迁移计划不应放在架构文档目录
docs/architecture/tui-app-server-decoupling-refactor-plan.md记录的是阶段性计划、未完成 Phase 和迁移差距,不是当前稳定架构。放在docs/architecture会与权威现状文档并列,并且当前内容已经与部署设计产生冲突。请移到现有的docs/plans/tui-app-server-decoupling-refactor-plan.md;如果方案仍待决策,也可以先保留在 Issue/PR 描述中。稳定决策和已交付运行链路再同步到权威架构文档。
建议修改
- 保留
TuiBackend,新增/恢复直接调用 Runtime port 的 Embedded adapter;不要让 TUI 绕过该抽象。 - Shared 继续使用现有 IPC adapter;不要在本 PR 中承诺迁移到 App Server wire。
AppServerTuiBackend只用于已有明确需求的 Web/外部 Rich Client;后续有真实消费者时再扩展协议。- 为 Embedded、Shared、App Server adapters 建立同一组核心 session/turn 行为契约测试,而不是通过强制同一 transport 获得一致性。
- 将 capability、限制、handler 注册和安全策略下放给 Host,并补齐 Shared 语义后再单独评审物理协议迁移。
- 移动 plan 文档,并同步修正与现行架构文档冲突的目标描述。
- 修复当前 Frontend Build 的
ConfigUpdate生成类型失败,并在 PR 描述中补充架构影响、验证结果和迁移边界。
这个方向仍能保留本 PR 最有价值的 TUI 解耦,同时避免默认 CLI 的额外协议成本、双协议长期并存,以及未来 Shared 能力回退。
Summary
Fixes #
Type and Areas
Type:
Areas:
Motivation / Impact
Verification
Reviewer Notes
Checklist