SurfSense 亚马逊子代理Amazon Sub-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/SurfSense导读本文围绕 SurfSense 多智能体聊天架构中的亚马逊子代理amazonsub-agent系统提示词展开完整解读其职责边界、amazon_scrape工具调用剧本playbook、参数语义、失败处理策略与严格的结构化输出契约output contract。通过对照仓库中的子代理构建代码、amazon.scrapecapability 的输入输出模型与底层爬虫实现你将掌握如何在 SurfSense 中让子代理完成商品调研、比价与购买框跟踪、评论挖掘、ASIN 目录补全、畅销榜监控等任务并理解多智能体系统如何通过提示词约束保证只汇报工具真实输出的可靠性。一、子代理在多智能体架构中的定位SurfSense 的多智能体聊天采用监督者supervisor— 子代理sub-agent的委派模式。亚马逊子代理是其中一个内置builtin子代理它接收来自监督者代理的委派指令并返回结构化结果供监督者综合见 system_prompt.md 开头。从构建代码看agent.py 通过SurfSenseSubagentSpec打包子代理description与system_prompt分别读取同目录下的description.md与system_prompt.md工具则来自 tools/index.py 中定义的amazon.scrapecapability。其职责描述description.md明确抓取公开的 Amazon 商品列表并返回结构化产品数据——标题、ASIN、品牌、价格与划线价、星级评分与评论分布、库存状态、图片、特性、畅销排名、商城报价、第三方卖家、商品变体以及页面内顾客评论。典型触发场景包括在 Amazon 上找 X、X 在 Amazon 的价格、这个 Amazon 商品的评论、比较这些 Amazon 商品、Amazon 上最畅销的 X、查一下这个 ASIN / Amazon URL。二、系统提示词的核心结构system_prompt.md采用清晰的 XML 风格标签组织共八个区块这是理解子代理行为的关键骨架区块作用goal定义子代理的根本目标基于公开 Amazon 商品数据回答委派问题任务要求比较时需与会话中已有的早期结果对比available_tools白名单工具声明amazon_scrape、read_run/search_runplaybook针对不同任务的参数使用剧本tool_policy工具使用红线out_of_scope明确不做什么safety不确定性的报告要求failure_policy三类失败场景的返回约定output_contract强制的 JSON 输出格式值得注意的是提示词通过include snippetrun_reader/与include snippetoutput_contract_base/内联了共享片段分别位于 run_reader.md 与 output_contract_base.md。这种基座提示词 共享片段的组装方式保证了所有子代理在长结果分页与输出契约上遵循同一套约定。三、Playbook 详解如何用参数驱动不同任务playbook是实战价值最高的部分它把任务意图映射为amazon_scrape的具体参数组合发现产品调用amazon_scrape并传入search_terms如[mechanical keyboard]当目标是非美国商城时设置domain如www.amazon.co.uk。指定商品在urls中传入 Amazon 商品页 URL也支持搜索、类目、畅销榜以及 a.co 短链接。快速列表模式设include_detailsfalse只返回卡片级结果不逐个打开商品页适合批量侦察。价格与购买框提高max_offers拉取更多商城报价设include_sellerstrue附带卖家档案。变体展开提高max_variants把变体作为独立结果返回设include_variant_pricestrue获取每个变体的独立价格。本地化定价/库存设置country_code与zip_code。批处理尽量在一次调用中批量传入多个 URL 或搜索词而不是多次单源调用。比较请求拉取当前商品与会话中先前工具结果对比报告具体增量价格涨跌、评分变化、排名移动、库存变化。四、amazon_scrape工具的输入契约amazon_scrape对应 definition.py 中注册的amazon.scrapecapability其完整字段定义在 schemas.py 的ScrapeInput中与提示词剧本一一对应字段类型/默认值约束说明urlslist[HttpUrlStr]默认[]最多 20 个商品/搜索/类目/畅销榜/a.co 短链接 URLsearch_termslist[str]默认[]最多 20 个搜索关键词max_itemsint默认101–100单次搜索词最多返回的商品数domainstr默认www.amazon.com正则^(?:www\.)?amazon\.[a-z.]$商城域名languagestr \| None—页面语言country_codestr \| None2 个字符本地化定价/库存的国家码zip_codestr \| None1–20 个字符本地化交付的邮编include_detailsbool默认True—是否打开商品页取详情max_offersint默认00–100额外拉取的商城报价数include_sellersbool默认False—是否附带卖家档案max_variantsint默认00–100变体作为独立结果的条数include_variant_pricesbool默认False—是否抓取逐变体价格模型校验器强制两条规则至少提供urls或search_terms之一两者合并数量不得超过MAX_AMAZON_SOURCES 20这正是提示词中cannot be combined arbitrarily beyond the source cap的来源。estimated_units属性估算最坏情况返回量len(search_terms) * max_items len(urls) * (1 max_variants)并封顶于MAX_AMAZON_RESULTS 1000。参数到底层爬虫的映射见 executor.pyinclude_details→scrapeProductDetails、max_offers→maxOffers、include_sellers→scrapeSellers、max_variants→maxProductVariantsAsSeparateResults、include_variant_prices→scrapeProductVariantPrices、country_code/zip_code→countryCode/zipCode。该 capability 按BillingUnit.AMAZON_PRODUCT计费且 ScrapeOutput.billable_units 只统计成功商品——报错条目不产生计费。五、长结果分页read_run/search_run当工具结果过大时完整结果会被存储只展示一个以run_uuid结尾的预览见 run_reader.md。共享片段强制约定禁止为了看更多内容而重跑工具用read_run(ref, offset, limit)对已存储的 run 分页每行是一个 JSON 结果项用search_run(ref, pattern)在 run 内做正则过滤若单条结果本身超出响应长度保持offset在该行并继续用char_offset深入截断提示会给出下一个值。这套机制既避免重复抓取省成本、防风控又让子代理能完整消费大数据集。六、严格的输出契约Output 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 }亚马逊路由专属规则evidence.findings最多 10 条每条必须是单句陈述一个独立商品或一个 delta禁止粘贴原始载荷evidence.sources最多 10 个 URL与 findings 对应每个 URL 只列一次。共享片段 output_contract_base.md 补充了全局规则statussuccess时next_step与missing_fields必须为nullstatuspartial|blocked|error时next_step必须非空next_step仅用于你自己无法执行的动作——如果下一步本是调用自己的工具如用read_run/search_run分页、调整参数重跑应立即执行并汇报改进后的结果而不是返回partial因缺少必需输入而blocked时missing_fields必须非空assumptions记录对用户意图的推断无需推断时为nullevidence字段以路由专属契约为准禁止编造工具未返回的字段当结论来自爬虫 run 时必须把该 run 的[n]引用标签工具结果会标注Cite this scraper run as [n]原样追加到 finding 文本中保证引用能存活到最终答案——标签必须逐字复制不得自造。七、失败处理策略failure_policy定义了三种失败形态及对应状态码使监督者能机械地消费错误场景返回请求不明确无可用搜索词或 URLstatusblockedmissing_fields列出缺失字段工具失败statuserror附带简洁的恢复建议next_step没有可用证据statusblocked附带更窄的查询建议或仍需要的范围八、边界、安全与工具红线out_of_scope边界不做通用网页搜索——那是 Google Search 专家的职责不读取/抽取任意非 Amazon 页面——将 URL 转交给网页爬虫专家不生成交付物、不做 connector 变更——只返回发现由监督者决定行动只取公开、匿名的 Amazon 数据绝不触碰需要登录或卖家账号的内容。tool_policy工具红线只使用available_tools中列出的工具只汇报工具输出中实际存在的结果严禁编造标题、ASIN、价格、评分或排名必须至少提供urls或search_terms之一且二者合并不得超过来源上限。safety安全证据不完整或相互冲突时明确报告不确定性绝不把未经验证的说法当作事实陈述。这些约束在底层爬虫层面同样成立专有实现 README.md 明确声明爬虫只读取匿名访客可见的公开页面不登录、不使用账号 Cookie、不获取账号门控内容深度评论分页需要 Amazon 账号因此不在范围内页面内评论通过productPageReviews与productPageReviewsFromOtherCountries返回。九、底层实现架构与验证方式amazon.scrape的底层实现README.md分为五个职责清晰的模块schemas.py——稳定的输入、产品与错误模型url_resolver.py——分类商品、搜索、畅销榜与短链接 URLfetch.py——代理感知的 HTTP 访问、封禁检测、重试与匿名定位会话parsers.py——纯函数、防御式 HTML 解析器scraper.py——协调发现、富化、并发、限额与流内错误。验证方式离线单元测试覆盖每个解析器与流程cd surfsense_backend uv run pytest tests/unit/platforms/amazon tests/unit/capabilities/amazon另有 capability 注册测试 test_registry.py手动端到端检查需要网络与住宅代理凭据uv run python scripts/e2e_amazon_scraper.py。该脚本e2e_amazon_scraper.py会抓取一个商品详情页校验asin与title和一个搜索结果页校验卡片含asin与categoryPageData支持--refresh-fixtures用实时响应刷新解析器测试固件。结语SurfSense 亚马逊子代理的系统提示词展示了一套可复用的多智能体工程范式用 XML 标签把目标—工具—剧本—红线—失败策略—输出契约显式化用共享片段统一长结果分页与输出约定用 capability 层amazon.scrape把提示词参数与真实爬虫能力一一绑定并通过仅汇报工具真实输出 强制 JSON 契约 失败状态码化三管齐下保证监督者能得到可靠、可综合、可计费的结构化证据。理解这份提示词就理解了 SurfSense 如何把开放网络的商品数据安全地转化为可供 LLM 综合的结构化研究素材。【免费下载链接】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 亚马逊子代理（Amazon Sub-agent）系统提示词深度解析：从搜索词到结构化产品证据
SurfSense 亚马逊子代理Amazon Sub-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/SurfSense导读本文围绕 SurfSense 多智能体聊天架构中的亚马逊子代理amazonsub-agent系统提示词展开完整解读其职责边界、amazon_scrape工具调用剧本playbook、参数语义、失败处理策略与严格的结构化输出契约output contract。通过对照仓库中的子代理构建代码、amazon.scrapecapability 的输入输出模型与底层爬虫实现你将掌握如何在 SurfSense 中让子代理完成商品调研、比价与购买框跟踪、评论挖掘、ASIN 目录补全、畅销榜监控等任务并理解多智能体系统如何通过提示词约束保证只汇报工具真实输出的可靠性。一、子代理在多智能体架构中的定位SurfSense 的多智能体聊天采用监督者supervisor— 子代理sub-agent的委派模式。亚马逊子代理是其中一个内置builtin子代理它接收来自监督者代理的委派指令并返回结构化结果供监督者综合见 system_prompt.md 开头。从构建代码看agent.py 通过SurfSenseSubagentSpec打包子代理description与system_prompt分别读取同目录下的description.md与system_prompt.md工具则来自 tools/index.py 中定义的amazon.scrapecapability。其职责描述description.md明确抓取公开的 Amazon 商品列表并返回结构化产品数据——标题、ASIN、品牌、价格与划线价、星级评分与评论分布、库存状态、图片、特性、畅销排名、商城报价、第三方卖家、商品变体以及页面内顾客评论。典型触发场景包括在 Amazon 上找 X、X 在 Amazon 的价格、这个 Amazon 商品的评论、比较这些 Amazon 商品、Amazon 上最畅销的 X、查一下这个 ASIN / Amazon URL。二、系统提示词的核心结构system_prompt.md采用清晰的 XML 风格标签组织共八个区块这是理解子代理行为的关键骨架区块作用goal定义子代理的根本目标基于公开 Amazon 商品数据回答委派问题任务要求比较时需与会话中已有的早期结果对比available_tools白名单工具声明amazon_scrape、read_run/search_runplaybook针对不同任务的参数使用剧本tool_policy工具使用红线out_of_scope明确不做什么safety不确定性的报告要求failure_policy三类失败场景的返回约定output_contract强制的 JSON 输出格式值得注意的是提示词通过include snippetrun_reader/与include snippetoutput_contract_base/内联了共享片段分别位于 run_reader.md 与 output_contract_base.md。这种基座提示词 共享片段的组装方式保证了所有子代理在长结果分页与输出契约上遵循同一套约定。三、Playbook 详解如何用参数驱动不同任务playbook是实战价值最高的部分它把任务意图映射为amazon_scrape的具体参数组合发现产品调用amazon_scrape并传入search_terms如[mechanical keyboard]当目标是非美国商城时设置domain如www.amazon.co.uk。指定商品在urls中传入 Amazon 商品页 URL也支持搜索、类目、畅销榜以及 a.co 短链接。快速列表模式设include_detailsfalse只返回卡片级结果不逐个打开商品页适合批量侦察。价格与购买框提高max_offers拉取更多商城报价设include_sellerstrue附带卖家档案。变体展开提高max_variants把变体作为独立结果返回设include_variant_pricestrue获取每个变体的独立价格。本地化定价/库存设置country_code与zip_code。批处理尽量在一次调用中批量传入多个 URL 或搜索词而不是多次单源调用。比较请求拉取当前商品与会话中先前工具结果对比报告具体增量价格涨跌、评分变化、排名移动、库存变化。四、amazon_scrape工具的输入契约amazon_scrape对应 definition.py 中注册的amazon.scrapecapability其完整字段定义在 schemas.py 的ScrapeInput中与提示词剧本一一对应字段类型/默认值约束说明urlslist[HttpUrlStr]默认[]最多 20 个商品/搜索/类目/畅销榜/a.co 短链接 URLsearch_termslist[str]默认[]最多 20 个搜索关键词max_itemsint默认101–100单次搜索词最多返回的商品数domainstr默认www.amazon.com正则^(?:www\.)?amazon\.[a-z.]$商城域名languagestr \| None—页面语言country_codestr \| None2 个字符本地化定价/库存的国家码zip_codestr \| None1–20 个字符本地化交付的邮编include_detailsbool默认True—是否打开商品页取详情max_offersint默认00–100额外拉取的商城报价数include_sellersbool默认False—是否附带卖家档案max_variantsint默认00–100变体作为独立结果的条数include_variant_pricesbool默认False—是否抓取逐变体价格模型校验器强制两条规则至少提供urls或search_terms之一两者合并数量不得超过MAX_AMAZON_SOURCES 20这正是提示词中cannot be combined arbitrarily beyond the source cap的来源。estimated_units属性估算最坏情况返回量len(search_terms) * max_items len(urls) * (1 max_variants)并封顶于MAX_AMAZON_RESULTS 1000。参数到底层爬虫的映射见 executor.pyinclude_details→scrapeProductDetails、max_offers→maxOffers、include_sellers→scrapeSellers、max_variants→maxProductVariantsAsSeparateResults、include_variant_prices→scrapeProductVariantPrices、country_code/zip_code→countryCode/zipCode。该 capability 按BillingUnit.AMAZON_PRODUCT计费且 ScrapeOutput.billable_units 只统计成功商品——报错条目不产生计费。五、长结果分页read_run/search_run当工具结果过大时完整结果会被存储只展示一个以run_uuid结尾的预览见 run_reader.md。共享片段强制约定禁止为了看更多内容而重跑工具用read_run(ref, offset, limit)对已存储的 run 分页每行是一个 JSON 结果项用search_run(ref, pattern)在 run 内做正则过滤若单条结果本身超出响应长度保持offset在该行并继续用char_offset深入截断提示会给出下一个值。这套机制既避免重复抓取省成本、防风控又让子代理能完整消费大数据集。六、严格的输出契约Output 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 }亚马逊路由专属规则evidence.findings最多 10 条每条必须是单句陈述一个独立商品或一个 delta禁止粘贴原始载荷evidence.sources最多 10 个 URL与 findings 对应每个 URL 只列一次。共享片段 output_contract_base.md 补充了全局规则statussuccess时next_step与missing_fields必须为nullstatuspartial|blocked|error时next_step必须非空next_step仅用于你自己无法执行的动作——如果下一步本是调用自己的工具如用read_run/search_run分页、调整参数重跑应立即执行并汇报改进后的结果而不是返回partial因缺少必需输入而blocked时missing_fields必须非空assumptions记录对用户意图的推断无需推断时为nullevidence字段以路由专属契约为准禁止编造工具未返回的字段当结论来自爬虫 run 时必须把该 run 的[n]引用标签工具结果会标注Cite this scraper run as [n]原样追加到 finding 文本中保证引用能存活到最终答案——标签必须逐字复制不得自造。七、失败处理策略failure_policy定义了三种失败形态及对应状态码使监督者能机械地消费错误场景返回请求不明确无可用搜索词或 URLstatusblockedmissing_fields列出缺失字段工具失败statuserror附带简洁的恢复建议next_step没有可用证据statusblocked附带更窄的查询建议或仍需要的范围八、边界、安全与工具红线out_of_scope边界不做通用网页搜索——那是 Google Search 专家的职责不读取/抽取任意非 Amazon 页面——将 URL 转交给网页爬虫专家不生成交付物、不做 connector 变更——只返回发现由监督者决定行动只取公开、匿名的 Amazon 数据绝不触碰需要登录或卖家账号的内容。tool_policy工具红线只使用available_tools中列出的工具只汇报工具输出中实际存在的结果严禁编造标题、ASIN、价格、评分或排名必须至少提供urls或search_terms之一且二者合并不得超过来源上限。safety安全证据不完整或相互冲突时明确报告不确定性绝不把未经验证的说法当作事实陈述。这些约束在底层爬虫层面同样成立专有实现 README.md 明确声明爬虫只读取匿名访客可见的公开页面不登录、不使用账号 Cookie、不获取账号门控内容深度评论分页需要 Amazon 账号因此不在范围内页面内评论通过productPageReviews与productPageReviewsFromOtherCountries返回。九、底层实现架构与验证方式amazon.scrape的底层实现README.md分为五个职责清晰的模块schemas.py——稳定的输入、产品与错误模型url_resolver.py——分类商品、搜索、畅销榜与短链接 URLfetch.py——代理感知的 HTTP 访问、封禁检测、重试与匿名定位会话parsers.py——纯函数、防御式 HTML 解析器scraper.py——协调发现、富化、并发、限额与流内错误。验证方式离线单元测试覆盖每个解析器与流程cd surfsense_backend uv run pytest tests/unit/platforms/amazon tests/unit/capabilities/amazon另有 capability 注册测试 test_registry.py手动端到端检查需要网络与住宅代理凭据uv run python scripts/e2e_amazon_scraper.py。该脚本e2e_amazon_scraper.py会抓取一个商品详情页校验asin与title和一个搜索结果页校验卡片含asin与categoryPageData支持--refresh-fixtures用实时响应刷新解析器测试固件。结语SurfSense 亚马逊子代理的系统提示词展示了一套可复用的多智能体工程范式用 XML 标签把目标—工具—剧本—红线—失败策略—输出契约显式化用共享片段统一长结果分页与输出约定用 capability 层amazon.scrape把提示词参数与真实爬虫能力一一绑定并通过仅汇报工具真实输出 强制 JSON 契约 失败状态码化三管齐下保证监督者能得到可靠、可综合、可计费的结构化证据。理解这份提示词就理解了 SurfSense 如何把开放网络的商品数据安全地转化为可供 LLM 综合的结构化研究素材。【免费下载链接】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），仅供参考