Shippy 的启示：可靠 Agent 不是更听话，而是更少犯错空间（3 个集合收缩 + 4 类边界 + 整套 Eval）

Shippy 的启示：可靠 Agent 不是"更听话"，而是更少犯错空间

TL;DR

• 场景：Ai2/Skylight 团队在 Hugging Face 社区发表 “What building Shippy taught us about building agents”（作者 Kyle Wiggers，2026-07-15），复盘构建 Shippy（Skylight 海洋监测 Agent）时遇到的协议层"成功但答错"问题与四道工程边界。
• 结论：高风险 Agent 的可靠性不能只押注于模型更强。真正可迁移的是同时收缩动作空间、状态空间、后果空间——分别用版本化 Soul/Skills、Typed API + 确定性 CLI、会话级 Sandbox、Live-Data Agent Eval 落到工程实现。
• 产出：4 道边界（行为 / 动作 / 环境 / 验证）的设计原则、Typed API → CLI → Skill 三层结构、Sandbox 四件套（身份/文件/网络/生命周期）、专家 Rubric + LLM Judge + 脚本三重评测，及其向语音 Agent 迁移的方法。

版本矩阵

**摘要：**高风险 Agent 的可靠性不能只押注于模型更强。Shippy 的工程价值
在于用版本化行为工件、确定性 CLI、会话隔离和整套 Agent Eval，持续缩小
动作空间、状态空间与错误后果。

**关键词：**AI Agent、Shippy、Deterministic Tools、Sandbox、Agent Eval

目录

• 为什么"成功返回"可能更危险
• 版本化 Soul、Skills 与 Config
• Typed API、确定性 CLI 与 Skill
• 会话级隔离如何限制错误后果
• 为什么必须评测整套 Agent
• 迁移到语音 Agent 的方法

让一个大模型直接拼装复杂 API 请求，最危险的情况往往不是报错，而是"成功"。分页参数写错，接口仍返回前几页，结果只是悄悄缺失；Geometry 的层级或坐标编码出错，查询可能落到错误区域；过滤器类型被误解，响应字段完整、数据看似合理，但回答的已经不是用户提出的问题。系统没有异常，模型也能把结果组织成一段自信的解释，错误因此更难被发现。

Ai2/Skylight 在 Shippy 的早期原型里遇到的正是这类问题。Skylight API 有大量输入类型、嵌套过滤对象、分页游标和复杂几何参数。让 Agent 从零构造请求后，团队持续看到分页漏数、Geometry 编码错误，以及"请求看起来正确、返回数据却不对"的过滤问题。[1]

这类失败说明，高风险 Agent 的可靠性不能只押注于模型更强、更听指令。模型能力提高，确实可能降低选错工具、误读字段或漏掉步骤的概率，但它不会自动消除协议复杂度、身份越权、状态串扰和回归不可见等系统风险。真正可迁移的工程思路，是把不确定性包进可验证的边界：先减少模型可以选择的错误动作，再限制错误能够造成的真实后果，最后用整套 Agent Eval 持续发现边界是否失效。

所谓"缩小错误空间"，不是要求模型永不犯错，而是减少系统允许它抵达的无效状态和危险动作。Shippy 的架构把这件事分散到版本化的 Soul/Skills、Typed API、确定性 CLI、会话级 Sandbox 和端到端评测中。每一层都不完美，但每一层都让下一层少承担一部分不确定性。

可以把这套设计理解为同时收缩三个集合。第一是动作空间：模型能调用哪些操作、参数能取哪些形态；第二是状态空间：一次会话能看到哪些文件、凭据和历史；第三是后果空间：一次错误最多能触达哪些数据与外部服务。模型升级主要改变"在既定空间内选对动作的概率"，而 Typed Contract、Sandbox 和 Eval 改变的是空间本身、边界强度以及失败被发现的速度。两者互补，但不能互相替代。

先把行为定义变成可版本化工件

Shippy 把 Agent 拆成 Soul、Skills 和 Config。Soul 是系统提示，定义角色、行为边界以及不应做出的判断；Skills 描述特定任务的处理流程。两者被打包进版本化 Docker 镜像，形成可部署、可回滚、可比较的 Agent 工件。模型、Agent Harness 和 Runtime 设置属于 Config；API Key 等 Secrets 不写进镜像，而是在运行时注入。[1]

这个拆分的价值，不是"把 Prompt 写得更长"，而是把行为变化变成可审计的发布变化。一次 Skill 修改、一次 Soul 边界调整，都能对应到明确版本；模型或 Harness 的替换则可以作为配置变化单独观察。这样做后，团队至少能回答：线上回答来自哪个行为工件、哪个模型配置、哪套运行环境，以及某次回归从哪里开始。

Shippy 的 Skills 采用 Agent Skills 规范。该规范以带 YAML frontmatter 的SKILL.md为核心，也允许附带脚本、参考资料和静态资源；它的重点是把领域知识和多步流程变成可移植、可版本控制的目录。[2] 对高风险系统而言，Skill 的意义不是给模型更多"灵感"，而是减少每次执行时重新发明流程的机会。例如，查询某国专属经济区内的活动时，Skill 可以明确要求先通过区域 API 解析边界，再在该 Geometry 内查询事件，最后补充来源和可核验链接，而不是让模型凭记忆猜坐标或临时决定步骤。

但 Soul 和 Skill 仍不是完整的安全边界。提示可以被误解，Skill 可以被错误选择，模型也可能跳过步骤。它们提供的是行为约束、可读性和版本治理；真正阻止跨用户读写、限制网络访问或约束凭据作用域的，是后面的身份、文件和网络边界。把 Prompt 当作全部安全机制，会把"模型通常会遵守"误写成"系统保证无法越界"。

Typed API、确定性 CLI、Skill：把协议错误逐层拿走

Shippy 最关键的一层，是不让模型直接面对复杂 API。它通过面向任务的 Skylight CLI 发起调用。Agent 只需要生成类似skylight events search的命令并填写类型化过滤参数，CLI 则把鉴权、分页、Geometry 输入处理和结构化输出收进确定性代码。[1]

这不是简单地在 API 外面包一层命令行。它改变了错误发生的位置和可测试方式。

底层 Typed API 用明确 schema 规定输入、输出和字段含义，使协议约束可以被静态检查和单元测试覆盖。中间的 CLI 把嵌套对象、游标循环、几何编码、错误处理和认证流程折叠成更小的任务接口。上层 Skill 再告诉 Agent 在什么场景调用哪个命令、按什么顺序解释结果。于是形成 Typed API → Deterministic CLI → Agent Skill 的三层边界：API 可以独立跑测试，CLI 可以由人或 Agent 直接验收，Skill 可以在不重写底层 plumbing 的情况下做场景评测。每层只暴露下一层真正需要的自由度。

CLI 的--help和详细错误信息也很重要。对 Agent 而言，接口文档不是给开发者看的附录，而是运行时恢复机制：参数不合法时，系统应返回可操作的约束，而不是一段模糊的服务端异常。这样，模型仍可能选择错误任务，却更难生成协议层"似乎能运行"的任意结构。可靠性由此从"期待模型记住所有 API 细节"，转变为"让工具在边界处拒绝非法状态，并给出有限的修复路径"。

输出写入本地 JSON 文件，而不是经 Shell 管道传递，也是同一思路。Shippy 团队曾遇到大结果集触及 pipe buffer 限制或破坏下游jq处理的问题。落盘后，结果具有明确路径和结构，后续步骤可以重复读取，不必依赖一条脆弱的长管道。[1] 这并不能保证模型一定读对文件，却消除了缓冲区、流式截断和中间格式漂移等一批与推理无关的失败模式。

确定性工具的代价是真实的。团队要维护类型定义、命令设计、帮助文本、错误信息、兼容性和测试；每新增一个任务抽象，都增加工具工程成本。对于低风险、参数简单、失败显式的接口，直接工具调用可能已经足够。值得投入 CLI 和 Skill 边界的，通常是协议复杂、错误可能静默、调用有副作用，或错误答案会进入真实决策的路径。判断标准不是"能不能让模型调通"，而是"调错时是否容易发现、是否容易恢复、是否会造成高代价"。

Shippy 的评测也证明，工具边界不会消灭所有错误。团队仍观察到 Agent 发明不存在的 CLI 命令，或在 Geometry 简化后漏掉事件。差别在于，失败已经被压缩到更明确的接口和行为上：是命令不存在、边界解析不当，还是 Skill 指令不足。可定位性本身就是可靠性的一部分。

每个会话一个 Sandbox，解决的不是正确性，而是后果

工具层缩小"怎么调用"的错误空间，隔离层缩小"调用错了会影响谁"的后果空间。Mothership 会为每个用户会话创建独立的 Kubernetes Deployment，其中运行 Agent Runtime、Skills 和 Skylight CLI。会话创建时注入该用户的 Skylight JWT，使 API 请求天然受该用户权限约束；Agent 写入的文件只存在于本会话；网络层只允许访问任务需要的服务。[1]

这组边界分别处理不同风险。JWT 约束身份和数据作用域，独立文件系统避免中间结果跨用户泄漏，网络策略减少任意外连，会话生命周期则让临时状态可随会话销毁。即使模型选错工具、生成有问题的代码，或把某个中间文件处理错，错误也更难跨出租户和会话边界。

这仍然不代表 Kubernetes 是 Agent 的标配。每会话 Deployment 提供强隔离，也会提高资源占用、调度、镜像分发和生命周期管理的复杂度；对低价值、只读、短会话，它可能超过实际需要。更合理的原则是按风险选择"最小充分隔离"：看数据敏感度、工具副作用、任务持续时间、租户数量、状态是否需要落盘，以及错误是否可逆。高风险、多租户、可执行代码的工作流可以采用会话级 Sandbox；低风险查询可以使用更轻的隔离，但仍要保留租户级凭据、受限文件空间、网络白名单和完整审计。Shippy 展示的是一种针对其风险模型的实现，不是基础设施教条。

评测对象必须是 Agent 系统，而不是裸模型

只测模型回答静态问题，无法覆盖 Agent 真正的失败链：它是否选对 Skill，是否构造正确工具参数，是否在实时数据上得到完整结果，是否遵守边界，是否知道何时停止。Shippy 因此把模型、Skills 和 Sandbox 作为一个整体评测。

其场景和 Rubric 由领域专家定义。不同任务选择不同指标和权重，例如数据准确性、边界解析、时间范围、来源归因和表达方式并不等价。专家还会标注具体回答的正误，为 Judge 提供参照。执行时，自然语言任务进入真实 Sandbox，LLM Judge 对每项标准给出 0 到 1 的分数和文字理由，再按权重汇总，与固定阈值比较。[1]

Harbor 在这里承担的是沙箱化 Agent 任务的运行框架。Shippy 团队编写的 Harbor 插件会启动待测的精确 Shippy 版本，在用户会遇到的实时数据上执行任务，并产出带时间戳的结果文件以及相对上一次运行的分数差分。[1][3] 这使"改了 Skill、换了模型、底层数据更新后发生什么"可以进入持续回归流程，而不是依靠几次手工演示。

这类 Eval 的另一项价值，是把失败归因到系统层，而不是笼统归因于"模型不行"。原文披露的失败包括：巡逻规划任务中过度给出战术建议、Geometry 敏感查询因边界简化而漏数，以及虚构不存在的 CLI 命令。[1] 三种失败分别指向行为边界、数据处理和工具可供性，修复手段并不相同。只看一个总分，会掩盖这种差异；保留逐项 Rubric、Judge 理由、执行 Trace 和版本差分，才能让评测真正驱动工程修改。

实时数据带来生产真实性，也削弱完全可复现性。固定 Shippy 版本只能固定模型、Skill、Harness 和 Runtime 工件，无法冻结持续到达的卫星与船舶信号。时间戳和差分结果提供的是可追溯性，不等于同一任务未来会得到逐字、逐项一致的结果。工程上更稳妥的做法，是把快照或录制数据用于确定性回归，把实时数据用于生产漂移和真实工作流验证；这是从 Shippy 方案延伸出的测试设计，不是原文声称其 Live-Data Eval 已完全可复现。

LLM Judge 同样不是自动化真理机。它可以扩展到大量开放式结果，却只能评价专家事先定义的场景和 Rubric。遗漏的风险不会因为分数精确而自动出现，模糊标准还会把 Judge 的偏好包装成量化结果。Agent Skills 的评测指南也强调：能由代码验证的机械条件应优先使用脚本，人类复核负责发现断言没有覆盖的问题。[2] 因此，高风险 Eval 应把确定性检查、LLM Judge、专家标注和失败复盘组合起来，而不是用 Judge 替代领域责任。

Shippy 当前也有明确的能力边界。它现在返回可跳转的地图链接；由 Agent 直接操控地图仍是未来路线。模型路由尚在建设中。上下文可在线程内保留，但跨线程记忆也是规划能力。[1] 把这些路线图写成现有功能，会高估系统成熟度，也会混淆哪些边界已经接受过评测。

迁移到语音 Agent：版本化每个可变环节

从 AI Agent、语音系统与边云协同工程的视角，我更关注 Shippy 方法在语音链路上的迁移，而不是海事模型本身。以下是工程推导，不是 Shippy 已实现的语音能力。

语音 Agent 不应只记录"用了哪个大模型"。ASR 模型、VAD 和文本归一化策略需要单独版本化，因为识别错误会改变后续意图；对话状态 schema 和状态转移规则需要单独版本化，因为同一句话在不同状态下会触发不同动作；工具合同和确定性适配器需要单独版本化，负责鉴权、重试、幂等、参数校验和副作用确认；TTS 模型、发音词典和渲染策略也需要版本化，避免正确文本在播报阶段变成误导信息。

短期身份应绑定到会话、设备或租户作用域，不能只靠上下文里一句"你正在服务某用户"。Trace 则要串起 ASR 输入、状态快照、模型与 Prompt 版本、工具参数、工具结果、TTS 输出和时间戳。只有这样，一次错误才能被回答为：是听错、状态错、工具错、表达错，还是身份边界错。边云协同时，还要明确哪些状态留在端侧、哪些请求进入云端、断网时允许哪些降级动作，以及重连后怎样避免重复执行。

这套映射仍然遵循同一个原则：不要要求一个概率模型同时承担感知、协议、权限、状态和审计的全部正确性。把确定性部分从模型自由度里剥离，把身份和副作用放进可执行边界，再用端到端 Trace 和 Eval 验证整条链路。

可靠性来自约束、隔离和反馈闭环

更强模型仍然重要。它能改善意图理解、工具选择、复杂推理和异常恢复。但在高风险 Agent 中，模型能力只是系统可靠性的一个乘数，不是边界本身。没有 Typed API 和确定性工具，更强模型仍会面对不必要的协议自由度；没有会话隔离，一次错误仍可能扩大为跨用户后果；没有整套 Agent Eval，改进和回归都难以被持续观察。

Shippy 最值得迁移的结论，是把可靠性从"Prompt 是否足够严厉"改写成三个工程问题：系统允许模型做错多少事，做错后最多影响多大范围，变化后能否及时发现。版本化 Soul/Skills 让行为可追踪，Typed API 与 CLI 让调用可验证，Sandbox 让后果有边界，Live-Data Eval 让真实漂移进入反馈闭环。

可靠 Agent 不是从此不犯错，而是错误更少发生、更容易暴露、更难扩散，并且能够被定位和修复。对于不同业务，具体技术栈可以不同；应保持不变的是按风险选择最小充分隔离，并持续缩小模型不必拥有的自由度。

一手来源

[1] Ai2/Skylight, “What building Shippy taught us about building agents”, 2026-07-15：https://huggingface.co/blog/allenai/shippy-tech-blog

[2] Agent Skills 官方文档，Overview、Specification、Evaluating Skills：https://agentskills.io/home

[3] Harbor 官方网站与文档：https://www.harborframework.com/

FAQ

Prompt 写得足够严格，能替代执行隔离吗？

不能。Prompt 约束行为倾向，Sandbox、权限和网络策略约束真实后果。

每个 Agent 会话都应该创建 Kubernetes Deployment 吗？

不一定。应按数据敏感度、工具副作用和会话寿命选择最小充分隔离。

LLM Judge 能替代专家和脚本检查吗？

不能。机械条件优先脚本验证，专家负责 Rubric 和风险边界，人工复核发现断言未覆盖的问题。

错误速查卡

作者：武子康的个人博客
原文链接：https://huggingface.co/blog/allenai/shippy-tech-blog
Agent Skills 规范：https://agentskills.io/home
Harbor 框架：https://www.harborframework.com/