SurfSense YouTube 专家子代理深度解析从视频抓取到评论洞察的多智能体实现指南【免费下载链接】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 多智能体聊天系统中内置的YouTube 专家子代理YouTube Specialist为核心结合其职责定义文档、系统提示词、能力层注册与专有抓取引擎源码完整讲解该子代理的定位、触发时机、工具调用链、参数契约与底层实现原理。读完本文你将掌握如何在 SurfSense 中让 AI 代理按需拉取 YouTube 视频/频道/播放列表/Shorts/话题标签的结构化数据、获取评论与回复、并与对话早期结果做增量对比同时理解这套能力如何在无 API Key、无浏览器的约束下通过 InnerTube 协议与住宅代理实现。子代理的定位多智能体编排中的 YouTube 数据采集专家SurfSense 的聊天系统采用监督者supervisor多个子代理subagent的 deepagents 编排架构。每个内置子代理都有三份配套文件description.md职责描述供监督者做路由决策、system_prompt.md完整的运行指令、以及agent.py装配代码。YouTube 专家子代理的三份文件位于 surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/youtube/ 目录下。其职责定义文档 description.md 是子代理的名片——它明确写明了该子代理的能力边界与触发条件能力范围从 YouTube 拉取结构化数据覆盖视频、频道、播放列表、Shorts、话题标签hashtag五类目标字段包括标题title、观看数views、点赞数likes、发布日期、频道信息、描述以及可选的字幕subtitles支持按搜索词查找视频并可抓取单个视频的评论与回复comments and replies。比较能力将最新抓取的 YouTube 数据与本次对话中更早的发现进行对比输出增量差异。触发时机只要任务涉及 YouTube 内容或出现youtube.com/youtu.be链接就应启用。典型触发语句包括get this YouTube video/channel/playlist获取这个视频/频道/播放列表、find videos about X on YouTube在 YouTube 上找关于 X 的视频、how many views/likes多少观看/点赞、get the transcript/subtitles获取转录/字幕、get the comments on this video获取视频评论、what are people saying about this video大家怎么评价这个视频以及与对话中更早的 YouTube 结果做对比。边界普通网页不属于该子代理职责非 YouTube 的 URL 应交由专门的 Web 爬虫子代理web crawling specialist处理。从源码装配逻辑看agent.py 中的build_subagent()会通过read_md_file(__package__, description)读取上述 description 内容并作为description字段传入pack_subagent()最终进入 deepagents 的SubAgent规范见 spec.py。这意味着监督者完全依据这份 description 文本决定何时把任务委托给该子代理——文档即路由依据。装配原理工具加载、权限规则与提示词拼接agent.py的装配逻辑清晰地展示了子代理的三大构成tools [*load_tools(dependenciesdependencies), *(mcp_tools or [])] description read_md_file(__package__, description).strip() or \ Pulls structured data from YouTube videos, channels, playlists, and comments. system_prompt read_md_file(__package__, system_prompt).strip() return pack_subagent( nameNAME, descriptiondescription, system_promptsystem_prompt, toolstools, rulesetRULESET, dependenciesdependencies, modelmodel, middleware_stackmiddleware_stack, )对应的工具装配文件 tools/index.py 定义了三个关键常量NAME youtube子代理在注册表中的唯一标识。RULESET Ruleset(originNAME, rules[])该子代理的权限规则集目前为空即不主动追加审批规则由统一的 PermissionMiddleware 兜底。_CI_VERBS [YOUTUBE_SCRAPE, YOUTUBE_COMMENTS]两个核心能力动词最终通过build_capability_tools(workspace_id..., capabilities_CI_VERBS)转换成可被 LLM 调用的BaseTool。此外如果调用方注入了 MCP 工具也会一并挂载到该子代理上。在 subagent_builder.py 的pack_subagent()中系统提示词还会经历两个预处理步骤include snippet.../指令展开system_prompt.md中的include snippetrun_reader/、include snippetoutput_contract_base/等占位符会被替换为 shared/snippets/ 目录下的共享片段内容。未知的 snippet 名会直接抛错避免提示词残缺。追加当前 UTC 日期append_today_utc()会在编译期把Today (UTC): ...追加到提示词尾部使子代理与主代理共享同一时钟避免日期过滤类查询猜错日期。工具权限采用每个子代理独立的 PermissionMiddlewareSurfSense 默认allow */*规则打底叠加本子代理的ruleset最后叠加用户为该子代理持久化的始终允许Always Allow白名单规则实现无需重复确认的授权体验。运行指令System Prompt全解从目标到结构化输出system_prompt.md 是子代理行为的完整契约其结构对理解代理设计极具参考价值Goal目标Answer the delegated question from live YouTube data gathered with your verbs, comparing against earlier results already in this conversation when the task calls for it.子代理的一切行为都围绕用实时数据回答被委托的问题并且在任务要求时与对话中已有结果做对比。Available Tools可用工具工具用途youtube_scrape抓取视频/频道/播放列表/Shorts/话题页的结构化数据youtube_comments抓取指定视频的评论与回复read_run/search_run分页读取、正则检索已存储的抓取结果runPlaybook行动手册已知链接视频/频道/播放列表/Shorts/话题标签调用youtube_scrape把链接放进urls参数。按主题找视频调用youtube_scrape传入search_queries。针对特定视频的评论/舆情调用youtube_comments传入视频urls。批量优先把多个 URL 或查询合并进一次调用而不是多次单条调用这与下文MAX_YOUTUBE_SOURCES 20的设计相呼应。多视频评论分析的关键纪律批量评论结果按视频顺序列出截断预览通常只显示第一个或前几个视频。在汇总之前必须通过read_run分页或按视频 id 用search_run把每一个视频的真实评论都读出来——绝不能用一个视频的舆情推断另一个视频也绝不能在评论明明还躺在 run 里没读的情况下把某个视频报告为数据有限。对比请求拉取当前值与对话中更早的工具结果对比报告具体增量新增、删除、旧值 → 新值。Tool Policy工具使用策略只使用available_tools中列出的工具。一个条目status不是success就意味着没取到数据——应如实报告不可用绝不虚构。只报告能在证据中指出的增量严禁编造事实、数量、引语或 URL。Out of Scope职责边界不生成交付物deliverables不做连接器变更只把发现返回给监督者去决策。非 YouTube 网页属于 web 爬虫子代理。Safety安全要求证据不完整或矛盾时明确报告不确定性。绝不把未经验证的说法当作事实。Failure Policy失败处理场景返回请求信息不足无可用 URL 或搜索词statusblocked附缺失字段missing_fields工具调用失败statuserror附简明的恢复建议next_step没有可用证据statusblocked附更窄的查询词或仍需要的 URLOutput Contract输出契约子代理只允许返回一个 JSON 对象不得输出 Markdown 或散文结构如下{ status: success | partial | blocked | error, action_summary: string, evidence: { findings: [string, ...], sources: [string, ...], confidence: high | medium | low }, next_step: string | null, missing_fields: [string, ...] | null, assumptions: [string, ...] | null }路由级细则来自include snippetoutput_contract_base/展开后的共享契约evidence.findings最多 10 条每条一句话陈述一个独立事实或增量禁止粘贴原始载荷。evidence.sources最多 10 个 URL与 findings 尽量一一对应每个 URL 只列一次。这套结构化 JSON 回传监督者统一合成的机制正是多智能体系统中保证子代理输出可被可靠解析的关键设计。能力层实现youtube.scrape 与 youtube.comments 两个动词工具层并非直接调用抓取函数而是经由 SurfSense 的capability能力注册体系。两个动词分别注册在 app/capabilities/youtube/scrape/definition.py 与 app/capabilities/youtube/comments/ 下。youtube.scrape 动词注册定义definition.pyYOUTUBE_SCRAPE Capability( nameyoutube.scrape, description( Scrape public YouTube videos, channels, playlists, and subtitles. Use urls or search_queries. ), input_schemaScrapeInput, output_schemaScrapeOutput, executorbuild_scrape_executor(), billing_unitBillingUnit.YOUTUBE_VIDEO, docs_url/docs/connectors/native/youtube, )其输入输出契约定义在 schemas.py关键参数如下参数类型/取值默认值说明urlslist[URL]最多 20 个[]要抓取的 YouTube URL视频、频道handle或/channel/UC...、播放列表?list...、Shorts、话题页。与search_queries二选一至少提供一个search_querieslist[str]最多 20 个[]在 YouTube 上执行的搜索词每个搜索词最多返回max_results条视频max_resultsint1–100010每个来源、每种内容类型的最大条目数频道场景下视频/Shorts/直播各自独立封顶download_subtitlesboolfalse是否同时抓取每个视频的字幕轨道更慢、请求更多subtitles_languagestren字幕语言代码如en、fr仅在download_subtitlestrue时生效该 Schema 有一个内置校验器_require_a_sourceurls与search_queries全为空时直接抛错保证每次调用都有明确的抓取目标。值得注意的还有estimated_units属性——由于频道来源的max_results会独立作用于视频、Shorts、直播三种内容单个来源最多可能产出3 × max_results条结果因此预扣费估算采用(urls queries) × max_results × 3的保守算法确保永不出现负数余额的计费不变量。执行器executor.py把能力层的简洁输入映射为底层抓取引擎的完整输入actor_input YouTubeScrapeInput( startUrls[{url: url} for url in payload.urls], searchQueriespayload.search_queries, maxResultspayload.max_results, maxResultsShortspayload.max_results, maxResultStreamspayload.max_results, downloadSubtitlespayload.download_subtitles, subtitlesLanguagepayload.subtitles_language, )关键设计把同一个max_results同时赋给普通视频、Shorts、直播三个独立上限从而让频道抓取不会静默退化成只抓普通视频。执行过程还会通过emit_progress向前端推送Resolving YouTube targets → Scraped N video(s)的进度事件。youtube.comments 动词评论动词的输入契约comments/schemas.py参数类型/取值默认值说明urlslist[URL]1–20 个—要抓取评论的视频 URL只接受视频 URLmax_commentsint1–10000020每个视频返回的最大条目数同时计入顶层评论与回复sort_byTOP_COMMENTS|NEWEST_FIRSTNEWEST_FIRST评论排序按最多点赞或按最新执行器把max_comments映射到底层YouTubeCommentsInput.maxComments并把sort_by映射为 Apify 兼容的sortCommentsBy枚举随后通过emit_progress推送抓取进度。计费方面每条返回的评论/回复按一个计费单位计算billable_units len(items)。计费配置YouTube 抓取是按量计费的能力费率可在 surfsense_backend/app/config/init.py 中通过环境变量调整YOUTUBE_MICROS_PER_VIDEO默认2500每条视频/Shorts/直播的微积分单价。YOUTUBE_MICROS_PER_COMMENT默认1500每条评论/回复的单价与视频费率分离可独立调优源码注释指出这是为了对齐每条评论约 $0.40–2.00/1k的行业行情。总开关PLATFORM_SCRAPE_BILLING_ENABLED默认关闭控制整个平台抓取计费是否生效。底层抓取引擎无 API Key 的 YouTube 数据管道能力层的 executor 最终把调用转发到专有抓取引擎 app/proprietary/platforms/youtube/其架构完整记录在 README.md 中。核心设计如下协议与降级路径该引擎是 Apify YouTube Scraper 与 YouTube Comments Scraper actor 的同构克隆——同样的输入面、同样的输出条目形状camelCase 命名、extraallow开放契约。它直接与 YouTube 内部的InnerTubeAPI 对话辅以公开的 watch/channel 页面 HTML 解析不需要 API Key、不需要 Apify 账号快乐路径上也不需要无头浏览器。所有网络 I/O 集中在innertube.py的fetch_htmlGET 视频/频道页与post_innertubePOST InnerTubebrowse/search/next两个入口。反封锁与可靠性设计4 条铁律仅走代理出口每个请求都经过住宅代理app/utils/proxy.get_proxy_url绝不直连服务器 IP避免暴露与封禁。会话复用粘性 IP单个流程续页链或一个 worker 拉取的任务序列复用同一个 keep-aliveFetcherSession可将暖延迟从约 2.1s 降到约 1.0s只有首个请求付出 TCPTLS 握手成本并把出口 IP 固定在同一住宅节点上。被动式 IP 轮换粘性 IP 一直用到真正被封——遇到403/429或连接错误才轮换到新 IP 并重试最多_MAX_ROTATIONS3次。实测单 IP 连续 120 个请求零封禁因此采用被动轮换而非主动轮换。浏览器兜底若代理通道在 HTML 页面上全部失败fetch_html会降级到StealthyFetcher无头浏览器solve_cloudflareTrue需预先安装 patchright 浏览器。注意年龄限制内容需要登录无法绕过。会话通过ContextVar_current_session绑定到当前异步任务因此每个并发流程都透明地使用自己独立的会话与 IP解析器和编排器无需逐层传递会话参数。并发模型独立任务——每个startUrl、每个searchQuery、每个评论视频——通过fan_out热 worker 池_FANOUT_CONCURRENCY 16并发执行每个 worker 只开一个代理会话并在其拉取的顺序任务间复用只有首个任务支付握手成本。坏任务静默失败而非拖垮整批单个死 URL 或关闭评论的视频不会终止整个 runper-job try/except。结果按完成顺序流式产出在单个流程内部续页仍保持顺序分页。消费方提前停止时worker 会被取消并await保证每个会话的finally都能关闭不泄漏 keep-alive 连接。评论回复线程在同一多路复用会话上通过asyncio.gather并发抓取受剩余预算上限约束。五类数据流目标类型数据流视频URLfetch watch HTML →parse_video_page读取ytInitialDataytInitialPlayerResponse→ 可选字幕与翻译搜索InnerTube/search可叠加sp过滤 protobuf→ 续页 token 分页至maxResults频道先取 videos-tab 种子页元数据可复用About 面板走/browse再独立分页videos/shorts/streams三个 tab各自按maxResults/maxResultsShorts/maxResultStreams封顶sortVideosBy使用排序 chipsoldestPostDate做按日截止播放列表/browseVLid→ 续页 token 分页 → 每个视频再走视频流程话题标签专门的/hashtag/tag页面feed 是videoRendererlockups按搜索方式解析并非#tag搜索评论流程watch HTML 播种评论区 token →/next返回评论实体、每个线程的回复 token 与页 token。maxComments会计入每一个产出的条目评论回复。一个已知的工程取舍视频抓取器的VideoItem.commentsCount来自 search/watch HTML常常为null——补全它需要额外一次/next调用为了保持视频路径的廉价性刻意不做。输出条目VideoItem / CommentItemVideoItem覆盖了 description.md 中承诺的所有字段title/id/url/viewCount/date/duration/typevideo/shorts/stream/thumbnailUrl/text描述/descriptionLinks/hashtags/likes/commentsCount/location/collaborators/translatedTitle/translatedText/subtitles/频道字段channelName、channelUrl、channelUsername、channelId、numberOfSubscribers、channelTotalVideos、channelTotalViews、channelDescription、isChannelVerified、channelBannerUrl、channelAvatarUrl等。CommentItem则包含cid/comment/author/typecomment/reply/replyToCid/replyCount/voteCount/authorIsChannelOwner/hasCreatorHeart/publishedTimeText/videoId/commentsCount等字段。Run 读取机制大结果集如何不撑爆上下文YouTube 批量抓取动辄产生数百上千条结果若全部灌入 LLM 上下文必然爆掉。SurfSense 的解法是**存起来按需读**抓取能力输出被完整存入 Postgresruns/tool_output_spills表模型只能看到一份带上限的预览加上run_uuid/spill_uuid引用需要更多数据时再调用读取工具。这一机制实现在 run_reader.py即 system_prompt 中include snippetrun_reader/展开的内容提供三个工具read_run按行分页读取存储的 run支持offset/limit行级分页与char_offset字符级分页超大 JSON 行可达数百 kB只返回匹配窗口配合char_offset续读。所有查询都限定在调用方的工作区信任边界。search_run对存储的 JSONL 做子串或正则检索带 ReDoS 防护超长模式自动降级为子串匹配只返回匹配行及其行号比整读便宜得多。export_run把存储条目在代码内确定性地转成 CSV支持rowsitems按条目、rowslinks展开嵌套链接记录并作为工作区文档保存——数百行数据完全不经过模型。硬性行数上限_EXPORT_MAX_ROWS 20_000相同行自动去重。这正是 system_prompt 中多视频评论分析前必须分页读完每一个视频的真实评论这一纪律的底层支撑截断的预览可以靠read_run/search_run无限补全模型没有理由偷懒。验证与测试如何确保 YouTube 能力可靠该模块有完整的测试与验证体系见 app/proprietary/platforms/youtube/README.md 的 Testing 一节离线单元测试无网络每次改动必跑cd surfsense_backend .venv/Scripts/python.exe -m pytest tests/unit/scrapers/youtube/test_parsers.py解析/归一化、sp过滤 protobuf、URL 分类器基于手工构造与真实抓取的 fixtures 断言。test_fetch_resilience.py确定性地测试被封即轮换429/错误 → 轮换 → 200、轮换次数耗尽、404 不轮换、StealthyFetcher 兜底以及fan_out早停不泄漏会话的保证全部使用桩会话。实时功能验证需要真实网络可选代理凭据.venv/Scripts/python.exe scripts/e2e_youtube_scraper.py端到端覆盖视频/搜索/频道/评论/位置/协作者/翻译流程并把抓取结果重新生成为离线测试的 fixturestests/unit/scrapers/youtube/fixtures/。已知边界与扩展指南从源码注释README 中以ponytail:标记可以确认以下已知天花板使用时应心中有数话题页深度有限hashtag 抓取只返回单一 feed 页约 20–35 个视频该路径上 YouTube 不暴露续页 token需要更深的覆盖时可降级走#tag搜索路由。播放列表顺序播放列表视频 id 按序分页但每个视频的 watch-page 抓取经fan_out并发执行因此条目按完成顺序流回而非播放列表顺序——如需还原顺序按order字段排序即可约 150 个视频耗时约 70s。日期截止是日级精度oldestPostDate/oldestCommentDate最多精确到天频道/列表页只暴露如2 years ago的粗粒度相对时间。视频路径的commentsCount常为null如需权威评论总数应使用评论抓取器其commentsCount来自评论区头部的commentsHeaderRenderer.countText而非 watch 页懒加载字段。扩展方式Extending it一节新增输出字段 → 在parsers.py相应函数填充并登记到schemas.py输出为extraallow漏登记不会丢值但会丢失契约文档新增 URL 类型 → 扩展url_resolver.resolve_url 在scraper.py增加_*_flow与_dispatch分支新增搜索过滤 → 在YouTubeScrapeInput加字段并在search_filters.build_search_params中编码需在单元测试中与真实sptoken 逐字节比对。结语从职责文档到生产级抓取管线的完整链路回顾整条调用链监督者读取description.md做路由 → 系统提示词约束行为与输出 → 工具层把youtube.scrape/youtube.comments两个 capability 动词暴露给 LLM → 能力层做参数校验、进度上报与计费 → 专有引擎通过 InnerTube住宅代理并发 worker 池完成抓取 → 大结果集落入 run 存储由read_run/search_run/export_run按需读取。每个环节都有对应的源码、配置与测试支撑构成了一个既能在多智能体对话中被可靠驱动又能在生产环境稳定扛住大规模抓取的 YouTube 数据采集闭环。对希望在自己项目中复刻类似子代理平台抓取能力架构的开发者而言这套从职责文档到引擎实现的完整模板极具参考价值。【免费下载链接】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），仅供参考
SurfSense YouTube 专家子代理深度解析从视频抓取到评论洞察的多智能体实现指南【免费下载链接】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 多智能体聊天系统中内置的YouTube 专家子代理YouTube Specialist为核心结合其职责定义文档、系统提示词、能力层注册与专有抓取引擎源码完整讲解该子代理的定位、触发时机、工具调用链、参数契约与底层实现原理。读完本文你将掌握如何在 SurfSense 中让 AI 代理按需拉取 YouTube 视频/频道/播放列表/Shorts/话题标签的结构化数据、获取评论与回复、并与对话早期结果做增量对比同时理解这套能力如何在无 API Key、无浏览器的约束下通过 InnerTube 协议与住宅代理实现。子代理的定位多智能体编排中的 YouTube 数据采集专家SurfSense 的聊天系统采用监督者supervisor多个子代理subagent的 deepagents 编排架构。每个内置子代理都有三份配套文件description.md职责描述供监督者做路由决策、system_prompt.md完整的运行指令、以及agent.py装配代码。YouTube 专家子代理的三份文件位于 surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/youtube/ 目录下。其职责定义文档 description.md 是子代理的名片——它明确写明了该子代理的能力边界与触发条件能力范围从 YouTube 拉取结构化数据覆盖视频、频道、播放列表、Shorts、话题标签hashtag五类目标字段包括标题title、观看数views、点赞数likes、发布日期、频道信息、描述以及可选的字幕subtitles支持按搜索词查找视频并可抓取单个视频的评论与回复comments and replies。比较能力将最新抓取的 YouTube 数据与本次对话中更早的发现进行对比输出增量差异。触发时机只要任务涉及 YouTube 内容或出现youtube.com/youtu.be链接就应启用。典型触发语句包括get this YouTube video/channel/playlist获取这个视频/频道/播放列表、find videos about X on YouTube在 YouTube 上找关于 X 的视频、how many views/likes多少观看/点赞、get the transcript/subtitles获取转录/字幕、get the comments on this video获取视频评论、what are people saying about this video大家怎么评价这个视频以及与对话中更早的 YouTube 结果做对比。边界普通网页不属于该子代理职责非 YouTube 的 URL 应交由专门的 Web 爬虫子代理web crawling specialist处理。从源码装配逻辑看agent.py 中的build_subagent()会通过read_md_file(__package__, description)读取上述 description 内容并作为description字段传入pack_subagent()最终进入 deepagents 的SubAgent规范见 spec.py。这意味着监督者完全依据这份 description 文本决定何时把任务委托给该子代理——文档即路由依据。装配原理工具加载、权限规则与提示词拼接agent.py的装配逻辑清晰地展示了子代理的三大构成tools [*load_tools(dependenciesdependencies), *(mcp_tools or [])] description read_md_file(__package__, description).strip() or \ Pulls structured data from YouTube videos, channels, playlists, and comments. system_prompt read_md_file(__package__, system_prompt).strip() return pack_subagent( nameNAME, descriptiondescription, system_promptsystem_prompt, toolstools, rulesetRULESET, dependenciesdependencies, modelmodel, middleware_stackmiddleware_stack, )对应的工具装配文件 tools/index.py 定义了三个关键常量NAME youtube子代理在注册表中的唯一标识。RULESET Ruleset(originNAME, rules[])该子代理的权限规则集目前为空即不主动追加审批规则由统一的 PermissionMiddleware 兜底。_CI_VERBS [YOUTUBE_SCRAPE, YOUTUBE_COMMENTS]两个核心能力动词最终通过build_capability_tools(workspace_id..., capabilities_CI_VERBS)转换成可被 LLM 调用的BaseTool。此外如果调用方注入了 MCP 工具也会一并挂载到该子代理上。在 subagent_builder.py 的pack_subagent()中系统提示词还会经历两个预处理步骤include snippet.../指令展开system_prompt.md中的include snippetrun_reader/、include snippetoutput_contract_base/等占位符会被替换为 shared/snippets/ 目录下的共享片段内容。未知的 snippet 名会直接抛错避免提示词残缺。追加当前 UTC 日期append_today_utc()会在编译期把Today (UTC): ...追加到提示词尾部使子代理与主代理共享同一时钟避免日期过滤类查询猜错日期。工具权限采用每个子代理独立的 PermissionMiddlewareSurfSense 默认allow */*规则打底叠加本子代理的ruleset最后叠加用户为该子代理持久化的始终允许Always Allow白名单规则实现无需重复确认的授权体验。运行指令System Prompt全解从目标到结构化输出system_prompt.md 是子代理行为的完整契约其结构对理解代理设计极具参考价值Goal目标Answer the delegated question from live YouTube data gathered with your verbs, comparing against earlier results already in this conversation when the task calls for it.子代理的一切行为都围绕用实时数据回答被委托的问题并且在任务要求时与对话中已有结果做对比。Available Tools可用工具工具用途youtube_scrape抓取视频/频道/播放列表/Shorts/话题页的结构化数据youtube_comments抓取指定视频的评论与回复read_run/search_run分页读取、正则检索已存储的抓取结果runPlaybook行动手册已知链接视频/频道/播放列表/Shorts/话题标签调用youtube_scrape把链接放进urls参数。按主题找视频调用youtube_scrape传入search_queries。针对特定视频的评论/舆情调用youtube_comments传入视频urls。批量优先把多个 URL 或查询合并进一次调用而不是多次单条调用这与下文MAX_YOUTUBE_SOURCES 20的设计相呼应。多视频评论分析的关键纪律批量评论结果按视频顺序列出截断预览通常只显示第一个或前几个视频。在汇总之前必须通过read_run分页或按视频 id 用search_run把每一个视频的真实评论都读出来——绝不能用一个视频的舆情推断另一个视频也绝不能在评论明明还躺在 run 里没读的情况下把某个视频报告为数据有限。对比请求拉取当前值与对话中更早的工具结果对比报告具体增量新增、删除、旧值 → 新值。Tool Policy工具使用策略只使用available_tools中列出的工具。一个条目status不是success就意味着没取到数据——应如实报告不可用绝不虚构。只报告能在证据中指出的增量严禁编造事实、数量、引语或 URL。Out of Scope职责边界不生成交付物deliverables不做连接器变更只把发现返回给监督者去决策。非 YouTube 网页属于 web 爬虫子代理。Safety安全要求证据不完整或矛盾时明确报告不确定性。绝不把未经验证的说法当作事实。Failure Policy失败处理场景返回请求信息不足无可用 URL 或搜索词statusblocked附缺失字段missing_fields工具调用失败statuserror附简明的恢复建议next_step没有可用证据statusblocked附更窄的查询词或仍需要的 URLOutput Contract输出契约子代理只允许返回一个 JSON 对象不得输出 Markdown 或散文结构如下{ status: success | partial | blocked | error, action_summary: string, evidence: { findings: [string, ...], sources: [string, ...], confidence: high | medium | low }, next_step: string | null, missing_fields: [string, ...] | null, assumptions: [string, ...] | null }路由级细则来自include snippetoutput_contract_base/展开后的共享契约evidence.findings最多 10 条每条一句话陈述一个独立事实或增量禁止粘贴原始载荷。evidence.sources最多 10 个 URL与 findings 尽量一一对应每个 URL 只列一次。这套结构化 JSON 回传监督者统一合成的机制正是多智能体系统中保证子代理输出可被可靠解析的关键设计。能力层实现youtube.scrape 与 youtube.comments 两个动词工具层并非直接调用抓取函数而是经由 SurfSense 的capability能力注册体系。两个动词分别注册在 app/capabilities/youtube/scrape/definition.py 与 app/capabilities/youtube/comments/ 下。youtube.scrape 动词注册定义definition.pyYOUTUBE_SCRAPE Capability( nameyoutube.scrape, description( Scrape public YouTube videos, channels, playlists, and subtitles. Use urls or search_queries. ), input_schemaScrapeInput, output_schemaScrapeOutput, executorbuild_scrape_executor(), billing_unitBillingUnit.YOUTUBE_VIDEO, docs_url/docs/connectors/native/youtube, )其输入输出契约定义在 schemas.py关键参数如下参数类型/取值默认值说明urlslist[URL]最多 20 个[]要抓取的 YouTube URL视频、频道handle或/channel/UC...、播放列表?list...、Shorts、话题页。与search_queries二选一至少提供一个search_querieslist[str]最多 20 个[]在 YouTube 上执行的搜索词每个搜索词最多返回max_results条视频max_resultsint1–100010每个来源、每种内容类型的最大条目数频道场景下视频/Shorts/直播各自独立封顶download_subtitlesboolfalse是否同时抓取每个视频的字幕轨道更慢、请求更多subtitles_languagestren字幕语言代码如en、fr仅在download_subtitlestrue时生效该 Schema 有一个内置校验器_require_a_sourceurls与search_queries全为空时直接抛错保证每次调用都有明确的抓取目标。值得注意的还有estimated_units属性——由于频道来源的max_results会独立作用于视频、Shorts、直播三种内容单个来源最多可能产出3 × max_results条结果因此预扣费估算采用(urls queries) × max_results × 3的保守算法确保永不出现负数余额的计费不变量。执行器executor.py把能力层的简洁输入映射为底层抓取引擎的完整输入actor_input YouTubeScrapeInput( startUrls[{url: url} for url in payload.urls], searchQueriespayload.search_queries, maxResultspayload.max_results, maxResultsShortspayload.max_results, maxResultStreamspayload.max_results, downloadSubtitlespayload.download_subtitles, subtitlesLanguagepayload.subtitles_language, )关键设计把同一个max_results同时赋给普通视频、Shorts、直播三个独立上限从而让频道抓取不会静默退化成只抓普通视频。执行过程还会通过emit_progress向前端推送Resolving YouTube targets → Scraped N video(s)的进度事件。youtube.comments 动词评论动词的输入契约comments/schemas.py参数类型/取值默认值说明urlslist[URL]1–20 个—要抓取评论的视频 URL只接受视频 URLmax_commentsint1–10000020每个视频返回的最大条目数同时计入顶层评论与回复sort_byTOP_COMMENTS|NEWEST_FIRSTNEWEST_FIRST评论排序按最多点赞或按最新执行器把max_comments映射到底层YouTubeCommentsInput.maxComments并把sort_by映射为 Apify 兼容的sortCommentsBy枚举随后通过emit_progress推送抓取进度。计费方面每条返回的评论/回复按一个计费单位计算billable_units len(items)。计费配置YouTube 抓取是按量计费的能力费率可在 surfsense_backend/app/config/init.py 中通过环境变量调整YOUTUBE_MICROS_PER_VIDEO默认2500每条视频/Shorts/直播的微积分单价。YOUTUBE_MICROS_PER_COMMENT默认1500每条评论/回复的单价与视频费率分离可独立调优源码注释指出这是为了对齐每条评论约 $0.40–2.00/1k的行业行情。总开关PLATFORM_SCRAPE_BILLING_ENABLED默认关闭控制整个平台抓取计费是否生效。底层抓取引擎无 API Key 的 YouTube 数据管道能力层的 executor 最终把调用转发到专有抓取引擎 app/proprietary/platforms/youtube/其架构完整记录在 README.md 中。核心设计如下协议与降级路径该引擎是 Apify YouTube Scraper 与 YouTube Comments Scraper actor 的同构克隆——同样的输入面、同样的输出条目形状camelCase 命名、extraallow开放契约。它直接与 YouTube 内部的InnerTubeAPI 对话辅以公开的 watch/channel 页面 HTML 解析不需要 API Key、不需要 Apify 账号快乐路径上也不需要无头浏览器。所有网络 I/O 集中在innertube.py的fetch_htmlGET 视频/频道页与post_innertubePOST InnerTubebrowse/search/next两个入口。反封锁与可靠性设计4 条铁律仅走代理出口每个请求都经过住宅代理app/utils/proxy.get_proxy_url绝不直连服务器 IP避免暴露与封禁。会话复用粘性 IP单个流程续页链或一个 worker 拉取的任务序列复用同一个 keep-aliveFetcherSession可将暖延迟从约 2.1s 降到约 1.0s只有首个请求付出 TCPTLS 握手成本并把出口 IP 固定在同一住宅节点上。被动式 IP 轮换粘性 IP 一直用到真正被封——遇到403/429或连接错误才轮换到新 IP 并重试最多_MAX_ROTATIONS3次。实测单 IP 连续 120 个请求零封禁因此采用被动轮换而非主动轮换。浏览器兜底若代理通道在 HTML 页面上全部失败fetch_html会降级到StealthyFetcher无头浏览器solve_cloudflareTrue需预先安装 patchright 浏览器。注意年龄限制内容需要登录无法绕过。会话通过ContextVar_current_session绑定到当前异步任务因此每个并发流程都透明地使用自己独立的会话与 IP解析器和编排器无需逐层传递会话参数。并发模型独立任务——每个startUrl、每个searchQuery、每个评论视频——通过fan_out热 worker 池_FANOUT_CONCURRENCY 16并发执行每个 worker 只开一个代理会话并在其拉取的顺序任务间复用只有首个任务支付握手成本。坏任务静默失败而非拖垮整批单个死 URL 或关闭评论的视频不会终止整个 runper-job try/except。结果按完成顺序流式产出在单个流程内部续页仍保持顺序分页。消费方提前停止时worker 会被取消并await保证每个会话的finally都能关闭不泄漏 keep-alive 连接。评论回复线程在同一多路复用会话上通过asyncio.gather并发抓取受剩余预算上限约束。五类数据流目标类型数据流视频URLfetch watch HTML →parse_video_page读取ytInitialDataytInitialPlayerResponse→ 可选字幕与翻译搜索InnerTube/search可叠加sp过滤 protobuf→ 续页 token 分页至maxResults频道先取 videos-tab 种子页元数据可复用About 面板走/browse再独立分页videos/shorts/streams三个 tab各自按maxResults/maxResultsShorts/maxResultStreams封顶sortVideosBy使用排序 chipsoldestPostDate做按日截止播放列表/browseVLid→ 续页 token 分页 → 每个视频再走视频流程话题标签专门的/hashtag/tag页面feed 是videoRendererlockups按搜索方式解析并非#tag搜索评论流程watch HTML 播种评论区 token →/next返回评论实体、每个线程的回复 token 与页 token。maxComments会计入每一个产出的条目评论回复。一个已知的工程取舍视频抓取器的VideoItem.commentsCount来自 search/watch HTML常常为null——补全它需要额外一次/next调用为了保持视频路径的廉价性刻意不做。输出条目VideoItem / CommentItemVideoItem覆盖了 description.md 中承诺的所有字段title/id/url/viewCount/date/duration/typevideo/shorts/stream/thumbnailUrl/text描述/descriptionLinks/hashtags/likes/commentsCount/location/collaborators/translatedTitle/translatedText/subtitles/频道字段channelName、channelUrl、channelUsername、channelId、numberOfSubscribers、channelTotalVideos、channelTotalViews、channelDescription、isChannelVerified、channelBannerUrl、channelAvatarUrl等。CommentItem则包含cid/comment/author/typecomment/reply/replyToCid/replyCount/voteCount/authorIsChannelOwner/hasCreatorHeart/publishedTimeText/videoId/commentsCount等字段。Run 读取机制大结果集如何不撑爆上下文YouTube 批量抓取动辄产生数百上千条结果若全部灌入 LLM 上下文必然爆掉。SurfSense 的解法是**存起来按需读**抓取能力输出被完整存入 Postgresruns/tool_output_spills表模型只能看到一份带上限的预览加上run_uuid/spill_uuid引用需要更多数据时再调用读取工具。这一机制实现在 run_reader.py即 system_prompt 中include snippetrun_reader/展开的内容提供三个工具read_run按行分页读取存储的 run支持offset/limit行级分页与char_offset字符级分页超大 JSON 行可达数百 kB只返回匹配窗口配合char_offset续读。所有查询都限定在调用方的工作区信任边界。search_run对存储的 JSONL 做子串或正则检索带 ReDoS 防护超长模式自动降级为子串匹配只返回匹配行及其行号比整读便宜得多。export_run把存储条目在代码内确定性地转成 CSV支持rowsitems按条目、rowslinks展开嵌套链接记录并作为工作区文档保存——数百行数据完全不经过模型。硬性行数上限_EXPORT_MAX_ROWS 20_000相同行自动去重。这正是 system_prompt 中多视频评论分析前必须分页读完每一个视频的真实评论这一纪律的底层支撑截断的预览可以靠read_run/search_run无限补全模型没有理由偷懒。验证与测试如何确保 YouTube 能力可靠该模块有完整的测试与验证体系见 app/proprietary/platforms/youtube/README.md 的 Testing 一节离线单元测试无网络每次改动必跑cd surfsense_backend .venv/Scripts/python.exe -m pytest tests/unit/scrapers/youtube/test_parsers.py解析/归一化、sp过滤 protobuf、URL 分类器基于手工构造与真实抓取的 fixtures 断言。test_fetch_resilience.py确定性地测试被封即轮换429/错误 → 轮换 → 200、轮换次数耗尽、404 不轮换、StealthyFetcher 兜底以及fan_out早停不泄漏会话的保证全部使用桩会话。实时功能验证需要真实网络可选代理凭据.venv/Scripts/python.exe scripts/e2e_youtube_scraper.py端到端覆盖视频/搜索/频道/评论/位置/协作者/翻译流程并把抓取结果重新生成为离线测试的 fixturestests/unit/scrapers/youtube/fixtures/。已知边界与扩展指南从源码注释README 中以ponytail:标记可以确认以下已知天花板使用时应心中有数话题页深度有限hashtag 抓取只返回单一 feed 页约 20–35 个视频该路径上 YouTube 不暴露续页 token需要更深的覆盖时可降级走#tag搜索路由。播放列表顺序播放列表视频 id 按序分页但每个视频的 watch-page 抓取经fan_out并发执行因此条目按完成顺序流回而非播放列表顺序——如需还原顺序按order字段排序即可约 150 个视频耗时约 70s。日期截止是日级精度oldestPostDate/oldestCommentDate最多精确到天频道/列表页只暴露如2 years ago的粗粒度相对时间。视频路径的commentsCount常为null如需权威评论总数应使用评论抓取器其commentsCount来自评论区头部的commentsHeaderRenderer.countText而非 watch 页懒加载字段。扩展方式Extending it一节新增输出字段 → 在parsers.py相应函数填充并登记到schemas.py输出为extraallow漏登记不会丢值但会丢失契约文档新增 URL 类型 → 扩展url_resolver.resolve_url 在scraper.py增加_*_flow与_dispatch分支新增搜索过滤 → 在YouTubeScrapeInput加字段并在search_filters.build_search_params中编码需在单元测试中与真实sptoken 逐字节比对。结语从职责文档到生产级抓取管线的完整链路回顾整条调用链监督者读取description.md做路由 → 系统提示词约束行为与输出 → 工具层把youtube.scrape/youtube.comments两个 capability 动词暴露给 LLM → 能力层做参数校验、进度上报与计费 → 专有引擎通过 InnerTube住宅代理并发 worker 池完成抓取 → 大结果集落入 run 存储由read_run/search_run/export_run按需读取。每个环节都有对应的源码、配置与测试支撑构成了一个既能在多智能体对话中被可靠驱动又能在生产环境稳定扛住大规模抓取的 YouTube 数据采集闭环。对希望在自己项目中复刻类似子代理平台抓取能力架构的开发者而言这套从职责文档到引擎实现的完整模板极具参考价值。【免费下载链接】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），仅供参考
