SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场contract-author

contract-author

智能体与模型

查看项目

更新于 11-05 16:20

技能介绍

用途

Contract Author 是一个“契约先行”技能，用于在多智能体构建中，于任何实现开始之前生成机器可读的集成契约。它假设一种契约先行的多智能体构建模型：编排器并行调度角色智能体；每个角色智能体从 /contracts/ 消费机器可读契约；qe-agent 通过 qa-report.json 对构建进行把关。对于单智能体或临时性工作，该技能并不适用。

该技能在编排器的 Phase 4 运行，早于任何实现智能体被创建。其定位是：契约是可靠多智能体构建的基础——规范问题导致约 42% 的多智能体失败。没有契约时，各智能体会各自发明端点 URL、响应结构、类型定义与存储语义，结果是两个实现各自孤立可用却在集成时失败。契约通过预先定义接口来消除这一问题。

主要能力

  • 读取项目配置：检查 docs/agents/contract-format.md（由 /setup-project-skills 写入），该文件声明仓库偏好的契约格式与约定输出路径，并可能包含各智能体的消费说明。若存在，则以其为唯一事实来源；若缺失，则根据项目主语言回退检测（TS → TypeScript，Python → Pydantic，混合/HTTP 密集 → OpenAPI，事件驱动 → JSON Schema），并提示运行 /setup-project-skills 使选择持久化，不静默采用默认值。
  • 从计划中提取实体：领域实体（代表存储数据的名词）、关系、动作（成为端点的动词）、领域规则（跨智能体边界的业务逻辑）、集成点（需要契约覆盖的外部服务）。
  • 编写共享类型：始终先创建共享类型文件，作为单一扁平文件 contracts/types.<ext>（如 contracts/types.ts、contracts/types.py、contracts/types.json），而非目录 contracts/types/。定义每个实体、枚举、请求结构、响应结构与错误信封，使用可用的最强类型标注。
  • 编写 API 契约：以 references/openapi-template.yaml 为起点，为每个端点指定方法+路径、请求体、成功响应、错误响应、SSE/流式事件；必需章节包括约定、错误信封、CORS。
  • 编写数据层契约：以 references/data-layer-template.yaml 为起点，定义函数签名、返回类型、存储语义（流式/分块数据处理、级联删除、时间戳归属、ID 生成策略、必需索引）。
  • 编写事件契约（如适用）：以 references/asyncapi-template.yaml 为起点，定义频道/主题名、消息模式、投递保证、错误处理。
  • 分配横切关注点：将每个关注点明确分配给恰好一个智能体（URL 约定、响应信封、错误格式、CORS 配置、流式存储、无障碍等）。
  • 记录领域业务规则：在 contracts/README.md 的“Domain Rules”章节记录不变量、事务语义、幂等性要求、状态机转换。
  • 定义文件归属边界：在 contracts/README.md 中包含一张表，映射哪个智能体拥有哪些文件/目录，防止并行实现时的冲突。
  • 添加各智能体实现说明：说明应使用哪些库/框架、如何从共享类型文件导入或生成类型、以及智能体特定模式。
  • 质量检查清单：在将契约交给编排器之前，核对 URL 精确、响应结构为显式 JSON、所有状态码已指定、SSE 事件类型有精确 JSON 结构、存储语义明确、共享类型定义一次并被引用、尾斜杠约定已声明、错误信封已定义、横切关注点各分配给一个智能体、CORS 源已指定、每个契约已版本化（从 v1 开始）、领域业务规则已记录、文件归属边界已定义、各智能体实现说明已包含、所有契约文件中字段名一致、复杂度与项目范围匹配；TypeScript 项目还需 contracts/tsconfig.json 存在并能通过 tsc --noEmit 干净类型检查。

使用方式

该技能按以下流程执行：

0a. 读取项目配置 docs/agents/contract-format.md。若存在，使用其声明的格式与输出路径，跳过步骤 1 中的格式选择；若缺失，回退检测并提示。

0b. 从计划中提取实体、关系、动作、领域规则与集成点。

  1. 从共享类型开始：先创建共享类型文件，作为单一扁平文件 contracts/types.<ext>。按主语言选择格式：TypeScript → references/typescript-template.ts → contracts/types.ts；Python → references/pydantic-template.py → contracts/types.py；多语言 → references/json-schema-template.json → contracts/types.json。

  2. 编写 API 契约：使用 references/openapi-template.yaml，为每个端点指定方法+路径、请求体、成功响应、错误响应、SSE/流式事件；必需章节包括约定、错误信封、CORS。

  3. 编写数据层契约：使用 references/data-layer-template.yaml，定义函数签名、返回类型、存储语义。

  4. 编写事件契约（如适用）：使用 references/asyncapi-template.yaml。

  5. 分配横切关注点：每个关注点分配给恰好一个智能体。

  6. 记录领域业务规则：写入 contracts/README.md 的“Domain Rules”章节。

  7. 定义文件归属边界：在 contracts/README.md 中包含归属表。

  8. 添加各智能体实现说明。

  9. 执行质量检查清单。

契约版本化：所有契约从 v1 开始。构建期间需要变更时，递增版本、编写完整更新后的契约（而非仅差异）、通知所有受影响智能体并取得确认。变更日志仅存放于 contracts/CHANGELOG.md；生成的类型/契约文件最多在顶部带一行 // — vX.Y.Z 版本标记，绝不在文件内联多行版本历史块。

输出物（机器可读格式，非 markdown 叙述）：contracts/types.[ts|py|json]（单一扁平文件）、contracts/tsconfig.json（TypeScript 项目必需，须扩展工作区基础 tsconfig）、contracts/openapi.yaml（OpenAPI 3.1 规范）、contracts/data-layer.yaml、contracts/asyncapi.yaml（如适用）、contracts/README.md（含约定、命名转换表、横切关注点分配、领域业务规则、文件归属边界、各智能体实现说明、端点快速参考）、contracts/CHANGELOG.md（契约版本历史的唯一记录系统）。schemas/ 目录用于项目在 API 上下文之外使用基于模式的验证时的独立 JSON Schema 文件。

命名约定规则：当 API 使用 camelCase（OpenAPI/TypeScript）而后端使用 snake_case（Python）时，须在 contracts/README.md 中明确记录转换；Pydantic 模板包含 alias_generator=to_camel，双方必须就线上格式达成一致。

适用场景

适用于契约先行的多智能体构建：编排器并行调度角色智能体、每个角色智能体从 /contracts/ 消费机器可读契约、qe-agent 通过 qa-report.json 把关的构建模型。

限制

  • 权衡：偏向前期设计而非快速迭代。对于原型，跳过契约并使用直接模块导入。
  • 对于单智能体或临时性工作，该技能不是合适的工具。
  • 禁止为未来功能推测性地编写契约；只编写当前调度所需的契约。
  • 需匹配契约复杂度与项目范围：个人习惯追踪器配 SQLite 不需要 JWT 认证模式、AsyncAPI 规范或复杂安全中间件契约；无认证则完全省略安全方案；无实时组件则跳过 AsyncAPI；SQLite 项目使用自增 ID 而非 UUID，PostgreSQL 项目可使用 UUID v4。过度设计的契约会浪费智能体时间实现不必要的复杂度。
  • 关于具体收费、价格、平台支持等信息，资料中暂未提供。