Skip to content

feat(cli): add app server to cli - #2034

Open
zvzuola wants to merge 1 commit into
GCWing:mainfrom
zvzuola:refactor-cli
Open

feat(cli): add app server to cli#2034
zvzuola wants to merge 1 commit into
GCWing:mainfrom
zvzuola:refactor-cli

Conversation

@zvzuola

@zvzuola zvzuola commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #

Type and Areas

Type:

Areas:

Motivation / Impact

Verification

Reviewer Notes

Checklist

  • This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
  • Relevant verification is recorded above, or skipped checks are explained.
  • User-facing strings, docs, and locales are updated where applicable.

@limityan limityan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

总体判断

同意引入 TuiBackend,用统一端口解除 TUI 对 Core/Runtime 具体实现的直接依赖;但不建议把“Embedded 与 Shared 都必须经过 App Server”作为目标架构。当前 PR 实际上只有 Embedded 运行 BitfunAppServer,Shared 仍通过 agent-runtime-ipc v17SharedTuiBackend 只是兼容翻译层。因此本次变更主要获得了源码边界统一,并没有获得新的共享后端能力。

建议调整为以下方向后再合并:

TUI -> TuiBackend
  Embedded -> 进程内强类型 Runtime port
  Shared   -> 现有 Runtime IPC
  Web/外部 Rich Client -> App Server

这里统一的是 TUI 可依赖的行为契约,不要求所有部署模式使用同一 wire protocol。行为一致性应由 adapter contract tests 保证。

主要风险

  1. Shared 功能回退

    当前 Shared IPC 已负责实例发现和 token 校验、session controller lease、single-active-turn、断连取消、outcome_unknown、帧限制及空闲退出。App Server 当前没有这些进程和会话控制语义。Phase 5 如果仅把 Pipe/UDS wire 替换为 App Server,会造成并发控制、异常恢复和生命周期回退;在这些能力有明确 owner、协议和等价测试前,不应替换现有 Shared IPC。

  2. 默认 Embedded 路径增加了缺乏收益证明的复杂度

    Embedded 原本可以通过强类型 port 直接调用同进程 Runtime;当前实现增加专用线程、独立 Tokio runtime、request/response 分派以及 client/server 生命周期,却没有新增跨进程或共享能力,也没有启动时间、延迟或资源开销数据。这同时与 product-architecture.mdagent-runtime-deployment-design.md 中 Embedded 直连、默认 CLI 不承担 App Server 成本的现行约束冲突。

  3. 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 构造,不能由通用协议层写死。

  4. WebSocket 能力面被隐式扩大

    通用 BitfunAppServer 注册 TUI handlers 后,Web Host 也可能暴露 shell、diff、context reload 等本地控制能力。现有 WebSocket 主要依赖 loopback/origin allowlist,缺少完整的连接身份、workspace/user/execution binding。应按 Host 显式注册允许的 handler,并在扩大能力前完成相应威胁模型和认证边界。

  5. 迁移计划不应放在架构文档目录

    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 能力回退。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants