素材工房「真 Agent 化」设计方案

一、现在的问题：为什么要改

现在两条路上 LLM 都只是"被动打分器"，怎么找、怎么改，全是代码写死的：

另有两处 Codex 走查发现的暗伤，这次一并修：① 快搜/竞品的运行记录没盖当时的基因版本号（guidance_version 为空），"这批素材是哪一版检索文档找来的"答不上来；② 手动触发的快搜整个跑在 HTTP 请求结束后的 waitUntil 里，平台随时可能掐掉（7/10 消化引擎就是这么死的，§23.42）。

二、总架构：一个脑子 + 一个工人

要点在右下那条空隙：管家（实时、有人在）和检索工人（后台、慢慢跑）从不直接调用对方——中间永远隔一张 Postgres 队列表。这样任何一边挂了都不拖累另一边，而且两边的进展都落库，谁都能查。

为什么是"两个"而不是一个或三个

• 管家 Agent：业务 Agent 的人格化身。你在反馈页跟它说话，它秒回；没人理它的时候，它定期把攒下的零散反馈（点赞点踩、编辑附言）批量消化掉。对话和批量是同一个脑子的两种上班方式，共用同一套工具和同一部行为准则。
• 检索执行 Agent：无人格的工人，多源：快速搜索（TikHub 直搜）和竞品搜索（走桥）都归它，按查找目标自己决定用哪个源、怎么配比。只有深度搜索照旧派给 tobatsu，不动。
• 不设第三个：批量消化不是独立 Agent，就是管家在无人值守模式下跑了一班岗。

三、管家 Agent：完整规格

3.1 两种上班方式

3.2 工具清单（逐个列）

3.3 行为准则（写进 system prompt 的"宪法"，逐条列）

这些全部是 PM 已拍板的原则，从现在散落的 prompt 里升格为一份独立的版本化文件：

• 反馈对象决定侧重（§23.47）：「创意源」阶段的反馈默认改检索文档；「方案」「成片」的默认改创意规则；【整体】看内容定。内容明确涉及两边时可以都改。
• 用户意图至上：检索文档里用户亲手写的方向，只能顺着补充和聚焦，不能改掉、不能稀释。
• 强弱信号分层：带文字的反馈是强信号；纯点击是弱信号，只作趋势参考，量再大也不能盖过文字反馈。
• 对象分寸：针对某一条内容的意见用来修对应环节，只有针对整体的意见才动全局方向。
• 言行对照（四期）：用户嘴上说的和实际采用的素材不一致时，指出来并以行为证据为准提问，不擅自站队。
• 改动最小化：每次只改需要改的那一份文档，给完整文本不给 diff，summary 一句话说清这次改了什么方向。

3.5 view_object 的认知层：meta 从哪来（查库实证）

反馈引用的是视频，但管家"看"对象不需要现场跑视频理解——各源的理解产物早就落库了（2026-07-11 查共享测试库真实数据确认）：

• 有啥发啥、逐字段降级（PM 修正后定稿）：不预设任何字段一定存在——把对象实际存在的理解字段全部动态打包发给模型，缺哪个缺着并如实标注，不做固定映射。
• 视频理解 = mai 的 video-analysis-worker，纯工具：同账号 service binding（VIDEO_ANALYSIS_WORKER），POST /process 同步 180s，内部自走 URL→GCS→Gemini。已实测：200 / 29 秒（10 秒视频），输出直接就是"视频创意深度拆解报告"（结构透视/核心钩子/素材基因）——prompt 人家为广告创意调好了，零改造。还白送 /extract-frames（抽帧）和 /api/query（视频问答）两个端点。Gemini 的定位钉死：一个函数，无人格不决策，脑子永远是 claude。
• 库级不变式：进素材库的视频入库时已全部分析好——管家用时默认就绪，绝不跑第二遍（幂等）。分析写库带 analysis_source（gemini-mai / tobatsu / bridge）+ 时间戳。
• 亮点提前发现：分析时顺带要一个 highlight 评级+理由（零额外成本）——高潜素材入库瞬间即被标出，管家可主动冒泡、素材卡标"高潜"。
• 存量补齐：一次性 backfill 脚本 + 管家 lazy 兜底工具管漏网（触发即打日志——正常不该发生）。

3.6 对话里改基因的确认流（一步一步）

四、检索执行 Agent：完整规格

4.1 工具清单

4.2 它自己拿主意的事（现在做不到的）

• 关键词提炼和改写重试：搜"中世纪解压"没货，自己换"oddly satisfying medieval"再试。
• 跨平台、跨源调头：TikTok 三页都是水货，转去 Instagram；快搜整体没货，提交一轮竞品桥，等桥的间隙继续翻 TikHub——两个源的结果互补着凑满目标数。
• 该停就停：判断"越翻越水"提前收工，不硬凑数。
• 每轮的判断理由留在转录里——找得不好时你能看到它是怎么想的。

4.3 硬预算（框架层，防跑飞）

五、触发器全景（5 个入口，一个不漏）

规矩一句话：HTTP 请求里的 waitUntil 只准做一次 INSERT，永远不准跑 LLM。所有重活由分钟 tick（scheduled handler，15 分钟墙上时间）认领后 await 整跑。对话模式例外——它在请求存续期间流式跑，客户端连着就没有时限，本来就不走 waitUntil。⑤ 带来的唯一代价：反馈提交到消化开始多 0–60 秒，后台事，无感。

六、运行时：为什么管家住进 Durable Object

6.1 多开网页这个场景，无状态方案兜不住

6.2 责任划分（谁存什么）

6.3 连接协议

• 浏览器 ↔ DO：WebSocket（升级请求经 Worker 路由 /api/agents/:id/ws 转入 DO）。双向 + 广播原生支持，配 Hibernation API 空闲近零成本。
• 消息帧（mono 为帧类型）：chat.user / chat.delta（流式 token）/ chat.toolcall（工具调用可视化）/ gene.card / gene.card.resolved / run.progress / presence。
• 断线重连：客户端带 last_msg_id 重连，DO 从库补发缺口——和平常刷新页面走同一条加载路径。

6.4 为什么是 WebSocket 而不是 SSE（定论）

SSE 唯一优势是纯 HTTP 好穿企业代理；内部工具走 443 的 wss 不存在此问题。

6.5 各种"多个 session"，分四层各有答案

附带定一个细节：管家正在回答时又进来几条消息，不逐条跑 LLM——下一轮合并一起读，省钱且回答更连贯。

6.6 引入 DO 的代价（如实列）

• wrangler.jsonc 5 个环境各加 durable_objects binding + 一条 migration 声明（新增 class）。
• 部署形态第一次含 DO——直接在测试环境 sozai-st（sozai-st-test 域名）上验证，生产环境不碰。
• 计费多一项 DO 请求/存储费（Hibernation 下量级很小，预估每月个位数美元）。

七、数据结构：每张表逐项过

7.1 新表 ① agent_chat_messages（聊天记录）

CREATE TABLE agent_chat_messages (
  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  agent_id      uuid NOT NULL,            -- crawl_slots.id，一个 Agent 一条共享线程
  role          text NOT NULL CHECK (role IN ('user','assistant','system')),
  user_id       uuid,                      -- role=user 时记谁说的（团队共聊，区分发言人）
  content       jsonb NOT NULL,           -- 文本块 / 工具调用摘要块 / 卡片引用块
  gene_card_id  uuid,                      -- 这条消息挂的 diff 卡片（如有）
  created_at    timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX idx_chat_agent_time ON agent_chat_messages (agent_id, created_at DESC);

7.2 新表 ② agent_gene_cards（基因修改卡片，确认制的载体）

CREATE TABLE agent_gene_cards (
  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  agent_id        uuid NOT NULL,
  proposed_search text,                    -- 提议的新检索文档（不改则 NULL）
  proposed_steer  text,                    -- 提议的新创意规则（不改则 NULL）
  base_version    int  NOT NULL,          -- 基于哪一版提的（应用时乐观锁校验）
  reason          text NOT NULL,          -- 管家的一句话理由
  status          text NOT NULL DEFAULT 'pending',  -- pending/applied/rejected/expired
  resolved_by     uuid, resolved_at timestamptz,
  applied_version int,                     -- 应用后铸出的版本号
  created_at      timestamptz NOT NULL DEFAULT now()
);

7.3 新表 ③ agent_behavior_events（行为事件，四期）

CREATE TABLE agent_behavior_events (
  id            bigserial PRIMARY KEY,
  agent_id      uuid NOT NULL,
  user_id       uuid,
  event_type    text NOT NULL,   -- material_viewed / material_ignored / delivery_downloaded
  object_type   text, object_id uuid,
  source_run_id uuid,             -- 顺着它能查到当时的基因版本
  meta          jsonb DEFAULT '{}'::jsonb,
  created_at    timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX idx_behavior_agent_time ON agent_behavior_events (agent_id, created_at DESC);

只埋 viewed / ignored / downloaded 三个前端事件。"素材入方案""方案被派发"不用埋——从 creative_boards、deliveries 的现有引用关系就能算出来。

7.4 现有表的改动（只字段级，不动结构的红线）

八、上下文工程与缓存（PM 重点关注项，P1 施工图按此逐条验收）

8.1 上下文分两层，职责不同

刻意的设计：run 和 run 之间不传对话——"上次学到的"必须沉淀成基因文档的修订才算数。基因是用户可见、可编辑、可回滚的，Agent 的记忆不藏在任何黑盒里。

8.2 Prompt 三层结构（缓存友好的不变前缀）

铁律：前缀禁止时间戳、随机 ID、未排序 JSON——一个字节漂移，断点之后全部白给。agent-loop.ts 必须内建"断点装配器"，且每轮把 cache_read / cache_creation / input / output 四个 usage 数记进转录——成本可审计是 P1 验收项。

8.3 缓存经济学（为什么这是成本命门）

• 按 30 轮 loop、L0+L1≈8k tok、每轮增量≈1k 估算：无 cache 输入侧 ≈ 48 万 token/run（前缀被全价重复计费 30 次，O(n²)）；有 cache ≈ 6–9 万 token/run——约 7-8 倍成本差。
• 所以 P0 的 0.6 例（ZenMux cache_control 透传 + usage 计费字段回报）是闸门：不过 → 预定决策：agent 循环直连 Anthropic（需另配 key），ZenMux 只留给单发小调用。

8.4 新大户治理：视频拆解报告的分级注入

• 一份拆解报告 1–2k tok，前置分析 12 条 = 2 万 tok 的上下文炸弹——全文永不自动进上下文，只落 meta。
• analyze_video 返回结构化摘要，PM 定档：≈400–500 tok/条——按五类固定小节输出（镜头节奏 / 口播钩子 / 字幕文案要点 / 亮点评级 / 一句话判词，缺哪类写"无"），字段名固定：信息量够判创意，token 数也稳定可预算。150 tok 一句话档太薄，已否掉。
• 预算重算：12 条 × 500 ≈ 6k tok，进转录后随前缀被缓存复用（读价 0.1×），完全可承受；换来粗筛/终选不用回头翻全文。
• view_object 默认 digest 档，detail:'full' 显式请求才给全文且限 ≤2 条/轮（工具层硬限）。

8.5 修剪与缓存的张力（折叠必须批量）

• 折叠旧 tool_result 会改写前缀 → 断点后全部失效、一次冷写。所以不逐轮修剪：转录到 60k tok 才一次性批量折叠到 30k，折叠后前缀重新稳定——每 run 最多 1–2 次冷写，摊薄掉。
• 折叠保留 assistant 决策文字，tool_result 换一行占位（"[第2轮搜索结果，已入库12条]"）。双预算硬闸（40 轮 / 200k tok）不变。

8.6 各存储职责边界（不越位）

分析幂等不靠 KV：靠 meta 已有检查 + DB ON CONFLICT。对话模式每轮装配 = L0 + L1（当前基因）+ 最近 N 条聊天（按 ≈8k tok 预算倒推）；老历史只在 UI 懒加载展示、不进上下文；基因被他人手动改掉时 DO 收到版本事件 → 下一轮 L1 刷新、接受一次冷写——正确性优先于缓存命中。

九、UI 设计（PM 拍板：直接替代现有反馈中心的入口和位置）

不另开新页——管家对话页顶替当前反馈中心的入口和位置，细节 PM 后续迭代。旧反馈中心的内容去处：版本时间线 → 右栏常驻；历史反馈与版本推送 → 以时间线卡片出现在对话流开头（反馈本来就成为对话的一部分）。

整页只有一处要你做决定：那张墨蓝卡片。其它一切（它翻了什么、搜到哪一轮）都是可看可不看的过程信息，默认折叠，不抢注意力。

逐组件说明

十、行为日志：让 Agent 越用越准

没有行为记录，管家只能听你"说"了什么；有了它，管家还能看你"做"了什么——两边对照才知道怎么改。

血统接通后的完整追溯（一条线捋到底）

检索文档 V4 ──> 当时的检索 run（guidance_version=4，本次补上）
        ──> 这批素材 ──> 采用了几条 / 点踩几条
        ──> V4 比 V3 是变好还是变差 ──> 写进 V5 版本行的效果快照
        ──> 管家 read_performance() 读到 ──> 下次消化拿证据说话

每次铸新版时把上一版的成绩快照进版本行——版本时间线自动变成"每次改动有没有用"的成绩单，你看得到，管家也读得到。

十一、技术选型定论（每项一句话理由）

十二、动工前必须过的验证（第 0 步）

其它风险，如实列

• DO 首次进部署面：直接在 sozai-st 测试环境上验证（PM 已授权随便部署）；生产不碰。
• 三张新表 migration：手工 psql 按现有规矩执行，上线前给你过目 SQL。
• token 成本上升：管家对话按次计、检索 run 有 ¥3 上限闸；四期看板出来前先在转录里记每 run 花费。
• 批量消化换脑子后行为可能变化：feature flag（AGENT_NATIVE_DIGEST）新旧可随时切换，旧代码不删。

十三、改动清单：后端动哪些文件、前端动哪些

13.1 后端 · 新增文件

13.2 后端 · 改动的现有文件

13.3 前端 · 改动清单（SSR JSX + 客户端脚本）

十四、测试策略：部署到测试环境的端到端，本地不作数

验收只认一种证据：部署到 sozai-st（sozai-st-test.funplus-marketing.ai）之后，从真实入口打进去、走完整条路、在库里和页面上看到正确结果。typecheck 和单测只是提交门槛，不算验收。

14.1 用例目录：五期 62 例 + 每期回归 4 例（编号制，报告按号对账）

执行模型：Codex 全量跑（token 便宜，用例宁多勿少），每例出证据（SQL 输出 / 转录摘录 / 截图）；我抽验 ★ 号关键例亲手复跑后签收。完整编号目录在 docs/rfc-agent-native.md §14，这里列每期覆盖面：

14.2 测试基建（复用现成的）

• 部署纪律（已授权）：测试环境就是 sozai-st（新域名 sozai-st-test.funplus-marketing.ai），当前分支 随便部署、原地迭代——不做本地验证，直接部上去测，有问题改了再部。生产（sozai.funplus-marketing.ai）不碰。测试库为三个测试环境共用的同一个 Neon。
• 登录态（合规后门）：走现成的 POST /api/auth/test-session（Bearer MB_TEST_LOGIN_TOKEN，只在 _test 后缀环境生效，铸 *@material-board.local 会话）+ agent-browser 预置状态——飞书 OAuth 全程绕开，不新增任何登录绕过端点（红线，这个路由是既有且环境门禁的）。
• 脚本形态：scripts/e2e-agent-native-p{0..4}.mjs，风格沿用现有 e2e-pm-vibe-tobatsu.mjs；UI 断言用 agent-browser 截图。
• 共享库红线：三个环境同一个 Neon——测试 Agent 专建专删、绝不碰真实 Agent（如 3ef6492f 那个 PM 跟踪中的任务）。

十五、分期路线图（每期可独立验收、可随时叫停）

全程规矩：每期完成记 handoff §23.x；typecheck 必过；部署目标只有 sozai-st 测试环境（随便部），生产不碰；migration SQL 先给你过目（共用测试库，建表全环境可见）。Codex 走施工图制——我给图纸和自证清单，它实现并跑完自证，我再亲手复跑一遍才签收。

十六、等你逐项确认的清单