ai-video-fullstack/docs-developer/prompt-background-tasks.mdx

---
title: 提示词后台任务
description: 配置 Speaker 与独立的 Reasoner 或 OpenCode 任务后端。
---

# 配置提示词后台任务

提示词 Pipeline 的「对话模型 Speaker」负责语音交流与需求澄清；独立的「任务后端」处理需要持续推理或执行的目标。提交后 Speaker 获得任务编号并继续对话，语音断线不会取消后台任务。当前支持内置 Reasoner 和外部 OpenCode；完整架构见[任务后端说明](/prompt-task-backends)。

## 升级和启动

升级前先备份数据库。`20261023_0027` 会将旧 task 工具及助手绑定迁移为后端资源，并删除旧工具记录；该资源迁移不能安全 downgrade，回退需恢复迁移前备份。

更新后端与前端依赖，然后执行迁移、同步模型接口定义：

```bash
cd backend
uv pip install --python .venv/bin/python -r requirements.txt
.venv/bin/python -m alembic upgrade head
.venv/bin/python -m db.sync_interface_definitions
cd ../frontend
npm ci
```

生产前端还需运行 `npm run build`，随后重启前后端。数据库需已启动，连接使用后端环境配置。也可在仓库根目录运行 `make db-init` 完成迁移与接口定义同步；该命令需要本机安装 `uv`。

后台任务运行器随后端自动启动。当前要求单个应用进程、一个 Uvicorn worker，所有任务全局并发为 1。

## 创建任务后端资源

在「组件库 → 任务后端」点击「添加任务后端」，选择一种类型。

### 内置 Reasoner

1. 选择已启用的 LLM 模型资源；支持 `openai-llm` / `dashscope-llm` 接口，需真实可用的模型和凭据。每个任务会创建独立上下文，不复用 Speaker 的对话历史。
2. 推理强度默认「模型默认」。只有模型真实支持 `reasoning_effort`，且模型资源已声明 `supportsReasoningEffort` 时，才可选择 low / medium / high；未声明的非默认配置会被拒绝。当前没有通用 thinking budget 设置。
3. 在「可用工具」绑定允许 Reasoner 调用的 HTTP/MCP 服务端工具。Client 工具依赖浏览器，只能用于当前对话，不能供后台执行。
4. 按需添加内联技能名称与任务说明。技能指导工作方法，不能授予新工具或扩大权限。
5. 填写可复用的后端任务指令与任务时限，保存资源。时限默认 600 秒，可设置 30–7200 秒；新任务时限覆盖排队和执行。

Reasoner 没有内置通用 Shell/文件执行环境。需要修改仓库或运行远端命令时，使用配置好执行环境的 OpenCode 后端。

### 外部 OpenCode

先在执行机器准备仓库、模型配置和已有的 OpenCode 服务。平台不会代为安装 OpenCode 或启动远端进程。创建资源时填写：

| 字段 | 内容 |
| --- | --- |
| 服务地址 | 平台后端可访问的 HTTP(S) 地址，例如同机宿主运行时的 `http://127.0.0.1:4096` |
| 远端工作目录 | OpenCode 所在机器的仓库绝对路径，例如 `/workspace/my-project` |
| 服务用户名 | 默认 `opencode`，与远端服务鉴权配置一致 |
| 服务密码 | 对应 `OPENCODE_SERVER_PASSWORD`；编辑时留空保留原凭据 |
| 远端 Agent | 可选；留空使用远端默认 Agent |
| Provider ID / Model ID | 可选，必须成对填写；留空使用远端默认模型，模型凭据在远端配置 |
| 远端技能说明 | 记录已部署技能与配置来源；不会上传或安装技能 |
| 后端任务指令与时限 | 所有引用该资源的助手共享的要求；默认时限 600 秒 |

如果后端在 Docker 中、OpenCode 在宿主机，需使用容器可访问的宿主地址；浏览器电脑上的 `localhost` 与后端所在机器无关。

文件、Shell、沙箱和技能权限由远端 Agent 与执行环境管理。服务密码用于连接服务；工作目录不等于沙箱。远端出现权限请求时，由用户在任务卡片决定，不会自动批准权限。

## 绑定提示词助手

1. 打开提示词助手，运行方式选择「Pipeline」，在「模型与语音」选择 Speaker、ASR、TTS。
2. 在独立的「任务后端」区域选择刚创建的资源。无需到「外部工具」绑定 OpenCode，也不需要填写委派函数名。
3. 按需填写「该助手的任务指令」，例如完成后说明修改范围和验证结果；可引用已声明的动态变量。
4. 新配置通常保留「任务要求来源 → Speaker 生成任务要求」。旧 task 工具的固定值、变量和模板预设会迁入此处，编辑保存时保留；只有明确修改来源才替换预设。
5. 保存后，在手动语音调试中提出一个小任务。展开「后台任务」查看进度、结果、回答必要问题或停止任务；网页刷新后仍可查询。

Speaker 自动获得 `delegate_task`、`get_background_task`、`cancel_background_task` 和 `send_background_task_message` 控制入口，这些函数名由平台保留。单个待处理问题可通过对话回答；OpenCode 权限和多个问题在网页卡片处理。

## 执行、取消与恢复

- 提交回执只表示接受。Reasoner 需明确提交完成结果，OpenCode 需返回关联到本次消息的完成记录；普通文字、空闲状态或 HTTP 204 都不直接表示成功。
- 新任务保存截止时间，覆盖排队、执行和重新观察；重启后使用剩余时间。迁移前未保存截止时间的历史任务保留原有观察窗口语义。
- 全局 FIFO 串行。已有未结束的 OpenCode 句柄时，新任务不会提交到后端；需先核查或停止旧任务，再重新创建任务。不能约束平台之外的 OpenCode 客户端。
- 原生 Job 取消后仍需核查执行结果。OpenCode 调用 abort 并确认停止；未确认时显示「停止待确认」。Reasoner 停止本地推理，已发出的 HTTP/MCP 操作仍可能产生副作用，需核查业务系统。
- 应用重启后，OpenCode 仅使用已保存句柄重新观察，不重复发送未知提交；没有句柄的中断任务显示待核查。Reasoner 标记为中断失败，不自动重放工具调用。
- 新任务冻结后端连接、模型、工具与技能配置。资源后续修改不会改变已有任务；公开任务 API 不返回密码或连接快照。
- 插话和断线保留任务。在线结果通过现有 app message 和 Pipecat 上下文通知 Speaker；离线结果保留在任务卡片，新语音连接不自动播报旧结果。

## 管理接口

所有管理接口使用现有管理员鉴权。

- `GET /api/task-backends`、`POST /api/task-backends`：查询和创建后端资源。
- `GET /api/task-backends/{id}`、`PUT /api/task-backends/{id}`、`DELETE /api/task-backends/{id}`：读取、修改和删除；被助手引用的资源不能删除。
- `POST /api/task-backends/{id}/duplicate`：复制资源，凭据在服务端处理。
- `GET /api/background-tasks?assistant_id=...`：最多 100 项任务，优先未结束任务。
- `GET /api/background-tasks/{id}`：任务快照，含 `backendId` / `backendType`。
- `POST /api/background-tasks`：携带 `assistantId`、`instruction`、`requestId`，由助手绑定解析后端；不接收 `toolId`，重复请求 ID 返回原任务。
- `POST /api/background-tasks/{id}/cancel`：请求停止。
- `POST /api/background-tasks/{id}/refresh`：核查状态；OpenCode 可以重新观察，不重发原任务。
- `POST /api/background-tasks/{id}/input`：回复当前待处理问题或 OpenCode 权限请求。

## 当前边界与验收

当前只有提示词 Pipeline 支持任务后端。自动测试/Responses 的模拟工具路径不提交或控制真实后台任务；请在配置好模型、工具和远端服务后使用手动调试验收。运行中任意修改目标尚未支持，需要更改目标时先停止，再提交新任务。

测试中的 OpenCode HTTP/SSE 和模型模拟会明确标注，不能据此声称已修改真实仓库或验证了生产权限/沙箱。本版的具体测试、迁移验收记录见 `implement-stage/task-backends/BUILD_NOTE.md`；真实 OpenCode 编码与真实模型联调仍需在部署环境完成。后端沿用单管理员访问范围，尚无多租户隔离。

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