---
title: 提示词助手的对话模型与任务后端
description: Speaker 与内置 Reasoner、外部 OpenCode 任务后端的配置和运行边界。
---

# 提示词助手的对话模型与任务后端

状态：第一版已实现。任务后端使用独立资源配置；内置 Reasoner 和外部 OpenCode 都有运行路径。真实模型和远端 OpenCode 仍需使用有效连接配置进行部署联调，模拟协议测试不代表完成过真实编码任务。操作步骤见[后台任务使用说明](/prompt-background-tasks)。

## 范围与职责

仅提示词 Pipeline。一个助手配置一个 Speaker，可选一个任务后端：内置 Reasoner 或外部 OpenCode。Workflow、Realtime 和启动 Action 不支持任务委派。切换为 Realtime 时，界面会先确认解除当前助手的任务后端绑定，后端资源仍保留。

Speaker 使用现有 ASR → 对话 LLM → TTS 链路，负责交流、澄清、委派与播报。任务后端使用独立上下文处理目标，执行期间 Speaker 继续响应用户。

```text
用户 ⇄ ASR / Speaker / TTS
                  │ 委派、查询、回答问题、取消
                  ▼
        TaskService + 应用级 Coordinator
                  │ Pipecat 原生 Jobs
          ┌───────┴────────┐
          ▼                ▼
  内置 Reasoner        OpenCode 后端
 BackendLLMWorker      HTTP / SSE 适配
 独立 LLMContext       远端 session
          │                │
 平台 ToolExecutor     自己的工具、技能与环境
          └───────┬────────┘
                 ▼
         任务事件、结果、待回答问题
                 ▼
        数据库存储 / 网页 / Speaker
```

管理员在「组件库 → 任务后端」创建资源，再在提示词助手中选择。普通工具资源只包含 HTTP、MCP、Client。Speaker 通过平台自动注册的 `delegate_task` 发起委派，无需填写函数名或绑定一项 OpenCode 工具。

## 资源与配置

`TaskBackendResource` 与模型、工具资源并列，类型为 `reasoner | opencode`。资源负责连接、模型、执行策略和技能；助手的 `taskBackend` 只包含 `backendId`、`instructions` 和 `instructionSource`。

| 配置 | 内置 Reasoner | OpenCode |
| --- | --- | --- |
| 基本信息 | 名称、说明、启用状态 | 名称、说明、启用状态 |
| 连接与模型 | 引用已启用的 LLM 模型资源，凭据在服务端解析 | 服务地址、用户名、服务密码、远端工作目录 |
| 推理配置 | 模型默认，或经能力声明的 low / medium / high | 可选远端 Agent；可成对指定 Provider ID / Model ID |
| 执行策略 | HTTP/MCP 工具白名单、任务时限；并发固定 1 | 任务时限；权限和沙箱由远端管理；并发固定 1 |
| 技能 | 内联技能名称与说明，加载到任务上下文 | 记录远端已部署技能的说明，平台不上传或安装技能 |
| 任务指令 | 可复用的后端指令，加上该助手的任务指令 | 相同 |

默认任务时限为 600 秒，可设置 30–7200 秒。资源配置保存时和助手绑定时都会校验模型、工具及变量引用。修改资源不会改变已创建任务的冻结配置。

### 内置 Reasoner

Reasoner 引用 `openai-llm` 或 `dashscope-llm` 的 LLM 模型资源。即使与 Speaker 选择同一资源，每个任务也会创建独立的模型服务、上下文和运行设置。

推理强度使用实际的 `reasoning_effort` 参数。选择 low / medium / high 前，管理员须确认模型支持该参数，并在模型资源中声明 `values.supportsReasoningEffort = true`。未声明时只能使用「模型默认」；服务端会拒绝非默认值。当前没有通用 thinking budget 配置，也不自动推测模型能力。

Reasoner 只能调用该后端显式绑定的 HTTP/MCP 服务端工具，继续复用现有 `ToolExecutor`。Client 工具依赖浏览器连接，不能作为后台工具。技能是工作方法，不能扩大工具许可。平台没有为 Reasoner 增加通用 Shell/文件环境；需要远端编码执行时选择 OpenCode。

### 外部 OpenCode

平台连接已有的 OpenCode 服务，不安装软件、不启动远端进程。地址必须由平台后端可访问；工作目录使用远端机器上的绝对路径。服务鉴权凭据、远端模型 API 凭据与执行权限分别管理。

- 服务地址、用户名与密码负责 HTTP Basic 鉴权。
- `agent` 留空使用远端默认 Agent。
- `modelProviderId` / `modelId` 同时填写或同时留空；留空使用远端默认模型。模型凭据在 OpenCode 端配置。
- 文件、Shell、沙箱、技能权限由远端 Agent、运行账号和部署环境执行。工作目录不等于沙箱。
- `skillsNote` 仅记录远端技能及配置来源；平台不保证自动同步远端 `SKILL.md`。

界面没有提供无法实际生效的权限或沙箱开关，也不会自动授予远端执行权限。需要确认权限时由用户在任务卡片处理。

## Pipecat 复用与任务生命周期

应用级 `WorkerRunner`、常驻 Coordinator 和串行任务 Worker 持有执行 Jobs；媒体 Pipeline 只订阅任务事件。断线或用户插话不会取消任务，明确取消时才进入停止流程。

内置 Reasoner 使用 Pipecat `BackendLLMWorker` 管理独立的上下文和模型/工具调用循环；业务适配器注册 `complete_task` 与 `ask_user`。必须明确完成或提出问题，普通文本、模型空闲或 attach 回执都不是任务成功证明。平台没有自行实现第二套推理循环，也未修改 Pipecat。

任务结束后通过公开接口清空上下文、工具与处理器引用。当前 Pipecat 运行器仍保留结束 Worker 的注册对象直到应用关闭；本版适用于 MVP，长期高任务量运行还需要验证该框架行为。

`LLMWithBackend` / `BackendConnector` 可供后续评估，但本版没有直接替换 Speaker 的 LLM 槽；保留应用级所有者才能维持语音断线后的执行。

Pipecat 负责 Job 派发、FIFO 串行、超时和取消。`TaskService` 负责业务任务 ID、后端选择、冻结配置、记录和事件投影。数据库记录不代替原生调度器。

- **并发与部署**：仅单应用进程、一个 Uvicorn worker；所有任务全局并发固定为 1。已有未结束的 OpenCode 句柄会阻止新任务提交到后端，需先核查或停止旧任务。该约束无法控制平台之外的 OpenCode 客户端。
- **截止时间**：新任务在创建时保存截止时间，覆盖排队和执行；OpenCode 重连观察或应用重启后使用剩余时间，不重新延长截止时间。迁移前没有截止时间的历史任务保留原有观察时限语义。
- **成功判定**：OpenCode 的 204 只表示接收。需要取得关联到本次 message ID 的完成消息；Reasoner 需调用明确完成控制函数。
- **取消**：先取消原生执行 Job，再核查对应后端。OpenCode 需 abort 后确认状态，未确认时保留「停止待确认」。Reasoner 可停止本地执行；已发出的 HTTP/MCP 请求可能已有副作用，应核查业务系统结果。
- **恢复**：OpenCode 使用已存 session/message 句柄重新观察，不重发未知提交。Reasoner 在应用重启后标为中断失败，保留记录，不自动重放可能有副作用的工具。
- **输入与目标变更**：共同支持查询、取消、回答当前待处理问题。首版不支持任意运行中 steer；修改目标时先停止，再创建新任务。
- **通知**：网页保存和展示进度、问题及结果；Speaker 接收必要状态和结果，不默认播报内部推理或原始工具日志。离线结果保留在任务卡片，新语音连接不自动重播旧结果。

自动测试/Responses 的模拟工具执行路径不会提交或控制真实后台任务，不能用该路径证明真实任务后端已连通。

## 数据迁移与升级

迁移 `20261023_0027` 把旧 task 工具迁为 OpenCode 后端资源，迁移助手绑定，并保留固定值、变量或模板形式的 `instructionSource`。旧工具记录和普通工具绑定会移除。历史任务保留任务 ID、结果、冻结连接和远端句柄，并补充后端来源。

迁移不可安全 downgrade。升级前备份数据库；回退需要恢复迁移前备份与匹配的旧代码，不要只回退应用版本。若旧数据包含多个 task 绑定或非提示词 Pipeline 绑定，迁移会明确失败，需先修正这些配置。

本机运行时更新依赖后执行：

```bash
cd backend
.venv/bin/python -m alembic upgrade head
.venv/bin/python -m db.sync_interface_definitions
```

也可在仓库根目录运行 `make db-init`，它会迁移并同步模型接口定义。不要用演示数据 seed 代替正常升级。

迁移后的原 instruction 预设显示在助手「任务要求来源」中；未修改时保存仍保留该来源。默认「Speaker 生成任务要求」适用于新的对话委派。

## 代码位置

| 模块 | 职责 |
| --- | --- |
| `task_backend_schemas.py` / `db.models` | 后端资源、助手绑定和任务来源 |
| `routes/task_backends.py` / `services/task_backend_resources.py` | 管理、校验、服务端凭据解析 |
| `services/background_tasks/service.py` / `native.py` | 业务任务投影与应用级原生 Jobs |
| `services/background_tasks/reasoner.py` | `BackendLLMWorker`、完成/提问控制与工具桥 |
| `services/background_tasks/opencode.py` | HTTP/SSE、结果关联、abort、重新观察 |
| `services/brains/prompt_tasks.py` | Speaker 委派入口、查询/输入/取消与通知 |
| `routes/background_tasks.py` | 从助手已绑定的后端解析提交配置，任务 API 不接收 toolId |
| 前端任务后端资源页 / 提示词编辑器 | 独立资源、Speaker 标注、指令预设和任务卡片 |

## 验证边界

验收应检查上下文隔离、不支持的推理配置明确拒绝、工具白名单和技能不能扩大权限、状态未知不重复执行、断线继续执行、取消可核查，以及旧凭据和指令预设不会丢失。仓库自动测试中使用的模型和 OpenCode 协议模拟会明确标注；真实 Provider、远端编码执行与部署网络仍需单独联调。具体执行记录以 `implement-stage/task-backends/BUILD_NOTE.md` 为准。

## 参考

- [Pipecat BackendLLMWorker](https://reference-server.pipecat.ai/en/latest/api/pipecat.workers.llm.backend_llm_worker.html)
- [Pipecat LLMWithBackend](https://reference-server.pipecat.ai/en/latest/api/pipecat.pipeline.llm_with_backend.html)
- [OpenCode Server](https://opencode.ai/docs/server/)
- [OpenCode 权限](https://opencode.ai/docs/permissions/)
- [OpenCode 技能](https://opencode.ai/docs/skills/)