bidirekt

Bidirekt 合约

根据服务代码编写和更新服务的 Bidirekt 合约文件，将其与代理进行核对，并根据部署检查报告修复。

https://bidirekt.com/llms.txt 是唯一参考资料。合约文件的规则、带标志和提示信息的 CLI 命令、报告格式，以及每条中断项的含义，都来自该文件；本文仅说明步骤。在每个步骤中：

• 合约描述代码的实际行为。只修改服务自身的合约文件，绝不修改代码，也绝不只是为了让检查通过而修改合约。
• 只运行读取类 CLI 命令：本地验证（它会检查文件，并将其与已部署到某个环境中的对应合约进行比较，不会存储任何内容）、参与方列表和环境列表。
• 绝不在代理中存储合约版本，绝不运行部署检查（它会询问某个已存储版本是否可以部署，并在代理中记录结果），绝不记录部署，绝不创建参与方或环境，也绝不重命名参与方。这些都由工程师执行。

1. 阅读 llms.txt

在做任何其他事情之前，获取 https://bidirekt.com/llms.txt 并以原始文本形式阅读完整文件。严格运行 curl -sSfL https://bidirekt.com/llms.txt，不得添加其他标志，也不得与其他命令串联：-f 已会在任何非 2xx 响应时失败。只有在没有 shell 的情况下才使用网页抓取；如果返回的是摘要而不是文件，则视为无法读取参考资料。每个步骤都必须遵循其中的规则、命令和提示信息。

如果获取失败、响应不是 200，或内容不是 Bidirekt 参考资料（例如 HTML 页面、停放域名页面或错误页面）：立即停止，告知工程师无法读取 https://bidirekt.com/llms.txt 上的参考资料，并且不要写入任何内容。绝不要凭记忆或依据其他副本编写合约，也绝不要猜测语法。

2. 检查 CLI 和代理

在写入任何内容之前，运行参与方列表。运行时需要满足以下条件：llms.txt 指定的 CLI 二进制文件位于 PATH 中，并且已配置代理：

• 找不到该二进制文件：停止，并展示 llms.txt 的 ## Setup 部分中用于安装 CLI 并将其指向代理的命令。
• CLI 提示未配置代理（llms.txt 记录了该提示信息）：
  • 如果同时指定了一个配置文件：使用该配置文件，并在之后的每条命令中使用 BIDIREKT_PROFILE=<name> 或 --profile <name>，同时告知工程师你使用了哪个配置文件；
  • 如果指定了多个配置文件：询问工程师要使用哪一个，然后等待回复；
  • 如果未指定配置文件：停止，并展示 ## Setup 中用于将 CLI 指向代理的命令。
• 任何其他错误：停止，并向工程师展示错误信息。

绝不要自行安装 CLI 或将其指向代理：这些操作由工程师完成。

3. 确定名称

阅读代码，然后在写入任何内容之前确定所有名称。需要工程师确认名称时，先询问并等待回复。

• 服务自身的参与方：从项目已有的 CLI 传参位置获取（例如 CI 工作流或脚本）；否则询问工程师。绝不要将其保存到任何地方。
• 本地验证所用的环境：从相同位置获取，或询问工程师。与环境列表核对。如果列表中没有该环境，不要使用它运行任何命令：展示列表中相似的名称并询问。
• 服务调用的每个提供方：根据代码推断其参与方名称（客户端名称，或类似 PETSTORE_API_URL → petstore_api 的环境变量），并与参与方列表核对。如果列表中没有该名称，不要写入该提供方：展示相似名称（petstore_apl → petstore_api？）并询问。如果工程师确认代理中尚不存在的新提供方，则写入该提供方，并警告工程师：在该提供方将其合约存入代理之前，部署检查会失败。仅由该提供方导致的中断项属于预期情况：保留相关调用，并报告这些中断项。

4. 根据代码编写契约

无论使用哪种语言，都要在代码中找到：

• 服务提供的资源，其类型须属于 llms.txt 文档所述的类型 → provides；
• 服务对其他服务发起的调用 → consumes，按第 3 步中各提供方的名称分别列出；
• 服务提供、读取和发送的正文类型 → schemas。

按照 llms.txt 的说明编写。如果代码执行的操作无法用 llms.txt 表达，就将其省略并告知工程师；切勿自行编造语法。

根据代码的实际行为填写 optional 和 nullable，并遵循 llms.txt 中关于如何对 null 和缺失值建模的规则，切勿仅依据声明的类型。如果类型声明为可空或可选，但没有任何代码路径会产生 null 或省略该键，就两者都不要填写，并告知工程师该类型的范围比代码实际行为更宽。如果无法从代码中判断，就提出询问。

目录：contracts/，或项目已有的契约目录（例如，CI 传给 CLI 的文件所在目录）。

文件组织方式建议（而非规则）：

• 模块化项目：每个模块一个文件；
• 非模块化且资源较少：一个文件；
• 资源超过 50 个，或 schema 超过 50 个：拆分为多个文件，例如 provides.yaml 和 consumes.yaml；
• 单体架构还是微服务架构不影响这一点：上下文均为当前服务；
• 项目已有组织方式：遵循现有方式。

如果文件不止一个，遵循 llms.txt 中关于多个文件的规则。

5. 更新现有契约

如果契约文件已存在，就在原文件中编辑；切勿重新生成文件。

• 只修改代码有变动的部分。保留注释、顺序、格式以及所有 description。
• 只有当代码不再使用某个资源或属性时才将其删除，并在最终答复中列出每一项删除：对于提供方一侧，删除可能会导致消费者出现问题。

6. 检查变更

1. 运行参与方列表，并按照第 3 步的做法，检查 consumes 中的每个提供方名称。
2. 使用参与方、环境和文件运行本地验证。
3. 根据验证结果，按照 llms.txt 的说明修正契约，并按照第 8 步的方式处理每一项破坏性变更，然后重新运行上述两项检查，直至验证通过。

如果剩下的唯一修正会与代码相矛盾，就停止循环并告知工程师：要么修改代码，要么向对接方提出请求；并按照第 8 步写明请求。如果剩下的破坏性变更仅是新增提供方时预期会出现的变更（第 3 步），也要停止并报告。

如果本地验证提示该服务自身的参与方不存在，就停止并告知工程师，同时列出参与方列表中的相似名称：是否创建该参与方由工程师决定。

7. 完成

列出已编写或修改的文件、所有删除项、所有警告以及所有对接方请求。如果契约文件有变更，就在答复末尾写出下一条要运行的命令：llms.txt 中用于将契约存入 broker 的命令，包含参与方和文件，并将版本写为占位符（或使用项目 CI 中的版本）。

8. 根据部署检查报告修复契约

工程师会在对话中粘贴报告，或指出包含报告的文件（CI 日志）。执行步骤 1 和 2，并按照步骤 3 确定服务自身的参与方和环境（报告会标明环境）。按照 llms.txt 文档说明的格式查找报告，并结合 llms.txt 中解释每条中断及其修复方法的部分，逐条阅读中断行。

对于每条中断行，在服务的契约和代码中找到它所指的位置（对应方、端点、方法、请求或响应状态、属性路径），并判断由哪一方的修改来修复：

• 如果服务的契约没有描述其代码在该处的行为（例如，代码不会读取该属性，或不需要该属性也能正常工作），则由服务修改：按照 llms.txt 针对该行给出的方法修改契约，使其与代码一致，然后重新执行步骤 6。
• 如果契约已描述代码的行为，则由对应方修改：即使可以访问对应方的文件，也不要修改对方的内容，而是写明给对应方的修改请求，包括要改什么、在哪里改（端点、方法、请求或响应状态、属性路径），以及原因（对应的中断行）。如果修改服务的代码也能修复问题，则应说明这一点；由工程师决定如何处理。

然后按照步骤 7 完成。