ai-video-fullstack/implement-stage/BUILD_NOTE.md

Build Note — Prompt background tasks

Rung	Feature	Acceptance check	Tier	Status
F0	原生Job主线、断线独立与取消	PYTHONPATH=backend backend/.venv/bin/python -m unittest discover -s backend/tests -p test_background_task_native.py	MUST	passed
F1	OpenCode协议适配与状态关联	cd backend && .venv/bin/python -m unittest tests.test_background_task_native tests.test_opencode_tasks	MUST	passed
F2	持久记录、管理API、应用宿主	cd backend && .venv/bin/python -m unittest tests.test_background_tasks	MUST	passed
F3	提示词绑定、任务通知、网页	cd frontend && npx tsc --noEmit	MUST	passed
F4	回归、文档与假设审阅	make test	MUST	passed; sweep provisional

Run record

• F0: PYTHONPATH=backend backend/.venv/bin/python -m unittest discover -s backend/tests -p test_background_task_native.py → exit 0; native-jobs-smoke.json。
• F1: 原生 Job + httpx 模拟远端协议共 3 项测试通过；未调用真实模型。
• F2: 累计 7 项原生Job、协议、服务生命周期与密钥保留测试通过。
• F3: 累计9项后端任务测试通过，TypeScript检查通过，前端lint无错误（BatchTestPage已有1条warning）。
• F4: make test → exit 0；367 项后端测试、4 项前端契约测试、5 项公开契约检查与生产构建通过。前端已有 BatchTestPage useEffect warning 1 条，无错误。
• F4: 初次回归发现公开契约快照需更新；随后构建受沙箱 Google Fonts 网络限制，联网重试通过；未修改字体设计。
• F4: 补充待回答问题的状态核查保留与原生超时清理检查；任务生命周期专项测试通过。最终全量 make test 再次 exit 0。
• 新增迁移区间 SQL：cd backend && .venv/bin/python -m alembic upgrade 20260907_0025:head --sql → exit 0。旧历史迁移含数据库读取，未声称全历史离线生成通过。
• F4 数据库集成：使用本机已有 pgvector/pgvector:pg17 镜像创建独立临时库，alembic upgrade head → exit 0；真实 PostgreSQL TaskRepository + ASGI 管理 API + 原生 Pipecat Job + MockTransport 远端 → exit 0（一次远端 prompt、持久事件连续、服务重启可查询）。临时容器已删除，现有数据库未改动。
• 普通 PostgreSQL 15 镜像不含既有 vector 扩展，首次全历史迁移在旧迁移 0005 失败；切换到仓库 Compose 相同的已缓存 pgvector 镜像后通过，未修改历史迁移。
• F4 审阅修复验收：任务/启动动作专项29项通过；完整 make test → exit 0（367项后端、4项前端契约、5项公开契约及生产构建），仅保留既有1条lint warning。

Deferred

• 真实远程 OpenCode + 模型联调：未提供服务地址/凭证。
• 多进程分布式总线及通用插件发现：超出单进程 MVP。

Blockers

• 真实远程 OpenCode 联调未执行（未提供地址/凭证）；现有开发库未修改，使用前仍需迁移。

假设审阅

• 第一轮：4 项未声明决策（3 semantic）与4项台账不一致。全部记录至台账，修复自动测试控制入口、启动 Action 校验、待停止任务重启和远端未结束时的新任务提交；结果保存完整文本、通知显式标注省略、列表展示范围同步改进。
• 第二轮：1项未声明 semantic 决策、0项台账不一致；已补 A-022 说明被阻挡的新任务终结失败且需重新提交。本轮仅更新声明和文档，未改代码；2轮审阅预算已用尽，最后声明由执行者核对，未进行第三轮复审。两轮原始回复归档于 SILENT_ASSUMPTION_SWEEP.json。
• 审阅结论为 gaps，same-family / provisional，不声称模型审阅无遗漏。F0–F4 的确定性验收均已通过；远端真实编码联调与浏览器交互验收仍延后。

行为约定（全部 semantic 决策）

• A-001 — 范围：只允许提示词 Pipeline 绑定任务工具；不开放 Workflow、Realtime、启动 Action（Source: user）。

• A-002 — 任务生命周期：应用级原生 Worker 拥有 Job；网页断线任务继续（Source: user）。

• A-005 — 远端执行关联：一次任务一个 OpenCode session；提交前保存session及messageID，初始idle不算完成（Source: default）。

• A-006 — 取消：原生Job取消后调用远端abort并核查；无法确认时保留待确认，不能宣称已停止（Source: default）。

• A-007 — 通知：普通进度仅网页；完成/失败/取消/状态未知/等待输入在线时触发前台通知；离线结果保留供查询（Source: default）。

• A-008 — 恢复：单进程；重启恢复观察有远端句柄的任务，不自动重新发送未知提交（Source: default）。

• A-010 — 补充输入：本版仅支持回答远端问题及权限确认；任意实时修改要求需先停止再提交，不自动批准权限（Source: default）。

• A-011 — 验证边界：未提供真实远端服务，使用httpx MockTransport验证协议和真实Pipecat验证调度；真实联调待部署配置（Source: default）。

• A-012 — 外部编码变更：仅明确调用任务工具时会启动远端执行，不因查看页面自动执行（Source: default）。

• A-013 — 任意运行中修改任务：本版支持远端待回答的问题/权限；任意实时 steer 延后，新增要求通过停止后重新提交（Source: default）。

• A-015 — 同一工作区并发修改：本版原生execute Job采用全局FIFO串行；排队计入本次等待时限；另有未结束远端句柄时不启动新的编码提交，状态未知/停止未确认需先核查。不能约束平台之外的远端客户端（Source: default）。

• A-016 — 状态未知后恢复：网页提供显式核查/重新观察；只重连已有远端句柄，绝不重复发送原任务（Source: default）。

• A-017 — 自动测试边界：task工具不出现在普通工具模拟列表；测试运行器中调用task只返回不支持，真实执行需手动语音调试（Source: default）。

• A-018 — 远端结果保留与通知长度：平台保存消息API关联到本次任务的完整助手文本及错误文本，不包含工具原始日志；独立session.error事件仅保留失败提示；语音上下文最多保留首尾各8000字符并显式标记省略，完整结果可在网页查看（Source: sweep）。

• A-019 — 超时定义：时限针对每次本地观察Job（包含排队）；重启/重新观察重新计时，超时与用户停止都进入远端abort核查，确认停止后才显示cancelled，不作为累计任务寿命上限（Source: sweep）。

• A-020 — 自动测试控制函数：测试运行器中提交、查询、取消、回复全部拒绝，不访问真实任务服务；修复首轮审阅发现的仅提交有防护问题（Source: sweep）。

• A-022 — 远端未结束时的新任务：已接受的本地排队任务若发现其他未结束远端句柄，会以failed终结并明确说明未向远端提交；不会等旧任务解决后自动恢复，需用户重新提交（Source: sweep）。

接口约定与验证范围

• A-003 — 配置入口：新增 task 工具类型，复用 Tool CRUD/绑定；每个助手最多一个（Source: default）。
• A-004 — 任务作用域：平台生成 task_id，记录来源 conversation/assistant；管理接口沿用现有管理员鉴权（Source: default）。
• A-009 — 远端配置：地址/工作目录/Basic鉴权由管理员工具配置，任务冻结连接信息；LLM不能改地址和目录（Source: default）。
• A-014 — 任务API字段：与现有API一致使用camelCase；执行器内部保持Python snake_case（Source: default）。
• A-021 — 任务列表范围：管理API最多100项，优先未结束任务；网页展示全部返回项，无分页，更早记录可凭task_id查询/控制（Source: sweep）。
• ASK=never；共22项决定（2 user、15 default、5 sweep）；生产链路没有固定结果占位实现，模拟执行器仅在明确标注的测试中注入。
• 未进行浏览器交互验收或真实模型/远端编码验收；前端通过类型检查、lint、契约检查和生产构建。