deepreef

Done 2026-06-18

Phase 0: 回归保护

• 新增 resolveEffectiveTools 回归测试：
  • Supervisor + loop 零工具（包含工程工具时也全过滤）
  • Worker + loop 按 agentToolNames 生效（三种情况：白名单 / undefined / []）
• 新增 WorkflowCoordinator.parseDecision 回归测试：
  • approve/completed → approve
  • ask_user/ask user → ask_user
  • blocked/cannot continue → blocked
  • revise → revise
  • 其余 → continue
• 验证：1104 tests pass, typecheck pass

Phase 1: ThreadGoal 类型和文件持久化

• 新增 packages/core/src/goal/types.ts — ThreadGoal 接口、GoalStatus 类型
• 新增 packages/core/src/goal/store.ts — GoalStore 实现：
  • createGoal 仅在无 goal 或 terminal (complete/budget_limited) 时创建
  • replaceGoal 显式 API，绕过创建限制
  • updateGoal 只允许 complete|blocked，支持 expectedGoalId 校验
  • accountProgress 累加 token/time，超 tokenBudget 自动置 budget_limited
  • systemSetStatus 供系统层控制任意状态
  • clearGoal 删除文件，getGoal 返回 null
  • setTokenBudget 更新活跃 goal 预算
  • 持久化到 .deepreef/sessions/<sessionId>/goal.json
• 新增 31 个测试覆盖所有核心路径
• 验证：1128 tests pass, typecheck pass

Phase 2: Goal tools

• 新增 packages/core/src/goal/tools.ts — 工厂函数创建 AgentTool：
  • createGetGoalTool(provider) → 使用 GoalToolProvider 获取当前 goal，无需 threadId
  • createUpdateGoalTool(provider) → 标记 complete/blocked，自动绑定 expectedGoalId
  • createGoalTools(provider) → 返回所有 goal 工具数组
• 新增 7 个测试覆盖 goal 工具核心路径
• 验证：1137 tests pass, typecheck pass

Phase 3: Structured protocol

• 新增 packages/core/src/workflow-coordinator/structured-protocol.ts：
  • Zod schemas: SupervisorPlanSchema, WorkerReportSchema, SupervisorDecisionSchema
  • parseSupervisorDecision / parseSupervisorPlan / parseWorkerReport
  • 优先解析 fenced JSON block → 再解析 prose + JSON → zod 校验
  • 失败时返回 null，caller 自行 fallback legacy parseDecision
• 修改 coordinator.ts runSupervisorCheck():
  • 优先使用 structured protocol 解析
  • 失败时 fallback legacy 并 emit low_confidence_decision 事件
• 新增 10 个测试覆盖各种解析路径
• 验证：1147 tests pass, typecheck pass

Phase 4: Mailbox JSONL

• 新增 packages/core/src/agent-comm/:
  • types.ts — AgentMessage, DeliveryMode, MessageKind, MailboxReadOptions
  • mailbox.ts — Mailbox 类，JSONL 文件持久化
  • controller.ts — AgentCommController
  • index.ts — 统一导出
• 新增 18 个测试覆盖 mailbox 和 controller
• 验证：1165 tests pass, typecheck pass

Phase 5: Coordinator 接入 mailbox + goal

• 修改 coordinator.ts：
  • 新增 agentComm 和 goalStore 可选参数
  • runSupervisorAnalyse → 写入 plan 到 mailbox task
  • runWorkerDo → 从 mailbox 读取未读 task 构建 prompt
  • runWorkerReport → 写入 report 到 mailbox
  • runSupervisorCheck → 从 mailbox 读取 report；approve 时 update_goal(complete)，blocked 时 update_goal(blocked)
  • 无 agentComm/goalStore 时保持原有行为，完全向后兼容
• 新增 3 个集成测试覆盖 mailbox 和 goal 集成路径
• 验证：1168 tests pass, typecheck pass

Phase 6: 工具过滤重构

• 新增 packages/core/src/agent-comm/tools.ts — mailbox 工具工厂
• 重构 resolveEffectiveTools.ts — Supervisor+loop 治理工具，Worker+loop 工程+mailbox
• 更新现有测试，新增 3 个 Phase 6 专项测试
• 验证：1171 tests pass, typecheck pass

Phase 7: GoalRuntime 自动续跑

• 新增 packages/core/src/goal/steering.ts：
  • buildContinuationPrompt(goal, iteration) — 续跑提示模板
  • buildBudgetLimitPrompt(goal) — 预算耗尽提示
  • buildUsageLimitPrompt() — 使用上限提示
• 新增 packages/core/src/goal/runtime.ts：
  • GoalRuntime.onEngineIdle(threadId) — 判断是否可以自动续跑
  • GoalRuntime.continueGoal(threadId) — AsyncGenerator 执行续跑
  • GoalRuntime.onTurnError() — 连续错误计数与熔断
  • 条件：仅 active、未超 maxAutoContinuations、未超 tokenBudget
• 新增 11 个测试覆盖 runtime 和 steering
• 验证：1182 tests pass, typecheck pass

Phase 8: Slash 命令和 TUI 入口

• 新增 /goal 斜杠命令类型和解析器 (commands.ts)
  • /goal — 显示当前目标状态
  • /goal <objective> — 设置目标
  • /goal edit <text> — 编辑目标
  • /goal pause / /goal resume — 暂停/恢复目标
  • /goal clear — 清除目标
  • /goal budget <n> — 设置 token 预算
  • /goal no-budget — 无限制预算
• CommandRegistry.ts 注册所有 /goal 变体
• buildHelpText 输出 /goal 命令说明
• App.tsx 添加 /goal 命令处理器，使用 GoalStore 读写 goal.json
• 新增 1 个测试验证 /goal 解析
• 验证：1337 tests pass, typecheck pass

Phase A: 修复 /goal 命令真实用户路径

• GoalStore.clearGoal() 改为 rmSync 删除文件，getGoal() 返回 null
• GoalStore.setTokenBudget(threadId, budget|undefined) 新增 API
• /goal pause 使用 systemSetStatus("paused") 而非 updateGoal
• /goal resume 使用 systemSetStatus("active") 而非 updateGoal
• /goal clear 使用 clearGoal 删除文件
• /goal budget <n> 使用 setTokenBudget 更新已有 active goal 预算
• /goal no-budget 使用 setTokenBudget(undefined) 清除预算
• /goal edit <text> 使用 replaceGoal 更新目标描述
• 验证：1183 tests pass, typecheck pass

Phase B: loop start 与 goal 创建合并

• App.tsx 的 start_workflow handler 自动写入 GoalStore
• 进入 loop 模式输入目标 → 同时创建 goal.json
• 核心路径：GoalStore.createGoal → WorkflowCoordinator.startWorkflow
• 验证：1183 tests pass, typecheck pass

Phase C: CLI 接入 GoalStore/Mailbox 到 WorkflowCoordinator

• packages/cli/src/tui.ts 创建 GoalStore 和 Mailbox 实例
• 传入 WorkflowCoordinator 构造函数
• coordinator.ts 新增 mailbox 选项和 getOrCreateController() 方法
  • 优先使用已有的 agentComm
  • 否则从 mailbox + 当前 goal/workflow 动态创建 AgentCommController
• 所有 phase 方法（analyse/do/report/check）使用 getOrCreateController()
• 暴露 getCurrentGoal()、getGoalStore()、getCurrentThreadId()、getCurrentAgentComm() 公共方法
• 验证：1345 tests pass, typecheck pass

Phase D+H: 注册动态 governance 工具 + 角色绑定

• agent-comm/tools.ts 重构为 MailboxToolProvider 模式 + AgentRole 绑定
  • createSendMessageTool(provider, role) — 方向验证
  • createFollowupTaskTool(provider, role) — 方向验证
  • createReadMailboxTool(provider, role) — 自动绑定收件角色
• Supervisor 方向限制：send/followup_task 只能 to=worker
• Worker 方向限制：send 只能 to=supervisor，followup_task 仅限 review
• goal/tools.ts 重构为 GoalToolProvider 模式（无 threadId 参数）
• CLI 注册：worker engine 注册 goal + worker mailbox tools；supervisor engine 注册 goal + supervisor mailbox tools
• 验证：1345 tests pass, typecheck pass

Phase E: Supervisor/Worker loop prompt 更新

• engine.ts Supervisor loop prompt：允许治理工具，禁止工程工具，要求审计
• engine.ts Worker loop prompt：读取 mailbox，执行工程任务，不更新 goal
• types.ts SUPERVISOR_WORKFLOW_PROMPT 同步更新
• 旧 “Do not call tools” 改为 “You may use only governance tools”
• 验证：1345 tests pass, typecheck pass

Phase F: 结构化协议审计门槛

• structured-protocol.ts 新增 CompletionAuditItemSchema、BlockerAuditSchema
• SupervisorDecisionSchema 新增可选 completionAudit 和 blockerAudit
• runSupervisorCheck() 审计规则：
  • approve：仅 structured 且 completionAudit 全 proven 且每个 proven 有 evidence 才 complete
  • legacy approve（无 structured）降级为 continue
  • blocked：仅 structured 且 blockerAudit.canMakeProgress=false 且连续 >= 3 轮才 blocked
  • 不同 blocker 重置计数，canMakeProgress 重置计数
• 新增 BlockerAuditState 在 coordinator 中维护
• 验证：1345 tests pass, typecheck pass

Phase G: loop continuation 续跑

• WorkflowCoordinator.canContinue() 当有 goalStore 时检查 goal 状态
• runWorkflow() 后处理：goal active 不标记 blocked，停在当前 phase
• bridge.tsx driveWorkflow() 外层 while 循环自动检查 goal 状态重跑
• steering prompts 注入：
  • buildContinuationPrompt → supervisor_analyse 和 supervisor_check 输入
  • buildBudgetLimitPrompt → budget_limited 时注入
  • buildUsageLimitPrompt → usage_limited 时注入
• 验证：1356 tests pass, typecheck pass

验收测试

• 新增 11 个验收测试 (phase-ab-acceptance.test.ts)：
  • /goal pause 不抛错 status=paused
  • /goal resume 不抛错 status=active
  • /goal clear 后 getGoal null
  • /goal budget 不因 active goal 抛错
  • /goal no-budget 清除预算
  • /goal <objective> 已有 active 则 replace
  • legacy approve 不能直接 complete
  • blocked 需 3 轮才能生效
  • Supervisor send_message 只能 to=worker
  • Worker send_message 只能 to=supervisor
  • Supervisor followup_task 只能 to=worker

Phase I: 验收问题修复（第 2 轮）

问题 1：workflowId 统一

• App.tsx:812 bridge.runWorkflow(goal, callback) → bridge.runWorkflow(goal, callback, workflowId) — 传入 sessionId
• bridge.tsx:157 Bridge 接口类型加 workflowId?: string 参数

问题 2：/goal gate（仅 loop 模式）

• App.tsx:671 入口检查 workflowMode !== 'loop'，非 loop 模式返回提示

问题 3：blockerAuditState 跨轮保留

• coordinator.ts:589 非 blocked continue 分支不再清空 blockerAuditState

问题 4：goalShouldContinue 只允许 active

• coordinator.ts:271 删掉 || goal.status === "blocked"

问题 5：续跑 re-entry

• 自然成立：runWorkflow() 允许从 supervisor_analyse 进入，while 循环后续迭代正常执行

Scrum 7: Loop Worker Report 整改 (Phase 1-5)

• Phase 1: 5 个回归测试 — 完整 4 阶段推进、report 传递、workflowId 统一、mailbox 不污染、tool error 不阻断
• Phase 2: coordinator state 主路径确认（useMailboxWorkflow 默认 false）
• Phase 3: runSupervisorAnalyse — tool error 不阻断非空 plan，仅 !plan 时 block
• Phase 4: Supervisor loop 工具收紧（get_goal/update_goal/list_dir/grep/read_file），analyse 期仅 list_dir 探索，check 期可读文件验证
• Phase 5: bridge 续跑仅允许 idle/supervisor_analyse 重入
• 提交: 9397df6, 6c33913

最终验证

• bun test packages/core packages/tui packages/cli — 1366 pass, 0 fail
• bun run typecheck — pass
• Git commits: 4850260, caa8981, a76b26e, 002a208, 5226e68, 9397df6, 6c33913

This site is open source. Improve this page.