企业官网建设流程全解析

SurfSense 主智能体 Anthropic Claude 提示词适配：provider_hints 结构化推理与工具纪律解析

【免费下载链接】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 多智能体聊天系统中"主智能体（main agent）"针对 Anthropic Claude 系列模型定制的模型侧提示词片段（anthropic.md）展开。该片段并非独立成篇的完整提示词，而是主智能体系统提示词（system prompt）组装流水线中的一个"供应商提示（provider_hints）"模块，用于在运行时把"你跑在什么模型上、该模型应该怎样思考、怎样调用工具"这类模型差异显式注入上下文。读完本文，你将掌握 SurfSense 主智能体提示词的组装架构、Anthropic 供应商提示逐条语义、以及它与其他模型供应商（DeepSeek、Gemini、Grok、Kimi、OpenAI 系列）提示的对比和背后的工具纪律设计。

一、定位：provider_hints 在整个提示词组装流水线中的角色

SurfSense 的主智能体系统提示词并不是一份静态的 Markdown 文件，而是由 builder/compose.py 在每次创建 agent 时按固定顺序动态拼装的。默认顺序如下：

<agent_identity> [用户的 custom_system_instructions，如果有] <core_behavior> # 默认主体 <knowledge_base_first> # 默认主体 <dynamic_context> # 始终注入 <routing> # 默认主体 <specialists> # 始终注入（动态名单） <tools> # 始终注入（垂直切片式） <memory_protocol> # 默认主体 <citations> # 始终注入 <output_format> # 始终注入 <refusal_and_limits> # 始终注入 <reminder> # 始终注入

在 compose.py 中，build_main_agent_system_prompt()接收model_name参数，把上述所有片段拼接为最终提示词。而providers/anthropic.md这类模型供应商提示，就是这套流水线中负责"模型侧适配"的组成部分——它告诉运行在 Claude 上的主智能体：你的推理风格、任务管理方式和工具调用纪律应该是什么样的。

每个供应商提示都以<provider_hints>与</provider_hints>标签包裹，这种 XML 风格标签与<tools>、<routing>、<specialists>等区块标签保持了一致的解析语义，便于模型在长上下文中快速识别"这一段是关于我当前运行模型的适配指令"。

从源码结构可以推断：提示词片段统一通过 load_md.py 中的read_prompt_md(filename)读取，它基于importlib.resources以包名app.agents.chat.multi_agent_chat.main_agent.system_prompt.prompts为基准加载.md资源，文件名即providers/anthropic.md这样的相对路径。这一设计保证了提示词与 Python 代码可以一起被打包分发。

二、anthropic.md 逐条解析：Claude 模型侧适配的四个维度

anthropic.md 全文仅一个<provider_hints>区块，包含四个主题，下面逐一结合仓库实现展开。

1. 结构化推理（Structured reasoning）

原文：

For non-trivial work,<thinking>/ short<plan>before tool calls is fine.

这明确许可 Claude 在调用工具之前使用<thinking>标签进行推理，或写一个简短的<plan>计划，但限定为"非平凡工作（non-trivial work）"——即不允许对例行操作过度推理。这与 core_behavior.md 中的全局行为约束（"Don't narrate intent — just act"）形成互补：核心行为负责"行动优先、不絮叨"，而 Anthropic 供应商提示负责在 Claude 平台上给出推理的合法边界。也就是说，思考是允许的，但思考必须服务于工具调用质量，而不是替代行动。

2. 专业客观性（Professional objectivity）

原文：

Accuracy over flattery; verify withtask(e.g.task(web_crawler, …)to read a page,task(google_search, …)for public facts) when unsure — don't invent connector access.

这一条把"准确性优先于迎合"落实为具体的工具纪律：当 Claude 不确定事实时，应当通过task工具调用对应的专家子智能体（specialist）去验证，而不是凭训练数据猜测。这里出现的关键词task是主智能体唯一的"委派通道"，其语义由 tools/task/description.md 定义：task(subagent_type, description)单发模式，或task(tasks=[{description, subagent_type}, ...])批量扇出模式。而"don't invent connector access"直接呼应 refusal_and_limits.md 中的铁律："Never claim filesystem access, connector access, or persistent storage you don't have"——主智能体本身没有任何连接器工具，所有连接器能力都必须通过task路由给对应专家。

3. 任务管理（Task management）

原文：

For 3+ steps, use todo tooling; update statuses promptly.

当任务需要三步以上时，要求 Claude 使用待办（todo）工具，并及时更新状态。这条规则在实际提示词中有更细化的落地：routing.md 指出write_todos用于在跨多个专家或步骤的回合序列中维护结构化计划，并要求在task调用之前把对应条目标记为in_progress、调用返回后标记为completed；跨回合的串行依赖（如"先找到知识库文档，再据此发邮件"）也要靠write_todos保持计划存活。单步请求则跳过 todo。

write_todos与update_memory一起，属于主智能体仅有的"直接工具（direct tools）"阵营——从 routing.md 可以看到，直接工具只有这两类，其余一切工作都走task委派。

4. 工具调用（Tool calls）

原文：

Parallelise independent calls; sequence only when outputs chain. Never pretend you can run connector-specific tools directly — route throughtaskwhen needed.

这一条是整份提示中最关键的工程约束，包含两层：

• 并行化纪律：独立的工具调用应并行发出，仅当后一个调用依赖前一个的输出时才串行。这与 openai_reasoning.md 中的multi_tool_use.parallel建议同源，也与 routing.md 中"两个task调用互相不引用对方输出且目标不同专家（或同专家但范围不重叠）即为独立"的判定标准一致。
• 禁止假装拥有连接器工具：主智能体绝不直接调用连接器专属工具，需要时一律通过task路由。这保证了"主智能体是纯路由器（pure router）"的架构立场不被模型越权破坏。

三、横向对比：providers 目录下各模型的差异化适配

providers/目录中与 anthropic.md 并列的还有 7 份供应商提示，覆盖了 SurfSense 主智能体可能运行的主要模型家族。它们的共同点是都包裹在<provider_hints>标签内、都强调"通过 task 委派连接器工作、不要假装拥有不存在的工具"，但在侧重点上各有不同：

从这组对比可以清晰看出 SurfSense 的供应商适配哲学：平台不变的"行为宪法"由core_behavior、routing、kb_first、refusal_and_limits等公共片段承载，而平台可变的"模型性格与调用习惯"由provider_hints承载。因此 DeepSeek 的提示专门写"不要把思维链泄漏进工具参数"（R1 类模型特有风险），而 Gemini 的提示专门写"三行以内的直接回答"（Gemini 输出风格特征），Anthropic 的提示则专门写"非平凡工作允许<thinking>/<plan>"（Claude 的结构化推理习惯）。

值得注意的是，default.md和providers/__init__.py均为空文件，从源码结构可以推断：默认情况下如果没有匹配的供应商提示，主智能体仅依赖公共行为片段运行，供应商提示属于可选增强层。

四、与任务委派机制的联动：task 工具与验证协议

anthropic.md 中反复出现的task是理解这份提示的关键锚点。主智能体（含运行在 Claude 上的实例）的全部外部能力都通过task委派给 subagents/builtins 下的专家子智能体，例如knowledge_base（用户知识库语义/关键词混合检索）、mcp_discovery（Slack、Notion、Jira、Gmail 等已连接应用）、web_crawler（页面抓取）、google_search（公开事实检索）、以及reddit/youtube/tiktok/google_maps/amazon/walmart等平台情绪专家。

每个专家子智能体都是隔离运行的，拥有自己的工具栈和上下文，返回单个综合结果。task的单发参数为：

• subagent_type：要调用的专家名，必须与<specialists>动态名单中的条目匹配。该名单由 builder/sections/specialists.py 依据当前工作区的连接器可用性动态渲染——deliverables和knowledge_base因声明了空连接器依赖集合而始终存活。
• description：完整的任务提示词。由于专家看不到当前线程上下文，所有约束和所需返回内容都必须写进这一字段。

批量模式task(tasks=[...])用于单个请求展开为 3 个及以上独立专家调用的场景，运行时以信号量控制并发并返回每个子任务一个[task <index>]前缀的 ToolMessage 块；但批量子任务不支持人工介入（human-in-the-loop）中断，需要审批的子任务会报错并要求以单发形式重新派发。

针对变更类操作，tools/task/description.md 内置了一套<verification>验证协议：专家的自然语言回复只是"自报（self-report）"，不是证据。主智能体必须核对state['receipts']中的结构化Receipt（route、type、operation、status、external_id、verifiable_url、preview），只有status="success"才代表后端已提交；对高风险变更还可以用task(web_crawler, verifiable_url)从外部确认。这份协议与 anthropic.md 的"Accuracy over flattery"一脉相承——客观性不是态度问题，而是用工具与结构化证据强制出来的结果。

五、Claude 运行时的工程配套：提示缓存与回退

围绕 Claude 主智能体，仓库还有两处值得注意的配套工程：

1. 提示缓存中间件：shared/middleware/anthropic_cache.py 基于langchain_anthropic的AnthropicPromptCachingMiddleware构建，对系统提示、工具和消息块统一打上提示缓存标注，unsupported_model_behavior="ignore"保证在不支持缓存的模型上静默降级。它被挂在主智能体的 middleware/stack.py 和知识库子智能体的 middleware_stack.py 上。考虑到主智能体提示词由十余个片段拼装而成且每个会话反复复用，提示缓存是控制成本与延迟的关键手段。
2. 模型回退链：shared/middleware/resilience/fallback.py 中保留了anthropic:claude-3-5-haiku-20241022作为回退候选；scoped_model_fallback.py 则明确只在供应商/网络错误时切换回退模型，编程错误照常抛出——这保证了 Claude 侧提示词适配在故障切换场景下仍可被其他模型承接。

另外，middleware/noop_injection/middleware.py 展示了供应商兼容层面的精细处理：部分供应商（LiteLLM、Bedrock、Copilot）在模型调用缺少任何工具时直接返回 400，于是中间件按ls_provider启发式判断，仅对这些供应商注入一个_noop占位工具。这类代码与 anthropic.md 共同说明了 SurfSense 对"模型供应商差异"是一套从提示词到中间件再到回退策略的立体适配。

六、提示词资源的可靠性保障：测试守护

提示词是系统行为的关键资产，仓库用测试防止其静默退化。核心依据是 tests/unit/agents/multi_agent_chat/test_prompt_resources.py：

• 提示词片段通过importlib.resources按包名加载而非 import 加载，一旦包被移动而.md文件未跟随，read_prompt_md会返回空字符串并静默劣化系统提示词；
• 该测试因此断言core_behavior.md、routing.md、tools/task/description.md等关键片段必须解析为非空内容；
• 同时断言每个专家子智能体都必须携带非空的description.md，守护<specialists>动态名单的完整性。

这也意味着：如果你在本地浏览或修改这些提示词，需要同步关注测试文件中的守护清单，任何"提示词文件被移动"的改动都会被 guardrail C 拦截。

七、实操视角：如何观察与验证 Claude 主智能体的提示词行为

对于部署或二次开发 SurfSense 的工程师，可以按以下路径观察这套提示词机制的实际效果：

1. 定位入口：主智能体在 runtime/factory.py 中调用build_main_agent_system_prompt()，它从 LLM 实例的model_name属性解析当前模型，连同线程可见性、启停用工具集合、用户自定义系统指令、引用开关等参数一起传入。model_name参数即提示词组装流水线感知"当前是哪个供应商"的输入端（从源码结构可以推断，供应商提示的选择依据就是该模型名）。
2. 观察组装顺序：在 compose.py 中，公共片段（core_behavior、kb_first、routing、output_format、refusal_and_limits、reminder）与动态片段（dynamic_context、specialists、tools、citations、memory_protocol）交替拼装；custom_system_instructions是叠加而非替换——它插在身份与默认主体之间，保证平台级安全网始终生效；use_default_system_instructions=False则跳过四个"默认主体"片段但保留全部常驻平台片段。
3. 验证行为契约：Claude 主智能体应当表现出 anthropic.md 规定的四项行为——非平凡任务先思考再行动、不确定时用task验证而非臆造、三步以上用 todo 跟踪、独立调用并行发出且绝不假装拥有连接器工具。这些行为都可以通过阅读 routing.md 中的大量 few-shot 示例（<example>块）来对照理解，例如"搜索发现、爬虫阅读"的职责划分、请求 N 个实体时的去重规则、完整数据集导出为文件而非贴聊天等。

八、总结：一份提示词背后的供应商适配方法论

anthropic.md 虽然只有 16 行，却是 SurfSense 多智能体架构"提示词即配置"理念的缩影。它揭示了三个可迁移的设计原则：

1. 把平台不可变的行为宪法与平台可变的模型性格分离：安全、路由、引用、拒答等规则放进公共片段，推理风格、输出简洁度、工具调用习惯放进provider_hints，新增模型只需新增一份 Markdown。
2. 用提示词强制架构边界：通过"绝不假装拥有连接器工具、一律走 task"的显式指令，把"主智能体是纯路由器"的架构约束写进模型上下文，配合 Receipt 验证协议把"客观准确"从口号变成可执行、可验证的协议。
3. 为供应商差异提供立体配套：提示词只是第一层，其下还有 Anthropic 提示缓存中间件、供应商兼容的_noop注入、模型回退链和资源解析测试，共同保证无论切换哪个模型家族，主智能体都能以一致的边界感完成研究、检索与委派任务。

对于希望深入探究的读者，建议依次阅读 compose.py、routing.md、tools/task/description.md 以及 test_prompt_resources.py，即可完整拼出从"一份 16 行的模型提示"到"整个主智能体运行时"的全景。

【免费下载链接】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