Shippy 的启示可靠 Agent 不是更听话而是更少犯错空间TL;DR场景Ai2/Skylight 团队在 Hugging Face 社区发表 “What building Shippy taught us about building agents”作者 Kyle Wiggers2026-07-15复盘构建 ShippySkylight 海洋监测 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 WiggersAi2 Comms / Ai2Comm14 upvote作者归属✅ 已验证HF schema.org creator/author 均为 Kyle Wiggershuggingface.co/Ai2Commspublisher Hugging FaceShippy 拆为 Soul / Skills / Config✅ 已验证原文明确Soul 与 Skills 打包为版本化 Docker 镜像Config 选模型/Harness/Runtime/SecretsSecrets 不写进镜像运行时注入✅ 已验证原文Agent Skills 规范SKILL.md YAML frontmatter scripts/references/assets✅ 已验证agentskills.io/home 文档确认frontmatter 至少含 name description可附带脚本/参考/资源Agent Skills 渐进披露三阶段✅ 已验证Discoverynamedescription→ Activation完整 SKILL.md→ Execution执行脚本/加载文件Agent Skills 由 Anthropic 发源并开源✅ 已验证agentskills.io/home “Open development” 段Agent Skills 评测指南✅ 已验证agentskills.io 提供 Overview / Specification / Evaluating Skills 三大块Skylight CLIskylight 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 HarborVMware/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目录为什么成功返回可能更危险版本化 Soul、Skills 与 ConfigTyped 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 设置属于 ConfigAPI 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 提供参照。执行时自然语言任务进入真实 SandboxLLM 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-15https://huggingface.co/blog/allenai/shippy-tech-blog[2] Agent Skills 官方文档Overview、Specification、Evaluating Skillshttps://agentskills.io/home[3] Harbor 官方网站与文档https://www.harborframework.com/FAQPrompt 写得足够严格能替代执行隔离吗不能。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” 等未在原文出现的产品名被引入二次解读时混入外部信息查原文是否提及仅引用原文一手来源不引入未核验的产品名作者武子康的个人博客原文链接https://huggingface.co/blog/allenai/shippy-tech-blogAgent Skills 规范https://agentskills.io/homeHarbor 框架https://www.harborframework.com/
Shippy 的启示：可靠 Agent 不是更听话，而是更少犯错空间（3 个集合收缩 + 4 类边界 + 整套 Eval）
发布时间：2026/7/24 22:40:13
Shippy 的启示可靠 Agent 不是更听话而是更少犯错空间TL;DR场景Ai2/Skylight 团队在 Hugging Face 社区发表 “What building Shippy taught us about building agents”作者 Kyle Wiggers2026-07-15复盘构建 ShippySkylight 海洋监测 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 WiggersAi2 Comms / Ai2Comm14 upvote作者归属✅ 已验证HF schema.org creator/author 均为 Kyle Wiggershuggingface.co/Ai2Commspublisher Hugging FaceShippy 拆为 Soul / Skills / Config✅ 已验证原文明确Soul 与 Skills 打包为版本化 Docker 镜像Config 选模型/Harness/Runtime/SecretsSecrets 不写进镜像运行时注入✅ 已验证原文Agent Skills 规范SKILL.md YAML frontmatter scripts/references/assets✅ 已验证agentskills.io/home 文档确认frontmatter 至少含 name description可附带脚本/参考/资源Agent Skills 渐进披露三阶段✅ 已验证Discoverynamedescription→ Activation完整 SKILL.md→ Execution执行脚本/加载文件Agent Skills 由 Anthropic 发源并开源✅ 已验证agentskills.io/home “Open development” 段Agent Skills 评测指南✅ 已验证agentskills.io 提供 Overview / Specification / Evaluating Skills 三大块Skylight CLIskylight 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 HarborVMware/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目录为什么成功返回可能更危险版本化 Soul、Skills 与 ConfigTyped 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 设置属于 ConfigAPI 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 提供参照。执行时自然语言任务进入真实 SandboxLLM 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-15https://huggingface.co/blog/allenai/shippy-tech-blog[2] Agent Skills 官方文档Overview、Specification、Evaluating Skillshttps://agentskills.io/home[3] Harbor 官方网站与文档https://www.harborframework.com/FAQPrompt 写得足够严格能替代执行隔离吗不能。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” 等未在原文出现的产品名被引入二次解读时混入外部信息查原文是否提及仅引用原文一手来源不引入未核验的产品名作者武子康的个人博客原文链接https://huggingface.co/blog/allenai/shippy-tech-blogAgent Skills 规范https://agentskills.io/homeHarbor 框架https://www.harborframework.com/
)
