Skip to content

refactor(cli): use direct runtime for embedded TUI - #2297

Closed
limityan wants to merge 1 commit into
GCWing:mainfrom
limityan:yanzhn/embedded-tui-direct-runtime
Closed

limityan wants to merge 1 commit into
GCWing:mainfrom
limityan:yanzhn/embedded-tui-direct-runtime

Conversation

@limityan

@limityan limityan commented Aug 14, 2026 •

Copy link
Copy Markdown
Collaborator

概要

交付 Embedded TUI direct-runtime Phase 5 的实现切换:同进程 CLI 不再启动 AppServer、ACP channel 和第二套 Tokio runtime,而是通过唯一的 CliAgentRuntimeClient 调用 Agent Runtime owner;Shared TUI 继续使用私有 Runtime IPC,Web/远程 AppServer 保持独立 transport 边界。

主要变化:

  • 删除 CLI 的 EmbeddedAppServerHost、AppServerTuiBackend、SharedTuiBackend 与三个 AppServer 直接依赖。
  • 将 Session、Turn、Permission、UserInput、事件和恢复语义统一到 TuiRuntimePort::{Embedded, Shared};管理面按 Model/Registry/MCP/Account/Worktree/Hook/External Source 等真实 owner 注入,不新增总括式 management port。
  • 补齐 Remote workspace identity、OutcomeUnknown、processing restore、Pending UserInput ready/resolved、late attach、同 tool id 多 registration 和事件因果顺序等 fail-closed 合同。
  • 删除无生产消费者的 AppServer management service;保留协议方法并返回结构化 unsupported。
  • 完成 AppServer v4 connection negotiation、事件预订阅、permission snapshot/watermark、Web typed notification 和 reconnect resync;Web Host 使用实际 256 KiB frame limit,Web client 按协商字节限制在发送前拒绝超大请求。
  • 更新既有边界规则、架构文档与跨端投影;未新增 crate、transport 或 CI job,并在现有 Frontend Build job 中补入 Mobile Web tests。

这里的“Phase 5 已交付”指实现路径已经切换并删除旧 CLI AppServer detour;统一 Direct/Shared 行为 fixture、启动/延迟/内存基准与跨版本升级证据仍是后续验收项,不在本 PR 中虚报完成。

架构与兼容性

合同 变更 影响与兼容策略
Agent Runtime SDK v6 → v7 新增 context reload 与 Pending UserInput 恢复合同;外部 Rust embedder 需按 v7 facade 迁移。
Shared Runtime IPC v17 → v18 restore 返回 Pending UserInput 与事件 watermark;旧 Host/client 在握手阶段 fail closed。
AppServer protocol v3/min v2 → v4/min v4 新 ToolEvent/restore 合同要求客户端同步升级;连接先完成 app/initialize,不兼容连接结构化拒绝且不进入业务/事件通道。
Remote Connect additive capability initial_sync 与 workspace_info 广告 answer_question_identity_v1;新客户端对旧 Host 本地阻断,旧客户端对新 Host 获得 upgrade_required 错误与恢复提示;禁止退回仅按 tool_id 路由。

Embedded 与 Shared 共享 Runtime owner 行为,但不共享 transport 生命周期。Web AppServer 没有被改造成 CLI 内部总线,也没有引入第二套 Runtime owner。

对抗性复审中修复的问题

  • AppServer v4:业务/事件在 initialize 前可能外泄、拒绝响应可能未 flush、initialize 与事件订阅存在窗口、重复 initialize 可造成状态分裂。
  • Permission sync:snapshot 与 watermark 非原子、缺 owner 时错误地返回空成功;现在为 connection-local 有序、按 request_id at-least-once 去重并 fail closed。
  • Web:曾使用虚构前端事件且 reconnect 未重新协商;现在消费真实 typed notifications,每个 generation 都执行 initialize → sync → business gate。Permission stream lag 通过权威 snapshot 恢复;agent snapshot 不可恢复时关闭连接并明确要求整页 reload,不留下无 consumer 的永久 gate。
  • Remote:同 tool id 的多个注册会互相覆盖,rolling upgrade 会误路由;现在以完整 registration identity 跟踪,UserInputResolved 精确终结对应 registration,并通过 additive capability 安全升级。
  • Shared MCP:controller 曾启动第二套本机 MCP service 并管理错误 owner;现在只有 Shared Runtime Host 启动 MCP,Shared TUI 管理返回带重启路径的 typed unsupported。
  • CLI/IPC:Create/Fork 在副作用完成后丢响应或绑定失败会被当普通可重试错误;现在统一为 typed OutcomeUnknown,9 MiB fork 响应测试证明不允许同连接重放。

依赖闭包

统计口径:bitfun-cli --no-default-features 的 normal + build 依赖,按 name@version 规范化去重;基线为本 PR 的 main 父提交。

Target Before After Delta
Windows x86_64 641 628 -13
Linux x86_64 663 650 -13
macOS arm64 640 627 -13
  • Cargo.lock package 数:1159 → 1159。
  • 无新增、删除、升级或降级 Cargo package;仅从既有 package records 删除 7 条直接 dependency edge。
  • pnpm-lock.yaml 只为 Mobile Web 测试 importer 复用仓库已有 Vitest resolution,没有新增解析 package。
  • 未宣称 wall-clock、启动时延或内存收益。

验证

  • pnpm run check:core-boundaries
  • pnpm run check:repo-hygiene
  • pnpm run check:github-config:14/14
  • cargo metadata --locked --offline --no-deps --format-version 1
  • Web AppServer/Dispatch/reload focused:77/77;pnpm run type-check:web;pnpm run i18n:audit
  • AppServer:13 lib + 24 agent_kernel + 3 round-trip + 1 doctest
  • Runtime IPC:68/68
  • CLI Runtime client:34/34;cargo check -p bitfun-cli --bin bitfun --no-default-features
  • Remote Connect contracts:66/66;Core remote answer path:1/1
  • Mobile Web Remote manager:4/4;type-check 与 production build
  • cargo check -p bitfun-server --bin bitfun-server
  • pnpm run harmony:architecture
  • 最终三路独立对抗复审:基于 exact tree 39dd824e,架构、行为、范围/CI 三路均无 P0–P3;最终闭合了 Remote settled identity 与 Harmony 同 tool id 多 registration 的终态合并交错。

验证边界

  • 本机 DevEco/Hvigor 仅支持 model 6.1.0,仓库目标为 6.1.1,因此未运行 HarmonyOS LocalTest;仓库当前也没有 HarmonyOS CI job。本 PR 只把 pnpm run harmony:architecture 作为已通过证据,不宣称平台编译已验证。
  • 统一 Direct/Shared 行为 fixture、端到端跨版本升级矩阵,以及启动/延迟/内存 wall-clock 尚未交付;现有证据是 owner-focused 与 deployment-specific 行为测试。
  • .github/workflows/ci.yml 仅在既有 Frontend Build job 增加 pnpm --dir src/mobile-web test,没有新增 job;docs/superpowers/** 无改动。

@limityan
limityan force-pushed the yanzhn/embedded-tui-direct-runtime branch 3 times, most recently from 6289bf3 to 53eabca Compare August 14, 2026 22:14
Replace the in-process App Server detour with owner-scoped direct and shared runtime adapters, preserve typed restore and side-effect contracts, and remove obsolete management wiring.
@limityan
limityan force-pushed the yanzhn/embedded-tui-direct-runtime branch from 53eabca to 19e8996 Compare August 15, 2026 01:39
@limityan limityan closed this Aug 15, 2026
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.

1 participant