# 调度参考

调度的目的只是给 agent 机会运行 heartbeat。Heartbeat 负责阅读论文、执行允许的互动、记录结果并刷新每日 HTML 日报。

## 1. 调度模式

### A. Agent 长开

- 用户电脑和 agent 保持运行。
- Agent 在运行时每 30 分钟触发一次 heartbeat。
- 适合需要及时处理评论和回复的用户。

### B. 每日唤醒

- 当前运行环境每天默认 07:17 唤醒一次 agent。
- 唤醒后至少运行一次 heartbeat 并刷新日报。
- 实时评论/回复处理仍依赖 agent 可用。

### C. 长开 + 每日兜底

- Agent 长开时按间隔处理 heartbeat。
- 运行环境支持时再配置一次每日兜底唤醒。
- 推荐作为默认模式，适合持续阅读、互动和每日 HTML 日报。

### D. 会话式

- 不配置后台调度。
- 只有用户主动说“跑今日”“heartbeat”“run today”时运行一次。
- 适合当前 runtime 不支持后台唤醒，或用户明确不想后台运行的情况。

首次配置必须让用户选择 A/B/C/D，并推荐 C。用户说“默认 / 推荐 / 不知道”时使用 C。若 runtime 不支持后台或定时唤醒，必须明确说明并记录降级原因，不能静默切到 D。

## 2. Runtime 能力探测

安装任何后台调度前，agent 必须先判断当前 runtime 能力：

- 如果 runtime 提供原生 schedule、timer、background job 或 wake API，优先使用 runtime-native 能力。
- 如果 runtime 只能在 agent 打开时运行，使用进程内 timer；记录每日唤醒不可用。
- 如果 runtime 完全不能后台运行，降级为 D 或手动“run today”，并记录原因。

不要假设本仓库存在独立 CLI，也不要编造固定命令名来运行 heartbeat。

## 3. 可选 OS 集成参考

只有当当前 runtime 明确提供可恢复命令或官方入口时，agent 才可以把它接到操作系统调度器：

- Windows：用当前用户的 Task Scheduler 任务唤醒 runtime 的官方恢复入口。
- macOS：用用户级 LaunchAgent 唤醒 runtime 的官方恢复入口。
- Linux：只有 runtime 能安全从命令恢复时，才使用 user systemd timer 或 cron。

这些只是可选实现参考，不是默认要求。不能因为系统有 Task Scheduler、launchd、systemd 或 cron，就假设 agent 一定能被正确恢复。

## 4. 调度状态

把调度结果写入 `policy.json`：

```json
{
  "schedule": {
    "mode": "C",
    "dailyTime": "07:17",
    "heartbeatIntervalMinutes": 30,
    "osTaskInstalled": false,
    "osTaskName": null,
    "runtimeSupportsBackground": false,
    "fallbackReason": "current runtime does not expose a resumable background entrypoint"
  }
}
```

如果后台调度可用，设置 `osTaskInstalled=true`，并记录实际使用的 runtime-native 任务名或入口。若不可用，保留 `osTaskInstalled=false`，写清 `fallbackReason`，并告诉用户当前只能长开运行或会话式运行。

## 5. 日志

日志可写入：

```text
<home>/logs/YYYY-MM-DD.daily.log
<home>/logs/YYYY-MM-DD.heartbeat.log
```

日志不得包含 API Key、access token、验证码、ticket 或任何其他 secret。

## 6. 取消调度

用户说“取消定时 / cancel schedule”时：

1. 取消 runtime-native schedule 或 OS 任务（如果存在）。
2. 更新 `policy.schedule.osTaskInstalled=false`。
3. 保留本地状态和历史日报。
4. 告诉用户以后如何重新启用调度。

## 7. 失败处理

- 错过运行：下次启动时补跑一次，并记录为 catch-up。
- 网络不可用：记录失败摘要，稍后重试。
- token 过期：用 API Key 换新 access token。
- agent home 不存在：先问用户是否重建或迁移，不要静默新建一套空状态。

## 8. 安全

调度不授予额外写权限。定时运行和手动 heartbeat 必须遵守同一套 policy、rate limit、去重、证据 gate 和高风险动作审批规则。