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
69 changes: 69 additions & 0 deletions .scratch/worker-feishu-message-phases/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
Status: ready-for-agent

# Worker 飞书群展示各阶段的助手消息

Worker 在需求讨论中可能先写出完整问题和建议,随后用最终答复概括待决事项。用户希望直接在 Worker 群里看到两段原文。

## 已确认

- Worker 任务群展示 Codex 助手消息的三个阶段:过程说明(`commentary`)、部分答复(`partial_answer`)和最终答复(`final_answer`)。
- 每条助手消息写完后立即发送完整原文。同一条消息里的多个问题一起发送,正文省略阶段标签。
- Worker 开始本轮执行时,群里立即显示「处理中」。阅读最新消息时也能看到状态,包括第一条正文出现前和两条正文之间。
- 本轮持续期间显示「处理中」。每条助手正文写完即可发送,状态随本轮生命周期更新。本轮结束且本轮应发送的正文已投递后,显示「本轮已结束」。本轮以失败或中断结束时也使用这一结束文案。
- 群内状态提示只有上述两种。执行中用户仍可发送补充消息,原生提问和审批继续通过现有入口处理。
- 项目协调群的普通助手消息沿用现有最终答复投递条件。协调群公告、原生问题和审批各有独立的投递规则。见 [ADR 0017](../../docs/adr/0017-coordinator-group-announcements.md)。
- 本需求调整 [ADR 0006](../../docs/adr/0006-agent-owns-workflow-and-message-intent.md) 中 Worker 群普通回复的可见范围。现有显式中间汇报的投递规则见 [ADR 0021](../../docs/adr/0021-worker-discussion-routing.md)。
- Worker 群状态只使用「处理中」和「本轮已结束」。

## Problem Statement

Worker 的 `commentary` 和 `partial_answer` 会进入飞书「执行进度」,但普通 Worker 群只收到 `final_answer`。用户因此看不到执行过程中的问题,也无法判断 Worker 是否仍在工作。项目协调群需要继续保持当前只发送最终答复的行为。

## Solution

在 Worker 任务群中,按 Codex `agentMessage` 完成事件逐条发送 `commentary`、`partial_answer` 和 `final_answer` 的完整正文。Worker 本轮开始时发送或更新「处理中」状态,本轮完成、失败或中断并完成应发送消息的投递后显示「本轮已结束」。协调者群继续只投递当前规则允许的最终答复。

## User Stories

1. 作为 Worker 群用户,我希望看到每条已经完成的过程说明,以便及时了解 Worker 的问题和工作进展。
2. 作为 Worker 群用户,我希望看到部分答复和最终答复,以便掌握一轮对话的完整上下文。
3. 作为 Worker 群用户,我希望正文保持原文并省略阶段标签,以便直接阅读 Agent 的消息。
4. 作为 Worker 群用户,我希望 Worker 开始后立即看到「处理中」,以便知道暂时没有正文并不代表执行已结束。
5. 作为 Worker 群用户,我希望 Worker 结束后看到「本轮已结束」,以便知道何时可以开始下一轮交流。
6. 作为 Worker 群用户,我希望失败和中断也能显示本轮已结束,以便不会把终止的任务误认为仍在执行。
7. 作为 Worker 群用户,我希望执行期间继续发送补充消息,以便保持现有的任务群交互方式。
8. 作为项目协调群用户,我希望协调群仍只收到当前规则允许的最终答复,以便控制协调群噪声。
9. 作为系统维护者,我希望重启、重复事件和发送结果未知时保持消息幂等,以便恢复过程不会重复刷屏。
10. 作为系统维护者,我希望没有任务群时不补发历史 Worker 过程消息,以便新建群不会收到过期内容。

## Implementation Decisions

- 复用现有 Codex 执行事件、任务快照、任务 outbox 和飞书发送适配器。
- 把 Worker 普通消息可见性按任务角色限制为 Worker 群。协调者仍走现有最终答复和公告白名单。
- 用现有稳定输出身份和任务状态持久化消息与状态提示,支持重启、重试和发送确认不确定的恢复。
- 对状态提示使用有限状态模型,公开文案只有「处理中」和「本轮已结束」。
- 不把原始工具日志当作普通群消息。原生问题、审批和现有执行进度入口继续使用各自通道。

## Testing Decisions

- 测试通过 Agent Loop 的真实任务、执行快照和 Feishu 端口观察群消息与状态变化。
- 覆盖三种助手阶段、开始后尚无正文、同轮多条正文、正常结束、失败、中断、重启、重复事件、发送结果未知和没有任务群。
- 覆盖协调者群仍不发送过程消息,以及 Worker 群过程消息不进入协调者。
- 断言发送给用户的消息、状态和重复次数,不断言私有方法或内部调用顺序。

## Out of Scope

- 不改变 Codex 的 phase 定义。
- 不改变协调者群的最终答复、公告、原生问题和审批规则。
- 不发送原始工具输出,也不新增阶段标签或新的复杂状态文案。
- 不新增飞书卡片或外部看板。

## Further Notes

状态提示必须让最新群消息表达当前生命周期。每条助手正文仍以独立消息保留完整内容。

## Comments

2026-11-20:用户确认逐条发送完整正文并省略阶段标签,补充了在群聊中识别 Worker 仍在工作的需求。目前进度视图根据本轮执行状态及原生请求区分执行中、等待输入、等待审批和结束;群聊正文缺少同样的提示。

2026-11-20:用户确认阅读最新消息时应能看到状态,并将状态文案限定为「处理中」和「本轮已结束」。
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ npm start -- run --config config.json

实时事件由新版 `run` 进程写入相同数据目录的 SQLite。升级后重启执行服务一次即可开始记录,不需要重新创建任务。网页刷新或断线后回放已保存的事件;升级前的任务群消息可从“消息记录”查看,之前未记录的流式片段无法补回。调试记录与飞书通知独立,不改变任务唤醒、恢复、模型选择或审批规则。

飞书默认只转发 Agent 的最终答复。执行进度可通过固定文档标签页或消息卡片展示,同一时间只使用一种方式。原生问题与审批请求仍通过独立消息处理。
已打开的 Worker 群逐条显示完整的过程说明、部分答复和最终答复。群里用「处理中」和「本轮已结束」提示本轮状态。项目协调群的普通回复沿用最终答复可见规则。执行进度可通过固定文档标签页或消息卡片展示,同一时间只使用一种方式。原生问题与审批请求仍通过独立消息处理。

项目 Worker 默认没有任务群。普通答复和讨论留在原任务。用户在 Worker 群明确说“请汇报给协调者”后,Worker 才会向协调者发送一份汇报。用户需要直接对话时,在项目群自然语言提出,由协调者打开指定任务群。原生审批会按需建群并在项目群通知。Runtime 不发送定时监督提醒,没有新事件时协调者持续等待。新群不补发历史消息。群被手动解散后任务继续运行;现有进度发布只面向有效群,不提供新的项目进度总览。批量清理见[任务群管理](docs/task-groups.md)。

Expand Down
2 changes: 2 additions & 0 deletions docs/adr/0006-agent-owns-workflow-and-message-intent.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,5 @@ Runtime 及时转发 Agent 面向用户的进展说明和最终答复,不默
2026-11-11 任务交接决定,尚未实现:Runtime 提供通用 CLI 入口,接收调用方提供的 prompt 并创建新任务。用户要求从原任务交接工作时,由原 Agent 自行总结新任务需要的说明并调用 CLI;交接内容、文档引用与工作范围属于 Agent 的判断,Runtime 不承担旧会话总结或规格、工单的业务编排。此入口沿用现有任务准备与执行流程,设计细节见[规格](../../.scratch/spec-task-handoff/spec.md)。

2026-11-11 实现记录:通用 CLI 提交已实现,并通过源码和构建入口的隔离验收。正式 Agent 的运行环境说明提供提交和查询命令;具体任务 prompt 仍由调用 Agent 决定。正式服务启用状态与验收边界见[实现状态](../implementation-status.md)。

2026-11-20 更新:Worker 在普通过程说明中提出的完整问题需要在任务群直接可见。已打开的 Worker 群逐条接收助手写完的过程说明、部分答复和最终答复,保留正文与原有分段。群内只提示「处理中」和「本轮已结束」。协调者群沿用 ADR 0017 的可见规则。
2 changes: 1 addition & 1 deletion prompts/coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,6 @@ GitHub Feature 是外部需求提案,不是开发授权。需求描述清楚

Project 工具不会替你执行产品判断或 GitHub 合并。status 查询事实,dispatch 创建任务,send 传递指导,record 保存带版本的项目记录,rotate 在本轮安全结束后更换会话。没有新行动时结束本轮,Runtime 负责后续事件唤醒。项目群是主要用户交流入口,最终答复说明实际交付、当前阻塞和待决问题。暂不开展跨 Issue 共同根因分析。

Worker 和 verifier 默认无群。普通任务群问题、讨论和答复留在 Worker 群。只有所有者在当前 Worker 群明确要求向你汇报时,Worker 才能发送 final 或 escalation report,并用该用户消息的确切 ID 作为 requestId。查询 Worker 进展或产物时使用 status。收到汇报后核对实际来源和证据,区分用户决定与代理判断。用户需要直接与某个任务交流时,用 open_group 携带该任务的 taskId 和稳定 requestId 打开或复用任务群。原生审批按需建群,普通问题留在本任务。新群从当前状态开始交流。
Worker 和 verifier 默认无群。Worker 的完整助手消息逐条显示在已打开的任务群。只有所有者在当前 Worker 群明确要求向你汇报时,Worker 才能发送 final 或 escalation report,并用该用户消息的确切 ID 作为 requestId。查询 Worker 进展或产物时使用 status。收到汇报后核对实际来源和证据,区分用户决定与代理判断。用户需要直接与某个任务交流时,用 open_group 携带该任务的 taskId 和稳定 requestId 打开或复用任务群。原生审批按需建群,普通问题留在本任务。新群从当前状态开始交流。

批量解散群须另有用户授权。plan_group_cleanup 返回冻结清单并在项目群展示一次,排除所有项目协调群。用户发送该清单的确认文本后,使用 confirm_group_cleanup 携带实际 messageId,再调用 apply_group_cleanup。代理转述不能代替实际用户确认。失败先查明原因,修复后用新的 apply 请求继续原计划;不能重新计划以跳过失败。
2 changes: 1 addition & 1 deletion prompts/worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

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

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

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

Expand Down
8 changes: 5 additions & 3 deletions src/adapters/codex.ts
Original file line number Diff line number Diff line change
Expand Up @@ -533,7 +533,7 @@ export class CodexAppServer implements CodexPort {
return { kind: 'running', threadId, turnId, connectionEpoch: epoch,
requests: [...this.requests.values()].map(live => live.request).filter(request => request.threadId === threadId
&& (request.turnId === turnId || (request.kind === 'unsupported' && !request.turnId))),
outputs: [...this.outputs.values()].filter(output => output.threadId === threadId && output.turnId === turnId && output.phase === 'progress') };
outputs: [...this.outputs.values()].filter(output => output.threadId === threadId && output.turnId === turnId) };
}

async executionUse(threadId: string): Promise<'idle' | 'busy' | 'unknown'> {
Expand Down Expand Up @@ -641,8 +641,10 @@ export class CodexAppServer implements CodexPort {
const expectedTurn = this.awaitingHistory.get(threadId);
if (expectedTurn && !thread.turns.some(turn => turn.id === expectedTurn)) throw new TurnHistoryPendingError('Accepted Codex turn is not visible in history yet; reconcile before continuing');
for (const turn of thread.turns) {
if (turn.status === 'inProgress') continue;
for (const item of turn.items) this.captureOutput(threadId, turn.id, item, turn.status === 'completed');
for (const item of turn.items) {
if (turn.status !== 'completed' && typeof item.completedAtMs !== 'number') continue;
this.captureOutput(threadId, turn.id, item, turn.status === 'completed');
}
}
const mismatched = (thread.status.type === 'active') !== (latest?.status === 'inProgress');
if (expectedTurn && mismatched) throw new TurnHistoryPendingError('Accepted Codex turn state is still materializing; reconcile before continuing');
Expand Down
4 changes: 2 additions & 2 deletions src/execution-events.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { z } from 'zod';
export const executionEventSchema = z.object({
threadId: z.string(), turnId: z.string().nullable(), itemId: z.string().nullable(),
kind: z.enum(['agent_start', 'agent_delta', 'agent_message', 'tool_start', 'tool_output', 'tool_end', 'turn_start', 'turn_end', 'turn_status', 'error']),
label: z.string(), text: z.string(), createdAt: z.number(),
label: z.string(), text: z.string(), createdAt: z.number(), isFinalAnswer: z.boolean().optional(),
});
export type ExecutionEvent = z.infer<typeof executionEventSchema>;
export type VisibleExecution = Omit<ExecutionEvent, 'createdAt'> & { key: string; seq: number; taskId: string; createdAt: number | null };
Expand Down Expand Up @@ -57,7 +57,7 @@ export function executionEvent(method: string, params: unknown): ExecutionEvent
const { threadId, turnId, item } = parsed.data;
const scope = { ...base, threadId, turnId, itemId: item.id };
if (item.type === 'agentMessage') {
return { ...scope, kind: method === 'item/started' ? 'agent_start' : 'agent_message', label: item.phase === 'final_answer' ? '最终回答' : 'Agent', text: item.text };
return { ...scope, kind: method === 'item/started' ? 'agent_start' : 'agent_message', label: item.phase === 'final_answer' ? '最终回答' : 'Agent', ...(item.phase === 'final_answer' ? { isFinalAnswer: true } : {}), text: item.text };
}
const kind = method === 'item/started' ? 'tool_start' : 'tool_end';
switch (item.type) {
Expand Down
Loading