Collaborator画布事件日志设计：让AI Agent完全可观测的完整事件流清单

Collaborator画布事件日志设计让AI Agent完全可观测的完整事件流清单【免费下载链接】collab-publicCollaborator is a place to create with agents.项目地址: https://gitcode.com/gh_mirrors/co/collab-publicCollaborator 是一个让 AI Agent 与开发者并肩工作的桌面协作画布而它的画布事件日志Canvas Event Log正是实现Agent 完全可观测的核心机制。本文带你完整梳理这套事件流设计14 种事件类型、统一的 JSONL 持久化格式、从终端到主进程的数据流向以及如何用一条查询接口回放Agent 的每一步操作。为什么 AI Agent 需要可观测性在 Collaborator 的画布上终端、代码文件、图片和知识图谱以瓦片Tile形式自由排布多个 Agent 会话可以同时运行。对开发者来说Agent 刚才做了什么不该是黑盒它切换到了哪个目录执行了什么命令命令退出码是多少它创建、移动、聚焦了哪些瓦片哪个终端会话创建、退出、发生了前后台切换画布事件日志的答案是把所有关键动作统一记录为一条条 JSON 事件按会话持久化到磁盘。这样无论是事后排查、还是让另一个 Agent 读取日志来接管工作都有据可查。完整设计见 2026-04-05-canvas-event-log-design.md。完整事件流清单14 种事件类型一览表事件采用命名空间前缀组织分三大类共 14 种1️⃣ 终端 OSC 事件5 种——来自终端转义序列事件类型携带数据触发来源osc:cwd当前工作目录OSC 7osc:title窗口标题OSC 0 / OSC 2osc:prompt无提示符出现OSC 133;Aosc:command-start无用户按下回车OSC 133;Bosc:command-end退出码exitCodeOSC 133;DOSC 133 是终端 Shell 集成标记Collaborator 通过 pty.ts 中注入的 zsh 钩子__collab_precmd/__collab_preexec让 shell 自动发出这些标记无需 Agent 主动上报。2️⃣ PTY 生命周期事件3 种——终端会话状态事件类型携带数据pty:created启动的 shell、初始目录、目标如 PowerShell/WSL2pty:exited会话退出码pty:foreground当前前台进程名3️⃣ 画布瓦片事件6 种——用户的画布操作事件类型携带数据触发时机tile:created瓦片类型、目录创建瓦片时tile:deleted无删除瓦片时tile:moved坐标{x, y}拖拽结束时而非过程中tile:resized宽高调整大小结束时tile:focused无瓦片获得焦点tile:blurred无瓦片失去焦点瓦片事件由 tile-manager.js 与 tile-interactions.js 发出——在拖拽结束时才记录一次是刻意的设计避免日志被高频拖拽事件淹没。事件如何流转从瓦片到 JSONL 文件每个事件都是一行独立的 JSONJSONL 格式包含 5 个字段时间戳ts、类型type、来源瓦片tileId、PTY 会话sessionId、以及按类型变化的data载荷。数据流向分两条路径终端事件终端瓦片webview中的 OSC 处理器TerminalTab.tsx→ Shell 窗口补全tileId→ 经 shell.ts 暴露的shellApi.emitCanvasEvent()→ 主进程 EventLog 落盘PTY 事件主进程的 pty.ts 在会话创建/退出/前后台切换时直接写入 EventLog省掉一次 IPC 往返所有文件按会话命名events-{timestamp}.jsonl应用启动时首个写入即创建文件。设计上不做截断与轮转——历史会话的文件自然累积清理留待后续版本。一步查询像查数据库一样查事件流落盘的事件不是写完就完而是随时可查。主进程提供canvas:query-log查询通道支持 5 个过滤维度按类型支持通配符如pty:*匹配所有终端会话事件osc:command-*匹配命令开始与结束按瓦片 / 按会话tileId、sessionId精确过滤按时间窗口since/until时间戳区间按条数limit限制返回量默认 100 条结果按最新在前排序比如这个终端会话最后 10 次命令的退出码就是一次types: [osc:command-end]sessionId的查询。查询与写入共用同一套事件模型未来接入日志查看器 UI 也只是多一个消费端——这正是为 Agent 可观测性设计而非为人类看日志设计的取舍。与 Canvas 控制接口的关系事件日志是只读的眼睛而 Collaborator 还有一套可写的手canvas-rpc.ts 通过 json-rpc-server.ts 注册了canvas.tileList、canvas.tileCreate、canvas.tileMove等方法Agent 可以在终端里直接编排画布瓦片。使用方法见 SKILL.md。眼睛事件日志 手Canvas RPC组合在一起Agent 就获得了完整的画布可观测与可控能力它能看到自己和其他 Agent 做过什么也能继续往下做。快速上手三步验证事件流打开 Collaborator双击画布创建一个终端启动任意 Agent快速上手流程见 README.md让 Agent 执行几次cd与带退出码的命令打开events-*.jsonl文件你应该能看到osc:cwd、osc:command-start、osc:command-end依次出现——这就是 Agent 行为的完整证据链总结Collaborator 画布事件日志的设计可以浓缩为四个关键词统一OSC、PTY、瓦片三类来源收敛为同一种 5 字段事件持久JSONL 按会话落盘天然适合追加与回放可查通配符 时间窗口 会话维度的一站式查询接口面向 Agent日志是另一个 Agent 的输入这才是可观测性的终极目的如果你正在构建自己的 Agent 协作工具这套14 种事件 JSONL 通配查询的清单可以直接作为参照模板。【免费下载链接】collab-publicCollaborator is a place to create with agents.项目地址: https://gitcode.com/gh_mirrors/co/collab-public创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考