100 lines
8.3 KiB
Plaintext
100 lines
8.3 KiB
Plaintext
---
|
|
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. 按需在「可用工具」绑定允许 Reasoner 调用的 HTTP/MCP 服务端工具；默认无工具。Client 工具依赖浏览器，只能用于当前对话，不能供后台执行。
|
|
3. 「高级设置」中的推理强度默认「模型默认」。只有模型真实支持 `reasoning_effort`，且模型资源已声明 `supportsReasoningEffort` 时，才可选择 low / medium / high；未声明的非默认配置会被拒绝。当前没有通用 thinking budget 设置。
|
|
4. 在「高级设置」中按需添加内联技能名称与任务说明。技能指导工作方法，不能授予新工具或扩大权限。
|
|
5. 任务时限默认 600 秒，在「高级设置」可调整为 30–7200 秒；新任务时限覆盖排队和执行。该助手的任务要求在助手侧填写。
|
|
|
|
Reasoner 没有内置通用 Shell/文件执行环境。需要修改仓库或运行远端命令时，使用配置好执行环境的 OpenCode 后端。
|
|
|
|
### 外部 OpenCode
|
|
|
|
先在执行机器准备仓库、模型配置和已有的 OpenCode 服务。平台不会代为安装 OpenCode 或启动远端进程。创建资源时填写：
|
|
|
|
| 字段 | 内容 |
|
|
| --- | --- |
|
|
| 服务地址 | 平台后端可访问的 HTTP(S) 地址，例如同机宿主运行时的 `http://127.0.0.1:4096` |
|
|
| 远端工作目录 | OpenCode 所在机器的仓库绝对路径，例如 `/workspace/my-project` |
|
|
| 服务密码 | 对应 `OPENCODE_SERVER_PASSWORD`；编辑时留空保留原凭据 |
|
|
|
|
服务用户名默认 `opencode`。需要自定义用户名、覆盖远端 Agent 或 Provider ID / Model ID 时，展开「高级设置」；模型 ID 必须成对填写，留空使用远端默认配置。模型凭据、技能与执行权限由远端配置。任务时限默认 600 秒，按需在高级设置调整。已有资源中的备注和通用指令会随编辑保存保留。
|
|
|
|
如果后端在 Docker 中、OpenCode 在宿主机，需使用容器可访问的宿主地址；浏览器电脑上的 `localhost` 与后端所在机器无关。
|
|
|
|
文件、Shell、沙箱和技能权限由远端 Agent 与执行环境管理。服务密码用于连接服务；工作目录不等于沙箱。远端出现权限请求时，由用户在任务卡片决定，不会自动批准权限。
|
|
|
|
## 绑定提示词助手
|
|
|
|
1. 打开提示词助手，运行方式选择「Pipeline」，在「模型与语音」选择 Speaker、ASR、TTS。
|
|
2. 在独立的「任务后端」区域选择刚创建的资源。无需到「外部工具」绑定 OpenCode，也不需要填写委派函数名。
|
|
3. 按需填写「任务说明」，例如完成后说明修改范围和验证结果；可引用已声明的动态变量。
|
|
4. 新配置默认由 Speaker 根据对话生成任务目标。固定值、变量或模板等任务要求来源在「高级设置」中调整。旧预设会原样保留，并在折叠标题旁提示当前来源；仅展开或收起设置不会修改预设。
|
|
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/)。
|