> ## 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 在 PR 触及边界表面时能读取服务间的契约与 API。

当产品拆分在多个仓库中时——例如调用后端 API 的前端，或依赖共享契约包的服务——仅审查单个仓库可能会漏掉边界上的破坏。**关联仓库**（*linked repositories*）在代码审查期间为 Kody 提供这些兄弟代码库的可选、按需上下文。

> **计划要求：** 关联仓库适用于 **Teams** 和 **Enterprise** 计划（试用作为预览包含在内）。Free 计划不包含跨仓库上下文。

这与[跨代码库共享编码标准](/knowledge_base/zh/how-to-share-standards-across-repositories)（组织级规则与继承）不同。关联仓库共享的是审查用的**源码上下文**，而不是审查规则。

## 它做什么

对正在审查的仓库，你可以在同一组织中声明最多 **3** 个关联仓库。审查过程中：

1. Kody 用**确定性边界门控**（无 LLM）查看 PR diff。
2. 若 diff 看起来触及**契约表面**（DTO、export、字符串字面量、状态键、类 API 路径等），则启用跨仓库工具。
3. 仅当 Kody 真正需要读取或搜索时，才**懒克隆**关联仓库。
4. 发现仍**只锚定在当前 PR 的行上**——关联代码是证据，不是第二个审查目标。

若未配置任何关联，该功能完全关闭（零额外成本）。

## 在控制台中配置

关联仓库是**按仓库**的，不是全局的。关系是有方向的：`frontend` 上的关联仅在审查 `frontend` 的 PR 时生效。

1. 打开**代码审查设置**。
2. 选择**具体仓库**（不是 Global）。
3. 打开该仓库菜单中的 **Linked Repositories** 页面。
4. 在 **Linked repositories** 中添加已连接到组织的兄弟仓库。
5. 可选设置：
   * **Instructions** — 给 Kody 的自由文本提示（例如：“此前端消费的 REST API”）。
   * **Ref** — 可选的 branch/tag 固定。留空则使用自动 ref 级联（见下）。
6. 保存。

最多可关联 **3** 个仓库。仅接受已连接到同一组织的仓库。

## 在 `kodus-config.yml` 中配置

也可以在仓库配置文件中声明关联：

```yaml theme={null}
linkedRepositories:
  - repository: "org/backend-api"
    instructions: "REST API this frontend consumes"
    ref: main   # 可选固定；省略则使用同名分支级联
```

* `repository`（必填）：已连接到组织的仓库全名（`owner/repo`）。
* `instructions`（可选）：简短说明关联原因。
* `ref`（可选）：固定 branch、tag 或 commit。省略时 Kody 使用 ref 级联。

空的 `linkedRepositories: []` 表示功能关闭。

## 如何选择 ref

对每个关联仓库，Kody 按以下顺序尝试 ref，并使用第一个成功克隆的：

1. 该仓库的 **PR 描述覆盖**（见下）
2. **配置中的 `ref` 固定**（若已设置）
3. 关联仓库上 head 分支与 PR head 分支匹配的**打开中的 PR**
4. 关联仓库上的 **PR head 分支名**
5. 关联仓库的**默认分支**
6. 回退：`main`，然后 `master`

这使跨服务存在同名分支时的多仓库功能工作保持对齐，并在普通 PR 上安全回退。

## 通过 PR 描述覆盖 ref

对于一次性审查（例如对照某个后端 PR 审查），在正在审查的 PR 的**标题或描述**中提及已关联的仓库。覆盖仅适用于配置中**已经关联**的仓库。

支持的形式：

| 形式                  | 含义                                       |
| ------------------- | ---------------------------------------- |
| `owner/repo#123`    | 使用该仓库上 PR/MR `#123` 的 head               |
| PR/MR URL           | 同上（GitHub、GitLab、Bitbucket、Azure DevOps） |
| `owner/repo@branch` | 在关联仓库上固定该分支                              |

示例：

```text theme={null}
Depends on org/backend-api#842
Also needs org/shared-contracts@feature/new-events
```

同一仓库的后续提及优先。提及**未**关联的仓库会被忽略（不会创建新关联）。

## 何时激活跨仓库上下文（边界门控）

即使已配置关联，Kody **也不会**总是打开兄弟仓库。廉价、确定性的门控扫描 PR diff 中的**新增行**，仅在发现**边界表面**时激活，例如：

* 字符串字面量（路径片段、代码、事件名等）
* export（`export function`、类型、类等）
* enum / type / interface
* 对象或 payload 字段键
* status / state / error-code 类标识符
* 类契约路径（`dto`、`schema`、`api`、`client`、`openapi`、`proto` 等）

仅移动或重排非边界代码的内部重构通常保持门控关闭——克隆与边界提示保持空闲。

## Kody 对关联仓库能做什么、不能做什么

**可以：**

* 在门控开启时搜索并读取关联仓库中的文件
* 使用你的 **instructions** 理解关系
* 在当前 PR 的发现中将关联代码作为支持证据引用

**不能 / 不会：**

* 对仅存在于关联仓库中的文件发布审查评论
* 把整个关联仓库当作 PR 来审查
* 关联组织外或未连接到 Kodus 的仓库
* 超过每个审查仓库 3 个关联仓库的软上限

## 审查结束时的透明度

当关联仓库参与了运行时，审查元数据会记录配置了哪些仓库、解析了哪些 ref（以及来源：描述、固定、打开的 PR、head 分支或默认分支），以及边界门控是否激活。失败或跳过的关联会以警告形式呈现，而不会使整次审查失败。

## 推荐设置

| 场景                 | 从何处关联                  | 典型 instructions         |
| ------------------ | ---------------------- | ----------------------- |
| Frontend ↔ backend | Frontend → API 仓库      | “此 UI 依赖的 HTTP/REST 契约” |
| 服务 ↔ 共享契约          | 服务 → contracts/package | “共享事件、DTO 与 protobuf”   |
| BFF ↔ 多个后端         | BFF → 最多 3 个 backend   | 每个服务边界一行简短说明            |

优先使用**窄、有方向**的关联（消费者指向生产者），而不是把所有仓库互相连起来。

## 相关指南

* [如何跨代码库共享编码标准](/knowledge_base/zh/how-to-share-standards-across-repositories) — 组织级规则与继承（不是源码上下文）
* [如何使用项目特定上下文审查 PR](/knowledge_base/zh/how-to-review-prs-with-project-context) — 记忆、文件引用、自定义提示、MCP
* [如何减少代码审查噪音](/knowledge_base/zh/how-to-reduce-code-review-noise) — 增加上下文时仍保持审查聚焦