素材工房 · Agent 框架 · supervisor 实现讲解

agent-native:supervisor 是怎么把真 Agent 落地的

2026-07-11~13,supervisor 在 feat/agent-native 分支实现了"真 Agent 化"并已合入 st/test (含 R13–R22 共十几轮修复,净增约 1 万行)。母本是他自己的 RFC(docs/rfc-agent-native.md), 我们的设计稿起了部分参考作用。本页讲清楚:他建了什么、怎么运转、和我们稿的异同、现在处于什么状态。

代码基准:origin/st/test @ 4172505 · 阅读范围:agent-loop / butler / search-runner / DO / 迁移 0035–0041 / RFC

自研 loop

没用 langchain,~600 行裸循环

2 个 Agent

管家(对话+消化)/ 检索工人

DO ✓

每 Agent 一实例,WebSocket 群聊

7 项迁移

0035–0041,聊天/卡片/行为事件

Part 0

一图流:整个系统怎么转

浏览器标签页 ×N(多人/多开)
   │ WebSocket  GET /api/agents/:id/ws
   ▼
管家 Agent DO(AgentButlerDO,每个业务 Agent 一实例,idFromName(agentId))
   │ 对话模式:流式 tool-loop → ZenMux sonnet;写穿 Postgres(唯一事实源)
   │ 用户说"帮我找 XX" → order_search 下单 → agent_runs(status=queued)
   ▼
分钟 tick(cron scheduled,15 分钟额度)
   → FOR UPDATE SKIP LOCKED 认领 queued 的 digest run / search run
   → 检索工人 Agent 整跑:search_fast / search_competitor / analyze_video / save_materials / finish
   → 管家批量模式(消化):read_feedback / view_object / analyze_video / propose_update
   → sweep 兜底收尸

铁律写进了 RFC:「HTTP 请求里的 waitUntil 只准做一次 INSERT,永远不准跑 LLM」——就是我们 7/10 消化引擎被强杀那次事故换来的原则。对话是唯一例外:客户端连着,DO 里流式跑没有时限。

Part 1

运行时:没用 LangChain,自研了 agent-loop.ts

我们设计稿推荐 LangGraph(POC 也通了),supervisor 最终选择自研一个 ~600 行的裸循环(src/lib/agent-loop.ts):直接打 ZenMux 的 Anthropic SSE 接口,自己解析 tool_use / 拼 tool_result。换来的是四个 LangGraph 给不了的定制点:

机制	实现	为什么要
token 预算	默认 200k,预算将尽时注入「立即用收尾工具结束」的框架提示	成本护栏做在框架层,不靠 Agent 自觉
历史折叠	上下文超 60k tokens 自动折叠到 30k(旧 tool 结果压缩)	检索工人一跑几十轮,不折叠必爆上下文
收尾工具语义	工具可标 `endRun=true`(如 finish / propose_update / no_update),调用即结束循环	强制 Agent 以结构化产物收尾,不许"聊着聊着就完了"
transcript	每轮记录 stop_reason / usage / 工具调用预览	审计与调试,等价我们稿里的 agent_tool_calls

上限:40 轮 / 单请求 120s 超时 / 重试 2s。会话持久化没用 checkpoint 表——对话历史在 agent_chat_messages,批量任务的中间态随 run 的 transcript 走,DO 内存做热状态。

Part 2

管家 Agent:一个脑子,两种上班方式

对话模式(DO 里实时跑)

前端 WS 连到 /api/agents/:id/ws → Hono 路由校验会话后转发给 DO(用户身份塞进 header)。DO 支持多人同时在线(presence 广播)、断线补发(seq 游标,hydrate 时把"最后一条 assistant 之后的用户消息"捞回 pending inbox 继续答)、任务动态推送(下单的检索跑完了会回聊天室报告)。工具:record_feedback / order_search / propose_order / read_performance / propose_update。限速:60 秒只能下单一次检索,最多 5 张待确认单。

批量模式(消化,cron 认领跑)

替代旧 digest:反馈攒进来 → 入队 stage='digest' 的 run → tick 认领(每次 2 条)→ 管家用工具链干活:read_gene(读检索文档/创意规则)→ read_feedback → view_object(看被踩素材本体)→ analyze_video(真的看视频!) → read_performance(按 guidance 版本归因效果)→ propose_update 或 no_update 收尾。这正面解决了旧消化"只看标题猜"的核心缺陷。

最大的产品设计差异:改 guidance 不直接写,出「基因卡」等确认

我们稿里反馈 Agent 直接调工具改文档;supervisor 加了一道人审:propose_update 产出 agent_gene_cards 行(提案的检索文档/创意规则/约束 + 理由 + base_version),推到聊天室当卡片,用户点"应用"才落库(origin='chat'),点驳回则记录。防覆盖沿用版本号核对(base_version 不匹配即失效)——F4 语义完整保留。

Part 3

检索工人 Agent:替换假流水线的"真工人"

src/lib/agents/search-runner.ts(764 行)。触发五种:首搜 / 手动再找一批 / 聊天下单 / 每日自动 / 基因验证。全部先入队再由 tick 认领整跑(手动路径不再跑在 waitUntil 里——修掉了 RFC 点名的暗伤)。工具:

search_fast:TikHub 三平台,Agent 自己决定关键词、换词、翻页(上限 12 页)
search_competitor + check_competitor:竞品桥是异步任务,Agent 提交后自己轮询取结果(最多提交 2 次,超时 8 分钟)
analyze_video:对候选素材调 video-analysis-worker 看画面再定去留
save_materials:落 hot_materials(带 guidance_version 归因——修掉"这批素材是哪版文档找来的答不上"的暗伤)
finish:收尾工具,必须交代找了多少、为什么停

墙钟上限 10 分钟 / 预算 200k tokens。深度(热点)源不动,照旧派 tobatsu。

Part 4

数据模型:7 项迁移(0035–0041)

迁移	东西	用途
0035	`agent_runs.stage` + 'digest'	消化任务复用 runs 队列(和我们 0034 的 queued 状态配套)
0036	`agent_chat_messages`	聊天事实源:seq 全序(断线补发/分页),content 为 jsonb 块数组(文本/工具记录/卡片引用/事件)
0037	`agent_gene_cards`	基因卡提案:proposed_search/steer/constraints + base_version + status(pending/applied/rejected)
0038	guidance origin + 'chat'	聊天里应用的版本可溯源
0039	`agent_stage_feedback.meta`	反馈元数据(自动归档标记等)
0040	`agent_behavior_events`	我们稿没有的东西:浏览器行为遥测(素材被看/被忽略/被采纳、方案派发/修改、成片下载),带 guidance_version——隐式反馈进消化材料,不止靠用户开口
0041	`crawl_slots.constraints`	Agent 级约束(如成片时长上限),基因卡可提案修改

Part 5

对照我们的设计稿:哪些同、哪些不同

议题	我们稿(design-v1)	supervisor 实现
交互执行位	DO,每会话一实例	DO,每 Agent 一实例(群聊语义,多人共处一室)	同向,粒度不同
后台执行位	排队 + tick 认领(SKIP LOCKED)	完全一致,还写成了铁律	相同
运行时	LangGraph(POC 已通)	自研 agent-loop(预算/折叠/收尾工具)	不同——自研换定制力
会话持久化	langgraph checkpoint 4 表	chat_messages + transcript + DO 内存	不同
看素材本体(切帧)	extract_frames + analyze_media,标为唯一待建基建	独立 video-analysis-worker(service binding)+ analyze_video 工具,已建	相同,他建好了
改 guidance	Agent 直接写(工具层 F4 防覆盖)	基因卡提案 + 用户确认才落库	他更稳——人审一道
history 归因	read_history 工具	read_performance(按 guidance 版本聚合效果)+ 行为事件	同向,他更完整
实时反馈	一条反馈一次会话,不攒条	对话模式即时回应;批量消化仍走队列(但看得到素材本体)	大体同向

一句话评价:执行位、防覆盖、看本体、归因这些"骨架决策"和我们稿一致;运行时选了自研而非 LangGraph;"卡片确认制"和"行为事件"是他超出我们稿的两个好设计。我们稿的价值兑现在了骨架上,POC 结论(workerd 能跑 agent loop)也被自研路线间接采用。

Part 6

现状与注意事项

已合入 st/test(merge f86a183 + R13–R22 修复轮:防伪造聊天回执、markdown 安全渲染、任务完成通知进聊天、模型历史与系统产物分离、fallback 消化加固、竞品每日去重等)。合并审计还顺手修了我们两处缺陷(fast queued 每日幂等、cap 满员 429 语义)。
灰度开关:AGENT_NATIVE_DIGEST / CHAT / SEARCH / BEHAVIOR 四个 flag,目前在 sozai-st(test)环境全开;旧 digest 路径保留为 fallback。
新基建依赖:video-analysis-worker(独立 worker,service binding + AUTH key)——st/prod 要上必须先部署它并配 VIDEO_ANALYSIS_AUTH_KEY。
st/prod 尚未合并:线上还是 7/10 的版本。上线前置:迁移 0035–0041 跑 st 线上库、DO migration(付费计划 OK)、video-analysis-worker 部署、四个 flag 决定开哪几个。
supervisor 的评审页(与 RFC 同步维护):visual-explain.fpai.io/sozai-agent-native/design.html;母本 docs/rfc-agent-native.md,待确认项在其 §16。