🧩pi-interactive-subagents是一个让 pi 在 cmux、tmux、zellij、WezTerm 等多路复用器中异步派生、编排子代理会话的扩展。它的消息渲染器（message renderer）把子代理的任务结果、运行状态、求助信号变成 TUI 里带彩色背景的卡片，并按Ctrl+O一键展开完整摘要。这篇文章带你走进这套渲染器的源码，看懂彩色卡片、可展开摘要和实时状态栏背后的实现细节。

三类"会说话"的自定义消息卡片

pi 的扩展 API 提供了registerMessageRenderer：你声明一种customType，TUI 就能用任意方式把这种消息画出来。pi-interactive-subagents 恰好注册了三种，全部集中在 pi-extension/subagents/index.ts 里：

三种消息都通过pi.sendMessage(..., { triggerTurn: true, deliverAs: "steer" })发出——卡片不只是给人看的装饰，它同时是一条"steer"异步通知，会触发父代理新一轮处理。渲染入口在 pi-extension/subagents/index.ts#L2009-L2084。

彩色结果卡片的四步流水线

subagent_result渲染器是整个扩展视觉体验的核心，它分四步把一段文本"包装"成卡片：

1. 判成败，定底色：读取details.exitCode与errorMessage，失败时用theme.bg("toolErrorBg")，成功时用theme.bg("toolSuccessBg")，图标也同步切成红色✗或绿色✓（见 index.ts#L2020-L2025）。
2. 清洗展示文本：卡片展示的是"给人看的版本"。渲染器用正则剥掉Sub-agent "X" completed (…)这类前缀和结尾的Session/Resume引用块，让正文只剩干净的摘要。
3. 折叠/展开两种形态：折叠态只显示摘要的前 5 行，多出的行汇总成一行… N more lines，再附一条灰色Ctrl+O to expand提示；展开态则打印完整摘要，并附上Session:路径和Resume: pi --session <path>恢复命令（见 index.ts#L2051-L2076）。
4. 用 Box 画背景框：内容行被塞进new Box(1, 1, bgFn)，由 pi-tui 的 Box 组件统一负责背景填充与内边距，顶部还留一个空行做视觉分隔。

卡片头部的格式是✓ Scout (scout) — completed (1m 20s)，耗时由 formatElapsed 统一格式化。真正投递给模型的那份文本则由 resolveResultPresentation 生成——"模型看到的"与"人看到的"被刻意分成两层，这正是可展开摘要的前提。

💡Ctrl+O键位本身绑定在 pi 核心 TUI 上，渲染器只通过keyHint("app.tools.expand")显示提示文案，保持"提示"与"行为"解耦。

实时状态栏：手绘的 ANSI 边框 + 状态分类机

输入框上方的Subagents状态栏没有用 Box，而是纯字符串手绘：borderTop / borderLine / borderBottom 用╭ ─ ╮ │ ╰ ╯拼出边框，并用 ANSI 转义\x1b[38;2;77;163;255m手工着成#4DA3FF的强调蓝。每一行左侧是耗时 + 名字，右侧是状态标签，窄终端下优先保状态、截断名字。效果大致如下：

╭─ Subagents ───────────────────────────── 2 running ─╮ │ 00:23 Scout: Auth (scout) active · bash 7m │ │ 00:45 Scout: DB (scout) waiting 2m │ ╰─────────────────────────────────────────────────────╯

状态右侧标签由 formatWidgetRightLabel 生成，而其取值来自 pi-extension/subagents/status.ts 里的一套纯函数状态机：

• starting：子进程已启动，但还没读到有效活动快照；
• active：观察到模型回合、provider 请求、流式输出或工具执行；
• waiting：回合结束、等待输入或下一阶段；
• stalled：60 秒（SNAPSHOT_STALLED_AFTER_MS）拿不到有效快照；
• running：Claude 等无快照后端的兜底标签。

分类逻辑在 classifyStatus，每轮 startStatusRefresh 定时循环读取快照、推进状态，只有stalled/recovered这类关键跃迁才会以subagent_status卡片（同样支持Ctrl+O展开，见 index.ts#L2087-L2113）唤醒父会话；interactive子代理则保持安静，只更新 widget，避免浪费一次编排回合。

卡片背后的数据源：500ms 节流的活动快照

右侧的active · bash 7m这类细粒度标签，来自子进程自己写的活动快照。子会话内的 recorder（createSubagentActivityRecorder）监听agent_start、provider_request、tool_execution_start等约 20 种事件，把当前phase、activeScope（tool / provider / streaming / agent / turn）写进subagent-activity/<id>.json：

• 高频事件（如流式message_update）走500ms 节流，关键事件立即落盘；
• 写入采用"临时文件 + rename"的原子方式，父进程读到的一定是完整 JSON；
• 每次写入递增sequence，父端 observeStatus 会拒绝比上一次更旧的快照，防止乱序。

父端每秒轮询这个文件，读不到就按missing / invalid / wrong-id处理并计时，超过 60 秒即判stalled——所以卡片上的时间不是"猜"的，而是两端时钟与序号约束下的可靠状态。

快速定位这份源码

📌 小技巧：状态栏展示受config.json中status.enabled控制（参考 config.json.example），关掉它，widget 右侧会退化为简单的starting…/running…。

小结

这套消息渲染器把"异步子代理"这件抽象的事，翻译成了三样直观的东西：一张红绿分明、Ctrl+O可展开的结果卡片，一条蓝色手绘边框的实时状态栏，以及一张会主动敲门的求助卡片。而背后是主题色、Box 组件、原子化活动快照和纯函数状态机的组合拳。理解了它，你基本也就掌握了 pi 扩展做 TUI 自定义渲染的完整套路——声明customType、注册渲染器、用 steer 消息驱动新回合，三步即可。