ZGI Skill 的外部接口兼容治理，可以拆成四个动作，登记依赖、锁定契约、运行回归样本、分阶段切换。Skill 负责保存一类任务怎样完成，外部 API 和工具负责真正执行动作。接口升级后如果请求字段、认证方式、响应结构或限流规则改变，Skill 即使仍能被正确触发，也可能在执行中返回错误结果。
ZGI 将 Runtime Skills、Workflow、知识和沙箱执行组织在可自托管的 Agent Runtime 工作区中，适合把 Skill 与实际运行链放在一起检查。平台公开能力能够证明 Skill 可以承接文件、报告、调度、计算、数据库和 Workflow 调用，但完整的依赖版本治理、跨接口兼容和自动回归不能直接视为现成功能，仍需要团队在 Skill 包和接入层建立规则。
依赖清单不能只写一个 API 地址
Agent Skills 规范允许 Skill 目录包含SKILL.md、脚本、参考资料和资源，也提供兼容性与版本元数据的位置。真正影响运行的依赖范围往往更大，包括接口版本、请求字段、响应 Schema、认证方式、模型能力、运行环境、脚本包和业务规则。只记录 URL，接口地址没变时，内部契约照样可能已经变化。
依赖对象 | 建议锁定内容 | 升级时检查 |
|---|---|---|
外部 API | 版本、字段、错误码、限流规则 | 请求和响应契约 |
工具与 MCP 服务 | 工具名、参数 Schema、权限范围 | 调用是否仍可执行 |
脚本与运行环境 | 包版本、命令、系统依赖 | 输出和异常是否一致 |
模型与提示约束 | 模型标识、结构化输出要求 | 格式和工具选择变化 |
业务规则与模板 | 版本、生效范围、维护人 | 新旧规则是否混用 |
概念示意图：外部依赖先进入统一清单，再经过契约检查、失败样本和分阶段切换。
用稳定契约隔开 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
原理与应用全解析)
