企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• RAG
• 深度研究
• 搜索引擎
• 后端
• 代码智能体

导读

本文深入解析 openJiuwen DeepSearch 搜索 Agent（DeepSearchAgent）中discovered_clues的REPORT（报告式）线索模式，它以deepsearch_run_action_clues_report.md为规范骨架，要求模型在每次状态补丁中为每个被更新的变量写入一条「History + Candidate」双段式研究报告，完整记录调研路径、候选发现过程与线索校验结论。读完本文，你将掌握 REPORT 模式与 blacklist（黑名单淘汰式）、none（禁用式）三种discovered_clues_mode的语义差异与切换方式，理解discovered_clues在状态空间搜索中的「记忆与推理证据链」作用，并能结合源码与测试用例写出符合规范、可被解析器正确落库的线索条目。

一、背景：搜索 Agent 的状态空间搜索与线索字段的定位

openJiuwen DeepSearch 的 Search Agent 采用状态空间搜索模型：将复杂问题分解为多个变量（Variable），通过「初始化状态 → 发现动作 → 执行动作 → 产出答案」的循环逐步逼近答案。核心流程由三个子工作流构成（见 README_search.md）：

1. init_state：解析问题，构建初始搜索状态；
2. find_action：从当前状态提出可执行的搜索动作（Action）；
3. state_creation：执行动作、调用工具、扩展状态空间。

其中state_creation的核心执行节点是RunActionNode，其底层实现位于 run_action.py。每个状态（State）由若干Variable组成，字段定义见 search_context.py：

discovered_clues是 Agent 跨轮次推理的「增量记忆」：它把一次 Action 中探索到的路径、排除的候选、验证过的线索写入状态，供后续动作与并行分支继续消费。REPORT 模式正是这套记忆机制的规范化描述语言——它规定线索条目「怎么写、写什么、写到多细」。

二、REPORT 模式核心规则（规范原文继承）

deepsearch_run_action_clues_report.md定义了在 REPORT 模式下模型更新discovered_clues时必须遵守的规则，共 5 条硬性约束：

1. 整体替换而非追加：discovered_clues会被你在状态补丁（state patch）中提供的内容整体替换（REPLACED），而不是追加。因此每次补丁都必须携带该变量的完整线索快照。
2. 一变量一条目：在此模式下，每更新一个变量，discovered_clues必须恰好是只含一条字符串的列表（list with exactly one string entry），即["REPORT: ..."]。
3. 条目双段式结构：唯一的那条字符串必须包含两个带标签的段落：
   • History：对该变量到目前为止调研过程的高信号（high-signal）叙事——尝试过哪些研究方向和动作、考虑过哪些候选或假设、为何被否决或仍未证实。
   • Candidate：若存在当前候选，说明它是如何被发现的（关键搜索词、工具或页面）、已对照问题线索（question clues）做过哪些校验、这些线索是否被满足、是否查找过其他候选以评估唯一性，并引用搜索/抓取结果中的相关原文；若没有当前候选，此段留空。
4. 允许压缩重写：不必逐字保留全部历史细节；随着掌握的信息增多，可以重写与压缩过往信息，只要报告仍反映当前的知识本质状态。
5. 统一格式：REPORT: History: [探索路径与已否决候选的简明历史] Candidate: [当前候选状态、发现方式、对照问题线索的校验、唯一性评估] | Sources: [URL1, URL2, ...]

三、三种 discovered_clues_mode 的语义对照

REPORT 模式并非唯一选项。prompts 目录下共存放三个线索段落模板，由配置项discovered_clues_mode选择，其加载逻辑见 run_action.py 中的build_react_prompt_context：

clues_key = discovered_clues_mode if discovered_clues_mode in ("blacklist", "report", "none") else "blacklist" context = {"CLUES_SECTION": get_prompt_section(f"deepsearch_run_action_clues_{clues_key}")}

blacklist 模式的对照要点

在blacklist模式下，discovered_clues可以被写成多条淘汰条目，格式为：

ELIMINATES: [candidate/group description] - [reasoning/evidence]. [If applicable: Include any assumptions about other variables that cause a contradiction or lead to this elimination] | Sources: [URL1, URL2, ...]

且要求：补丁中提供的线索必须保留此前所有仍然有效的信息；线索应通过「排除具体候选」或「按属性排除一组候选」来收窄候选池；候选被变更时，与其相关的所有线索须同步更新。该模式提供的示例包括：

• "ELIMINATES: John Smith - published work in 1823, but University College London was not established until 1826. Assumption: Variable 2 (university) is University College London| Sources: url_of_the_source"
• "ELIMINATES: Chicago - as there is no soccer team that is based in Chicago that competed in the FA Cup (requirement stated in question clues) | Sources: url_of_the_source1, ..."

对照可见两种模式的本质差异：blacklist 记录「否证」（谁被排除、为什么），report 记录「正证与过程」（怎么查的、查到了什么、候选是否唯一）。二者同时约束着主提示词中的一条铁律——不能在 discovered_clues 中被淘汰的候选，同时仍保留在 state 的 candidate 中。

四、REPORT 条目格式与示例逐段解析（规范原文继承）

4.1 格式模板

REPORT: History: [concise history of explored paths and rejected candidates] Candidate: [current candidate status, how it was found, checks against question clues, and uniqueness assessment] | Sources: [URL1, URL2, ...]

4.2 示例一：数学家变量（教师关系确认）

原文给出的完整示例：

"REPORT: History: For the mathematician variable, we began with several 19th‑century figures linked to Ada Lovelace (Charles Babbage, Augustus De Morgan, and George Boole), checking biographies and correspondence for explicit evidence of a teaching role; Babbage and Boole were rejected because sources describe them as collaborators or contemporaries rather than her formal tutor, and their institutional roles did not match the degree program in the question. Candidate: Augustus De Morgan was surfaced by targeted searches for "Ada Lovelace calculus tutor" and "De Morgan teaches Ada Lovelace"; one biographical entry explicitly states that 'De Morgan later tutored Ada Lovelace in mathematics at her mother's request,' and a university archive notes that 'Lovelace studied calculus under Augustus De Morgan at University College London in the 1840s.' Taken together, these excerpts satisfy the tutor-relationship and timeline clues, and we have not found another mathematician who fits them simultaneously, suggesting De Morgan is a unique fit. | Sources: url..."

逐段拆解其信息负载：

• History 段：交代了初始候选集（Babbage、De Morgan、Boole 三位与 Ada Lovelace 相关的 19 世纪数学家）、验证手段（传记与书信中的教学角色证据）、两条淘汰原因（Babbage 与 Boole 在文献中被描述为合作者/同代人而非正式导师；其机构角色与问题中的学位项目不符）。
• Candidate 段：给出候选发现路径（"Ada Lovelace calculus tutor"、"De Morgan teaches Ada Lovelace"两组定向搜索）、两处原文引证（传记条目、大学档案）、线索校验结论（满足师生关系与时间线两条线索）、唯一性评估（未发现其他同时满足的数学家）。
• Sources 段：附上支撑来源 URL 列表。

4.3 示例二：城市变量（港口城市 + 山顶教堂识别）

"REPORT: History: For the city variable, we first tested several European port cities with major early‑20th‑century expositions (Paris 1900, London 1908, Hamburg 1903), comparing archival photos and maps to the question's description of a colonial exposition overlooked by a hilltop basilica above the harbor; Paris and London were ruled out because their exposition sites are inland and lack the specified basilica, while Hamburg's waterfront skyline does not feature a comparable hilltop church. Candidate: Marseille emerged by searching for "1906 colonial exhibition port city basilica on hill"; a heritage article describes 'the 1906 Colonial Exhibition held in Marseille, showcasing France's overseas possessions,' and a tourism page notes that 'the basilica of Notre-Dame de la Garde stands on a limestone outcrop overlooking the Vieux-Port.' These quoted passages jointly match the exposition and skyline clues, and we have not identified any other port city with both a colonial exhibition in this period and a comparable hilltop basilica, so Marseille is currently the only strong candidate. | Sources: url..."

该示例展示了 REPORT 模式对多属性联合约束的处理：History 段按「博览会年份 + 港口位置 + 山顶教堂」三重特征逐个淘汰候选（巴黎、伦敦因场地在内陆且无教堂被排除，汉堡因滨水天际线无同类教堂被排除）；Candidate 段以一条查询同时命中展览与地貌两个线索，并通过「无其他城市同时具备两个特征」完成唯一性论证。

五、REPORT 条目如何进入状态补丁

REPORT 条目是<state>状态补丁中discovered_clues字段的值。主提示词 deepsearch_run_action.md 规定了三种互斥的输出模式：

1. TOOL CALL MODE：调用web_search/web_fetch/retrieve工具收集证据（工具定义见 run_action.py）；
2. FINAL ANSWER MODE：证据足以满足全部问题线索时，输出<answer>块，含answer、new_state（可选discovered_clues）；
3. STATE PATCH MODE：研究方向已被充分探索但尚无最终答案时，输出<state>块，仅包含发生变更的变量。

REPORT 模式下，一个典型的<state>补丁形如：

<state> { "new_states": [ { "state": [ { "id": 1, "candidate": "Augustus De Morgan", "candidate_strength": 0.8, "discovered_clues": [ "REPORT: History: ... Candidate: ... | Sources: url1, url2" ] } ] } ] } </state>

注意补丁的三项约束（见 deepsearch_run_action.md）：

• 只写发生变更的变量，不要重复整个 state；
• id、question_clues不可变，不可增删变量、不可改 question_clues；
• 每项discovered_clues在 REPORT 模式下必须是完整列表（整体替换语义），type与question_clues不得出现在补丁中。

5.1 无进展时的空补丁约定

当动作被充分探索但无任何新信息时，必须返回空补丁<state>{"new_states":[]}</state>以向编排器发出「动作完成」信号，而不是无限循环调用工具。这同样适用于 REPORT 模式——即使没有新候选，History 段也可记录「已探索、无进展」的路径，供后续分支避免重复。

5.2 与 candidate_strength 的协同

REPORT 模式的 Candidate 段天然与candidate_strength置信度语义配套。主提示词定义了强度分档：proven > 0.9；strong 0.7–0.9；tentative 0.4–0.7；weak < 0.4。当某变量与其最终答案关联、且candidate_strength > 0.7时，模型必须直接输出最终答案而非状态补丁。REPORT 条目中的「唯一性评估」正是模型给强度打分的证据基础：完成充分交叉验证并确认唯一 → 高强度；仅部分线索满足、其他关联变量缺候选 → 用 0.4–0.7 的暂定分先行记录，待后续动作补齐。

六、源码级实现：REPORT 条目如何被解析与落库

6.1 模板选择链路

run_action执行时按use_candidate_strength选择主提示词模板（deepsearch_run_action或deepsearch_run_action_no_cs），并通过build_react_prompt_context注入{{CLUES_SECTION}}段落（run_action.py）。deepsearch_run_action_no_cs.md与主模板结构一致，仅不输出candidate_strength字段（候选强度通过use_candidate_strength: bool配置开关控制，默认 True）。

6.2 补丁应用逻辑：apply_patch

模型输出的<state>内 JSON 由parse_run_action_result提取（run_action.py），随后进入apply_patch（run_action.py）合并到基态。对discovered_clues的处理分支：

discovered_clues_mode = config.get("discovered_clues_mode", "report") ... if "discovered_clues" in pv and pv["discovered_clues"] is not None: if discovered_clues_mode == "none": nv.discovered_clues = [] else: new_clues = pv["discovered_clues"] if isinstance(new_clues, list): nv.discovered_clues = new_clues elif isinstance(new_clues, str): nv.discovered_clues = [new_clues] ...

从源码可见三个关键实现事实：

1. none模式在引擎侧被硬编码为强制清空（[]），即使模型违规携带了内容也会被剥离；
2. report与blacklist在落库层面共享同一「整体替换」路径——discovered_clues总是被补丁值替换，而非追加（与规范第 1 条一致）；
3. 模型偶尔把单条字符串而非列表输出时，解析器会宽容地包装为单元素列表（[new_clues]）。

此外apply_patch强制要求每个被补丁的变量必须携带不可变id，且id必须存在于基态，否则抛出RUN_ACTION_PARSE_ERROR（run_action.py）。

6.3 状态合并与多分支并行

parse_and_apply_llm_result支持new_states数组携带多个分支补丁（_normalize_new_states还会自动把「扁平变量字典」包装为独立分支），每个分支经apply_patch生成一个新的 State 并全部加入all_merged_states。这意味着 REPORT 模式下，同一变量的多个互斥候选可写成多个补丁分支进入并行探索——每条 REPORT 条目的 History 段记录了各自分支的探索足迹，后续采样与验证节点据此决定取舍。

6.4 校验器兜底

配置中的validator_agent可开启validate_new_states/validate_answer（默认 False），开启后新状态会先经过验证器再落库（run_action.py）。验证器实现见 validate_new_state.py，它会按isolated / linked / set模式核对候选与线索（CandidateVerifiedClues输出每条线索的 pass/fail/pending 状态），进一步保证了 REPORT 条目中「已对照线索校验」结论的可信度。

七、配置与切换：discovered_clues_mode 实战参数

discovered_clues_mode定义于 config.py，属于SearchWorkflowConfig.state_creation_agent（即StateCreationAgentConfig）：

discovered_clues_mode: Literal["report", "blacklist"] = Field(default="blacklist", description="发现线索模式")

在 README_search.md 的配置参考表中：

切换为 REPORT 模式只需将配置置为：

search_workflow: state_creation_agent: discovered_clues_mode: report use_candidate_strength: true

注意两个适用前提：

• discovered_clues_mode的 Literal 类型仅含report与blacklist两个合法值；none是build_react_prompt_context内部识别、但不作为公开配置枚举的隐藏模式（若传入非法值会被兜底为blacklist）；
• 模式影响的是注入提示词的线索段落与解析分支，不会改变discovered_clues字段本身的数据结构（始终是字符串列表）。

八、与 blacklist 模式的选型建议

结合两者在提示词与实现上的差异，选型建议如下：

• 需要跨轮次传递「调研过程」时选report：适合多跳、多变量关联、需要后续 Agent 理解「为什么排除了 A、为什么选中 B」的复杂推理题（如 BrowseComp 式多线索交叉验证）。REPORT 的 History 段让每个并行分支独立可追溯，避免重复劳动；
• 以候选池收窄为主时选blacklist：淘汰逻辑简单直接、条目可多条并列，适合「排除法」型问题与对 token 消耗更敏感的场景；
• 对线索记忆无需求时使用none：强制空列表，最大化压缩上下文。

无论哪种模式，都需遵守主提示词中的共同铁律：线索中被淘汰的候选不得继续出现在candidate中（"You cannot have a candidate that is eliminated in the discovered_clues and still be a candidate in the state"）；以及「无进展必须返回空补丁、禁止动作悬挂」的终止纪律。

九、测试与验证依据

仓库测试覆盖了 run_action 的完整路径与线索模式配置：

• test_run_action.py 的_params构造器显式以"discovered_clues_mode": "report"驱动测试，验证成功路径（success=True、mode 路由、token 累计）、重试耗尽返回失败、以及上下文超限时reduced_retrieval_request策略将top_k减半（10→5）、top_k_multiply_factor减半（8→4）的降级逻辑；
• conftest.py 的base_actionfixture 预置了含discovered_clues=["eiffel tower"]的状态样例，供各类状态补丁合并测试复用；
• main_graph_nodes.py 的RunActionNode文档注释明确了：空<state>是给编排器的有意信号而非错误；工具调用经规范化后进入pending_tool_calls队列；上下文超限可按策略修剪消息重试。

十、编写高质量 REPORT 条目的最佳实践

1. History 段写「决策过程」而非流水账：保留候选集合、验证手段、淘汰理由三条主干信息，冗余细节可随轮次压缩；
2. Candidate 段必须包含可核验的三要素：发现方式（搜索词/工具）、原文引证（quote extracts）、线索满足情况与唯一性评估；引文要短而高信号；
3. 每个被更新变量恰好一条条目，且携带完整 Sources 列表——这是解析器与后续校验器共同依赖的格式契约；
4. 候选被淘汰时同步重写 History：REPORT 是整体替换语义，旧条目中的失效信息需在重写中移除，避免「已淘汰候选仍出现在线索中」的一致性冲突；
5. 善用空补丁：无进展时返回<state>{"new_states":[]}</state>并在 History 中记录「已探索但无收获」的方向，为并行分支提供负样本信息；
6. 与置信度分档对齐：唯一性论证充分才给 strong（0.7–0.9）以上，仅部分线索满足时用 tentative（0.4–0.7），关联变量缺候选的暂定候选不要虚高置信度。

REPORT 模式将「排除法」升级为「研究履历法」：它让 openJiuwen DeepSearch 的每个搜索分支都能携带自己的调研史进入下一轮推理，从机制上支撑了片段级可溯源、多假设并行验证的深度搜索能力。理解并正确使用discovered_clues_mode的三种模式，是定制与调优 Search Agent 推理行为的关键一环。

• 人工智能
• 大模型
• AI Agent
• RAG
• 深度研究
• 搜索引擎
• 后端
• 代码智能体