---
title: 提示词后台任务
description: 使用 Pipecat 原生 Jobs 委派远程 OpenCode 任务。
---

# 提示词后台任务 MVP

提示词 Pipeline 可以绑定一个「后台任务」工具。对话模型提交任务后立即获得任务编号，继续对话；应用级 Pipecat Worker 拥有长任务，语音断线不取消远端执行。OpenCode 是当前唯一实现的执行器。

## 使用

1. 更新后端依赖，并执行数据库迁移：`cd backend && .venv/bin/python -m alembic upgrade head`。迁移新增任务记录/事件表，并允许 task 工具类型。
2. 重启后端。第一版要求单个应用进程（一个 Uvicorn worker），使用原生 AsyncQueueBus。
3. 在远端准备好仓库、OpenCode 模型与服务。此功能连接已有 `opencode serve`，不会在远端安装软件或启动进程。服务应通过后端可访问的地址提供 HTTP(S)，如开启 Basic 鉴权，请配置 `OPENCODE_SERVER_PASSWORD`。
4. 在「组件库 / 工具」新建「后台任务 · OpenCode」，填写服务地址、远端工作目录、用户名、服务密码和等待时限。服务地址/目录固定于配置，不由 LLM 参数决定。
5. 在提示词 Pipeline 助手的「外部工具」中选择该工具。默认 instruction 参数由模型提供，可配置固定值或助手变量。任务工具不支持最终结果映射到会话变量。
6. 保存助手，在手动语音调试中提出任务。展开「后台任务」查看进展、结果，处理远端问题/权限，或停止任务。网页刷新后仍可按助手查询任务。

前台新增三个控制函数：`get_background_task`、`cancel_background_task`、`send_background_task_message`。主提交函数使用工具资源的函数名。控制函数名由平台保留。单个远端问题可由对话工具回答；权限和多个问题请在网页卡片处理。不会自动批准权限。

## 运行与恢复

- NativeTaskRuntime 只组装 `WorkerRunner`、常驻 CoordinatorWorker 和 RemoteAgentWorker。派发、超时、取消和 FIFO 串行执行由 Pipecat 原生 Job 系统负责。
- 等待时限覆盖每次本地 Job（含排队），重启或重新观察后重新计时，不代表累计任务寿命上限；超时触发远端停止核查。原生 Job 全局 FIFO 串行；若另有未结束的远端句柄，新的编码任务不会提交，需先核查或停止旧任务。被阻挡的新任务会标为失败并说明尚未向远端提交；解决旧任务后需重新提交，不会自动恢复。无法约束平台之外的 OpenCode 客户端。
- 提交回执表示平台接受任务。OpenCode 的 204 只表示远端接收；必须取得关联到本次 messageID 的完成消息才能显示成功。
- OpenCodeAdapter 负责创建远端 session、订阅 SSE、异步提交、结果查询和 abort。每个任务使用独立远端 session，内部步骤仍由 OpenCode 完成。
- 原生 Job 取消不代表远端已停止。适配器调用 abort 并查询远端状态；未确认时保留「停止待确认」。
- 连接中断会尝试重新观察，不重新发送原指令。无法核查时显示「状态待核查」，可显式核查或请求停止。
- 应用退出仅停止本地监听，不主动 abort 远端任务；重启后使用已保存的远端句柄重新观察。没有远端句柄的中断任务不会自动重新提交。
- 任务和远端连接配置保存在数据库；公开 API 不返回密码或连接快照。平台保留远端助手文本与错误文本，未保存工具原始执行日志；语音通知超过16000字符时保留首尾并明确标记省略，网页可查看完整已保存文本。资源后续编辑不会改变已运行任务的地址/目录。
- 在线进度通过现有自定义 app message 传送，网页任务卡片另按助手轮询快照以支持刷新。完成/失败/取消/状态未知/等待输入通过 Pipecat 原生上下文消息触发前台模型回复；用户/助手正在说话时由原生聚合器安排。离线结果只保留在任务卡片，不自动在新语音连接中播报旧结果。

## 第一版边界

仅提示词 Pipeline 支持任务工具。Workflow、Realtime、启动 Action 不支持。自动测试/Responses 测试的模拟工具执行路径不提交、查询或控制真实任务；请使用手动语音调试验收。运行中的任意实时 steer 尚未支持；需要修改目标时，先停止，再提交新的任务。

后端使用现有管理员鉴权；第一版沿用整个管理台的单管理员访问范围，尚无多租户隔离。持久化记录是业务历史和恢复依据，不是另一套任务调度器。

## 管理接口

- `GET /api/background-tasks?assistant_id=...`：最多100项任务，优先显示未结束任务；网页显示全部返回项，无分页。
- `GET /api/background-tasks/{id}`：任务快照。
- `POST /api/background-tasks`：提交已绑定工具的任务，携带 assistantId/toolId/instruction/requestId；重复 requestId 返回原任务。
- `POST /api/background-tasks/{id}/cancel`：请求停止。
- `POST /api/background-tasks/{id}/refresh`：核查远端并重新观察，不重发原任务。
- `POST /api/background-tasks/{id}/input`：回复待处理的 permission/question。

## 验证边界

测试覆盖真实 Pipecat Jobs 的派发/进度/断线独立/取消，以及显式模拟的 OpenCode HTTP/SSE 协议。不把模拟执行结果当作真实代码修改结果。本次在与项目一致的临时 pgvector/PostgreSQL 17 容器中完成了全量 Alembic 迁移、真实任务 API + 原生 Job + 数据库存储验收，覆盖重复请求不重复提交、事件序号与服务重启后的查询；远端仍由 MockTransport 显式模拟。现有开发库未修改，部署时仍需执行迁移，真实 OpenCode 联调待配置服务后进行。

协议配置可参考 [OpenCode Server 官方文档](https://opencode.ai/docs/server/)。