SurfSense 多智能体中的 Deliverables 子代理制品生成系统提示词、输出契约与可验证 Receipt 机制深度解析【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense导读SurfSense 的多智能体对话架构中主代理supervisor会把生成报告、播客、视频演示、简历、图片这类长时、可交付的任务委托给一个专职子代理执行而承载其全部行为约束与通信规范的正是 deliverables 子代理系统提示词。本文以该提示词为骨架逐段拆解其目标定义、工具边界、失败策略与严格 JSON 输出契约并结合仓库源码揭示generate_report、generate_image等工具的底层实现、共享 snippetoutput_contract_base、verifiable_handle与异步后台生成语义。读完本文你将掌握SurfSense 如何让一个 LLM 子代理只吐一个 JSON地完成制品生成、如何用 Receipt 机制让上游主代理可独立验证生成结果以及报告的分节修订、知识库检索增强等可复用设计模式。一、子代理的定位从委托指令到结构化结果该子代理在系统中的正式身份是 SurfSense deliverables operations sub-agent它的工作模式非常明确接收主代理委派的指令执行制品生成然后返回结构化结果供主代理综合见 system_prompt.md。这意味着它不直接面对用户而是多智能体流水线中的一个专用执行单元。其职能简介description.md将其定义为Specialist for producing long-form deliverables: reports, podcasts, video presentations, resumes, and generated images. Use proactively when the user wants one of these artifacts produced.即它是长式交付物专家覆盖报告、播客、视频演示、简历、生成图片五类制品并且应当被主动调度——只要用户表达出生产其中一种制品的意图。从构建入口 agent.py 可以看到子代理是如何被装配的build_subagent通过read_md_file(__package__, description)与read_md_file(__package__, system_prompt)把上述两个 Markdown 文件读入内存再经pack_subagent打包成SurfSenseSubagentSpec名称、描述、系统提示词、工具集、权限规则集等。其中read_md_file的实现在 shared/md_file_reader.py按{stem}.md从包资源中读取并去除末尾换行且对共享 snippet 做了lru_cache缓存。换句话说本文讲解的这份 system_prompt.md 是直接参与运行时子代理构造的活文件而非仅作文档展示。二、Goal 与 Available Tools五种制品五个工具提示词的goal段落定义了子代理的核心使命Producedeliverables: shareableartifactsthe user keeps (reports, slide-style video presentations, podcasts, resumes, images). Use explicit constraints and reliable proof of what was generated.关键语义有三点产出物是用户留存的可分享制品artifact必须遵循明确的生成约束受众、格式、语气、核心内容必须提供可靠的生成证明reliable proof——这正是后文 Receipt 机制的由来。available_tools段落给出了该子代理被允许调用的全部工具清单共五个工具对应制品类型generate_report报告reportgenerate_podcast播客podcastgenerate_video_presentation幻灯片式视频演示video_presentationgenerate_resume简历resumegenerate_image图片image在源码层这五个工具的注册完全对应 tools/index.py 中的load_tools工厂函数依次调用create_generate_podcast_tool、create_generate_video_presentation_tool、create_generate_report_tool、create_generate_resume_tool、create_generate_image_tool通过dependencies注入workspace_id、db_session、thread_id等工作区上下文。其中generate_report额外注入connector_service、available_connectors、available_document_types用于知识库检索见下文第四节generate_image额外注入image_gen_model_id_override用于自动化任务中以捕获的模型运行见第五节。同时 agent.py 的模块注释说明了一个有趣的设计该子代理的工具会在工具体内部通过request_approval自我把关self-gate而其权限规则集RULESET是空的index.py 中RULESET Ruleset(originNAME, rules[])空规则集仍会被分层进PermissionMiddleware以保证结构统一。这是一种把权限判断内聚到每个工具自身的架构选择。三、Tool Policy、Out of Scope 与 Safety把约束焊进提示词tool_policy是提示词中偏执行纪律的部分共三条只用available_tools里的工具——禁止越权调用其他子代理或系统的工具必须收集关键的生成约束audience 受众、format 格式、tone 语气、core content 核心内容之后才能开工关键约束缺失时返回statusblocked并附missing_fields——宁可阻塞也不臆测绝不在没有工具确认的情况下声称制品生成成功。out_of_scope只有一条不得执行与制品生成无关的连接器connector数据变更。也就是说deliverables 子代理是只读研究 只写制品的执行体不允许顺手改用户的连接器配置。safety两条避免在关键约束缺失时生成制品宁要一个完整制品不要多个残缺制品Prefer one complete artifact over partial multi-artifact output。这组约束与 report.py 中generate_report的触发判定逻辑高度呼应工具文档里专门列出什么不算要报告——对报告主题的提问、讨论、追问如 What else could be added?、Is the data accurate?都应回到对话而非触发生成判据是消息中是否包含针对交付物的创建/修改动词write、create、generate、draft、add、revise、update、expand、rewrite、make。可见约束先行、识别意图不仅是提示词口号也在工具描述层被程序化落实。四、Output Contract只吐一个 JSONoutput_contract是该提示词最核心的部分它强制子代理只返回一个 JSON 对象禁止任何 Markdown 或散文其完整 schema 如下{ status: success | partial | blocked | error, action_summary: string, evidence: { artifact_type: report | podcast | video_presentation | resume | image | null, artifact_id: string | null, artifact_location: string | null, receipts: Receipt[] | null }, next_step: string | null, missing_fields: string[] | null, assumptions: string[] | null }各字段语义归纳如下字段类型说明status枚举四种状态成功 / 部分成功 / 被阻塞缺约束/ 出错action_summarystring本次执行的行动摘要evidence.artifact_type枚举/空制品种类未生成时为nullevidence.artifact_idstring/空制品 IDevidence.artifact_locationstring/空制品位置evidence.receiptsReceipt[]/空本轮工具返回的 Receipt 列表next_stepstring/空下一步建议失败/阻塞时必填missing_fieldsstring[]/空缺失的关键输入字段blocked 时必填assumptionsstring[]/空对用户意图的推断无需推断时为null紧随 schema 的Route-specific rules规定了evidence.receipts的填写方式必须逐字verbatim引用本轮generate_report/generate_podcast/generate_video_presentation/generate_resume/generate_image返回的 Receipt且 Receipt 的type枚举与上述五种制品一一对应。通用规则注入output_contract_baseschema 末尾的include snippetoutput_contract_base/会把 shared/snippets/output_contract_base.md 的内容内联进提示词。这份通用输出契约定义了跨子代理的状态机规则statussuccess→next_stepnull、missing_fieldsnullstatuspartial|blocked|error→next_step必须非空next_step只能填写你自己无法执行的动作如果后续步骤是对自己工具的一次调用如用read_run/search_run读取已存储的运行、用调整后的参数重跑应当立即执行并返回改进后的结果而不是报partialstatusblocked缺输入→missing_fields必须非空assumptions记录对用户意图的推断无推断时为nullevidence对象的字段由 route-specificoutput_contract定义不得虚构工具未返回的字段当结论来自一次 scraper 运行时把该运行标注的[n]原样追加到结论文本中工具会提示 Cite this scraper run as [n]确保引用能存活到最终答案且必须逐字复制标签不得自创。这套规则的作用是让所有子代理不只是 deliverables共享同一套可机器解析、可自动调度的响应协议从而让主代理能够可靠地依据next_step、missing_fields决定下一步动作。五、Verifiable HandleReceipt 就是可靠的生成证明include snippetverifiable_handle/引入 shared/snippets/verifiable_handle.md它把第一节提到的 reliable proof of what was generated 具体化为Receipt 机制变更类工具在返回正常载荷之外还会返回一个结构化的Receipt对象。主代理supervisor依据 Receipt 的verifiable_url和external_id独立确认操作是否成功——不得转述、缩写或猜测这些值。Receipt 的使用规则逐字引用每个 Receipt 的verifiable_url与external_id必须一字不差地填入evidence.receiptsfailed 语义Receipt 的statusfailed→ 子代理自身statuserror并把 Receipt 的error字段放入next_steppending 语义关键Receipt 的statuspending表示制品走的是异步后端播客、视频演示以及任何经 Celery 排队的内容此时子代理应自身返回statussuccess原样呈现该 pending Receipt在action_summary中告知主代理制品正在后台生成例如 Podcast 38 queued; orchestrator should report it as kicked off, not yet readypending Receipt 通常没有verifiable_url制品还不存在这是预期行为而非缺陷不等待、不轮询、不重试——控制权立即交还主代理制品随后通过自己的 UI 界面以带外out of band方式呈现给用户严禁虚假声称没有收到statussuccess或pending的 Receipt就不得声称变更成功只读工具豁免不返回 Receipt 的只读操作搜索、查询等不适用上述规则只看 route-specific 的evidence字段。这一设计解决了多智能体系统中子代理说自己成功了但父代理无从验证的信任问题主代理拿到verifiable_url后可以独立复核制品真实存在而异步制品的 pending 语义则避免子代理在长任务上死等保持流水线吞吐。在实现层with_receipt/make_receipt位于 shared/receipts/command.py 与同目录 receipts 模块工具通过with_receipt(payload..., receipt..., tool_call_id...)将普通载荷与 Receipt 一并返回见 report.py 与 generate_image.py。六、Failure Policy失败也是可调度的结果failure_policy定义了两条兜底规则与前文的输出契约互相咬合生成失败 → 返回statuserror并给出最佳重试建议best retry guidance关键约束缺失 → 返回statusblocked并列出缺失字段。结合第四节的状态机可知失败与被阻塞是两种截然不同的返回blocked意味着信息不足、补齐missing_fields即可继续error意味着执行过程中出错、需要按next_step的重试指引调整。把失败建模成可解析的结构化字段正是让主代理能够自动编排下一步的关键。七、源码级纵深generate_report 与 generate_image 的实现细节7.1 generate_report单次生成、分节修订与知识库增强report.py 的工厂文档字符串揭示了generate_report的三段式设计1来源策略source_strategy共四种provided只用source_content默认向后兼容conversation对话中已有足够上下文此前问答、文件系统探索、粘贴文本、上传文件、抓取的网页把对话历史总结为source_content传入——用户之前的提问和你的回答本身就是素材不要冗余搜索知识库kb_search内部检索知识库需提供 1~5 条精准search_queries工具内部完成检索不要手工读取并倾倒 /documents/ 文件autosource_content内容足够就用它否则自动回退到内部知识库检索。auto的回退阈值在实现中是启发式的当source_content少于约 200 词时判定不足触发 KB 检索report.py。KB 检索采用search_chunkshybrid search每个查询使用独立短生命周期会话top_k10最多并发 5 个查询按document_id去重合并再渲染为标题 分块内容的纯文本注入提示词report.py。渲染时刻意省略引用标注——当前报告不输出[n]引用标签仅提供有依据的原文内容。2生成与修订版本化新报告走单次生成single-shot一次 LLM 调用提示词模板要求输出含# 标题、执行摘要、组织化章节与结论的结构化 Markdownreport.py修订parent_report_id非空优先走分节修订先把报告按#/##标题切段代码块内的#不会误判为标题让 LLM 产出修改/新增/删除哪些小节的 JSON 计划然后只对受影响小节重写、未修改的小节逐字节保留同时插入新小节、删除冗余小节report.py若小节过少、计划解析失败或全部小节都要改则回退到整篇修订每次修订都会在父报告的report_group_id分组下生成新版本report.py。3格式规范_FORMATTING_RULES强制输出裸 Markdown禁止整篇包在代码围栏里、代码示例必须带语言标识与正确缩进、Mermaid 图每个语句独立成行、数学公式一律用 LaTeX。此外report_stylebrief会触发约 400 词约一页的硬性长度约束。生成过程还会通过dispatch_custom_event上报report_progress进度事件如kb_search、writing、revising_section、adding_section让前端能实时展示生成阶段。7.2 generate_image模型解析与 UI 就绪载荷generate_image.py 展示了另一个工具的完整链路参数prompt尽量具体地描述主体、风格、色彩、构图、情绪与n生成数量1~4默认 1每次调用使用独立短生命周期会话shielded_async_session避免并发工具调用共享 AsyncSession 引发的自动刷写autoflush污染模型解析分两条路径负 ID 走全局模型/连接config.GLOBAL_MODELS正 ID 走工作区数据库中的Model Connection且都会校验模型的image_gen能力与工作区/用户归属随后统一经to_litellm转换后调用 litellm 的aimage_generationimage_gen_model_id_override让自动化任务可以在捕获的模型上运行与后续工作区配置变更隔离结果写入ImageGeneration表并生成签名访问令牌若模型返回b64_json如 gpt-image-1则通过后端/api/v1/image-generations/{id}/image?token...端点托管避免兆级 base64 撑爆 LLM 上下文最终返回 UI 就绪载荷src、alt、domain: ai-generated、generated: true等并附带statussuccess的 Receiptgenerate_image.py。7.3 播客与视频演示Celery 异步后台生成从verifiable_handle的规则可以确认播客与视频演示以及任何经 Celery 排队的制品属于异步后端工具调用后立即返回statuspending的 Receipt子代理按规则五报成功但不声称立即可用随后制品由后台任务生成、经其自身 UI 面呈现。这与提示词中不要等待、轮询或重试的指令完全一致也是 deliverables 子代理能够快速交还控制权、避免长任务拖垮对话流的原因。八、设计要点总结提示词即接口契约deliverables 子代理的行为完全由 system_prompt.md 界定运行时由 agent.py 直接装配——改提示词即改行为且通过include snippet复用共享规则保证多个子代理的输出协议一致。结构化输出优先强制单一 JSONstatus / evidence / next_step / missing_fields / assumptions让主代理可以无歧义地编排后续动作blocked与error的区分把缺信息与执行失败两种场景分开处理。可验证性内置Receiptverifiable_urlexternal_id把工具声称成功升级为可独立复核的成功而pending语义为异步制品提供了不阻塞的优雅通道。意图判定下沉到工具generate_report在工具描述层就内置了创建/修改动词判定与四档来源策略配合提示词中的工具策略从两层防止误触发与素材错配。质量约束显式化受众/格式/语气/核心内容四项关键约束缺失即blocked一个完整制品优于多个残缺制品的安全偏好保证交付物质量下限。这套严格提示词 结构化输出契约 可验证 Receipt 异步语义的组合既可直接用于理解 SurfSense 的制品生成流水线也可作为设计其他多智能体系统中专用执行子代理的参考范式。相关实现与测试均可在本仓库的 deliverables 工具目录 与 共享 snippets 目录 中继续深挖。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考