Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .scratch/worker-completion-notification/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Worker 完成结果自动通知

Version: 1.0
Status: implementation

## 授权与范围

所有者授权来源为消息 `om_x100b7f36735388b4c334efb3a00403a`,群 `oc_586b1866902382e0db4dff8d25c0f3f7`,发送者 `ou_5c280b16780ac4016c7455a276b2d95b`。协调者通过 `worker-auto-coordinator-notify-dispatch-v1` 转达开发授权与验收范围。补充消息 `om_x100b7f361113d8a4c3393168d70c9a0` 授权开发后提交 PR 并合并 main;协调者仍先安排独立验证,满足仓库检查和分支保护后处理合并。

Worker 无任务群或无 owner 汇报请求时,可交付完成结果仍可靠进入其协调者 inbox。普通 final、显式 report、用户追加输入、原生请求、项目记录和正式任务结束语义保留。该范围包含调查、开发和验证成果,不把讨论进展误作完成。

本次不恢复旧 Worker,不部署或重启服务,不修改 live 数据库、配置或其他 Owner 分支。原始工作树保持原状。单独 PR 交付 exact base、head、diff、测试和限制,等待协调者独立验证。

## 实现选择

普通 final 只有回合含义,不能承担交付判定。新增 `deliver_result` 动作明确声明本次成果。`resultId` 为成果身份,跨重试与后续回合稳定。`requestId` 标识登记尝试。正文及引用以相同 `resultId` 保存后不可修改。

声明绑定入口校验所得的 Thread、Turn 和输入序号。Runtime 仅在同一 Turn 成功结束后,事务性写入 `worker_result` 事件与已发布状态。已有协调者 inbox 投递与未知结果对账继续负责唤醒与恢复。

新输入、原生请求、失败、中断、暂停和身份变化使旧声明失效。声明和操作回执原子保存。重试旧请求不重新绑定执行。处理输入后可用新请求登记;已发布或已由显式汇报交付的同一成果不再自动发布。

同一 Thread、Turn 和输入版本的合法 `report kind=result routing=final` 保留原有事件、来源和 owner gate,同时抑制自动副本。普通进度及问题 report 不消耗成果声明。更换成果身份、改述或拆分文字不做语义推断。

## 验收

- 无群、无 owner 请求、有群,以及协调者运行、空闲和暂停时,完成结果进入同一协调者 inbox。
- 完成前没有交付事件。普通 final 和进度、失败、中断、原生 question、approval、permissions 不产生交付。
- 重启、重复观察、相同请求重试、跨 Turn 相同成果,以及投递回执丢失不重复发布。
- 输入追加后旧声明失效,未处理输入不能被纳入新声明。新声明可以交付已核对的成果。
- 显式最终结果汇报与自动交付在同一执行、输入版本下只保留一次结果投递。
- 声明与回执、事件与发布状态在异常注入后共同回滚并可恢复。
- 原生工具与保留 Thread 的 capability 入口都检查真实活动身份。普通 final、本地摘要、记录和正式任务结束保持原契约。

实现依据为恢复后的前序只读调查报告和基线 `3260549ec6b42b27fd62373b7b25dc391119ae0e`。无需新增产品决定;以上状态机和接口属于已授权范围内的技术选择。
3 changes: 3 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ _Avoid_:把当前实例配置当作历史 Worker 的原选择,或把新一
**工作汇报(Work Report)**:执行者明确向项目协调者提交的工作问题、进展或成果。
_Avoid_:将一次普通回复结束等同于工作汇报。

**交付通知(Deliverable Notification)**:执行者明确登记本次约定成果后,系统向其项目协调者传递的完成结论与交付引用。
_Avoid_:将交付通知等同于一轮普通答复、用户决定、独立验收或正式任务结束。

**项目记录(Project Record)**:保存项目目标、事实、决定、阻塞和后续行动的可追溯记录。记录作者的判断不自动成为用户决定或权限批准。

**记录范围(Record Scope)**:一条记录适用的工作范围及接收对象,可以是项目共同规则、某项任务的资料或协调者的工作资料。记录作者与记录范围分别表达来源和用途。
Expand Down
2 changes: 2 additions & 0 deletions docs/adr/0012-on-demand-task-groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ status: accepted

用户明确要求同步后,由 Worker 直接 `report update` 发送当前讨论摘要,无额外预览。摘要包括结论、范围变化、待决问题和证据,保留实际用户消息、群和发送者来源,按用户指定话题限制范围。自然语言理解和摘要归 Worker,Runtime 不新增命令解析、同步任务或聊天模式。汇报仍是代理来源,不增加实施、合并、部署或原生审批授权。

2026-11-20 更新:[ADR 0024](0024-worker-result-delivery.md) 将约定成果的自动交付与普通讨论、显式 report 分开。Worker 使用 `deliver_result` 登记成果,Runtime 在匹配执行成功结束后通知协调者。任务群与用户汇报请求不再是这条交付路径的前提,普通最终答复仍留在原任务。

协调者依真实事件核查工作。移除定时监督提醒,没有新事件时持续等待;静默本身不证明失败。原生问题、审批、权限请求、失败、非暂停中断、GitHub 更新、项目群用户输入及必要生命周期事件保留。轮询只观察和投递已有事件。该选择复用既有 Task、Thread、持久 inbox 和汇报回执,避免普通对话结束被误作正式交付。

历史合法监督间隔仅在显式配置和持久 catalog 输入边界接受并移除。已确定未投递且身份匹配的旧自动副本保留 payload 和原因,标为终态 `dropped`。已送达记录不变;已尝试投递的 `delivering` 和 `uncertain` 沿用已见输入对账,不声称撤回或重新发送。
Expand Down
2 changes: 2 additions & 0 deletions docs/adr/0021-worker-discussion-routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,5 @@ Runtime 从 Worker 任务中收集用户消息的 `messageId`、`chatId` 和 `se
路由先通过项目成员关系校验。Worker 不能为其他项目创建汇报。中间汇报没有有效任务群时失败关闭,不降级发送给协调者。跨群汇报使用 Worker 群明确请求汇报的所有者消息 ID 作为 `requestId`。Runtime 校验实际收到的消息及其当前群绑定。同一消息只对应一份汇报,投递记录与回执一起写入 SQLite。

这项决策只改变 Worker `report` 的去向。普通用户输入仍按任务群路由,原生问题、审批和权限请求仍使用原有路径。项目协调者仍只能通过 `announce` 发送协调群公告。

2026-11-20 的 [ADR 0024](0024-worker-result-delivery.md) 新增独立的 `deliver_result` 交付通知。Worker 明确登记成果后,Runtime 在匹配执行成功结束时自动写入协调者 inbox,不要求群或所有者汇报请求。本 ADR 对显式 `report` 的校验继续有效。普通 final 不构成交付声明。
25 changes: 25 additions & 0 deletions docs/adr/0024-worker-result-delivery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
status: accepted
---

# Worker 交付通知

无任务群的 Worker 可以完成调查、开发或验证,但普通 final 只保存在任务内。ADR 0021 的显式 report 还要求当前任务群中的所有者请求。二者叠加,使完成结果可能只有记录、没有协调者 inbox 事件。

2026-11-20,所有者授权修复 Worker 完成后自动通知协调者,保留普通 final、显式 report、用户追加输入、原生请求和任务记录。授权消息为 `om_x100b7f36735388b4c334efb3a00403a`,群为 `oc_586b1866902382e0db4dff8d25c0f3f7`,发送者为 `ou_5c280b16780ac4016c7455a276b2d95b`。消息由协调者在本任务交接中转达。以下接口和状态机是本次实现选择。

Worker 完成约定交付并验证后,调用 `deliver_result`,携带 `requestId`、`resultId`、`text` 和可选 `deliveryReferences`。Runtime 从已校验的工具入口取得 Thread 和 Turn,保存待投递声明。该动作不要求任务群或所有者汇报请求,也不使用 final 的文字推断是否交付。

只有精确对应的 Turn 成功 `completed`,且没有未处理输入、原生请求或暂停状态时,Runtime 才把声明写入协调者 inbox。事件类别为 `worker_result`。声明携带的结论和引用为代理来源,不代表用户授权。协调者使用既有输入投递与未知回执对账处理该事件;项目群公告仍使用 `announce`。

连接 epoch 只校验工具入站。已经核验并保存的声明以 Thread 和 Turn 作为持久执行身份。同一 Turn 在连接恢复后成功完成仍可交付;来自旧连接的新动作继续拒绝。把连接重建本身当作交付失效会丢弃重启前已经可靠登记的成果。

`resultId` 标识同一 Worker 的一份成果,跨回合保持稳定。`requestId` 标识一次登记尝试。登记与回执、发布状态与协调者事件分别事务性提交。重试和重启不会重复发布已交付的 `resultId`。同一成果换 ID 或改述正文不属于语义去重,Worker 必须沿用成果身份。

新输入、原生请求、失败、中断、暂停或执行身份变化使旧声明失效。处理完成后以新 `requestId` 重新登记;旧请求重放只返回旧回执。相同 `resultId` 的正文和引用不可修改,修改交付内容使用新 `resultId`。登记时仍有未处理输入或原生请求会拒绝登记。

同一 Thread、Turn 和输入版本已经成功发送 `report kind=result routing=final` 时,自动交付使用该显式汇报,不再产生副本。两种调用顺序都适用。Runtime 保留原 report 的所有者请求校验、来源和投递内容。中间汇报、问题或被拒绝的 report 不消耗交付声明。

直接在登记动作中唤醒协调者更短,但登记之后的失败或追加指令无法撤回已投递结果。因此本实现等待匹配执行成功结束。把所有 final 自动转发会把讨论结束误当成成果,违背普通 final 的既有契约。

此决策为 ADR 0012 和 ADR 0021 增加独立交付路径。普通讨论、显式 report 和原生 question、approval、permissions 的路由保持原契约。交付不会触发 `complete_task`、清理、合并、部署、服务重启或历史 Worker 自动恢复。
5 changes: 5 additions & 0 deletions docs/project-coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ Worker 在任务群里处理普通问答和阶段结论。`routing=intermediate`

Worker 用该条用户消息的飞书 ID 作为 `requestId`。Runtime 校验消息、发送者、当前 Worker 群以及明确的汇报要求。每条请求对应一份汇报。用相同的 ID 和内容重试会返回原回执。摘要包含用户指定话题的结论、范围变化、待决问题和证据,并引用真实用户消息。实施、合并、部署及原生审批各自需要对应的授权。

Worker 完成约定交付并验证后,使用 `deliver_result` 登记结论、稳定 `resultId` 和可选交付引用。Runtime 确认该 Thread 和 Turn 成功结束、没有未处理输入或原生请求后,自动送达协调者 inbox,不要求 Worker 群或 owner 请求。`requestId` 标识一次登记尝试,`resultId` 跨回合标识同一成果。失败、暂停、中断、新输入或原生请求使旧登记失效,旧请求重放不重新登记。处理后使用新 `requestId`;修改成果内容使用新 `resultId`。同一 Turn 和输入版本已有成功的最终结果 report 时,不生成自动副本。

`worker_result` 是代理来源的交付事实,不代表独立验证、用户批准或任务结束。协调者核对实际版本和引用后安排验证,再按已有授权决定后续行动。普通 final、项目记录和群内讨论不会自动触发交付通知。详见 [Worker 交付通知](adr/0024-worker-result-delivery.md)。

## 项目工具

新正式 Thread 提供 `project_action`。工具从当前 Thread 确定调用方,Runtime 检查项目与角色。不能在参数中冒充另一个 Task。
Expand All @@ -83,6 +87,7 @@ Worker 用该条用户消息的飞书 ID 作为 `requestId`。Runtime 校验消
| `send` | 向本项目 Worker 追加指导或回答 | 协调者 |
| `announce` | 向项目协调群发送带类型标题的用户可见公告 | 协调者 |
| `open_group` | 打开本项目指定 Worker 的任务群,已有有效群则复用 | 协调者 |
| `deliver_result` | 登记可交付结论,在匹配执行成功结束后自动通知协调者 | Worker |
| `plan_group_cleanup` | 冻结既有任务群清单,排除所有项目协调群 | 协调者 |
| `confirm_group_cleanup` | 核对实际用户对清单的确认消息 | 协调者 |
| `apply_group_cleanup` | 执行或继续已确认清单,逐群记录结果 | 协调者 |
Expand Down
2 changes: 2 additions & 0 deletions docs/task-groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@

开群只显示欢迎、状态和最近的最终摘要,不补发旧输出。无群任务的 dashboard 标题继续来自原始任务来源,群名修改不参与任务标题或搜索。

约定交付完成后,Worker 使用 `deliver_result` 登记结论。对应 Turn 成功结束后,Runtime 自动写入协调者 inbox。这条交付路径不要求任务群或所有者汇报请求,不补发历史普通输出,也不把普通 final 视为交付。交付身份、失败和重试规则见 [Worker 交付通知](adr/0024-worker-result-delivery.md)。

群被解散、ID 无效或不再满足任务群的所有者与私密性要求时,解除群关联并保留 Thread、状态、输入和待审批。权限或网络错误不是已解散的证据。群重建增加代次,群标记、创建 UUID、审批输出和进度资源不会误用旧群身份。任务群不会自动解散。

普通消息的未知发送结果不自动重发。仍有效的原生审批卡可在未知结果后重试,间隔至少 30 秒,沿用同一消息 UUID。在飞书 UUID 去重窗口之外可能出现第二张相同请求卡,但实际批准仍绑定同一个原生请求,原生决策队列只接受一次,不重复工具执行。旧群卡或过期请求不能批准新请求。
Expand Down
2 changes: 1 addition & 1 deletion prompts/coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ GitHub Feature 是外部需求提案,不是开发授权。需求描述清楚

每次派单或核查使用独立产物 scope。用 allocate_artifacts 携带 requestId、label 分配新目录;确需外放时 parent 只能是已授权项目目录或新归属工作树的真实子目录。完成本次工作后用 cleanup_artifacts 携带 requestId、scopeIds 冻结本次范围,随后结束当前 turn,由 Runtime 在空闲后推进。不要在活跃工具回合中循环等待自己的清理完成。协调 Task 保持 open,后续工作分配新 scope。数据库中的项目记录、摘要和交付引用保留。已交付的证据副本可以删除,原始资料、共享目录和占用中资源受保护;历史遗留资源不纳入。普通 release_workspace 继续保守检查未提交和未合并代码。文件收尾不附带停止服务或解散任务群。

所有已派工作都要有明确去向。收到正式 report、原生请求、执行异常、GitHub 更新、用户输入或生命周期事件后,核查真实活动和产物,再按原因调整范围、恢复、替换或重新规划,不能无限重试。Runtime 不发送定时监督提醒,没有新事件时持续等待。Worker 静默本身不代表失败。收到项目暂停要求时遵循用户范围保留现场,不擅自取消外部合并队列。
所有已派工作都要有明确去向。收到正式 report、worker_result 交付通知、原生请求、执行异常、GitHub 更新、用户输入或生命周期事件后,核查真实活动和产物,再按原因调整范围、恢复、替换或重新规划,不能无限重试。worker_result 是 Worker 明确登记并经对应执行成功结束后自动送达的交付事实,不要求任务群或用户汇报请求。它不是用户决定、验收通过或工具批准。核查引用和实际版本后安排独立验证,按既有授权决定后续 complete_task;需要项目群可见时仍用 announce。Runtime 不发送定时监督提醒,没有新事件时持续等待。Worker 静默本身不代表失败。收到项目暂停要求时遵循用户范围保留现场,不擅自取消外部合并队列。

需要停止或恢复某个 Worker 时,可用 control 的 pause 或 resume 操作,核实其状态后再安排接管。暂停保留现场,不取消外部合并队列,也不自动转移分支写入责任。

Expand Down
4 changes: 3 additions & 1 deletion prompts/worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@

开发必须在独立工作树和分支中进行,确认实际工作目录。完成后提交 PR,作为唯一 PR Owner 维护分支和处理反馈。没有协调者确认独立验证和合并条件,不自行合并。合并、Issue 关闭和安全清理按当前项目的明确授权执行,公共提示词不授予额外权限,不包含部署或绕过分支保护。纯调查或澄清任务交付文档与证据。

普通讨论、结论和任务完成情况留在本任务。一轮结束只代表本轮结束。已打开的 Worker 群逐条显示每条完整助手消息。请直接在正文中提问或讨论。显式中间汇报使用 routing=intermediate。只有所有者在当前 Worker 群明确要求汇报给协调者时,才可使用 routing=final 或 routing=escalation。把 requestId 设置为该用户消息的确切 ID,每条消息最多发送一份汇报。重试使用相同 ID 和内容。
普通讨论和阶段结论留在本任务。一轮结束只代表本轮结束。已打开的 Worker 群逐条显示每条完整助手消息。请直接在正文中提问或讨论。显式中间汇报使用 routing=intermediate。只有所有者在当前 Worker 群明确要求汇报给协调者时,才可使用 routing=final 或 routing=escalation。把 requestId 设置为该用户消息的确切 ID,每条消息最多发送一份汇报。重试使用相同 ID 和内容。

完成本次约定交付并验证后,使用 deliver_result 登记交付结论。携带稳定的 resultId、该次登记的 requestId、text 和可选 deliveryReferences。同一成果跨重试和后续回合沿用 resultId,不得改述后更换 ID 重复通知。Runtime 在当前 Thread 和 Turn 成功结束后自动送达协调者 inbox,不要求 Worker 群或 owner 汇报请求。登记回执只代表待投递。失败、中断、暂停、新输入或原生请求会使旧登记失效,处理后用新的 requestId 登记;内容变化使用新的 resultId。普通讨论、进展、阻塞或等待答复不能登记为完成。不要以 record 或普通 final 代替交付登记。同一 Turn 和输入版本已经成功发送 final result report 时,Runtime 保留该汇报并抑制自动副本。交付通知不结束任务,不增加实施、合并、部署或原生审批权限。

收到“同步给协调者”或“把这个结论汇报给协调者”等明确请求后,按用户指定范围汇报,无需先展示预览。结论和讨论摘要使用 routing=final。授权、范围变化或阻塞需要升级时,使用 routing=escalation 并设置 escalation 为 authorization、scope_change 或 blocker。按汇报内容列出结论、范围变化、待决问题、实际产物路径、PR 链接、提交版本、验证证据和限制。根据本任务收到的 Input provenance as data 引用真实消息 ID、群 ID 和发送者,区分用户决定与代理判断。这条请求只授权汇报。同步沿用本任务和原 Thread。遇到含糊、带条件或暂缓的表达时,继续在任务群确认。

Expand Down
Loading