新 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 需要在设计阶段确认。