Agent × 可视化：我的 5 次高价值开源贡献复盘Agent × 可视化：我的 5 次高价值开源贡献复盘

我把 #284、#285 和 #286 合在一起看，因为它们处理的是同一个更大的问题。

多 Agent 系统要怎样保存结构化信息，怎样复用已经生成的计划，又怎样稳定地把不同阶段路由到指定模型？

第一步是共享记忆。原来的持久化层以字符串为边界，但 Agent 之间传递的经常是对象和数组。#284 没有粗暴地把整个存储层改成任意类型，而是在公共 API 接受 JSON 可序列化值，继续保留 MemoryStore 的字符串持久化契约，再通过 JSON metadata 标记和恢复结构化内容。读取、列表和摘要展示都能识别这些值，还可以用可选的 Zod schema 校验 handoff。

这个边界很重要。对调用者来说，结构化数据不需要先手工压成字符串。对存储层来说，原有契约没有被打碎。

第二步是计划回放。#285 增加了可序列化的 plan artifact，让 plan-only 运行产生的计划可以被保存。再次执行时，不需要重新调用 coordinator，而是沿用已有的 explicit-task 路径，保留 task id、描述、assignee、依赖关系和 memory scope。

第三步是模型路由。#286 提供 opt-in 的确定性路由策略，可以按 phase、agent、task role、priority、leaf status 和 dependency status 选择模型。路由不会修改 team 或 agent 的原始配置，worker、delegated、short-circuit、coordinator 与 synthesis 调用则共享同一种策略形状。

三条 PR 合计新增 753 行、删除 89 行，分别关闭 #17、#272 和 #271。对应的 shared-memory、orchestrator、agent-pool 与 task-utils 测试也都写进了 PR 的验证记录。

这组贡献让我更确定一件事，Agent 系统真正难的不是再加一个模型下拉框，而是让数据、计划和路由都可保存、可复现、可解释。

MapLibre GL JS #7725 看起来像一次 TypeScript 类型整理，但它碰到的是渲染系统里很具体的数值边界。

renderer shader uniforms 使用 32 位矩阵，custom layer 输入却可能需要 32 位或 64 位矩阵。如果两条路径共用一个模糊的矩阵类型，类型检查无法告诉调用者某个位置究竟接受什么，运行时的 typed array 也可能和字段契约不一致。

这个 PR 增加 Mat4f32 与 Mat4f64，让 ProjectionData 对矩阵 backing array 变成泛型，再拆出 RendererProjectionData 与 CustomLayerProjectionData。terrain render-to-texture 的投影矩阵也被明确为 Mat4f32，初始化改用 Float32Array。同时修正了 custom layer 文档里一个指向不存在字段的引用。

改动跨越 16 个文件，不只是改一处 type alias。它需要让 projection transform、terrain、custom style layer、collision 和 draw tests 对同一套精度边界达成一致。PR 记录了 typecheck、ESLint 和多组 Vitest 验证，并在 collaborator approval 后合并，关闭 #6316。

我把它排在第二，不是因为改动覆盖文件多，而是因为它把一个容易靠约定维持的隐性规则，变成了编译器能够检查的公共契约。

对可视化基础设施来说，这类工作不显眼，但很硬。

CodeIsland #197 是五条里改动量最大的一次单 PR 贡献，新增 703 行，涉及 Swift 安装器、pi 扩展、OMP 扩展和安装器测试。

目标不是在支持列表里多写两个名字，而是让 CodeIsland 能识别、安装、启停、卸载和修复 pi 与 Oh My Pi 的扩展。

Swift 侧的 ConfigInstaller 会在 ~/.pi/agent 或 ~/.omp/agent 存在时，把打包的 TypeScript 扩展安装到各自的全局 extension 目录。扩展带版本标记，repair 流程可以识别过期安装。运行时再由 pi 和 OMP 各自的 package 接口上报 session 状态、审批与终端 metadata。

验证也不只停在编译通过。PR 包含安装、目录缺失 no-op、安全卸载和旧版本识别测试；两份扩展分别对本地 package 做了 typecheck，还用 omp-pi 做了 smoke test，确认 CodeIsland 能收到带 Ghostty metadata 的 live session。

这条贡献证明的是另一种 Agent 能力，不是写 orchestration framework，而是把不同 harness 接到真实桌面产品里。配置目录、包名、生命周期事件、版本迁移，少一块都只能算 demo。

Supermemory #1032 处理了一个很典型的协议与界面错位。

memory graph 初始只加载分页后的文档子集，但原来的摘要和界面没有把这层事实说清楚。用户看到一张图，很容易把当前页误认为完整数据。

修复从 MCP structured content 开始，增加分页 metadata，并把文本摘要改成 showing N of total documents。UI 增加 Load more，后续页面复用已有的 app-only fetch-graph-data tool 获取。初始 page size 保持为 10，避免第一次就加载过大的关系图。

这次改动覆盖 server、结构化数据 helper、UI 和 CSS，并增加 graph structured content 与摘要文案测试。PR 明确记录了一个边界，仓库全量 typecheck 当时会被 @supermemory/tools 既有错误阻断，但相关 Vitest 与 MCP UI build 已通过。最终 PR 获得两次 approval 后合并。

我很看重这里的透明度。验证不是必须写成一片绿色，真正有用的是把已通过的范围和仓库原有阻塞拆开说明，让 reviewer 知道哪些结论可以信。

这也是 Agent Memory 和可视化交叉处经常遇到的问题。图上显示了什么、没有显示什么、还能不能继续取数，都应该成为协议的一部分。

New API #5963 只有 4 行新增和 2 行删除，却是我最想保留的一条案例。

表面现象是创建 API key 后进入 500 错误页。很容易顺着这个页面去查后端，但本地复现显示 /api/token/ 一直返回 200。真正崩掉的是前端。

Chrome 的 Google Translate 会把 React 管理的文本节点替换成 <font> 包装节点。保存按钮状态、toast 和表格刷新再次触发 React reconciliation 时，React 尝试删除的原始节点已经不在预期位置，于是抛出 NotFoundError: Failed to execute 'removeChild' on 'Node'。

修复很小。在 default 与 classic 两个前端入口增加 Google notranslate meta，并给 #root 添加 translate="no" 和 notranslate，阻止浏览器翻译器改写 React 托管的根节点。项目本身已有 i18next，多语言能力不依赖浏览器直接修改 DOM。

PR 的验证记录包含基线创建、模拟 <font> 包装后的失败、加入 notranslate 后的成功，以及服务端持续返回 200 的对照。它关闭 #5962 后合并。

这条贡献提醒我，小 diff 不等于小问题。能把服务端 200、前端 500、第三方 DOM mutation 和 React reconciliation 串成一条因果链，才是它真正有价值的地方。

回头看这五条经历，我积累的不是五个互不相干的 patch，而是两条逐渐靠近的技术线。

一条是 Agent 工程。从结构化 shared memory、plan replay、model routing，到 pi / OMP extension，再到 MCP memory graph，核心问题始终是状态怎样表达、工具怎样接入、执行怎样复现。

另一条是可视化与交互基础设施。MapLibre 让我处理矩阵精度和渲染契约，Supermemory 让我处理图数据分页与界面认知，New API 则把视线拉回浏览器 DOM 和 React 更新边界。

它们最后会在同一个问题上汇合。

Agent 生成的状态，怎样被稳定地展示给人，又怎样允许人继续检查、理解和操作？

这也是我现在最想继续深入的方向。不是只做一个会调用模型的 Agent，也不是只画一张好看的图，而是把数据、执行和交互做成可以互相验证的系统。

这些 PR 的规模和项目背景不同，但有效的工作方式非常接近。

先把表面现象拆成可验证的因果链。New API 的 500 页面不能直接证明后端 500，memory graph 出现十个节点也不能证明总共只有十个节点。

再把边界写进代码。MapLibre 用矩阵类型表达精度，Open Multi Agent 用 plan artifact 和 routing policy 表达过去藏在运行时里的决定。

验证要跟着风险走。安装器要测 install、repair 和 uninstall，渲染类型要跑相关 draw tests，DOM mutation 要保留修复前后的对照，不能只留一句「本地验证通过」。

最后，接受 review 和仓库规则也是实现的一部分。AI 使用披露、issue 关联、测试命令、已知阻塞和 changelog 都不是收尾 paperwork，它们决定维护者能不能复核这次贡献。

这五条，是目前最接近这个标准的五次。