业务逻辑验证

概述

业务逻辑验证检查拉取请求是否交付了任务所要求的内容。Kody 找到 PR 引用的任务，从你的任务管理工具中读取它，并列出每条需求在代码中的状态。结果是 PR 上的一条评论，并保持最新，在 GitHub、GitLab、Bitbucket、Azure Repos 和 Forgejo 上都一样。当 PR 只交付了任务的一部分时，评论如下：

Kody · Business Logic #291 · Ticket SLA badge — 待修复：缺少 2 项需求
需求在此 PR 中
✅ MET 工单标题栏显示一个标出剩余 SLA 时间的徽章。 TicketPanel.tsx:40 · 标题栏中显示了徽章，内容为 “SLA Xh Ym”。
❌ MISSING 剩余时间少于 1 小时时，徽章变为红色。 SlaBadge.tsx:14 · 徽章始终使用 “info” 色调。Do: 少于 60 分钟时切换为 danger 色调。
❌ MISSING 已解决的工单不显示徽章。 TicketPanel.tsx:40 · 无论状态如何都会显示。Do: 工单已解决时隐藏它。

	需求	在此 PR 中
✅ MET	工单标题栏显示一个标出剩余 SLA 时间的徽章。	`TicketPanel.tsx:40` · 标题栏中显示了徽章，内容为 “SLA Xh Ym”。
❌ MISSING	剩余时间少于 1 小时时，徽章变为红色。	`SlaBadge.tsx:14` · 徽章始终使用 “info” 色调。Do: 少于 60 分钟时切换为 danger 色调。
❌ MISSING	已解决的工单不显示徽章。	`TicketPanel.tsx:40` · 无论状态如何都会显示。Do: 工单已解决时隐藏它。

修复后，同一条评论会变为 “All requirements met · ✅ 3 of 3 met”，并在下方保留之前的检查结果。

前提条件

在 Plugins 中连接的任务管理工具：Linear、Jira (Atlassian Rovo)、Notion、Git Issues 或自定义插件。
Kody 只按 ID 读取任务，以及任务所链接的内容（父任务、子任务、附加文档）。它从不搜索任务，也从不写入你的任务管理工具。
没有任务管理工具时，你仍然可以在命令中粘贴任务文本（见下文）。

启用

Business Logic 默认启用。在 Code review → What to review 的 Business Logic 一行中，或在 kodus-config.yml 中开启或关闭：

reviewOptions:
  business_logic: true

点击该行的 Business Logic 打开其设置，或使用该行的 ⋯ 菜单：Edit 打开设置，Try it 直接打开测试面板。

Kody 如何找到任务

Kody 按顺序在 PR 标题、分支名和描述中查找任务引用：

类似 PROJ-123 的键（Jira、Linear 和大多数任务管理工具）
#123 和 owner/repo#123（Git issues；属于拉取请求的编号会被忽略）
AB#123（Azure Boards）
指向 Linear、Jira、Notion、GitHub/GitLab issue 和 Azure work item 的链接

只有当任务管理工具返回 ID 完全一致的任务时，引用才算数，因此标题中的 UTF-8 或 gpt-5 永远不会被误认为任务。标题中的小写键（feat(kod-10)）在你的任务管理工具中存在该团队或项目时算数；Linear 项目 ID（P-KOD-1）永远不算。 Kody 还会读取任务所链接的内容：

父任务（Linear 子 issue、Jira 子任务、ClickUp 子任务）：PR 会与本任务标题所涵盖的父任务需求进行核对。只写着”见父任务”的子 issue 也会被检查。
子任务：由某个子任务交付的需求显示为 CHECK MANUALLY（“Delivered by KOD-20”），永远不会显示为缺失。
附加到任务的文档（Linear docs）：作为任务的一部分读取，包括其中的验收标准。

PR 如何引用任务

“Closes PROJ-1”，或标题、分支中的键：PR 与整个任务进行核对。
“Part of PROJ-1”：PR 只交付其中一部分。缺失的内容会列出，但不作为合并前需要完成的事项。
描述中的 “Refs PROJ-1”、“see PROJ-1” 或 “related to PROJ-1”：只是提及。仅当 PR 没有指明其他任务时才会检查，此时将其视为 PR 自身的任务。
每个 PR 最多检查三个任务，每个任务一个部分。引用更多任务的 PR（例如发布或合并）会被跳过。

五种状态

状态	含义	需要修复
MET	diff 实现了该需求。	否
PARTIAL	需求所述内容已部分实现。	否，仅显示：完成一半属于主观判断，两次运行之间可能不同
MISSING	此 PR 的 diff 中没有证据，或 PR 依赖的代码没有实现它。	是
CHECK MANUALLY	视觉或流程类需求、Kody 读过仓库后仍不确定的需求，或可能位于过大而无法读取的文件中的需求。	从不
NOT IN TASK	任务没有要求的变更。	否，仅显示

每一行都会引用其依据的文件和行号，并说明需要修改什么。

显示差距之前

差距意味着要求作者返工，因此 Kody 会用代码核实每一个差距：

按任务原文理解需求。 任务从未提及的输入或边界情况（负数金额、另一条代码路径、未提及的格式）永远不会使某行变为 PARTIAL，变更之后发生的事情也不会（例如现有任务是否发送了 PR 放入队列的消息，某个路由是否使用了 PR 填充的序列化器）。
PR 调用的代码，而不只是 diff。 当规则位于 PR 调用但未修改的代码中（验证器、辅助函数、构建响应的 mapper），Kody 会在显示任何内容之前，在 PR head 处的仓库中读取它，并对每一个 MISSING、PARTIAL 和 CHECK MANUALLY 行做同样的事。只有基于 Kody 读过的文件和行，某行才会变为 MET，并注明它已存在于代码中、位于 diff 之外。只有当 Kody 读过 PR 所依赖的代码并引用缺少该规则的那一行时，某行才会变为 MISSING。仓库无法确定的内容保持原状。
属于别处的工作。 由子任务交付的需求，或团队指南说明不在此处检查的需求，保持为 CHECK MANUALLY，永远不会被重新判定为缺失。

在拉取请求上

Kody 在 PR 的首次审查时进行检查。之后，当有人评论 @kody -v business-logic 或运行 @kody review --force 时会再次检查。Re-check 也可以设置为仍有缺失时每次 push（修复后评论会自动更新，无需任何人请求），或每次 push；每种都会让每次 push 多一次验证。
随时可以用 @kody -v business-logic 重新检查。同一条评论会被编辑；Kody 从不发布第二条评论。
满足任务的 PR 会收到一行评论（”✅ 4 of 4 met”），外加需要手动检查的内容，让作者知道已经检查过。关闭 Comment when every requirement is met 可在这种情况下不发评论。
评论是所有平台上的信号：Kody 不写入 check 或 status，因此它本身永远不会阻止合并。评论标题会说明还有哪些需要修复。

回复评论

回复 Business Logic 评论并提及 @kody。当评论发在该评论的讨论串中（GitLab、Bitbucket、Azure Repos）、引用了该评论，或指明了某个需求、评论中写出的状态（MISSING、PARTIAL）或任务 ID 时，Kody 才会将其视为回复；其他评论会交给聊天处理。

提出异议：“这在 useDrag.ts 中已经覆盖了”。Kody 会重新检查你指出的内容，要么将其标记为 MET，要么说明它查看了什么并保留原状态。
接受某项发现（PR 作者以外的人：在 GitHub 上需对仓库有写权限；在 GitLab 上需在仓库中拥有 Developer 或更高权限；在 Bitbucket、Azure Repos 和 Forgejo 上需是平台列出的组织成员）：“键盘重新排序不在范围内，已移至 SAA-102”。Kody 确认 SAA-102 存在，将该行标记为 ACCEPTED 并注明接受者，该行不再需要修复。只要任务文本没有变化，即使 Kody 对需求的措辞略有不同，这一决定在之后的重新检查中也保持不变；任务被编辑后，需要重新接受该需求。

Kody 的回复：

回复	Kody
评审者接受并移至 SAA-102	”Got it. SAA-102 exists, I marked AC #2 as accepted by @rafa and updated the table above.”
PR 作者尝试接受	”The pull request’s author can’t accept its own requirements: ask a reviewer to. If the code already covers it, say where and I’ll re-check.”
没有上述权限的人	”Only someone with write access to the repository can accept a requirement…”
移至的任务不存在	”I couldn’t find SAA-102 in the task tracker, so nothing was accepted. Check the id and reply again.”

Kody 何时不发表评论

Kody 只在作者能够采取行动时才发表评论：

情况	在 PR 上
任务只有标题	一条请求提供验收标准的评论
`SAA-999` 不存在，但 SAA 是你任务管理工具中的一个团队	一条指出可能是拼写错误的评论，并附上最接近的真实任务。开启 Ask for a task 时，该评论保持未解决直到修正
没有引用任务，或只有任何任务管理工具都没有的 ID（标题中的 `UTF-8`）	不做任何事。开启 Ask for a task 时，发布一条请求提供任务的评论（从不在机器人的 PR 上发布）
引用的是 GitHub issue，但只连接了 Linear	不做任何事；管理员会在设置页面上看到计数。开启 Ask for a task 时，发布一条说明哪个任务管理工具无法读取它的评论
任务管理工具宕机或其令牌已过期	不做任何事；会通知所有者，任务管理工具恢复响应后 Kody 会重新检查（自首次失败起最多一天）

每次跳过的原因都会被记录，并显示在 Business Logic 设置页面上。

按需运行

在 PR 上评论（而不是在某一行代码上）：

@kody -v business-logic：重新检查 PR 引用的任务
@kody -v business-logic PROJ-123 或任务链接：与该任务进行核对
@kody -v business-logic 后跟文本形式的需求：与你写的内容进行核对，无需任务管理工具

设置

打开 Code review → What to review，点击 Business Logic（或 ⋯ → Edit）。每项设置都可以全局设置，并按仓库或目录覆盖。

Task source：所有已连接的任务管理工具（包括 ClickUp 等自定义任务插件），或某一个插件。对于自定义插件，选择按 ID 读取单个任务的工具；只会提供只读工具。使用固定在页面右侧的 Try it（需要编辑这些设置的权限）：只填任务时会显示 Kody 从中读取的内容，填写拉取请求时会使用屏幕上的设置（无论是否已保存）运行完整检查且不发布任何内容。Post to the pull request 会发布所显示的结果，而不会重新运行，每次测试只发布一次；如果测试之后拉取请求有了新的提交，发布会被拒绝，请先重新运行测试。
Custom task id format（可选）：用于 Kody 自身无法识别的 ID 的正则表达式：T(\d{4}) 会将 T1234 读作任务 1234。类似 SAA-96 的键、#12、AB#8、CU-… 以及任务管理工具链接无需此设置即可识别，分支名中类似 sc-123 的小写键也是如此。标题或描述中的小写键只有在 Linear 或 Jira 存在该团队或项目时才会被采用；其他任务管理工具请设置格式。格式捕获的数字只有在 Git Issues 是任务来源时才会被读作 Git issue；使用所有已连接工具时，T1234 永远不会被当作仓库的 issue #1234。
Where acceptance criteria live：自动检测（验收标准字段、清单或描述中的列表）、在描述中的某个标题下，或在自定义字段中；没有该字段的任务从其描述中读取。将 Under a heading 设为 Acceptance criteria 时，下面的任务会按其中三个要点核对，上方的段落作为背景：
Agents should see at a glance how much time is left on a ticket's SLA. ## Acceptance criteria - The ticket header shows a badge with the remaining SLA time. - The badge turns red when less than 1 hour is left. - Resolved tickets show no badge.
Comment when every requirement is met（默认开启）：满足任务的 PR 会收到一行评论。关闭后不会收到评论；缺失项仍会发布。
Ask for a task when the PR references none：Kody 会发表评论询问该 PR 对应哪个任务（或指出拼写错误），而不是跳过它。由机器人（如 Dependabot 或 Renovate）创建的 PR 不受影响。任务管理工具宕机永远不算在内。
Re-check：仅在请求时（默认）、仍有缺失时每次 push，或每次 push。每次检查都像评审一样使用组织的模型，因此选择每次 push 意味着每次 push 消耗一次验证。
Skipped pull requests：代码审查跳过的 PR 在这里也会被跳过：标题包含被忽略关键词（ignoredTitleKeywords，例如 wip）的 PR，以及 runOnDraft 关闭时的草稿。@kody -v business-logic 评论始终会运行。
Team guidance：Kody 判断时遵循的说明，例如”当功能开关存在且默认关闭时，视为已实现”。它不能改变判定格式，也不能让 Kody 编造需求。

常见配置

团队	设置
需要检查，但不要噪音（默认）	Re-check 仅在请求时，开启 Comment when every requirement is met
每个 PR 都必须交付一个任务	开启 Ask for a task，re-check 设为仍有缺失时：没有任务的 PR 会被要求提供任务，每次修复都会更新评论，直到通过
只想了解缺失项	关闭 Comment when every requirement is met
各领域使用不同任务管理工具的 monorepo	按目录设置 Task source 和 Where acceptance criteria live

kodus-config.yml 中的相同设置：

businessLogic:
  taskSource: 'auto'              # 或插件的 integration id
  taskSourceTool: 'get_ticket'    # 仅自定义插件：按 ID 读取单个任务的工具
  taskIdPattern: 'T(\d{4})'       # 可选：Kody 自己找不到的 ID
  criteriaLocation: 'heading'     # auto | heading | field
  criteriaHeading: 'Acceptance criteria'
  # criteriaField: 'Acceptance Criteria'   # 与 criteriaLocation: 'field' 一起使用
  teamGuidance: 'Feature flags count as implemented when the flag exists and defaults to off.'
  commentWhenMet: true
  recheckOn: 'request'            # request | failing | push
  requireTask: false

通过 CLI

编码代理可以在创建 PR 之前检查自己的工作：

kodus pr business-validation --task-id AB#8
kodus pr business-validation --task-id AB#8 --format json

它会将你的本地变更与任务进行核对，并为每条需求输出一行及其状态。使用 --format json（或 --agent）时，它会以结构化形式输出相同的判定结果，供代理据此行动。不会向任何拉取请求发布内容。

Cockpit

Cockpit → Delivered as asked 显示满足任务的 PR 比例、不在任务中的变更、开发者认同 Kody 的频率，以及按代码编写者（人或编码代理，依据提交作者和 Co-Authored-By trailer 判断）和按团队的分布。它跟随 Cockpit 的仓库选择器，并且可以像其他标签页一样在 Organization → Cockpit 中隐藏。

快速开始

计费与许可证

AI 代码审查

CLI

驾驶舱

Kody 工单

组织管理

安全

故障排除

业务逻辑验证

概述

前提条件

启用

Kody 如何找到任务

PR 如何引用任务

五种状态

显示差距之前

在拉取请求上

回复评论

Kody 何时不发表评论

按需运行

设置

常见配置

通过 CLI

Cockpit

​概述

​前提条件

​启用

​Kody 如何找到任务

​PR 如何引用任务

​五种状态

​显示差距之前

​在拉取请求上

​回复评论

​Kody 何时不发表评论

​按需运行

​设置

​常见配置

​通过 CLI

​Cockpit

概述

前提条件

启用

Kody 如何找到任务

PR 如何引用任务

五种状态

显示差距之前

在拉取请求上

回复评论

Kody 何时不发表评论

按需运行

设置

常见配置

通过 CLI

Cockpit