F4: document task backend operation and publish API contracts
This commit is contained in:
Xin Wang
@@ -1,52 +1,102 @@
|
||||
---
|
||||
title: 提示词后台任务
|
||||
description: 使用 Pipecat 原生 Jobs 委派远程 OpenCode 任务。
|
||||
description: 配置 Speaker 与独立的 Reasoner 或 OpenCode 任务后端。
|
||||
---
|
||||
|
||||
# 提示词后台任务 MVP
|
||||
# 配置提示词后台任务
|
||||
|
||||
提示词 Pipeline 可以绑定一个「后台任务」工具。对话模型提交任务后立即获得任务编号，继续对话；应用级 Pipecat Worker 拥有长任务，语音断线不取消远端执行。OpenCode 是当前唯一实现的执行器。
|
||||
提示词 Pipeline 的「对话模型 Speaker」负责语音交流与需求澄清；独立的「任务后端」处理需要持续推理或执行的目标。提交后 Speaker 获得任务编号并继续对话，语音断线不会取消后台任务。当前支持内置 Reasoner 和外部 OpenCode；完整架构见[任务后端说明](/prompt-task-backends)。
|
||||
|
||||
## 使用
|
||||
## 升级和启动
|
||||
|
||||
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. 保存助手，在手动语音调试中提出任务。展开「后台任务」查看进展、结果，处理远端问题/权限，或停止任务。网页刷新后仍可按助手查询任务。
|
||||
升级前先备份数据库。`20261023_0027` 会将旧 task 工具及助手绑定迁移为后端资源，并删除旧工具记录；该资源迁移不能安全 downgrade，回退需恢复迁移前备份。
|
||||
|
||||
前台新增三个控制函数：`get_background_task`、`cancel_background_task`、`send_background_task_message`。主提交函数使用工具资源的函数名。控制函数名由平台保留。单个远端问题可由对话工具回答；权限和多个问题请在网页卡片处理。不会自动批准权限。
|
||||
更新后端与前端依赖，然后执行迁移、同步模型接口定义：
|
||||
|
||||
## 运行与恢复
|
||||
```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
|
||||
```
|
||||
|
||||
- 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 原生上下文消息触发前台模型回复；用户/助手正在说话时由原生聚合器安排。离线结果只保留在任务卡片，不自动在新语音连接中播报旧结果。
|
||||
生产前端还需运行 `npm run build`，随后重启前后端。数据库需已启动，连接使用后端环境配置。也可在仓库根目录运行 `make db-init` 完成迁移与接口定义同步；该命令需要本机安装 `uv`。
|
||||
|
||||
## 第一版边界
|
||||
后台任务运行器随后端自动启动。当前要求单个应用进程、一个 Uvicorn worker，所有任务全局并发为 1。
|
||||
|
||||
仅提示词 Pipeline 支持任务工具。Workflow、Realtime、启动 Action 不支持。自动测试/Responses 测试的模拟工具执行路径不提交、查询或控制真实任务；请使用手动语音调试验收。运行中的任意实时 steer 尚未支持；需要修改目标时，先停止，再提交新的任务。
|
||||
## 创建任务后端资源
|
||||
|
||||
后端使用现有管理员鉴权；第一版沿用整个管理台的单管理员访问范围，尚无多租户隔离。持久化记录是业务历史和恢复依据，不是另一套任务调度器。
|
||||
在「组件库 → 任务后端」点击「添加任务后端」，选择一种类型。
|
||||
|
||||
### 内置 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/background-tasks?assistant_id=...`：最多100项任务，优先显示未结束任务；网页显示全部返回项，无分页。
|
||||
- `GET /api/background-tasks/{id}`：任务快照。
|
||||
- `POST /api/background-tasks`：提交已绑定工具的任务，携带 assistantId/toolId/instruction/requestId；重复 requestId 返回原任务。
|
||||
所有管理接口使用现有管理员鉴权。
|
||||
|
||||
- `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`：核查远端并重新观察，不重发原任务。
|
||||
- `POST /api/background-tasks/{id}/input`：回复待处理的 permission/question。
|
||||
- `POST /api/background-tasks/{id}/refresh`：核查状态；OpenCode 可以重新观察，不重发原任务。
|
||||
- `POST /api/background-tasks/{id}/input`：回复当前待处理问题或 OpenCode 权限请求。
|
||||
|
||||
## 验证边界
|
||||
## 当前边界与验收
|
||||
|
||||
测试覆盖真实 Pipecat Jobs 的派发/进度/断线独立/取消，以及显式模拟的 OpenCode HTTP/SSE 协议。不把模拟执行结果当作真实代码修改结果。本次在与项目一致的临时 pgvector/PostgreSQL 17 容器中完成了全量 Alembic 迁移、真实任务 API + 原生 Job + 数据库存储验收，覆盖重复请求不重复提交、事件序号与服务重启后的查询；远端仍由 MockTransport 显式模拟。现有开发库未修改，部署时仍需执行迁移，真实 OpenCode 联调待配置服务后进行。
|
||||
当前只有提示词 Pipeline 支持任务后端。自动测试/Responses 的模拟工具路径不提交或控制真实后台任务；请在配置好模型、工具和远端服务后使用手动调试验收。运行中任意修改目标尚未支持，需要更改目标时先停止，再提交新任务。
|
||||
|
||||
测试中的 OpenCode HTTP/SSE 和模型模拟会明确标注，不能据此声称已修改真实仓库或验证了生产权限/沙箱。本版的具体测试、迁移验收记录见 `implement-stage/task-backends/BUILD_NOTE.md`；真实 OpenCode 编码与真实模型联调仍需在部署环境完成。后端沿用单管理员访问范围，尚无多租户隔离。
|
||||
|
||||
协议配置可参考 [OpenCode Server 官方文档](https://opencode.ai/docs/server/)。
|
||||
|
||||
Reference in New Issue
Block a user