wx44wx/ai-video-fullstack
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

fix: preserve task stop intent and guard remote execution boundaries

Browse Source
This commit is contained in:
Xin Wang
2026-10-23 19:53:17 +08:00
parent 8ac75a1873
commit 89c3bad58e
16 changed files with 199 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs-developer/prompt-background-tasks.mdx
+7 -7
View File
@@ -12,7 +12,7 @@ description: 使用 Pipecat 原生 Jobs 委派远程 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 参数决定。
4. 在「组件库 / 工具」新建「后台任务 · OpenCode」，填写服务地址、远端工作目录、用户名、服务密码和等待时限。服务地址/目录固定于配置，不由 LLM 参数决定。
5. 在提示词 Pipeline 助手的「外部工具」中选择该工具。默认 instruction 参数由模型提供，可配置固定值或助手变量。任务工具不支持最终结果映射到会话变量。
6. 保存助手，在手动语音调试中提出任务。展开「后台任务」查看进展、结果，处理远端问题/权限，或停止任务。网页刷新后仍可按助手查询任务。
@@ -21,24 +21,24 @@ description: 使用 Pipecat 原生 Jobs 委派远程 OpenCode 任务。
## 运行与恢复
- NativeTaskRuntime 只组装 `WorkerRunner`、常驻 CoordinatorWorker 和 RemoteAgentWorker。派发、超时、取消和 FIFO 串行执行由 Pipecat 原生 Job 系统负责。
- 任务时限包含原生队列等待时间；本版所有 coding 任务串行执行，避免同时修改同一仓库。
- 等待时限覆盖每次本地 Job（含排队），重启或重新观察后重新计时，不代表累计任务寿命上限；超时触发远端停止核查。原生 Job 全局 FIFO 串行；若另有未结束的远端句柄，新的编码任务不会提交，需先核查或停止旧任务。无法约束平台之外的 OpenCode 客户端。
- 提交回执表示平台接受任务。OpenCode 的 204 只表示远端接收；必须取得关联到本次 messageID 的完成消息才能显示成功。
- OpenCodeAdapter 负责创建远端 session、订阅 SSE、异步提交、结果查询和 abort。每个任务使用独立远端 session，内部步骤仍由 OpenCode 完成。
- 原生 Job 取消不代表远端已停止。适配器调用 abort 并查询远端状态；未确认时保留「停止待确认」。
- 连接中断会尝试重新观察，不重新发送原指令。无法核查时显示「状态待核查」，可显式核查或请求停止。
- 应用退出仅停止本地监听，不主动 abort 远端任务；重启后使用已保存的远端句柄重新观察。没有远端句柄的中断任务不会自动重新提交。
- 任务和远端连接配置保存在数据库；公开 API 不返回密码或连接快照。资源后续编辑不会改变已运行任务的地址/目录。
- 在线进度通过现有自定义 app message 传送，网页任务卡片另按助手轮询快照以支持刷新。完成/失败/等待输入通过 Pipecat 原生上下文消息触发前台模型回复；用户/助手正在说话时由原生聚合器安排。离线结果只保留在任务卡片，不自动在新语音连接中播报旧结果。
- 任务和远端连接配置保存在数据库；公开 API 不返回密码或连接快照。平台保留远端助手文本与错误文本，未保存工具原始执行日志；语音通知超过16000字符时保留首尾并明确标记省略，网页可查看完整已保存文本。资源后续编辑不会改变已运行任务的地址/目录。
- 在线进度通过现有自定义 app message 传送，网页任务卡片另按助手轮询快照以支持刷新。完成/失败/取消/状态未知/等待输入通过 Pipecat 原生上下文消息触发前台模型回复；用户/助手正在说话时由原生聚合器安排。离线结果只保留在任务卡片，不自动在新语音连接中播报旧结果。
## 第一版边界
仅提示词 Pipeline 支持任务工具。Workflow、Realtime、启动 Action 不支持。自动测试/Responses 测试的模拟工具执行路径不会启动真实任务；请使用手动语音调试验收。运行中的任意实时 steer 尚未支持；需要修改目标时，先停止，再提交新的任务。
仅提示词 Pipeline 支持任务工具。Workflow、Realtime、启动 Action 不支持。自动测试/Responses 测试的模拟工具执行路径不提交、查询或控制真实任务；请使用手动语音调试验收。运行中的任意实时 steer 尚未支持；需要修改目标时，先停止，再提交新的任务。
后端使用现有管理员鉴权；第一版沿用整个管理台的单管理员访问范围，尚无多租户隔离。持久化记录是业务历史和恢复依据，不是另一套任务调度器。
## 管理接口
- `GET /api/background-tasks?assistant_id=...`：最近100项任务。
- `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`：请求停止。
@@ -47,4 +47,4 @@ description: 使用 Pipecat 原生 Jobs 委派远程 OpenCode 任务。
## 验证边界
测试覆盖真实 Pipecat Jobs 的派发/进度/断线独立/取消，以及显式模拟的 OpenCode HTTP/SSE 协议。不把模拟执行结果当作真实代码修改结果。当前开发环境没有可连接的数据库或远端 OpenCode 服务，因此数据库迁移生成检查与真实服务联调应在部署环境执行。
测试覆盖真实 Pipecat Jobs 的派发/进度/断线独立/取消，以及显式模拟的 OpenCode HTTP/SSE 协议。不把模拟执行结果当作真实代码修改结果。本次在与项目一致的临时 pgvector/PostgreSQL 17 容器中完成了全量 Alembic 迁移、真实任务 API + 原生 Job + 数据库存储验收，覆盖重复请求不重复提交、事件序号与服务重启后的查询；远端仍由 MockTransport 显式模拟。现有开发库未修改，部署时仍需执行迁移，真实 OpenCode 联调待配置服务后进行。