> ## 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.

# 引导评审（聚焦）

> 通过 PR 评论或 CLI 使用一次性的评审指令，将 Kody 的注意力引导到拉取请求的特定区域

**评审指令**让你告诉 Kody 在单次评审中应把最深入的分析集中在哪里。你无需修改任何配置，只需在触发评审时附上一条简短说明——例如"聚焦于认证和会话逻辑"——Kody 便会把最严格的分析用在匹配的改动代码上。

<Note>
  指令是**临时的**：仅对该次评审运行生效。它不会保存到你的设置中，也不会影响后续评审。若要永久改变 Kody 的行为，请改用 [Custom Prompts](/zh/how_to_use/code_review/configs/custom_prompts) 或 [Kody Rules](/zh/how_to_use/code_review/configs/kody_rules)。
</Note>

## 何时使用

* 一个 PR 改动了很多文件，但你最关心其中某个高风险区域（认证、支付、数据库迁移）。
* 你希望 Kody 追踪某处改动的调用方与被调用方，并更严格地审视它。
* 你在重新运行评审，想在不编辑任何配置的情况下引导注意力。

## 是优先级，而非过滤器

这是最需要理解的一点：

<Warning>
  指令设定的是**优先级，而不是过滤器**。Kody 会优先关注聚焦区域，但仍会报告它在 diff **其他位置**发现的任何具体缺陷、安全或性能问题。它绝不会隐藏聚焦之外的发现，也不会未经查看就批准 PR 的其余部分。
</Warning>

用指令来表达 *"这里要最重点地看"* ——而不是 *"只看这里"*。

## 如何触发

<Tabs>
  <Tab title="PR / MR 评论">
    在拉取请求评论中，紧接评审命令之后写上你的聚焦文本：

    ```text theme={null}
    @kody review 聚焦于认证和会话逻辑
    ```

    你也可以使用 `start-review`，并与 `--force` 组合：

    ```text theme={null}
    @kody start-review 聚焦于新的数据库迁移
    @kody review --force 聚焦于 webhook 解析器的错误处理
    ```

    <Note>
      `--force` 会强制重新执行审查，即使 Kody 通常会跳过（"自上次审查以来没有新提交"）。无论是否附带聚焦指令，都可以在修复了导致上次运行失败的问题后获取全新审查，或将更新后的配置应用到已审查过的 PR。
    </Note>

    <Note>
      只有命令之后的**第一行**会被用作指令。后续各行都会被忽略，因此请把聚焦内容写在一行内。
    </Note>

    支持 GitHub、GitLab、Azure DevOps、Bitbucket 和 Forgejo。
  </Tab>

  <Tab title="CLI">
    运行评审时传入 `--focus` 参数：

    ```bash theme={null}
    kodus review --focus "认证和会话逻辑"
    ```

    完整命令请参见 [CLI 命令参考](/zh/how_to_use/cli/commands)。
  </Tab>
</Tabs>

## Heavy mode

<Warning>
  **Alpha —— 需申请开通。** Heavy mode 对任何组织都不是默认开启的。想试用请通过
  [Discord](https://discord.gg/TFZBRk9fT6) 或 [support@kodus.io](mailto:support@kodus.io)
  联系我们为你的组织开通。在此之前该标志会被接受但不产生任何效果 —— 参见下方的
  [可用性](#可用性)。
</Warning>

聚焦指令告诉 Kody *在哪里*看得最仔细。`--heavy` 则告诉它看得*更久*:finder 会对同一份 diff
额外执行几轮"你漏掉了什么?"的批评式检查,以更慢的审查和更多待筛选的候选为代价,发现更多
真实问题。

```text theme={null}
@kody review --heavy
@kody review --heavy focus on the payment reconciliation logic
kodus review --heavy
```

`--heavy` 可以放在命令行的任意位置 —— 在聚焦文本之前或之后 —— 两种情况下都会从指令中被剔除,
因此 `@kody review 关注重试逻辑 --heavy` 聚焦的是"关注重试逻辑"。

<Warning>
  **要与 `--force` 组合使用时,请把 `--force` 放在前面。** `--force` 只有紧跟在命令之后才会被
  识别,因此 `@kody review --force --heavy` 会执行一次强制的 heavy 审查,而
  `@kody review --heavy --force` 执行的是**未**被强制的 heavy 审查。
</Warning>

短横线是必需的:单独的 `heavy` 会被当作指令文本,因此 `@kody review heavy 结账路径` 聚焦的是
"heavy 结账路径",而不会启用该标志。

### 可用性

Heavy mode 是一个 **alpha** 功能。它只对我们显式开通的组织生效:

|         | 状态                                                              |
| ------- | --------------------------------------------------------------- |
| **云端**  | 可申请开通 —— 我们会把你的组织切换到 `alpha` 发布轨道。                              |
| **自托管** | 尚未提供。无论 `BETA_FEATURES` 如何设置,alpha 功能都保持关闭;等它升级为 beta 后才会进入自托管。 |

<Note>
  **该标志会静默降级,而不是报错。** 如果你的组织未开通,`--heavy` 会被接受,审查则**按正常方式
  运行** —— 没有报错、没有警告、结果也没有区别。如果你申请了访问却无法判断它是否生效,请联系
  我们,不要凭猜测。
</Note>

如需申请访问,请带上你的组织名称,通过 [Discord](https://discord.gg/TFZBRk9fT6) 或
[support@kodus.io](mailto:support@kodus.io) 联系我们。

<Tip>
  在漏掉问题代价高昂的改动上使用它 —— 迁移、认证改动、支付链路 —— 而不是把它当默认。
  在日常 PR 上,多出来的候选通常是你还得再筛一遍的噪音。
</Tip>

## 如何写好一条指令

* **明确区域，而非结论。**"聚焦于队列消费者的并发"比"找出缺陷"更有效。
* **指名代码，而非结果。** 指向某个模块、流程或关注点（"重试逻辑"、"报表服务中的 SQL"）。
* **保持简短。** 指令上限为 **500 个字符**；只会读取评论的第一行。

<AccordionGroup>
  <Accordion title="好的示例">
    - `@kody review 聚焦于认证与令牌刷新流程`
    - `@kody review 聚焦于新的 Stripe webhook 处理`
    - `kodus review --focus "后台 worker 中的竞态条件"`
  </Accordion>

  <Accordion title="较弱的示例">
    * `@kody review 请仔细一点` —— 没有可优先的区域。
    * `@kody review 只评论文件 X` —— 指令不是过滤器；请用[忽略路径](/zh/how_to_use/code_review/configs/general)来限定文件。
  </Accordion>
</AccordionGroup>

## 说明与限制

* **长度：** 指令会在 500 个字符处截断。
* **仅第一行：** 在 PR 评论中，只有命令之后的第一行会成为指令。
* **设计上不信任：** 由于任何能评论 PR 的人都可以提供指令，文本在使用前会被清洗（去除控制字符和尖括号）。这不会改变你的聚焦——只是防止文本篡改 Kody 的内部提示词。
* **不持久化：** 不会向你的仓库或组织设置写入任何内容。