Governance

规范目标

agent-service-spec 是 Agent as a Service 平台的统一真源，用于：

• 约束公共接口和内部平台契约
• 统一多语言 SDK 与 runtime 的行为
• 为后续实现、测试、代码生成与兼容性治理提供基线

规范性关键词

• MUST: 强制要求；实现不满足即视为不符合规范。
• SHOULD: 强烈建议；如不满足，必须有明确且可审计的偏离说明。
• MAY: 可选能力；实现可以支持或不支持，但必须明确声明。

规范层级

当不同文件看起来冲突时，按以下顺序解释：

1. state-machines/ 与 domains/ 中的语义与生命周期定义
2. schemas/ 中的机器可读对象结构
3. api/ 中的 transport 映射
4. examples/ 中的示例负载

补充规则：

• 如果字段语义与 wire shape 冲突，以 schemas/ 的字段结构为准，再通过文档修正语义说明。
• 如果 transport 文档与领域语义冲突，以领域语义和状态机为准。

版本策略

• 大版本目录使用 vN 管理。
• 大版本之间允许存在破坏性变更。
• 同一大版本内只允许：
  • 向后兼容的字段新增
  • 新增可选事件
  • 新增可选能力
  • 更清晰的语义澄清
• 同一大版本内禁止：
  • 删除必填字段
  • 改变已有字段类型
  • 改变既有状态机的合法转移含义
  • 复用旧字段表达新语义

变更分类

• patch: 纠正文档、示例、拼写、无语义变化的结构修复
• minor: 向后兼容的字段、接口、事件、能力新增
• major: 破坏性变化或语义重构

兼容性治理

• 所有偏离规范的现存实现必须记录到 v1/conformance/compatibility.md。
• 所有新实现必须以本规范命名和状态机为准，不得复制已有实现中的临时兼容字段。
• 实现方如需引入实验能力，必须使用明确的 capability 声明与版本门控，不得直接污染稳定字段。

变更流程

一次规范变更至少必须同步更新：

• 相关 Markdown 语义文档
• 至少一个机器可读 schema 或 API 文件
• CHANGELOG.md
• 如涉及兼容性影响，则更新 compatibility.md