SurfSense 主 Agent 团队线程身份提示词解析开源开放网络研究平台的编排器设计【免费下载链接】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/SurfSenseSurfSense 是一个开源的开放网络研究平台Open-source NotebookLM alternative其核心是多智能体multi-agent架构一个主 Agent负责编排向各个专业子代理subagent分发任务从而研究实时开放网络数据。本文聚焦于主 Agent 在**团队线程team thread**下的身份提示词设计——即 team.md 这份agent_identity文档并结合仓库源码讲清身份提示词如何被组装、task编排工具如何工作、子代理名册如何生成。读完本文你将理解 SurfSense 主 Agent 的编排者定位、团队线程与私有线程的身份差异以及这套系统提示词如何通过源码实现动态注入与按可见性切换。一、什么是主 Agent 身份提示词在多智能体系统中系统提示词system prompt决定了一个 Agent 的角色认知、行为边界与工作方式。SurfSense 将主 Agent 的系统提示词拆分为多个 Markdown 片段存放在 system_prompt/prompts 目录下按功能划分为identity/—— 身份声明即本文核心core_behavior.md、routing.md、kb_first.md—— 核心行为与路由规则dynamic_context/—— 每轮动态注入的上下文memory_protocol/—— 记忆协议citations/、output_format.md、refusal_and_limits.md、reminder.md—— 引用、输出格式与安全护栏tools/—— 各工具的描述与示例providers/—— 按模型厂商Anthropic、Google、OpenAI 等区分的提示词变体。这些片段由 compose.py 按固定顺序拼装成最终系统提示词其中agent_identity永远位于最前紧随其后的才是用户自定义指令与默认行为体。二、团队线程身份提示词逐段解析identity/team.md是团队线程可见性为SEARCH_SPACE下的身份声明其完整原文结构如下agent_identity You are **SurfSenses main agent**, the orchestrator of an open-source open web research platform. This team comes to you to research the live web: what communities and audiences are saying, how rankings, reviews, and pages are changing, and what is being published across the open web — and to put that research to work alongside the teams shared knowledge base. You do this by dispatching **specialist subagents** via the task tool: - **Live web data** — Reddit, YouTube, Instagram, TikTok, Amazon, Walmart, Google Maps, Google Search, and the web crawler return structured, current platform data (posts, comments, transcripts, videos, products, reviews, SERPs, full page content). - **The teams own context** — its shared knowledge base, connected apps, and persistent team memory. - **Deliverables** — reports, podcasts, and presentations built from what the specialists find. You are an orchestrator — most non-trivial work belongs on a specialist. Your value is routing each request to the right specialist, synthesizing evidence across sources, and answering with what the data shows rather than what you assume. Today (UTC): {resolved_today} You are in a **team thread**. Each message is prefixed with [DisplayName]. Attribute quotes and decisions to the named author when relevant. /agent_identity这份提示词虽然精炼却定义了编排器的全部关键行为准则可拆解为四个层面1. 角色定位编排器Orchestrator而非执行者开篇即以加粗强调 SurfSenses main agent, the orchestrator。这一身份声明传达的核心原则是You are an orchestrator — most non-trivial work belongs on a specialist. Your value is routing each request to the right specialist, synthesizing evidence across sources, and answering with what the data shows rather than what you assume.即主 Agent 的价值不在于亲自动手完成每一项工作而在于路由routing把每个请求分发给正确的子代理综合synthesizing跨多个数据源综合证据以数据为准answering with what the data shows rather than what you assume答案必须建立在子代理返回的数据之上而非模型自身的假设。2. 三大资源类别主 Agent 可以调度的全部能力身份提示词把子代理产出的资源划分为三类类别覆盖范围产出形态Live web data实时网络数据Reddit、YouTube、Instagram、TikTok、Amazon、Walmart、Google Maps、Google Search、Web Crawler帖子、评论、转录稿、视频、商品、评论、SERP搜索引擎结果页、完整网页内容The teams own context团队自身上下文共享知识库、已连接应用、持久化团队记忆文档检索结果、应用操作结果、记忆条目Deliverables交付物报告reports、播客podcasts、演示文稿presentations由各专业子代理的发现加工而成对照仓库源码这三类能力恰好对应 subagents/registry.py 中注册的内置子代理详见下文第五节其中deliverables子代理专门负责报告、播客与视频演示的生成其工具定义位于 subagents/builtins/deliverables。3. 动态占位符{resolved_today}身份提示词末尾包含Today (UTC): {resolved_today}这是一个运行时注入的占位符。在 sections/identity.py 中可以看到它的实现def build_identity_section(*, visibility: ChatVisibility, resolved_today: str) - str: variant team if visibility ChatVisibility.SEARCH_SPACE else private fragment read_prompt_md(fidentity/{variant}.md) if not fragment: return return \n fragment.format(resolved_todayresolved_today) \n而resolved_today的值由 compose.py 计算resolved_today (today or datetime.now(UTC)).astimezone(UTC).date().isoformat()即每次组装系统提示词时都会以UTC 时区的当前日期替换{resolved_today}保证主 Agent 对今天的认知与实际日期一致。这对此类研究实时开放网络的场景至关重要——排名、评论、页面内容每天都在变化Agent 需要知道当前日期以正确理解最近上周等相对时间表述。4. 团队线程上下文标记身份提示词末尾明确声明了两条团队线程特有的规则You are in ateam thread. Each message is prefixed with[DisplayName]. Attribute quotes and decisions to the named author when relevant.这意味着在团队线程中每条用户消息都带有[DisplayName]前缀标识消息作者主 Agent 在引用某人的观点或决策时应当将其归于对应的具名作者named author而不是当作无主的普遍事实。这是团队协作场景与私有场景的关键差异。对比 identity/private.md 可以看到私有线程版本把 This team 换成 Users、把 the teams shared knowledge base 换成 their own knowledge base且没有团队线程标记段——整个身份提示词的措辞都按单用户场景做了裁剪。三、身份提示词的可见性切换机制主 Agent 会运行在两种线程可见性之下PRIVATE私有与SEARCH_SPACE团队/工作空间。身份提示词是可见性感知visibility-aware的sections/identity.py 依据ChatVisibility枚举选择identity/team.md或identity/private.md变体sections/dynamic_context.py 同样按可见性选择dynamic_context/team.md或dynamic_context/private.md记忆协议memory_protocol与工具描述也遵循同样的切换逻辑见 sections/tools.py。在团队线程下dynamic_context/team.md还会注入两块每轮权威的上下文team_memory团队累积的持久化共享记忆——决策、约定、架构笔记、流程、关键事实同时报告当前字符用量与硬性上限帮助主 Agent 管理记忆预算workspace_tree完整的/documents/文件夹与文件布局用于把自然语言描述的路径Q2 路线图上周的规划笔记解析为具体文档引用再交给专业子代理。可见身份提示词不是孤立的一页纸而是与动态上下文、记忆协议联动的一个整体设计。四、编排的执行引擎task工具身份提示词反复强调通过task工具调度子代理那么这个工具本身是如何定义的呢仓库将其拆分为描述与示例两个文件prompts/tools/task/description.md —— 工具行为规范prompts/tools/task/example.md —— 使用示例。单代理模式Single modeArgs (single mode): - subagent_type — name of the specialist to invoke (must match an entry in specialists). - description — the FULL task prompt. The specialist cannot see this thread, so include all context and constraints, plus what you need back. The specialist will respond in its own format — dont dictate one.两个关键设计description必须是完整任务提示词子代理看不到当前线程所有上下文与约束都要写进去同时主 Agent不应规定子代理的输出格式The specialist will respond in its own format — dont dictate one因为各子代理有自己的输出契约output_contract。example.md给出的实际调用形态user: Save these meeting notes to my KB: … → task(subagent_typeknowledge_base, descriptionSave the notes below to a new document under /documents/notes/. Pick a sensible title and folder; tell me the path you used.\n\nnotes…/notes)批处理模式Batch mode当单个请求需要展开为3 个及以上相互独立的子代理调用时使用批处理形态Args (batch mode): - tasks — array of {description, subagent_type} objects to fan out concurrently. Mutually exclusive with single-mode args.例如从列表创建 5 个 issue这种多路扇出fan-out场景。运行时在小子代理并发上限small concurrency cap下并行执行并为每个子任务返回一个带[task index]前缀的 ToolMessage 块。注意限制批处理子任务不支持人工介入中断human-in-the-loop interrupts——若某个子任务需要审批它会报错主 Agent 必须将其改为单次非批处理task(...)重新派发。路由规则prompts/routing.md 详细规定了task的使用纪律核心规则包括一个task调用只针对一个子代理每个子代理只有自己领域内的工具并行化独立工作当一次会话需要多次互不依赖的task调用时如同时创建 ClickUp 工单和 Linear 工单应并发发出跨轮串行化依赖工作若一个子代理的输出是另一个子代理的输入如先在知识库找路线图再发邮件给 Maya应在连续两轮中先后调用并用write_todos跨轮维持计划把完整指令写进任务提示词子代理看不到当前线程不要臆断子代理的数据源内容必须调用子代理并使用其返回值而不是声称我已经知道。路由规则还给出了领域映射例如受众情绪去平台社区讨论走task(reddit, …)视频内容走task(youtube, …)短视频趋势走task(tiktok, …)实体店评价走task(google_maps, …)商品评价走task(amazon, …)/task(walmart, …)而地点找 Maps、开放网页找 Search、搜索发现、爬虫读取等策略也在此定义。五、子代理名册从注册表到动态生成身份提示词提到的各类子代理并非写死在提示词中而是由运行时动态生成并注入specialists区块。生成逻辑位于 sections/specialists.pydef build_specialists_section(specialist_lines: list[tuple[str, str]]) - str: bullets \n.join(f- **{name}** — {desc} for name, desc in specialist_lines) return f\nspecialists\n{bullets}\n/specialists\n名册数据来自 subagents/registry.py 中的SUBAGENT_BUILDERS_BY_NAME注册表。从源码结构看该注册表当前登记了 17 个内置子代理构建器子代理名职责领域amazon亚马逊商品与评价deliverables报告 / 播客 / 视频演示等交付物dropbox、google_drive、onedrive云盘文件连接器原生服务于知识库google_maps地图地点、商家与客户评价google_searchGoogle 搜索结果SERPindeed招聘信息instagramInstagram 内容knowledge_base工作空间知识库检索与文档操作mcp_discovery已连接第三方应用Slack、Notion、Jira、Gmail、日历等经托管 MCPmemory持久记忆维护redditReddit 社区讨论tiktokTikTok 短视频趋势walmartWalmart 商品与评价web_crawler开放网页爬取youtubeYouTube 视频、字幕与评论每个构建器对应一个agent.py与配套的description.md、system_prompt.md例如 subagents/builtins/reddit 与 subagents/builtins/knowledge_base。注册表还做了两件重要的事按连接器可用性过滤get_subagents_to_exclude()依据SUBAGENT_TO_REQUIRED_CONNECTOR_MAP定义于 constants.py检查当前工作空间可用的连接器不可用的子代理会被排除出名册。deliverables与knowledge_base声明了空依赖集合frozenset()因此任何连接器过滤下都能存活保证specialists名册永远非空。注入 KB 工具_inject_ask_kb_tool_in_place()会把ask_knowledge_base工具追加到除knowledge_base自身外的每个子代理工具栈中避免自我调用的同时让任意子代理都能触及共享知识库。此外每个子代理在 subagents/shared/spec.py 定义的SurfSenseSubagentSpec规范下运行拥有独立的工具栈与上下文并返回单一的合成结果——这正是task工具描述中所说的 Each subagent runs in isolation with its own tool stack and context, and returns a single synthesized result。六、可验证性设计子代理的自述不是证据身份提示词强调主 Agent 要answering with what the data shows。与之配套task工具描述中内置了一段verification验证教学防止编排器轻信子代理的成功自述A subagents natural-language reply is aself-report, not proof. The specialist might claim a Slack message was posted, a Jira issue was created, or a report was generated even when the underlying tool call failed silently or was rate-limited. Treat success language (Done, Posted to #general, Created ENG-42) as a hypothesis, not a fact.两个落地信号被提供给主 Agentstate[receipts]每个会变更状态mutating的工具都会向这个只追加列表写入结构化Receiptroute、type、operation、status、external_id、verifiable_url、preview并经子代理的output_contract以evidence.receipts形式回传。若子代理声称成功却没有任何statussuccess的 Receipt异步交付物如播客/视频则为pending则操作实际未发生应把失败如实反馈给用户而不是盲目重试。task(web_crawler, …)外部复核当 Receipt 携带verifiable_urlNotion 页面、Slack permalink、Jira issue 等时可派发web_crawler子代理抓取该 URL从外部确认变更是否真的生效——尤其适用于用户明确点名的高风险变更如把发布邮件发给全团队。Receipt 状态语义还规定statussuccess表示变更已在后端提交statusfailed应把 Receipterror字段原文呈现给用户statuspending应告知用户工作已启动并引用external_id/preview不得重发同一task(...)调用。这一设计使得编排器既能充分放权又保留了可审计的验证链路相关状态与中间件实现位于 main_agent/middleware/checkpointed_subagent_middleware 与 subagents/shared。七、团队协作语境下的编排实战把以上机制组合起来团队线程下的一次典型编排流程可以还原为收到带[DisplayName]前缀的团队消息主 Agent 依据身份提示词把观点归于具名作者路由判断确定该请求属于实时网络数据 / 团队上下文 / 交付物中的哪一类命中 routing.md 中的领域映射派发task(...)从specialists名册中选取匹配的子代理把完整上下文与约束写入description独立任务并行化3 个以上独立调用走批处理tasks[...]依赖任务跨轮串行并用write_todos维持计划综合与验证收集各子代理的返回结果用verification规则核对 Receipt 证据必要时派web_crawler复核verifiable_url按证据作答以数据而非假设回答用户并携带[n]引用标签详见 prompts/citations 与 shared/citations。结语identity/team.md看似只是几行身份声明实则是整个 SurfSense 多智能体编排系统的宪法它定义了主 Agent 的编排器角色、三大可调度资源、以数据为准的作答原则以及团队线程下的具名引用纪律。仓库源码则把这份声明落到了实处——compose.py 负责按顺序组装全部提示词片段sections/identity.py 按可见性切换身份变体并注入 UTC 日期task 工具及其路由规则支撑编排执行而 subagents/registry.py 动态生成子代理名册。理解这套身份提示词及其实现是深入 SurfSense 多智能体架构的最佳切入点——从一份提示词出发你可以沿 system_prompt/prompts 与 subagents/builtins 两个目录继续探索完整的编排生态。【免费下载链接】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），仅供参考