mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-17 20:50:49 +08:00
oliver
896126ef88
Keeps the running-count badge visible without competing with the new-chat action above the session list. Co-authored-by: Cursor <cursoragent@cursor.com>
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
---
|
||
name: background-jobs
|
||
description: "长时间任务（数分钟到数小时）用 start_job/get_job；同轮不要干等；断线后任务可继续，靠 job_id 恢复或 notify 通知。"
|
||
---
|
||
|
||
# 后台长任务 — Background Jobs
|
||
|
||
## 核心事实
|
||
|
||
1. **同轮等不了两小时**（也不该等）。`sleep` 最多 120 秒。
|
||
2. `start_job` 立刻返回 `job_id`；**agent 断线 / 本轮结束，进程仍可继续跑**（gateway 进程在的前提下）。
|
||
3. 正确姿势是 **交作业 → 告知用户 job_id → 结束本轮**；以后再查，或靠完成通知。
|
||
|
||
## 推荐流程（1–2 小时任务）
|
||
|
||
```text
|
||
1. write_file 写自包含脚本（输入/输出路径写死）
|
||
2. start_job(command=..., timeout_s=7200, name=..., notify={...可选})
|
||
3. 回复用户：已提交后台任务，job_id=...，跑完会通知 / 请稍后问「查任务 job_xxx」
|
||
4. 结束本轮（不要 sleep 循环两小时）
|
||
5. 之后任意一轮：get_job(job_id) 或 list_jobs → 读产出 → 需要时 save_deliverable_attachment
|
||
```
|
||
|
||
## 断线后会怎样
|
||
|
||
| 情况 | 行为 |
|
||
|------|------|
|
||
| 本轮对话结束 / 用户离开 | 任务继续；磁盘有 `data/jobs/<job_id>/` |
|
||
| 用户过一会再问 | `get_job` / `list_jobs` 恢复状态 |
|
||
| Gateway 重启但子进程还在 | 后台 reaper（约 15s）按超时/pid 对账回收；Chat 徽章也会刷新 |
|
||
| Gateway 整机挂掉 | 子进程可能被系统清掉；下次 reaper/`get_job` 标失败/超时 |
|
||
|
||
## notify（可选，推荐渠道场景）
|
||
|
||
`start_job` 可带：
|
||
|
||
```json
|
||
"notify": {
|
||
"channel": "whatsapp",
|
||
"chat_id": "<群或会话 id>",
|
||
"account_id": "wa-default",
|
||
"message": "可选自定义文案"
|
||
}
|
||
```
|
||
|
||
任务结束（成功/失败/超时/取消）后会往该渠道塞一条出站提醒（含 `job_id`）。
|
||
微信需额外 `context_token`（与现有 weixin 出站一致）。
|
||
|
||
**WebChat**：没有渠道 notify 时，靠用户稍后再问 + `list_jobs`。
|
||
|
||
## 工具
|
||
|
||
| 工具 | 作用 |
|
||
|------|------|
|
||
| `start_job` | 后台启动，返回 `job_id`（默认 2h，最大 3h） |
|
||
| `get_job` | 查状态与日志尾；`done=true` 表示结束 |
|
||
| `list_jobs` | 近期任务 |
|
||
| `cancel_job` | 取消 |
|
||
| `sleep` | 仅短轮询间隙（≤120s），不是长等 |
|
||
|
||
与 `run_command` 同一开关：`AIA_ENABLE_RUN_COMMAND`。
|
||
|
||
## Chat 可视化
|
||
|
||
Chat 左侧导航底部 **「后台任务」**（用户区上方）右侧数字徽章持续显示运行中数量（约每 4 秒刷新，无需点开面板）；用户菜单也有入口：
|
||
- 有任务时按钮高亮，右侧数字徽章变红
|
||
- 点开后可：列表 / **终止** / **全部终止** / **清除记录** / 日志
|
||
- 面板打开时约每 4 秒自动刷新列表
|
||
|
||
## 不要做
|
||
|
||
- 同轮 `sleep`/`get_job` 死循环拖两小时
|
||
- 用 `run_command` 跑多小时脚本
|
||
- 不告诉用户 `job_id` 就结束（断线后难找回，除非用户记得或去 Chat「后台任务」/ `list_jobs`）
|