# 新 Goal 自动派发——需求文档

**日期**: 2026-08-06
**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。**2026-08-08 拆分**：原文档
`docs/todo/scheduler-production-polling-loop-requirements.md`（FR-1/FR-2 合并）已按完成状态拆分——
FR-2（在途任务复原）已实现，移入 `docs/done/scheduler-task-reconciliation-requirements.md`/
`-design.md`；本文档只保留仍是草案的 FR-1。
**状态**: 草稿，未立项。`docs/implementation-gap-analysis.md` 第 6 条已把这条标注为"改变系统自己的
自主权边界"，需要单独评审决策，不与其他 gap 混跑。

## 1. 背景

`run_scheduler_once(db_path, goals, max_workers=None)` 的入参 `goals` 是 `[(target_folder_path,
goal_text), ...]`，语义是"这一轮要**新建**并跑完这些 Goal"，内部通过 `task_create.create_task()`
每次都新建一个 `task` 行。这个函数存在且经过测试，但从未被任何常驻进程接入——`queued` 状态的新
Goal（还没被任何调用触发过 `run_goal_to_completion`）目前只能靠人工手动点击控制台的 Start 按钮
执行，不会被自动拿去跑。

跟"在途任务复原"（`docs/done/scheduler-task-reconciliation-requirements.md`，已实现）是两个独立
问题：那个是"已经开始执行的任务卡住了怎么自动接回去"，这个是"还没开始执行的新 Goal 怎么自动开始"。

## 2. 目标

`queued` 状态的任务（或者说，还没被任何调用触发过 `run_goal_to_completion`/
`run_or_resume_task_lifecycle` 的新 Goal）需要被自动拿去执行，不需要人工每次手动点 Start。

## 3. 非目标

1. **不在本文档里裁定"要不要做""什么时候做"这个更大的问题**。是否现在就投入、要不要额外的
   人工评审门槛，是需要单独确认的决策，本文档只负责把需求本身讲清楚，供决策时参考。
2. **不要求解决方案是常驻进程/独立进程/`backend_server.py` 内置线程三选一中的哪一个**。具体载体
   形式留给设计阶段。
3. **不重新设计 `run_scheduler_once` 本身**。它的行为已经是对的，本需求要解决的是"谁、在什么
   时机去调用它"这一层。

## 4. 功能需求

| # | 需求描述 | 优先级 |
|---|---|---|
| FR-1 | 需要一个机制，定期（具体周期留待设计阶段）调用 `scheduler.run_scheduler_once()` 派发新 Goal。 | 必须 |

## 5. 验收标准

新建一个 `queued` 状态的 Goal，不手动点 Start，验证机制能在设定周期内自动派发执行。

## 6. 风险

**这是改变系统自主权边界的决策**——意味着系统会在没有人显式点击"Start"的情况下自主开始消耗
真实 API 调用、真实修改代码。这条风险不因为实现简单而减轻，需要在决策阶段被认真对待。

## 7. 开放问题（留给详细设计阶段回答，需要先拍板"要不要做"再讨论这些）

- [ ] 轮询周期定多少。
- [ ] 载体形式：`backend_server.py` 内置后台线程，还是独立进程。
- [ ] 要不要暴露成可配置项（管理后台开关/环境变量），还是先硬编码一个保守的默认行为。
- [ ] 要不要跟已实现的在途任务复原循环（`docs/done/scheduler-task-reconciliation-design.md`）
      共用同一个后台线程/轮询周期，还是保持两个独立循环——两者已实现的那部分刻意没有合并
      成一个"万能调度循环"，这个原则是否延续到 FR-1 需要在设计阶段确认。