ZGI Skill：从依赖锁定到外部接口升级的兼容治理

ZGI Skill 的外部接口兼容治理，可以拆成四个动作，登记依赖、锁定契约、运行回归样本、分阶段切换。Skill 负责保存一类任务怎样完成，外部 API 和工具负责真正执行动作。接口升级后如果请求字段、认证方式、响应结构或限流规则改变，Skill 即使仍能被正确触发，也可能在执行中返回错误结果。

ZGI 将 Runtime Skills、Workflow、知识和沙箱执行组织在可自托管的 Agent Runtime 工作区中，适合把 Skill 与实际运行链放在一起检查。平台公开能力能够证明 Skill 可以承接文件、报告、调度、计算、数据库和 Workflow 调用，但完整的依赖版本治理、跨接口兼容和自动回归不能直接视为现成功能，仍需要团队在 Skill 包和接入层建立规则。

依赖清单不能只写一个 API 地址

Agent Skills 规范允许 Skill 目录包含SKILL.md、脚本、参考资料和资源，也提供兼容性与版本元数据的位置。真正影响运行的依赖范围往往更大，包括接口版本、请求字段、响应 Schema、认证方式、模型能力、运行环境、脚本包和业务规则。只记录 URL，接口地址没变时，内部契约照样可能已经变化。

概念示意图：外部依赖先进入统一清单，再经过契约检查、失败样本和分阶段切换。

用稳定契约隔开 Skill 和接口变化

Skill 不宜直接依赖外部系统的全部原始字段。接入层可以把常用动作整理成稳定工具契约，固定输入、输出、状态和错误分类，再把不同 API 版本适配到同一契约。外部系统把customer_id改成另一种字段，变化停在适配层，Skill 继续使用稳定参数。

错误也要进入契约。权限不足、限流、超时、字段缺失和业务拒绝不能都压成一句调用失败，因为它们对应的处理方式不同。权限不足应该停止并申请授权，限流可以等待，超时需要查询动作是否已经生效，字段缺失则应阻断输出。错误语义稳定后，Workflow 才能走到正确分支。

契约层并不能消除升级风险。每个关键 Skill 至少要保留正常输入、缺少字段、权限失效和外部超时几类回归样本。升级前后分别运行，比较工具选择、请求参数、结构化输出、停止位置和业务结果。只比较最终文本，很容易漏掉中间调用已经走错的情况。

新旧依赖要允许短期并存

直接覆盖旧接口会让所有调用者同时承担风险。更稳妥的做法是给依赖生成明确版本，让少量测试任务先走新版本，旧版本继续承接生产任务。测试样本通过后再扩大范围；出现字段或权限异常时，切回旧版本，同时保留失败运行用于修正契约。

ZGI Runtime 可以承接 Skill、Workflow 和工具执行之间的运行关系，依赖清单、契约测试、灰度比例与回滚条件仍要由团队明确配置和验证。开始时可以挑一个调用频率最高的 Skill，列出它依赖的接口、脚本、模型和业务规则，再主动制造一次缺少字段和一次认证过期。两种失败都能停在预期位置，接口升级才算进入可治理状态。

GitHub：https://github.com/zgiai/zgi

Gitee：https://gitee.com/zgiai/zgi