# 统一定时任务执行与投递设计

状态：设计完成，尚未实施

目标数据库版本：v11

适用范围：`scheduler`、Scheduled Agent、Cron tools、SQLite、WebUI 任务页

## 1. 背景

当前定时任务同时存在四组互相耦合的概念：

- `JobKind::Task` / `JobKind::Monitor`；
- `DeliveryPolicy::Direct` / `Always` / `OnAlert` / `Never`；
- Agent 自己调用 `send_message` 的旧执行路径，以及 Scheduler 托管投递的新执行路径；
- 通过 `NO_REPLY`、`NO_REPLY[INFO]`、`NO_REPLY[FAIL]`、`NO_REPLY[REFUSE]` 等字符串猜测运行结果的协议。

这导致任务“做什么”和“是否投递”没有形成正交模型。特别是 `NO_REPLY[INFO] XXXX`、Markdown 包裹、缺少冒号或模型附加解释时，字符串解析会把本应静默的结果当作普通内容投递。继续放宽正则只会扩大不确定协议，无法从根本上解决问题。

本设计把所有 AI 定时任务统一成一种 **Scheduled Run**：任务配置只声明调度、执行 Agent、完整 prompt、目标和投递策略；每次运行必须通过运行时注入的终结工具提交结构化结果；Scheduler 根据结构化结果和投递策略做确定性决策。

## 2. 设计目标

1. 删除 `task` / `monitor` 运行类型，任务语义只由 prompt 表达。
2. 删除所有 `NO_REPLY[...]` 魔法字符串和自然语言结果解析。
3. 删除 Agent 自行投递的 `Direct` 路径，所有投递由 Scheduler 拥有。
4. 统一普通通知、异常巡检和后台维护的执行路径。
5. 定时任务可选择 Root 或一个命名 Agent；命名 Agent 的 Provider、模型、工具、Skills 和委托边以 AgentCatalog 为准。
6. Scheduled Run 不产生脱离当前执行的后台子 Agent；请求后台委托时自动按前台委托执行。
7. 执行结果先持久化，再投递；进程重启后可以恢复未完成投递。
8. 无法确认是否完成的执行标记为 `unknown`，不盲目重跑同一 occurrence。
9. 使用一次性、原子、可失败回滚的 SQLite v11 自动迁移；迁移后运行时代码只认识新 schema 和新枚举。

## 3. 非目标

- 不提供分布式 Scheduler 或跨节点共识。
- 不承诺外部渠道 exactly-once。渠道发送成功但本地确认前进程崩溃时，仍可能重复投递。
- 不保存 Scheduled Run 的用户聊天历史；每次执行默认是隔离上下文。
- 不自动把上一次执行的工具结果带到下一次执行。
- 不增加 `shell`、Webhook 等第二种 Job 执行类型；本期所有任务仍是 Agent 任务。
- 不保留旧字段、旧枚举、旧工具参数或旧字符串协议的运行时兼容分支。

## 4. 参考项目取舍

本设计采用以下参考经验：

- ZeroClaw：Cron 明确归属于某个 Agent，复用该 Agent 的身份、模型和权限；Cron 本身是一项顶层运行，而不是子 Agent 完成消息。
- Hermes：有限生命周期调用方不能接收后台完成结果时，委托回退为同步；进程崩溃后把副作用不确定的执行标记为 `unknown`，不自动重放。
- PicoBot：保留现有 SQLite 租约、Scheduler 集中投递、MessageBus 目标有序发送和命名 AgentCatalog。

明确不采用：

- Hermes 大量平台特例、JSON Job 主存储和多套 Scheduler provider；
- ZeroClaw 仅清除过期锁后重新执行的恢复方式；
- pi 的子进程式、无持久化 Subagent 示例；
- 把 Cron 结果伪装成后台 Agent Inbox 事件。

## 5. 核心模型

### 5.1 ScheduledJob

ScheduledJob 只回答五个问题：

```text
何时执行：schedule
由谁执行：agent_id
执行什么：prompt
发到哪里：channel + chat_id
何时投递：delivery_policy
```

目标 Rust 类型：

```rust
pub struct ScheduledJob {
    pub id: String,
    pub name: String,
    pub schedule: Schedule,
    pub prompt: String,
    /// None 表示 Root；Some(id) 表示当前 AgentCatalog 中的命名 Agent。
    pub agent_id: Option<String>,
    pub channel: String,
    pub chat_id: String,
    pub delivery_policy: DeliveryPolicy,
    pub enabled: bool,
    pub next_run_at: i64,
    pub last_run_at: Option<i64>,
    pub last_outcome: Option<ScheduledOutcomeKind>,
    pub created_at: i64,
    pub updated_at: i64,
    // durable claim
    pub locked_at: Option<i64>,
    pub lock_owner: Option<String>,
    pub lease_until: Option<i64>,
}
```

删除以下字段：

- `job_kind`：与 `delivery_policy` 重复；
- `model`：当前并未实际应用，且会绕开命名 Agent 的 Provider/Model 定义；
- `delete_after_run`：当前工具不开放且始终写 `false`；`Schedule::At` 完成领取后统一禁用，用户显式删除即可。

### 5.2 DeliveryPolicy

只保留三个值：

```rust
pub enum DeliveryPolicy {
    Always,
    OnAlert,
    Never,
}
```

- `always`：任何终态都投递；
- `on_alert`：仅 `alert`、`failed`、`refused`、`unknown` 投递；
- `never`：任何终态都不投递，只保留执行记录。

删除 `Direct`。Agent 不再有自行完成最终投递的职责。

### 5.3 ScheduledOutcome

Agent 可以主动提交四种结果，运行时恢复还可以产生 `unknown`：

```rust
pub enum ScheduledOutcome {
    Ok { message: String },
    Alert { message: String },
    Failed { message: String },
    Refused { message: String },
    Unknown { message: String }, // 仅运行时生成，模型不能提交
}
```

语义：

- `ok`：任务成功完成，没有需要用户关注的异常；
- `alert`：任务成功完成并发现需要用户关注的事实；
- `failed`：检查或任务没有可靠完成；
- `refused`：安全策略、授权或 Agent 自身约束拒绝执行；
- `unknown`：进程在持久化终态前退出，无法判断外部副作用是否发生。

投递矩阵：

| Outcome | `always` | `on_alert` | `never` |
|---|---:|---:|---:|
| `ok` | 投递 | 静默 | 静默 |
| `alert` | 投递 | 投递 | 静默 |
| `failed` | 投递 | 投递 | 静默 |
| `refused` | 投递 | 投递 | 静默 |
| `unknown` | 投递 | 投递 | 静默 |

Agent 只报告事实，不能通过工具参数提供 `notify=true/false`。投递权始终属于 Scheduler。

### 5.4 ScheduledRunStatus

运行状态只描述生命周期，不表达业务是否正常：

```rust
pub enum ScheduledRunStatus {
    Claimed,
    Running,
    Completed,
    Failed,
    TimedOut,
    Cancelled,
    Interrupted,
    Unknown,
}
```

成功调用终结工具后，生命周期状态是 `completed`，业务结果由 `outcome` 表达；例如 `completed + failed` 表示 Agent 正常结束并明确报告检查失败。Provider 错误或结果协议缺失则是 `failed + failed`。

## 6. 总体架构

```mermaid
flowchart TD
    Tick[Scheduler tick] --> Claim[Storage claim occurrence]
    Claim --> RunRow[(job_runs: claimed)]
    Claim --> Advance[提前推进 next_run / 禁用 At]
    RunRow --> Resolve[ScheduledAgentRunner]
    Resolve --> Catalog[Root config / AgentCatalog]
    Resolve --> Agent[AgentLoop]
    Agent --> Tools[受限工具 + complete_scheduled_run]
    Tools --> Outcome[ScheduledOutcome]
    Outcome --> Commit[原子提交 Run 终态与 delivery_status]
    Commit -->|suppressed / not_requested| Done[完成]
    Commit -->|pending| Delivery[Scheduler delivery drain]
    Delivery --> Bus[MessageBus / OutboundDispatcher]
    Bus --> Channel[Channel]
    Channel --> Ack[delivery_status = delivered]
```

组件职责：

| 组件 | 职责 | 明确不负责 |
|---|---|---|
| `Scheduler` | tick、领取、并发上限、执行超时、恢复、投递 drain | 解释模型自然语言 |
| `ScheduledAgentRunner` | 解析 Root/命名 Agent、构造隔离上下文、运行 Agent | 渠道发送、next-run 计算 |
| `AgentLoop` | 模型/工具循环、识别终结工具已提交 | Job 状态或渠道策略 |
| `complete_scheduled_run` | Schema 校验并提交一次结构化 Outcome | 消息发送、数据库写入 |
| `Storage` | occurrence、租约、终态、投递状态的原子转换 | Provider 和 Channel I/O |
| `OutboundDispatcher` | 目标有序、瞬态错误重试、渠道调用、类型化投递回执 | Scheduled Run 业务分类 |

## 7. 结构化终结协议

### 7.1 工具定义

所有 Scheduled Run 都运行时注入同一个工具：

```json
{
  "name": "complete_scheduled_run",
  "parameters": {
    "type": "object",
    "properties": {
      "outcome": {
        "type": "string",
        "enum": ["ok", "alert", "failed", "refused"]
      },
      "message": {
        "type": "string",
        "minLength": 1,
        "maxLength": 16384
      }
    },
    "required": ["outcome", "message"],
    "additionalProperties": false
  }
}
```

约束：

- `runtime_injected() == true`，Agent definition 的 `tools` 不得声明它；
- 只在 `ToolExecutionContext` 带 Scheduled completion sink 时可用；
- `exclusive() == true`，不与其他工具并行；
- 每次运行只接受一次；
- `unknown` 不出现在模型可见 schema 中；
- message 去除首尾空白后必须非空，并在字符边界安全截断到上限。

### 7.2 AgentLoop 终结行为

`ToolExecutionContext` 增加可选的 `ScheduledCompletionSink`。终结工具用一次性 compare-and-set 写入 Outcome。AgentLoop 在每个工具调用之后检查 sink：

1. 未提交：继续普通工具循环；
2. 已提交：把本次终结工具调用和结果写入 Agent transcript；
3. 同一 Provider 消息中排在终结工具之后的工具调用统一归约为 `Cancelled`，原因是 Scheduled Run 已完成；
4. 不再调用 Provider，立即返回结构化 Scheduled 结果。

终结工具必须是最后的语义动作，但运行时不依赖模型遵守这一提示来保证结束。

### 7.3 Fail-closed

只有合法的结构化提交才能得到 `ok` 并可能静默。以下情况统一生成 `failed`，不读取文本猜测：

- Agent 输出普通最终文本但没有调用终结工具；
- 输出任何 `NO_REPLY` 变体；
- 工具参数不合法且模型未修正；
- 达到最大工具迭代次数；
- Provider 错误；
- Agent 返回空结果；
- 执行超时。

普通最终文本可以截断后保存在 `diagnostic`，但不得作为通知正文。用户通知由 Scheduler 生成，例如：

```text
定时任务「生产站点巡检」未能完成：Agent 未提交结构化运行结果。
```

## 8. Agent 解析与权限

### 8.1 Root 任务

`agent_id = NULL` 表示使用当前 Root Provider、模型、上下文窗口和 Skills。工具从 Root registry 派生，但移除：

- `send_message`；
- `cron_add`、`cron_update`、`cron_remove`、`cron_enable`、`cron_disable`；
- `reload_config`；
- 只服务于交互会话或后台收件箱控制的工具。

再注入 `complete_scheduled_run`。Root Scheduled Run 不加载用户聊天历史。

### 8.2 命名 Agent 任务

`agent_id = Some(id)` 必须从当前不可变 AgentCatalog 解析：

- Provider profile、模型、上下文窗口来自 Agent definition；
- 工具和 Skills 完全按 definition allowlist；
- `complete_scheduled_run` 作为固有运行时工具额外注入，不构成权限扩张；
- 委托边按 definition 的 `delegates`；
- Job 不提供 per-job tools 或 model override。

创建和更新任务时校验当前 `agent_id`。如果之后重载删除或禁用了该 Agent，Gateway 不因一个 Job 无法启动；该 occurrence 记录为 `failed`，并按投递策略通知。Health 页面同时报告悬空 Agent 引用。

### 8.3 AgentRun 记录

Scheduled 顶层执行仍复用 `agent_runs` 审计和 transcript，但不增加新的 `AgentRunMode`：

- `mode = foreground`，因为 Scheduler 同步等待它；
- `caller_agent_id = SCHEDULER`；
- `caller_scope_id = scheduled:<job_id>`；
- `root_session_id = scheduled-run:<job_run_id>`，它是审计 scope，不是可接收 Inbox 的 Session；
- `completion_slot_reserved = false`；
- `job_runs.agent_run_id` 关联顶层 AgentRun。

这是执行来源的区别，不是第三种并发模式，因此不扩展 `foreground/background` 枚举。

## 9. 子 Agent 语义

Scheduled Agent 可以调用 `delegate`，但所有子任务必须在本次 Scheduled Run 内收敛：

```text
delegate(mode=foreground) → 正常执行
delegate(mode=background) → 自动改为 foreground，并在工具结果中说明降级
```

理由：

- `scheduled-run:<id>` 不是用户 Session，不能消费 durable inbox continuation；
- Scheduler 必须在一次 run 内得到完整 Outcome；
- 避免创建无法投递的 `cron:<id>` completion；
- 前台子 Agent 仍可并行批量执行并由父 Agent 汇总。

Scheduled Agent 不能使用 `emit_signal` 向用户 Session 建立旁路。子 Agent 的最终结果作为普通工具结果返回父 Scheduled Agent，只有父 Agent 可以调用 `complete_scheduled_run`。

`ScheduledCompletionSink` 是顶层运行能力，不随 `ToolExecutionContext` 克隆给子 Agent。Coordinator 构造子 Agent context 时必须显式清空该能力，子 Agent registry 也不得注入终结工具；否则子 Agent 会越过父 Agent 汇总直接结束整次任务。

Root Scheduled Agent 的第一次委托必须走 AgentCatalog 的 `root_can_delegate()` 规则，不能把合成的 `SCHEDULER` 或 `ROOT` 身份误当作命名 Agent 传给 `can_delegate()`。命名 Scheduled Agent 的后续委托仍走 `can_delegate(caller, target)`。这一区分只影响委托边校验，不创建第二条 Scheduled 执行路径。

## 10. occurrence、领取和崩溃恢复

### 10.1 领取事务

`claim_due_scheduled_jobs` 改为 `claim_due_scheduled_runs`。一次领取在同一事务中：

1. 选择 `enabled=1 AND next_run_at<=now` 且租约为空/过期的 Job；
2. 条件更新租约；
3. 插入唯一的 `job_runs(status=claimed, delivery_status=awaiting_result)` 行，并把其自增 `id` 作为本次 occurrence 的稳定 ID，同时快照 Agent、投递策略和目标；
5. 对 `Every/Cron` 把 `next_run_at` 推进到领取时刻之后的第一个未来时间；
6. 对 `At` 立即设置 `enabled=0`；
7. 提交后返回 `ClaimedScheduledRun { job_snapshot, run_id, owner }`。

领取条件、Run 插入和 Job 推进处于同一写事务；SQLite 的写串行化和条件租约保证一次到期状态只能提交一个 Run。无需额外维护 occurrence key 或 schedule revision。推进下次时间发生在执行之前，因此进程崩溃不会使本次 occurrence 被自动重放；用户之后重新启用一次性任务会建立一个新的 Run，不会与历史运行冲突。错过的多个历史 tick 不逐个补跑，只执行当前到期 occurrence，并计算下一个未来时间。

Job 执行租约固定为 `execution_timeout + shutdown_grace`，执行本身必须在 `execution_timeout` 内终止，因此不增加心跳续租任务。终态提交同时校验 `job_run_id + lock_owner + 非终态 status`；租约过期后迟到的旧执行不能修改新 Run 或 Job 摘要。

### 10.2 状态转换

```text
claimed → running → completed
                  ├→ failed
                  ├→ timed_out
                  ├→ cancelled
                  └→ interrupted

claimed/running --process restart--> unknown
```

所有终态不可重写。Job 的租约 owner 必须匹配才能提交终态，旧执行不得覆盖新领取。

### 10.3 启动恢复

Gateway 启动、Scheduler admission 尚未开放前：

1. 找到所有 `job_runs.status IN ('claimed','running')`；
2. 标记为 `unknown`，写入固定诊断；
3. 根据该 run 快照的 delivery policy 设置 `pending` 或 `not_requested`；
4. 清除关联 Job 的旧租约；
5. 不回退已推进的 `next_run_at`，也不重跑 occurrence；
6. 开放 Scheduler admission 后先 drain pending delivery，再领取新任务。

优雅关停由 TaskSupervisor 先停止新领取，再取消/限时等待运行；能够得到明确取消结果时记录 `interrupted`，只有硬崩溃才在下次启动归为 `unknown`。

## 11. 投递设计

### 11.1 先提交再发送

执行完成事务负责：

1. 提交 AgentRun 终态；
2. 提交 JobRun status、outcome、message、diagnostic 和 duration；
3. 更新 ScheduledJob 的 `last_run_at`、`last_outcome`；
4. 按矩阵把 delivery status 设置为：
   - `pending`：需要投递；
   - `suppressed`：`on_alert + ok`；
   - `not_requested`：`never`。
5. 释放 Job 租约。

任何渠道 I/O 都发生在事务之后。

### 11.2 复用 job_runs 作为轻量 outbox

不新增通用消息队列表。JobRun 自带目标快照和投递状态：

```text
awaiting_result → pending / suppressed / not_requested
pending → delivering → delivered
                     ├→ pending（瞬态失败、退避后重试）
                     └→ failed（永久失败或次数耗尽）
```

Scheduler 在每次 tick 前后以及启动恢复后有界 drain：

- 原子认领 `pending` 或租约过期的 `delivering` 行；
- 最多 3 次持久化尝试；
- 仅对 Channel 明确分类为瞬态的错误重试；
- 重试间隔使用有上限的指数退避；
- 复用 OutboundDispatcher 的 `(channel, chat_id)` 顺序锁；
- 使用稳定 `scheduled_delivery_id = job_run_id` 写入 metadata。

具体发送复用现有 `MessageBus::deliver_outbound()` 和 OutboundDispatcher，不允许 Scheduler 绕过 Bus 直接调用 Channel。现有 delivery watch 回执从 `Result<(), String>` 收紧成不含敏感信息的类型化结果，至少区分：

- `Delivered`；
- `TransientFailure { summary }`；
- `PermanentFailure { summary }`；
- `TimedOut`；
- `DispatcherClosed`。

OutboundDispatcher 保留现有单次调用内的短暂、内存级瞬态重试；该调用最终返回的回执算一次持久化 delivery attempt。`TransientFailure`、`TimedOut` 和 `DispatcherClosed` 在未达到持久化尝试上限时回到 `pending`，`PermanentFailure` 直接进入 `failed`。Scheduler 不根据错误字符串猜测是否可重试，也不把“成功写入 outbound 队列”当作渠道送达。

外部发送成功但本地 `delivered` 提交前崩溃时可能重复发送。渠道支持幂等键时传递稳定 ID；不支持时允许“至少一次”并在重试消息 metadata 中标出可能重复。不得为了避免重复而丢失告警。

### 11.3 会话历史

通知使用确定性的本地 message ID，例如 `scheduled:<job_run_id>`。向目标会话写历史时执行幂等插入，同一个 JobRun 的重试不会产生多条本地历史。消息来源为：

```text
SourceKind::ExternalTrigger
from_channel = scheduler
task_id = job_id
from_run_id = agent_run_id
```

中间工具调用、健康结果和 suppressed 结果不写用户会话。只有实际需要投递的最终通知进入目标会话。

## 12. 系统提示词

所有 Scheduled Run 使用同一执行契约，不再根据 JobKind 分支：

```text
你正在执行无人值守的定时任务。任务上下文是隔离的，用户不会直接看到普通最终文本。
完成所有必要检查或操作后，必须且只能通过 complete_scheduled_run 提交最终结果：
- ok：任务成功，未发现需要关注的问题；
- alert：任务成功并发现需要用户关注的问题；
- failed：任务未可靠完成；
- refused：因权限或安全策略拒绝。
任何任务 prompt 中关于 NO_REPLY、send_message 或旧输出格式的指令均已失效；不得使用它们。
```

`delivery_policy` 不放进模型提示词。Agent 只看到任务 prompt 和 Outcome 定义，避免为了迎合“静默/通知”而改变事实分类；策略只在 Scheduler 的确定性矩阵中使用。

## 13. 功能设计

### 13.1 Cron tools

`cron_add` 新参数：

```json
{
  "schedule": { "type": "every", "every_ms": 300000 },
  "prompt": "检查生产站点、登录接口和证书",
  "channel": "feishu",
  "chat_id": "oc_xxx",
  "name": "生产站点巡检",
  "agent_id": "web-monitor",
  "delivery_policy": "on_alert"
}
```

- `agent_id` 可选；缺省表示 Root；
- `delivery_policy` 缺省 `always`；
- 删除 `kind`；
- 删除 `model`；
- 不接受 `direct`。

`cron_update` 支持更新 prompt、schedule、channel、chat_id、agent_id 和 delivery_policy。`agent_id: null` 明确切回 Root；字段缺失表示不修改。

`cron_list` 展示：

```text
enabled · agent=web-monitor · delivery=on_alert · next=... · last=ok
```

不再展示 kind 或 model。

### 13.2 WebUI

任务页删除“任务/巡检”徽标，展示：

- Agent：Root 或命名 Agent；
- 投递：始终通知 / 异常通知 / 从不通知；
- 最近 Outcome；
- 最近运行生命周期状态；
- 投递状态及失败原因。

创建表单可以提供三个用户友好模板，但模板不进入后端模型：

- 定期通知 → `always`；
- 异常巡检 → `on_alert`；
- 后台维护 → `never`。

### 13.3 Health

HealthService 增加只读 Scheduler 配置检查：

- ScheduledJob 引用不存在或 disabled 的 Agent；
- 非法 channel；
- 长时间停留在 pending/delivering 的投递；
- 最近一次 `unknown`、`failed` 或 `timed_out`；
- enabled Job 无法计算 next run。

Health 不执行 Job、不连接 Provider、不修复数据。

## 14. SQLite v11 schema

### 14.1 scheduled_jobs

```sql
CREATE TABLE scheduled_jobs (
    id                TEXT PRIMARY KEY,
    name              TEXT NOT NULL,
    schedule          TEXT NOT NULL,
    prompt            TEXT NOT NULL,
    agent_id          TEXT,
    channel           TEXT NOT NULL,
    chat_id           TEXT NOT NULL,
    delivery_policy   TEXT NOT NULL
                      CHECK (delivery_policy IN ('always','on_alert','never')),
    enabled           INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0,1)),
    next_run_at       INTEGER NOT NULL,
    last_run_at       INTEGER,
    last_outcome      TEXT CHECK (
                        last_outcome IS NULL OR
                        last_outcome IN ('ok','alert','failed','refused','unknown')
                      ),
    locked_at         INTEGER,
    lock_owner        TEXT,
    lease_until       INTEGER,
    created_at        INTEGER NOT NULL,
    updated_at        INTEGER NOT NULL,
    CHECK (length(trim(id)) > 0),
    CHECK (length(trim(name)) > 0),
    CHECK (length(trim(prompt)) > 0),
    CHECK (length(trim(channel)) > 0),
    CHECK (length(trim(chat_id)) > 0),
    CHECK (agent_id IS NULL OR length(trim(agent_id)) > 0),
    CHECK (
      (locked_at IS NULL AND lock_owner IS NULL AND lease_until IS NULL) OR
      (locked_at IS NOT NULL AND lock_owner IS NOT NULL AND lease_until IS NOT NULL)
    )
);

CREATE INDEX idx_jobs_claimable
ON scheduled_jobs(enabled, next_run_at, lease_until);
```

### 14.2 job_runs

```sql
CREATE TABLE job_runs (
    id                       INTEGER PRIMARY KEY AUTOINCREMENT,
    job_id                   TEXT NOT NULL
                             REFERENCES scheduled_jobs(id) ON DELETE CASCADE,
    scheduled_for            INTEGER NOT NULL,
    agent_run_id             TEXT UNIQUE
                             REFERENCES agent_runs(id) ON DELETE SET NULL,

    -- claim-time immutable snapshot
    agent_id                 TEXT,
    delivery_policy          TEXT NOT NULL
                             CHECK (delivery_policy IN ('always','on_alert','never')),
    target_channel           TEXT NOT NULL,
    target_chat_id           TEXT NOT NULL,

    started_at               INTEGER,
    finished_at              INTEGER,
    status                   TEXT NOT NULL CHECK (status IN (
                               'claimed','running','completed','failed',
                               'timed_out','cancelled','interrupted','unknown'
                             )),
    outcome                  TEXT CHECK (
                               outcome IS NULL OR
                               outcome IN ('ok','alert','failed','refused','unknown')
                             ),
    message                  TEXT,
    diagnostic               TEXT,
    duration_ms              INTEGER,

    delivery_status          TEXT NOT NULL CHECK (delivery_status IN (
                               'awaiting_result','not_requested','suppressed','pending',
                               'delivering','delivered','failed'
                             )),
    delivery_attempts        INTEGER NOT NULL DEFAULT 0,
    delivery_next_attempt_at INTEGER,
    delivery_lease_owner     TEXT,
    delivery_lease_until     INTEGER,
    delivery_error           TEXT,

    created_at               INTEGER NOT NULL,
    updated_at               INTEGER NOT NULL,
    CHECK (agent_id IS NULL OR length(trim(agent_id)) > 0),
    CHECK (length(trim(target_channel)) > 0),
    CHECK (length(trim(target_chat_id)) > 0),
    CHECK (delivery_attempts >= 0),
    CHECK (duration_ms IS NULL OR duration_ms >= 0),
    CHECK (
      (delivery_lease_owner IS NULL AND delivery_lease_until IS NULL) OR
      (delivery_lease_owner IS NOT NULL AND delivery_lease_until IS NOT NULL)
    )
);

CREATE INDEX idx_job_runs_job_finished
ON job_runs(job_id, finished_at DESC);

CREATE INDEX idx_job_runs_recovery
ON job_runs(status, updated_at);

CREATE INDEX idx_job_runs_delivery
ON job_runs(delivery_status, delivery_next_attempt_at, delivery_lease_until);
```

不为 AgentCatalog 建数据库外键；Agent 定义是配置运行代资源，不是 SQLite 行。`agent_id` 和 definition hash 的最终审计值保存在关联 AgentRun 中。

## 15. 自动迁移设计

### 15.1 总体原则

- `SCHEMA_VERSION` 从 10 增加到 11；
- Storage 在 Gateway 启动后台任务之前执行迁移；
- migration 使用一个专用连接和 `BEGIN IMMEDIATE`，在单个 SQLite 事务中完成；
- 任一步失败则整体回滚，`user_version` 保持原值，Gateway 拒绝启动；
- v11 运行时代码不读取旧列、不解析旧枚举、不调用旧函数；
- 旧 schema 知识只存在于 `storage/migrations/v11_scheduled.rs`；
- v11 数据库由旧版本二进制打开时，沿用现有“数据库版本过新”拒绝策略；
- 不支持自动降级。

`BEGIN IMMEDIATE` 必须在配置的 SQLite busy timeout 内取得写锁；若另一个 PicoBot 进程仍在使用同一数据库且无法取得锁，启动直接报错，不等待后台任务运行后再迁移。部署流程必须先停旧进程再启动新版本。

### 15.2 初始化顺序调整

当前 `init_scheduler_schema()` 在 `migrate_schema()` 之前执行，会让新旧 DDL 的所有权混乱。实施后：

1. `migrate_schema()` 成为 Scheduler 表 DDL 的唯一入口；
2. 全新数据库直接创建 v11 表；
3. `user_version=0` 但已有旧表的数据库先执行现有 legacy→v10 规范化，再执行 v10→v11；
4. 测试不再直接调用可绕过 migration 的 `init_scheduler_schema()`，统一通过 `Storage::new` 或专用 latest-schema fixture。

### 15.3 v10 预检

在创建新表前读取并验证全部旧行：

- schedule JSON 必须能反序列化；
- delivery policy 必须是 `direct/always/on_alert/never`；
- Job ID、channel、chat_id 和 prompt 必须满足非空约束；
- 旧 JobRun 外键必须能找到 Job；
- Job lease 字段必须全部为空或全部非空；
- 发现损坏数据时返回包含 Job ID 的 migration error，不做默认修复。

### 15.4 Job 字段映射

| v10 | v11 | 规则 |
|---|---|---|
| `job_kind` | 删除 | 不读取其运行语义 |
| `delivery_policy=direct` | `always` | 新代码统一中央投递 |
| `always/on_alert/never` | 原值 | 保留 |
| `model` | 删除 | 当前执行路径未应用该值；迁移日志报告被删除的非空数量 |
| `delete_after_run` | 删除 | `At` 任务改为完成领取后禁用 |
| 无 `agent_id` | `NULL` | 使用 Root Scheduled Agent |
| `last_status=ok` | `last_outcome=ok` | 仅作列表摘要 |
| 其他非空 `last_status` | `last_outcome=failed` | 详细旧信息仍在历史 run |

内置 `picobot-routine-maintenance` 的 prompt 在迁移中按固定 Job ID 改成不含 `NO_REPLY` 的任务描述。用户自定义 prompt 不做不安全的字符串替换；新的系统级 Scheduled 契约明确忽略其中关于 `NO_REPLY`、`send_message` 和旧输出格式的指令。

### 15.5 历史 JobRun 映射

历史行只用于审计，绝不因升级重新投递：

| v10 值 | v11 值 |
|---|---|
| `status=ok` | `status=completed` |
| `status=timeout` | `status=timed_out` |
| `status=error/delivery_error` | `status=failed` |
| 其他状态 | `status=unknown` |
| `result_kind=quiet` | `outcome=ok` |
| `result_kind=content` 且 Job 为 `on_alert` | `outcome=alert` |
| `result_kind=content` 其他情况 | `outcome=ok` |
| `result_kind=reported_failure` | `outcome=failed` |
| `result_kind=refused` | `outcome=refused` |
| 无法映射 | `outcome=unknown` |
| `delivery_status=direct/delivered` | `delivered` |
| `suppressed/skipped` | `suppressed` |
| `failed` 或存在 `delivery_error` | `failed` |
| 其他 | `not_requested` |

其他字段：

- `scheduled_for = started_at`；
- `message = output`；
- `diagnostic = error`；
- `target_*`、`delivery_policy` 从迁移时的 Job 行快照；
- `agent_run_id = NULL`；
- 所有 delivery lease 字段为空。

### 15.6 迁移时发现旧执行锁

v10 只有 Job lease，没有预先建立的 JobRun。若迁移时发现 `lock_owner` 非空或 lease 尚未清理，说明旧进程可能在终态提交前退出：

1. 为它创建一条 `status=unknown/outcome=unknown` 的 JobRun；
2. message 固定说明升级时发现未完成执行；
3. `always/on_alert` 设置 delivery `pending`，`never` 设置 `not_requested`；
4. recurring Job 的 `next_run_at` 推进到迁移时刻之后；
5. `At` Job 设为 disabled；
6. 清除旧租约。

这条未知通知可能与崩溃前已经送达但未提交的通知重复，但不会静默掩盖不确定状态。

### 15.7 SQLite 表重建

SQLite 删除列和修改 CHECK 约束采用 canonical table rebuild：

1. `CREATE TABLE scheduled_jobs_v11 ...`；
2. 写入转换后的 Job；
3. `CREATE TABLE job_runs_v11 ... REFERENCES scheduled_jobs_v11`；
4. 写入转换后的历史 Run 和旧锁恢复 Run；
5. 删除旧 `job_runs`；
6. 删除旧 `scheduled_jobs`；
7. rename `scheduled_jobs_v11`、`job_runs_v11`；
8. 重建索引；
9. 执行 `PRAGMA foreign_key_check` 并要求零行；
10. 最后设置 `PRAGMA user_version = 11` 并提交。

表重建必须在同一连接、同一事务中完成。不得用多个 pool connection 分散 DDL，也不得在事务提交前启动 Scheduler。

### 15.8 “不在代码层面兼容过去”的准确含义

允许且必须存在：

- 一次性 migration 对 v10 表和旧枚举的读取与转换；
- migration tests 的 v10 fixture；
- 迁移日志和损坏数据诊断。

明确禁止：

- `row_to_job` 同时尝试新旧列；
- `DeliveryPolicy::parse("direct")`；
- 保留 `JobKind` 但在新路径忽略；
- 保留 `handle_cron_message` 作为 fallback；
- 继续解析任意 `NO_REPLY` 文本；
- 新旧工具参数并存；
- 根据 `user_version` 在 Scheduler 运行期分支。

迁移成功后，进程内只有 v11 类型和 v11 SQL。

## 16. 旧代码清理清单

### `src/scheduler/mod.rs`

删除：

- `ScheduledDisposition`；
- `parse_scheduled_disposition()`；
- `managed` / `Direct` 双路径；
- `job_kind == Monitor` 分支；
- Agent 返回普通文本后再分类的代码；
- 先发送、后写 JobRun 的顺序。

替换为：claim occurrence → `ScheduledAgentRunner` → typed outcome → terminal commit → delivery drain。

### `src/session/session.rs`

删除：

- `create_cron_agent()`；
- `create_managed_scheduled_agent()`；
- `handle_cron_message()`；
- `handle_managed_scheduled_message()`；
- Cron 专用 `NO_REPLY` / `send_message` prompt。

Scheduled Agent 构造迁移到 Agent/Coordinator 边界，SessionManager 不再执行 Cron Agent。

### `src/storage/scheduler.rs`

删除：

- `JobKind` 及 parser；
- `DeliveryPolicy::Direct`；
- `model`、`job_kind`、`delete_after_run` 映射；
- `set_scheduled_job_behavior()`；
- 完成时才插入 JobRun 的旧事务。

新增严格 typed parser、occurrence claim、终态提交、未知恢复和持久化 delivery claim。

### `src/storage/mod.rs` 与 `src/storage/migrations/`

把 `SCHEMA_VERSION` 一次提升到 11，删除 migration 之前调用 Scheduler 旧 DDL 初始化函数的顺序。新增唯一的 v11 Scheduler migration 模块和跨表终态事务 API；迁移完成后通用 Storage 查询不得包含任何 v10 列名。

### `src/tools/cron.rs`

删除 `kind`、`model` 参数与所有默认联动；默认 `delivery_policy=always`。新增可选 `agent_id`，更新 list 输出和测试。

### `src/tools`

新增 `complete_scheduled_run.rs`。它是 runtime-injected、exclusive、Scheduled context-only 的无外部副作用控制工具。

### `src/agent`

新增 `ScheduledCompletionSink` 和 `AgentCoordinator::execute_scheduled()`；复用 foreground AgentRun 持久化，不创建 inbox completion。AgentLoop 在终结工具成功后停止。

### `src/session/messenger.rs`

把 Scheduled 通知改成稳定 message ID 的幂等写入；删除任何依赖 `cron:<id>` 作为可消费会话的行为。

### `src/bus`

保留 `MessageBus::deliver_outbound()` 的等待回执入口，把 `OutboundMessage.delivery` 和 `BusError` 的字符串结果改为类型化、可判定 retry class 的安全回执。OutboundDispatcher 仍是唯一 Channel 调用方；普通无回执消息继续使用 `publish_outbound()`。

### Gateway / WebUI / Protocol

- API JSON 删除 `job_kind`、`model`、`delete_after_run`、`result_kind`；
- 增加 `agent_id`、`outcome`、delivery attempts/状态；
- `webui/src/pages/TasksPage.svelte` 删除“巡检/任务”判断；
- Health 与任务详情展示新的结构化状态。

### 文档与内置知识

实施时同步更新：

- `README.md`；
- `docs/ARCHITECTURE.md`；
- `AGENTS.md`；
- `resources/skills/about-picobot/references/architecture.md`；
- `resources/skills/about-picobot/references/config.md`；
- `resources/skills/about-picobot/references/db-schema.md`；
- `resources/skills/about-picobot/references/tools.md`；
- 内置维护任务 prompt。

全仓库应不存在运行时 `NO_REPLY`、`JobKind`、`DeliveryPolicy::Direct` 或 `handle_cron_message` 引用。

## 17. 并发与生命周期不变量

1. 一个 Job 同时最多有一个持租约 occurrence；短周期任务不会重叠执行。
2. occurrence 的 JobRun 在 Agent 启动前持久化；同一个到期状态只能提交一个 Run。
3. `next_run_at` 在 claim 事务中推进；执行失败和进程崩溃不会重放同一 occurrence。
4. 只有 lease owner 可以把 run 从非终态推进到终态。
5. 所有终态不可重写；迟到 Agent 结果必须丢弃并记录日志。
6. Outcome 和投递策略都使用 claim-time snapshot；运行过程中编辑 Job 只影响后续 occurrence。
7. Outcome、Job 摘要和初始 delivery status 在同一事务提交。
8. 渠道 I/O 不发生在 SQLite 事务或 Session mutex 内。
9. Scheduled Run 不预留 Agent Inbox slot，也不向合成 session 投递 completion。
10. 后台委托在模型可见参数不变，但 Scheduled context 强制变为 foreground。
11. `never` 严格不通知，包括失败、拒绝、超时和 unknown；这些状态仍可通过管理页面和 Health 查看。
12. 静默只来源于结构化 `ok` 与策略矩阵，不能来源于普通文本。

## 18. 错误处理矩阵

| 场景 | Run status | Outcome | 投递内容来源 |
|---|---|---|---|
| Agent 提交 `ok` | completed | ok | Agent message |
| Agent 提交 `alert` | completed | alert | Agent message |
| Agent 提交 `failed` | completed | failed | Agent message |
| Agent 提交 `refused` | completed | refused | Agent message |
| Agent 未调用终结工具 | failed | failed | Scheduler 固定协议错误 |
| Provider 失败 | failed | failed | 安全归一化错误，不含响应正文 |
| 运行超时 | timed_out | failed | Scheduler 固定超时说明 |
| Gateway 优雅取消 | interrupted | failed | Scheduler 固定中断说明 |
| 硬崩溃恢复 | unknown | unknown | Scheduler 固定 unknown 说明 |
| Agent 定义不存在 | failed | failed | Agent ID 和修复建议 |
| 渠道发送永久失败 | 原 run 不变 | 原 outcome | delivery_status=failed |

投递失败不改变已经确定的执行 Outcome；它只改变 delivery status。

## 19. 实施顺序

本设计应在一个功能版本中完成，不能长期保留两套路径：

1. 增加 v11 migration 和新 Storage 类型、测试；
2. 增加 Scheduled completion sink、终结工具和 AgentLoop 终止语义；
3. 增加 `AgentCoordinator::execute_scheduled()`；
4. 改写 Scheduler claim、执行、恢复和 delivery drain；
5. 切换 Cron tools/API/WebUI；
6. 更新内置维护任务和文档；
7. 删除所有旧类型、旧函数和魔法字符串；
8. 运行全量验证后再提交，并按功能变化增加产品中段版本号一次。

代码合并点只允许新路径。迁移代码可以先写，但最终提交中不允许 Scheduler 通过 feature flag 或 schema 判断走旧路径。

## 20. 测试设计

### 单元测试

- `DeliveryPolicy × ScheduledOutcome` 全矩阵；
- 终结工具 schema、空 message、额外字段、重复调用；
- 终结工具之后的同批工具归约为 Cancelled；
- 普通文本、所有 `NO_REPLY` 变体都不能产生 `ok`；
- named/root Agent 解析和工具收窄；
- Scheduled background delegate 自动前台化；
- 两个并发 Scheduler 对同一到期 Job 只有一个 claim 成功；
- At claim 后禁用；
- recurring claim 时推进到未来；
- lease owner 条件提交；
- 迟到结果不能覆盖 unknown/timeout；
- delivery claim、瞬态重试、永久失败和尝试上限；
- `deliver_outbound` 只有收到 Channel 成功回执才返回 Delivered，入队成功不算送达；
- 回执保留 transient/permanent 分类且不泄露渠道敏感响应；
- 本地历史稳定 message ID 去重。

### Migration 测试

- 空数据库直接得到 v11；
- 真实 v10 fixture 保留所有 Job 和历史 Run；
- `task/monitor` 列被物理删除；
- `direct` 全部转为 `always`，运行时无法解析 direct；
- 非空 model 计数被记录且列被删除；
- delete_after_run 列被删除；
- 历史 Run 不产生 pending delivery；
- 旧锁生成 unknown run 并按策略决定 pending/not_requested；
- 内置维护 prompt 不含 `NO_REPLY`；
- 损坏 schedule/policy 使迁移原子失败且 `user_version` 不变；
- `PRAGMA foreign_key_check` 为空；
- v11 重启迁移幂等；
- v12+ 数据库被拒绝。

### 集成测试

- `always + ok` 实际投递；
- `on_alert + ok` 静默但 JobRun 可查询；
- `on_alert + alert/failed/refused` 实际投递；
- `never` 在所有 Outcome 下均不投递；
- Provider 普通文本完成被转为协议失败通知；
- Gateway 在结果提交后、发送前重启，pending 在启动后恢复；
- Gateway 在发送后、ack 前重启，允许有标识的重复但不丢失；
- Gateway 在 Agent 执行中退出，恢复为 unknown 且不重跑同一 occurrence；
- 命名 Agent 被删除后 Job 明确失败且 Gateway 仍能启动；
- Cron 内 foreground 子 Agent 汇总成功，background 参数不会产生 Inbox 事件。

### 必跑验证

```bash
cargo test --lib
cargo test --test test_scheduler
cargo test --test test_request_format
cargo clippy --all-targets --all-features -- -D warnings
cd webui && npm run check && npm run build
cargo build
git diff --check
```

## 21. 验收标准

1. 新建和更新任务的 API/工具中没有 `kind`、`monitor` 或 `model` 字段。
2. 数据库 `scheduled_jobs` 不存在 `job_kind`、`model`、`delete_after_run`。
3. `DeliveryPolicy` 只有 `always/on_alert/never`。
4. 所有 Scheduled Run 都必须调用 `complete_scheduled_run`；无调用时 fail-closed。
5. 全仓库运行时代码不再出现 `NO_REPLY` 结果协议。
6. Scheduler 只有一条 Agent 执行和一条中央投递路径。
7. `on_alert + ok` 不投递，其余矩阵行为与本设计一致。
8. 结果提交后崩溃不会丢失待投递消息。
9. 执行中崩溃产生 `unknown`，同一 occurrence 不自动重跑。
10. v10 数据库首次启动自动迁移到 v11，失败时完整回滚；迁移后没有运行时兼容代码。