pikasTech-agentrun/docs/reference/spec-v01-scheduler.md

v0.1 Scheduler Deferred 规格

agentrun-scheduler 是 AgentRun 后续自动调度器。它扫描 pending runs，选择 backend/profile/capacity，创建 runner Jobs，并处理 stale lease recovery。v0.1 保留该规格用于边界收敛，但自动 scheduler 不作为第一阶段交付和发布通过条件。

在系统中的职责划分

• 只在 M1-M3 稳定后进入实现；MVP 先通过 CLI/manual dispatch 启动 runner。
• 未来负责 pending run scan、capacity selection、runner Job creation、stale lease recovery 和 scheduler restart recovery。
• 不直接执行 backend，不直接写 provider events，不绕过 agentrun-mgr claim/report。
• 不替代 tenant 业务授权；只能消费 manager 已保存的 run policy。

Deferred 边界

v0.1 第一阶段不得因为 scheduler 未实现而阻塞最小真实闭环。发布候选可以在 scheduler 未实现时通过，但必须满足：

• CLI/manual dispatch 能启动真实 runner。
• manager durable facts、runner claim、backend turn、events 和 terminal status 全部真实可用。
• scheduler 相关字段或状态不会被误报为 active runtime 通过证据。

若后续在 v0.1 lane 内启用 scheduler，必须更新本文并补齐测试规格，不得把一次性 poller、自定义 runner 或手工脚本伪装成 scheduler。

未来 API 与运行形态

Scheduler 未来应运行在 agentrun-v01 namespace，作为独立 Deployment 或 manager 内受控 loop 二选一；选择前必须重新评估 HA、leader election、lease recovery 和 rollout 风险。

未来 scheduler 只能通过 manager API 观察和改变 run 调度状态，不能直接写 Postgres 或直接调用 backend：

scheduler -> agentrun-mgr -> durable facts
scheduler -> Kubernetes API -> runner Job
runner -> agentrun-mgr -> events/status

测试规格

T1 Deferred 状态检查

阅读本文和 spec-v01-services.md，然后检查 v0.1 发布验收材料。确认 scheduler 未实现时被明确标记为 Deferred，且发布通过证据来自 CLI/manual dispatch 的真实 runner 闭环，而不是 scheduler 占位。

T2 未来 scheduler 启用前检查

阅读本文，然后在实现 scheduler 前检查设计是否包含 pending scan、capacity selection、runner Job creation、stale lease recovery、leader/restart 行为和 failureKind。缺少这些内容时不得启用自动 scheduler。

T3 不接受自定义 poller

阅读本文和 spec-v01-cicd.md，然后检查 runtime 与 CI/CD 链路。确认没有长期自定义 runner、CI.json runner、自研 poller 或手工脚本承担 scheduler 职责。

规格的实现情况

规格项	状态	说明
Scheduler 边界规格	已定义	本文定义 deferred 边界。
自动 pending scan	Deferred	不作为 v0.1 第一阶段验收目标。
runner Job 自动创建	Deferred	先使用 CLI/manual dispatch。
stale lease recovery	Deferred	未来实现前需补齐详细测试。