第 10 章:事件查看器和 Ink TUI——UI 只是事件投影
这一章不再讨论 runtime 怎样执行工具,而是讨论客户端怎样观察 runtime。
项目里有两个现成的客户端:
- Rust 写的
events事件查看器:最小、可脚本化,用来观察事件流; ui/下的 TypeScript Ink TUI:面向真实使用,支持多轮对话和审批。
它们共享同一个 mini-harness serve --stdio 后端,走同一套 JSONL 协议。读这章时,把 UI 当成协议客户端,而不是第二个 agent。
UI 不应该拥有的东西
一个 UI 可以拥有输入框、滚动位置、折叠开关和最后一次看到的 seq。它不应该拥有:
- provider client;
- executor;
- policy 决策;
- event log 的写权限;
- 对 unknown outcome 的猜测;
- 一份自认为权威的 SessionState。
把 UI 进程 kill 掉后,runtime 的会话仍然应该能恢复。这个性质是判断边界是否正确的简单方法。
UI 只看到安全投影
打开 src/protocol/event_projection.rs。durable Event 里的 tool.requested 可能包含完整 command、old_text 或工具输入,协议通知不能直接把完整 payload 广播出去。
v2 projection 只保留白名单字段,例如:
type
event_id
timestamp
schema_version
tool_call_id
execution_id
tool
approved
reason
input_summary
input_summary 是给审批界面看的短摘要:bash 显示 command 的有限前缀,read/edit 显示 path,其他输入显示 opaque。完整输入仍留在 event log 里。
客户端因此能显示“正在请求什么”,却拿不到全部原始内容。这是一个信任边界,不是遗漏。
事件查看器:最小的协议客户端
打开 src/ui/event_viewer.rs。它的流程很短:
启动 serve --stdio
→ 协商协议版本
→ session.create
→ turn.start
→ turn.wait 或持续接收通知
→ 按 seq 去重
→ 打印事件摘要
事件查看器的价值在于它把协议问题和终端渲染问题分开。先运行:
cargo test --test events_viewer
然后找到它处理 notification 的地方。注意它不是从 event log 读取事实,而是消费服务器发送的安全投影。
Ink TUI 的三层结构
打开 ui/src 目录,它只有三个文件,职责分得很清楚:
main.tsx 入口:解析参数、启动 serve、session.create、挂载 React
client.ts 协议客户端:spawn 子进程、按 id 路由响应、转发通知
ChatApp.tsx 渲染:React state、输入框、审批提示、消息列表
main.tsx 每次启动都创建一个新 session,并把 event log 放到临时目录,避免“日志非空”的冲突。它还会检查 stdin 是不是 TTY:不是就报错退出,并提示改用 mini-harness run。
client.ts 怎样路由消息
打开 ui/src/client.ts。它 spawn 出 mini-harness serve --stdio,stderr 直接继承给终端,stdout 交给 readline 逐行解析。每条消息只有两种命运:
有 id、且 pending 里有它
└─ response,resolve 对应的 Promise
method = event
└─ notification,发给 EventEmitter
这和 Rust 事件查看器里的路由是同一件事:如果客户端只读自己的 response,就会漏掉事件;如果把 notification 当 response,等待命令的 Promise 永远不会 resolve。
request() 给每条命令分配递增的 id,把 resolve/reject 存进 Map,再写到子进程 stdin。onEvent() 返回一个取消订阅函数。整个类不持有任何会话状态——它只负责转发命令、关联响应、转发通知。
一次 turn 的交互
打开 ui/src/ChatApp.tsx。用户按下回车后的顺序是:
turn.start → 返回 turn_id 和 queued
(后台持续接收 event notification)
turn.wait → 完成返回最终文本
→ timeout 返回 turn_pending
→ 需要审批返回 approval_pending
approval.respond → 用户按 y/n 后,把决定变成事实
关键点在审批:turn.wait 收到 approval_pending 并不代表失败。它对应一条已经收到的 tool.approval.requested 通知;UI 等用户按 y/n,再调 approval.respond,然后继续 turn.wait。
UI 自己不执行工具,也不决定权限。如果 Ink TUI 自己调用模型或 bash,协议边界就被绕开了。
UI 如何推导生命周期
屏幕上的 Running、WaitingApproval、RunningTool 和 Idle 都来自事件投影。src/runtime/state.rs 中的 run_state 会检查:
- 是否有 pending approval;
- 是否有 Running execution;
- 是否有 active turn。
UI 不应该看到一次 tool.approval.requested 后永远显示审批中;它要处理后续的 tool.approval.responded、tool.started 和终态事件。
重新连接或 resume 时,客户端应以事件 seq 为版本依据补齐缺失通知,而不是相信旧的内存列表。
读测试
cargo test --test events_viewer
cargo test --test tui_line_mode
cd ui && npm run typecheck
先看事件到生命周期的投影和按 seq 去重,再看 Ink 客户端的类型检查。每个检查都在说明同一件事:UI 可以改变显示,但不能改变事实。
思考题
- UI 为什么不能直接读取和解析 event log?
- 如果通知丢了一条,seq 怎样帮助客户端发现问题?
- 为什么 WaitingApproval 应该由事件投影推导,而不是只看 turn.wait 的错误码?
input_summary为什么不能直接等于工具的完整输入?- 想显示实时 stdout 增量,需要在协议中增加什么;安全投影边界会怎样变化?
- UI 重启后,哪些信息可以从事件恢复,哪些纯粹是 UI 本地状态?