钩子会对 Coroid 中发生的特定事件做出响应。您只需选定一个事件，用自然语言编写指令，事件触发时钩子便会自动运行。
在自动化功能下的工厂模块中即可找到它们。
在“新任务”中创建一个：选择“自动化”，然后点击“当某事件发生时”。“新任务”提供GitHub事件和Coroid的事件。详情请查看自动化。
可响应的事件
只有某个事件被触发时，钩子才会运行。大多数下述事件均由 Coroid 自身发送，少数则由您的系统生成。其余事件属于预留事件：编辑器不会列出它们，也无法为其创建新的钩子。若已为预留事件保存了钩子，编辑器和列表会将其标记为永远不会触发，但该钩子不会被删除。
Coroid 发送的事件
| 类别 | 事件 |
|---|---|
| 任务 | 已创建、状态变更、已完成、失败 |
| 智能体 | 已开始、已完成、出错 |
| 代码仓库 | 提交推送、分支创建、pull request 被打开/更新/合并、议题开启、提及 Coroid 的评论 |
| 迭代 | 已创建、规划开始、已开始、任务添加、任务移除、评审开始、已完成、取消 |
| 计划 | 阶段开始、已完成、失败 |
| 日程 | 运行开始、运行完成、运行失败 |
| 报告 | 已开始、已完成、失败 |
| 质量 | 检查开始、通过或失败；自动未解决 |
| 推广 | 已请求、已批准、已拒绝 |
| 发布 | 已创建、候选版本变更、备注变更、备注已批准、范围变更、检查清单完成、关卡评估、关卡覆盖、已批准、已发布、已回滚 |
| 部署 | 已排队、运行中、成功、失败、已取消、手动确认、手动确认回滚、健康检查通过、健康检查失败 |
| 同步 | 外部数据源已更新 |
| Slack 和 Telegram | 匹配自动化过滤规则的消息 |
您自己的系统触发的事件
| 类别 | 事件 |
|---|---|
| 分析 | 发现依赖项、发现安全问题、分析完成 |
| 外部部署 | 已开始、已完成、失败 |
Coroid 不会发送这些事件。CI 流水线、扫描器或您的其他系统会通过其 ID 触发钩子：它会调用POST /api/v1/organizations/hooks/:id/dispatch并传入一个服务账号该账号具备hooks:dispatch相应的权限。钩子会针对其保存时所关联的事件运行。编辑器会在“由您自己的系统触发”栏目下列出这些事件。
预留事件
这些事件尚未被发送或触发，因此编辑器不会提供它们：
| 类别 | 事件 |
|---|---|
| 任务 | 阶段变更 |
| 智能体 | 迭代、工具调用 |
| 计划 | 已创建、阶段完成、最终评审开始、最终评审完成、计划执行前的 pull request |
| 日程 | 已创建、已激活、已暂停 |
| 迭代 | 规划完成、任务完成、范围变更 |
| 发布 | 已暂存、已验证 |
| 推广 | 推广前的 pull request |
| 质量 | 检查不可用；修复开始或尝试中；重新验证开始；达成共识 |
工作的开始与结束
计划、日程、报告、质量检查、推广和发布在启动和结束时都会发送事件。钩子可据此响应工作的结束状态，您的系统也能借此衡量耗时长短。
| 工作 | 开始 | 结束 |
|---|---|---|
| 计划 | 阶段开始：计划执行开始时发送首个此类事件。 | 已完成、失败 |
| 日程 | 运行开始 | 运行完成、运行失败 |
| 报告 | 已开始 | 已完成、失败 |
| 质量检查 | 检查开始 | 通过、失败、自动未解决 |
| 推广 | 已请求 | 已批准、已拒绝 |
| 发布 | 已创建 | 已发布、已回滚 |
每个事件都会在其中记录发生时间occurredAt。反映工作结束情况的事件还会在其中记录工作开始时间startedAt，耗时则记录在durationMs。即startedAt这是occurredAt起始事件的内容，因此二者始终匹配。暂停期间耗费的时间会计入总时长。
每次变更保存时只会发送一次事件。撤销的变更不会发送任何事件，重试也不会重复发送两次事件。只有已启动的工作才会发送结束事件：计划的预演不会发送任何事件，启动前便取消的报告也不会发送事件。
除时间外，每个事件还包含以下内容：
| 事件 | 发送时机 | 字段 |
|---|---|---|
| 计划阶段已启动 | 计划的执行开始（即首个阶段），后续每当另一个阶段的首个任务启动时也会发送该事件。 | planId、plan(id, title),phase(id, sequence, title),firstPhase、executionStartedAt |
| 计划已完成或执行失败 | 计划的执行结束。正在规划过程中便失败的计划不会发送该事件。 | planId、plan、status、executionStartedAt |
| 计划运行已启动 | 计划运行开始 | scheduleId、runId、schedule(id, name),run(触发原因, 父级运行记录) |
| 计划运行已完成或执行失败 | 运行结束 | 相同的字段，status，以及tasksCreated或error |
| 报告已启动 | 报告开始生成。暂停与恢复操作会保持相同的起始时间。 | reportId、report(id, type, title) |
| 报告已完成或执行失败 | 报告保存完成，或执行失败、被取消。 | 相同的字段，以及tokensUsed、costUsd和hasActionableFindings，或error |
| 质量检查已启动 | 质量检查开始 | qualityRunId、check(subject, trigger, policy version, commit) |
| 质量检查通过或未通过 | 检查得出最终结果。 | 相同的字段，decision、redoCause、failedExpectationIds |
| 质量检查自动未解决 | Coroid 停止修复检查发现的问题。 | qualityRunId、workItemType、workItemId、reason |
| 升级请求已提交 | 升级任务已创建 | promotionId、laneId、promotion(title, status, branches, pull request) |
| 升级已获批 | 升级任务合并：在Coroid中获批，强制合并，在提供商端合并，或发布到版本中。 | 相同的字段，approval、approvedBy、forceReason |
| 升级被驳回 | 审核人员要求修改 | 相同的字段，reason、requestedBy、comment |
| 版本已发布 | 版本首次生产环境部署成功。 | releaseId、version、commitSha |
| 版本已回滚 | 回滚操作会替换环境中的版本。 | releaseId、version、rolledBackToReleaseId |
项目中工作的相关事件也包含projectId，因此仅限定于单个项目的钩子只会针对该项目触发。若钩子创建了相关工作，这些事件会计入该钩子的链式深度。
触发器与目标
每个自动化流程都有触发源（事件的来源）和目标（事件触发后的执行逻辑）。其中有两个目标会将事件转化为工作。
| 触发源 | 事件 |
|---|---|
| 工作流事件 | Coroid 中的事件，如上表所示 |
| GitHub | 拉取请求已打开、更新或合并；议题已打开；提及Coroid的评论 |
| Slack | 符合自动化过滤规则的消息 |
| Telegram | 符合自动化过滤规则的消息，例如以/coroid开头的消息 |
| Jira | 新议题 |
| 目标 | 执行操作 |
|---|---|
| 钩子 | 按本页说明执行你的只读指令。 |
| 对工作进行资格审核 | 将事件归档为请求。一旦资格审核通过，Coroid 便会创建工作。 |
| Coroid Check | 已停用。每个pull request的Coroid 审核设置在Quality Control；现有自动化流程已暂停 |
GitHub 事件需要GitHub应用支持。仅当评论作者对代码库有写入权限时，提及Coroid的评论才会被计数。详见GitHub。
仅当事件作者可信时，“对工作进行资格审核”生成的任务才会自动启动：即拥有代码库写入权限的GitHub、pull request、议题或评论作者。Slack、Telegram和Jira的作者均不可信，因此他们的任务需由他人手动启动。详见工作启动时机。
新的Jira工单仅能通过Coroid的Jira Webhook接入。它仅接收由为Coroid设置的Webhook密钥签名的交付内容，且仅针对新工单，同时要求工单的Jira项目键与Coroid的项目匹配。由于coroid.ai上尚未配置Jira Webhook，因此Jira触发器不会接收到任何事件；此时可改用导入Jira工单的方式。在已配置Webhook的场景下，新工单会进入Jira触发器的自动化流程，例如Quality Control中的Jira请求源，它会根据您选定的类型和优先级创建 qualifying 工单。若触发器上没有配置自动化规则，新工单则不会被录入任何流程。来自Jira的工作不会自动启动。请参阅工单追踪工具。
默认只读
钩子会进行分析并生成报告。它们可以创建后续任务，但不会直接修改您的代码。
正是这一默认设置使其能够被安全采用。响应事件而编辑代码的自动化操作，往往发生在最缺乏监督的时刻。一个钩子开启一个任务会通过常规流程产生相同的结果——即规范、规划、验证、评审以及pull request。
- 定时执行时间
- 事件自动化某事件发生时
普通任务
规格说明、计划、构建、验证、评审。它会占用一个代理槽位；请为其设定较低的优先级。
P2P3一份 pull request
它无法自行合并或提交到您的基础分支。
由您审批
编写优质的指令
钩子指令由模型处理，因此其表述方式类似于给同事的指令，而非代码。其质量标准与规范：说明要关注什么、什么才是重要的，以及该采取什么行动。
需明确说明“什么都不做”的情况。若缺少这一说明，钩子每次运行时都会生成一些输出内容，而总是有输出的钩子最终会被人们忽略。
防护机制
之所以设置三类防护机制，是因为事件驱动的自动化操作会以可预测的方式出现故障：
速率限制。每分钟、每小时及每天的限制均可针对每个钩子单独配置。若钩子关联高频事件，在合并操作繁忙时可能会触发数百次。
链式深度。钩子可触发事件，进而再触发其他钩子。通过设定最大链式深度可避免形成循环。
工具权限。钩子可访问的范围受到管控——只读权限、MCP调用及任务创建功能均被单独管理。
权限
仅有所有者和管理员才能创建、修改、测试或删除钩子；所有成员均可查看钩子及其执行历史。鉴于钩子是在组织层面运行的，这种权限差异是刻意设计的。
监控钩子运行情况
工厂中每个钩子的页面都会列出过去30天内的运行记录及执行结果：运行次数、失败情况及成本。每次自动化运行记录也会出现在“设置”→“活动”中，可通过“自动化”筛选查看。启用新钩子后请检查其运行状况——失败模式并非报错，而是钩子持续触发却未产生任何有效结果。
钩子与定时任务
| 运行机制 | 触发来源 |
|---|---|
| 钩子 | 平台事件 |
| 定时任务 | 时间 |
二者均属于自动化操作，在工厂中一同列出。请参阅自动化操作。