> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 关联代码库

> 让 Kody 在审查时把兄弟代码库作为上下文读取,从而发现跨代码库的契约不匹配。

关联代码库让 Kody 在审查一个 pull request 时,把兄弟代码库作为**只读上下文**读取。用它来发现单代码库审查看不到的 bug:后端重命名了一个 API 字段而前端仍在读旧字段、producer 新增了一个没有任何 consumer 处理的枚举值,或者 writer 与 reader 用不同方式推导同一个 key。

在 **Teams 和 Enterprise** 套餐中可用。按**代码库**配置 —— 没有全局默认值,因为这种关系是有方向的:关联 `frontend → backend-api` 意味着*对 `frontend` 的审查*可以查阅 `backend-api`,反之则不然。如果两个团队都想要这项检查,请显式地关联两个方向。

## 你会得到什么

举个具体例子。你的前端 PR 新增了这段错误处理:

```ts theme={null}
const isNotApproved =
    error.response?.data?.error === 'INTEGRATION_NOT_APPROVED';
```

关联了后端之后,Kody 会检查该契约的另一侧,并在 PR 上评论:

> **Bug · medium** —— 前端检查 `error.response?.data?.error` 是否为 `INTEGRATION_NOT_APPROVED`,但后端的 `sendError` 是在 `message` 字段中返回该代码的。not-approved 分支永远不会命中,因此用户始终看到通用错误提示。请改为读取 `data.message`。

审查摘要也会显示查阅了什么:**Additional context used:** `org/backend-api@main`。

## 工作原理

当一个配置了关联代码库的代码库中的 pull request 触及边界面(变更的字符串字面量、载荷字段、状态值、导出符号)时,Kody 的审查代理可以搜索并读取关联代码库 —— 就像在你自己的代码库中做 grep 一样 —— 以验证契约两侧是否仍然一致。只有在对应文件中获得确凿证据时才会提出发现,而且评论始终落在**你的** PR 的某一行上;关联代码库的代码只会作为佐证被引用在评论内,绝不会被直接评论。

使用了跨代码库上下文的审查会明确说明:审查摘要中会包含一行 **Additional context used**,列出每个代码库以及读取时所用的 ref。

<Info>
  * 只有**已连接到同一 Kodus 组织**的代码库才能被关联(Kody 复用你已有的 Git 集成 —— 无需额外令牌)。
  * 每个代码库最多关联 **3 个**代码库。
  * 访问为只读。Kody 绝不会向关联代码库推送、评论或修改内容。
  * 如果关联代码库无法获取(权限、超时),审查会在没有它的情况下正常继续。
</Info>

## 添加关联代码库

进入 **Code Review Settings → *你的代码库* → Linked Repositories**,从列表中选择一个代码库(只显示已连接的),然后保存。每个关联有两个可选字段,说明如下。

### Instructions(说明)

一段自由文本提示,告诉审查代理**这个关联是做什么用的、该看哪里**。没有它 Kody 也能工作,但一条好的说明会让跨代码库这一趟更快更准 —— 差别在于代理是从零开始探索关联代码库,还是直奔相关代码。

好的说明会点明关系和关键路径:

```text theme={null}
这个 dashboard 消费的 REST API。错误响应由
src/api/response.ts 构建 —— 请对照它核对错误码。
```

```text theme={null}
共享的订单状态机。状态枚举位于
src/domain/order-status.ts;我们必须处理它定义的每一个值。
```

差的说明只是重复显而易见的内容("后端代码库"),没有任何增益。

### Ref pin(分支选择)

控制 Kody 读取关联代码库的哪个分支("ref")。**大多数团队会留空**:此时 Kody 会读取与你 PR 分支同名的分支(如果存在),这样跨代码库的协同改动在合并前就能互相看到;否则回退到默认分支。

完整的解析顺序,先命中者胜出:

1. **PR 描述覆盖** —— 在被审查 PR 的描述中提及关联代码库的分支或 PR(例如 `org/backend-api#123` 或 `org/backend-api@feature-x`)。一次性,优先级最高。仅对已关联的代码库生效。
2. **配置中的 `ref` pin**(此字段),如果已设置。
3. **匹配分支上的开放 PR** —— 关联代码库中某个开放的 pull request,其 head 分支与你 PR 的 head 分支一致。
4. 关联代码库中的**同名分支**。
5. 关联代码库的**默认分支**(然后以 `main`/`master` 作为兜底)。

第 3–4 步正是让跨代码库的特性开发保持同步的关键:审查能在配套改动合并*之前*就看到它,而不是看到一个尚未包含它的默认分支。

当你希望针对某个稳定分支得到确定性的审查结果时,设置 **ref pin**(例如 `main`、`develop`、`release/2.x`) —— 例如分支名在多个代码库间被复用于互不相关的工作,同名匹配会选错目标。对于一次性场景,PR 描述覆盖仍然优先于 pin。

审查摘要始终会显示实际使用的 ref。想看带示例的完整流程,参见[如何使用关联代码库](/knowledge_base/zh/how-to-use-linked-repositories-in-code-review)。

## 何时使用

当多个代码库共享一个工具链无法强制保证的契约时,关联代码库最有价值:

* 在两侧各自重复声明载荷结构的 **前端 ↔ 后端** 组合。
* 传递状态值、事件名或 ID 的 **服务 ↔ 服务** 集成。
* 重新实现或镜像共享库类型的 **共享库使用方**。

<Note>
  关联代码库**不**覆盖存在于你代码之外的契约 —— 例如第三方 API 的校验规则,在任何关联代码库中都无法被发现。
</Note>