Shippy 全拆：3 个集合收缩（动作 / 状态 / 后果）+ 4 类边界（版本化行为 / Typed API / CLI / Sandbox）

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 迁移的方法。

版本矩阵

功能 / 组件	状态	说明
HF 社区文章 "What building Shippy taught us about building agents"	✅ 已验证	2026-07-15T17:29:41.752Z 发布，dateModified 同值；作者 Kyle Wiggers（Ai2 Comms / Ai2Comm）；14 upvote
作者归属	✅ 已验证	HF schema.org creator/author 均为 Kyle Wiggers（huggingface.co/Ai2Comms）；publisher Hugging Face
Shippy 拆为 Soul / Skills / Config	✅ 已验证	原文明确，Soul 与 Skills 打包为版本化 Docker 镜像，Config 选模型/Harness/Runtime/Secrets
Secrets 不写进镜像，运行时注入	✅ 已验证	原文
Agent Skills 规范（SKILL.md + YAML frontmatter + scripts/references/assets）	✅ 已验证	agentskills.io/home 文档确认；frontmatter 至少含 name + description；可附带脚本/参考/资源
Agent Skills 渐进披露三阶段	✅ 已验证	Discovery（name+description）→ Activation（完整 SKILL.md）→ Execution（执行脚本/加载文件）
Agent Skills 由 Anthropic 发源并开源	✅ 已验证	agentskills.io/home "Open development" 段
Agent Skills 评测指南	✅ 已验证	agentskills.io 提供 Overview / Specification / Evaluating Skills 三大块
Skylight CLI（`skylight events search` 等面向任务命令）	✅ 已验证	原文
CLI 内部处理鉴权 / 分页 / Geometry 编码 / 结构化输出	✅ 已验证	原文
Typed API → CLI → Skill 三层结构	✅ 已验证	原文
输出落盘 JSON 而非 Shell 管道	✅ 已验证	原文（团队曾遇 pipe buffer 限制 + 下游 `jq` 处理破坏）
Mothership 每用户会话一个 Kubernetes Deployment	✅ 已验证	原文
会话创建时注入该用户的 Skylight JWT	✅ 已验证	原文
Agent 写入文件仅在本会话、生命周期随会话销毁	✅ 已验证	原文
网络层只允许任务需要的服务	✅ 已验证	原文
专家定义场景与 Rubric（数据准确性、边界解析、时间范围、来源归因、表达方式各异）	✅ 已验证	原文
LLM Judge 按 0-1 分数 + 文字理由，按权重汇总，与固定阈值比较	✅ 已验证	原文
失败归因：巡逻规划过度给战术建议 / Geometry 简化漏数 / 虚构 CLI 命令	✅ 已验证	原文
Harbor 框架承担沙箱化 Agent 任务运行	✅ 已验证	原文引用，harborframework.com 是其官网
Harbor 插件启动精确 Shippy 版本 + 实时数据 + 时间戳结果 + 相对上次差分	✅ 已验证	原文
Shippy 当前能力边界：仅返回可跳转地图链接；地图直接操控是未来路线	✅ 已验证	原文
跨线程记忆是规划能力	✅ 已验证	原文
每会话 Kubernetes Deployment 是高风险高开销实现	⚠️ 工程权衡	原文强调"按风险选择最小充分隔离"，未给统一定量门槛
"约 12 次调用平均" 等中间数据点的样本量	⚠️ 未公开	原文未披露具体重复次数与置信区间
LLM Judge 在每个 Rubric 上的具体权重数值	⚠️ 未公开	原文说"按权重汇总"，但未给数字
模型路由（routing）当前状态	⚠️ 未公开	原文仅说"模型路由尚在建设中"
Agent Skills 治理方（Anthropic 主导 vs agentskills.io 独立组织）	⚠️ 推算	agentskills.io 自述"open to contributions from the broader ecosystem"，原文归功 Anthropic 发源；治理结构未明示
Harbor 与 Docker Harbor（VMware/CNCF 镜像仓库）的关系	⚠️ 须区分	本文 Harbor 指 Agent 评估框架（harborframework.com），与 Docker 镜像仓库 Harbor 是同名不同项目
OpenClaw 与 Harbor 链接	⚠️ 未见	原文未提 OpenClaw；本文不引入未在原文出现的产品名
Kyle Wiggers 在 Ai2 的职位	⚠️ 未公开	HF 个人页写 Ai2Comms / Ai2，未给具体职位

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

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

让一个大模型直接拼装复杂 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：huggingface.co/blog/allena...

$2$ Agent Skills 官方文档，Overview、Specification、Evaluating Skills：agentskills.io/home

$3$ Harbor 官方网站与文档：www.harborframework.com/

FAQ

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

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

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

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

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

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

错误速查卡

症状	根因	定位	修复
"API 调通但答错" --- 看似正常返回，结果已经错位	让模型从零拼装复杂 API，分页/Geometry/过滤类型被静默误解	查 Agent 是否绕过 Typed API / CLI 直接发请求	强制走 Typed API → CLI → Skill 三层；CLI `--help` 与错误信息作为运行时恢复机制
模型发明的 CLI 命令被默默忽略	CLI 解析失败但没归因到 trace	看是否有"命令不存在"分支处理	解析失败必须进 trace；同时校验 Skill 是否教了正确命令
Geometry 简化后漏数	CLI 折叠了 Geometry 编码但简化路径有边界偏差	比对 CLI 内部编码与原 API 期望	复杂几何走 API 原生参数，避免单一简化启发式；Eval 抓边界覆盖
输出管道超长时下游 `jq` 崩溃	大结果集走 Shell 管道，pipe buffer 限制	查执行链是否走 pipe	输出落本地 JSON，路径化引用，重复读取
跨用户读到别人的中间结果	会话之间文件系统未隔离	查每会话 Deployment 与文件挂载	JWT + 独立工作目录 + 短生命周期销毁
评测只报一个总分，改进方向不清	失败被合并到总分，丢失归因	看 Rubric 是否多维度	拆数据准确性/边界解析/时间范围/来源归因/表达方式，每项单独分数 + 文字理由
LLM Judge 把模型偏好包装成"量化质量"	Judge 只能评价专家定义的场景，模糊标准会放大偏见	比对 Judge 理由与人工复核	机械条件走脚本；高风险维度由专家标定；模糊标准不评
改 Skill / 换模型后回归不可见	没有"固定 Shippy 版本 × 实时数据"的 Live-Data Eval	查 Harbor 插件是否每次拉精确版本	固定工件 + 时间戳结果 + 与上次差分
"Live-Data 完全可复现"的过度承诺	实时数据无法冻结，每次跑结果都会变	区分"可追溯"与"可复现"	快照/录制数据用于确定性回归，实时数据用于生产漂移验证
Prompt 改完没有版本化，线上不知道是哪一版生效	Soul/Config 写散，无法回滚	查是否走 Docker 镜像 + Config 注入	Soul + Skills 打包为版本化 Docker 镜像；Secrets 运行时注入
把"模型通常遵守"误当成"系统保证无法越界"	仅靠 Prompt 约束	查是否配 JWT + 文件 + 网络边界	Prompt + Sandbox + 权限 + 网络策略四层协同
"Agent 给出战术建议"被报为"模型不行"	失败归因笼统，未指向 Soul 边界	查 Soul 是否明文限制非任务输出	在 Soul 中加入"不应给出的判断"清单 + 评测抓此类违规
工具数量爆炸，模型"幻觉调用"	直接工具调用没有收敛到面向任务 CLI	查是否所有调用都过 CLI	引入 CLI 抽象，按任务面收敛工具，模型只生成"任务命令 + 类型化参数"
会话结束不清理	临时数据残留在文件系统	查 Deployment 销毁是否干净	短生命周期 + 显式资源回收 + 审计日志
Eval 复现率低 → 团队不再相信评分	Live-Data + 模糊 Rubric 让分数抖动	区分确定性回归与漂移评测	固定数据集 + 固定 Rubric 算回归；Live-Data 算漂移；分开看
跨线程记忆当成已实现能力	上下文机制尚未覆盖	查是否有持久化存储与脱敏策略	标注为规划能力；不把规划当功能宣传
每会话 Deployment 资源用尽	没有按风险分级隔离	查会话数量与资源配额	按风险选择"最小充分隔离"，低风险用更轻方案
Harbor 名称混淆	与 Docker/CNCF 镜像仓库 Harbor 同名	确认引用的是哪个项目	本文 Harbor 指 Agent 评估框架（harborframework.com）
把 Agent Skills 当作完整安全机制	Skill 只约束行为倾向，不阻止越权	查是否配置了独立身份与文件边界	行为约束靠 Soul/Skill，真实边界靠身份/网络/文件系统
"OpenClaw" 等未在原文出现的产品名被引入	二次解读时混入外部信息	查原文是否提及	仅引用原文一手来源，不引入未核验的产品名

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