内容提要
文章介绍 SoduWork 如何以统一抽象管理七个 Agent 执行底座(harness)。核心设计包括:agent_catalog.json 声明各底座的传输方式与模型归属;contract.js 定义 14 项能力,并按 native、emulated、delegated 三级实现;registry.js 依据错误码降级,并隔离消费方。后端通过任务快照与职责分离防止行为漂移。作者实测仅跑通 Pi,并发现新增可执行 ACP 条目会导致底座列表异常。
延伸解读
能力声明与实现级别:抽象的核心机制
SoduWork 用 14 项能力声明统一七个底座,每项能力附带 native、emulated、delegated 三级实现级别。这比单纯的能力清单更细:调用方只认能力 id,不关心底座是谁。例如 turn.pause 可声明为 emulated,由上层用“记录进度+取消+重放”模拟。六项能力还被钉死到固定方法名,声明与实现不符会在注册期失败,避免运行期才暴露问题。
三层降级路径:让能力缺失可处理
面对底座差异,代码分三层处理:先通过 supports 预检决定是否渲染按钮或走恢复流程;真调用时若方法不存在,registry.js 抛出带 CAPABILITY_UNAVAILABLE 错误码的结构化错误,调用方按错误码降级而非匹配文案;最后用 validateConsumer 限定 chat、goal、task 三种消费方,隔离不同场景的能力使用。作者指出 supports 目前尚无调用点,实际生效的是后两层。
后端两道保障:快照与职责分离
前端抽象解决底座统一,后端解决任务不跑偏。任务创建时快照当时的能力要求和验收标准,之后管理员修改底座目录不影响已有任务,切断“底座升级导致旧任务行为突变”的风险。审批路由则做职责分离:AI 干的活不能算人工,否则人就成了自己审自己,产品“人签字才算完成”的承诺会落空。
实测边界:只跑通 Pi,抽象仍有未验证处
作者仅实际跑通 Pi 底座,其余六个 runner 类型未逐一验证,相关结论来自代码和 catalog。能力级抽象抹不平体验差异,例如两个底座都声明 turn.steer,实际可能一个立即改、一个排队到检查点。此外,新增可执行 ACP 条目后桌面端底座列表异常,OpenCode 跟着消失,作者推测探测时可能真的启动了常驻服务,已整理为 issue #358。
Q&A
SoduWork 是怎么让七个不同的 Agent 执行底座共用一套代码抽象的?
SoduWork 通过三层设计实现统一抽象:首先用 agent_catalog.json 声明每个底座的传输方式(direct 或 runner)和模型归属(managed 或 account);其次在 contract.js 中定义 14 项能力,每项能力按 native、emulated、delegated 三级实现;最后在 registry.js 中按错误码降级,并按消费方(chat/goal/task)隔离。业务侧只认能力 id,不认厂商。
SoduWork 的 14 项能力具体包括哪些?三级实现级别是什么意思?
14 项能力覆盖会话恢复、回合控制(取消/暂停/改向)、产出物列表、审批响应、目标控制、附件、模型选择、技能、MCP、工作区、原生事件等。三级实现级别指:native(底座自己实现)、emulated(上层模拟,如用取消+重放模拟暂停)、delegated(委托给子进程)。调用方看到的仍是同一能力 id,无需关心底层实现方式。
如果某个底座不支持某项能力,SoduWork 会怎么处理?
分三层处理:第一层用 supports() 预检,决定是否渲染按钮或走恢复流程;第二层在真正调用时若方法不存在,registry.js 抛出带 CAPABILITY_UNAVAILABLE 错误码的结构化错误,调用方按 error.code 降级而非匹配文案;第三层通过 validateConsumer 限定消费方(chat/goal/task),同一底座在不同场景可用的能力不同。
SoduWork 后端如何防止任务因为底座目录更新而行为漂移?
后端在任务创建时对能力要求和验收标准做快照(models.py 注释说明),之后管理员修改底座目录不影响已存在的任务。此外 approval_routing.py 实现职责分离,确保 AI 执行的工作不被归类为人工工作,避免人类审查者自己审自己,保障“人签字才算完成”的承诺。
作者实测 SoduWork 时遇到了哪些问题?
作者在 Arch Linux 上因缺少 gnome-keyring 导致启动卡在钥匙串缺失页面,安装后解决(并提了 PR #301)。另外,在 agent_catalog.json 中添加一个指向真实可执行文件的 ACP 条目后,桌面端底座列表从「Pi + OpenCode」变成只有「Pi」,而复制 dsh 条目(bins 未安装)则列表正常,推测探测时可能真的启动了常驻服务(issue #358)。作者只跑通了 Pi 底座,其余六个 runner 未实际验证。
SoduWork 的抽象设计有哪些边界或局限性?
文章指出五点边界:一、能力级抽象抹不平体验差异(如 turn.steer 实际行为可能不同);二、六个 runner 共用一套 adapter,排查成本较高;三、supports 预检目前需业务侧接入,目录内暂无调用点;四、作者只跑通 Pi,其余六个未真实运行验证;五、交叉审查需要两个可用模型,作者因额度用完只做了单模型自审,未能验证多模型互审的价值。