openJiuwen DeepSearch 线索禁用模式解析:deepsearch_run_action_clues_none 提示词与 discovered_clues 状态管理

原创2026-10-12 10:47:111,439 阅读
文章标签:人工智能大模型AI Agent深度研究RAG代码智能体搜索引擎Agent 工作流

openJiuwen DeepSearch 线索禁用模式解析:deepsearch_run_action_clues_none 提示词与 discovered_clues 状态管理

导读

deepsearch_run_action_clues_none.md 是 openJiuwen DeepSearch 的 Search Agent(DeepSearchAgent)在状态空间搜索机制中,用于完全禁用 discovered_clues 线索记录的模式提示词。它通过强制要求 Agent 在任何 state patch 中把 discovered_clues 置为空列表 <a href="https://link.gitcode.com/i/195f5c950fb160ed1667a4c574b5a978" target="_blank">],切断跨轮次线索的累积,从而把多步推理退化为「单轮事实核查 + 候选维护」的简化闭环。本文将逐条解读该提示词的约束语义,结合 [run_action.py、config.py 等源码说明其底层执行路径与配置方式,并与同目录下的 clues_report、clues_blacklist 模式做横向对比,帮助你根据问答场景选择正确的线索模式。


一、背景:discovered_clues 在 Search Agent 状态机中的角色

openJiuwen DeepSearch 的 Search Agent 采用状态空间搜索机制:初始化状态(init_state)→ 生成候选动作(find_action)→ 执行动作并扩展状态(state_creation)→ 循环直至产出答案。整个推理过程围绕两类核心数据结构展开(见 README_search_zh.md 与 search_context.py):

  • State:搜索过程中的一个状态,包含变量列表 state、搜索深度 depth、状态 ID、已检索证据 ID retrieved_evidence_ids 等;
  • Variable:状态中的未知实体,包含不可变字段 id、type、question_clues(源自问题本身的线索),以及可变字段 discovered_clues(研究中逐步发现的线索)、candidate(候选值)、candidate_strength(0–1 置信度)。

其中 discovered_clues 是 Agent 在多轮搜索中自行沉淀的知识:它记录候选的排除依据、验证进展、来源 URL 等,为后续轮次的 find_action、校验器(validator)与答案裁决提供依据。deepsearch_initialize_state.md(初始化提示词)规定初始化时所有变量的 discovered_clues 必须为空列表 [],说明该字段完全由搜索过程动态写入。

二、deepsearch_run_action_clues_none.md 逐条解读

该文档全文为三段约束,语义非常明确:

**IMPORTANT RULES FOR DISCOVERED_CLUES:**
- `discovered_clues` is DISABLED.
- You MUST ALWAYS provide an empty list `[]` for `discovered_clues` in any state patch.
- Do not store any information in this field.
  1. discovered_clues is DISABLED:声明本模式下线索字段整体停用,Agent 不应再把它当作可用的记忆载体。
  2. 必须始终提供空列表 []:在 <state> / <answer> 的状态补丁(state patch)中,只要涉及 discovered_clues 键,就必须显式给出 [],这是对 LLM 输出格式的硬性约束,防止模型自行发挥写入内容。
  3. 禁止向该字段存储任何信息:从语义层面禁止 Agent 把搜索发现、排除依据、来源链接等任何内容写入该字段。

值得注意的是,这份提示词是整个 run_action 系统提示词(deepsearch_run_action.md)中的可插拔片段(CLUES_SECTION),并非独立完整的系统提示词。在 deepsearch_run_action.md 第 63 行可以看到占位符 {{CLUES_SECTION}},运行时由 build_react_prompt_context 依据 discovered_clues_mode 注入对应片段(详见下文第五节)。

三、源码级佐证:none 模式在状态补丁应用时的强制清空

提示词约束并非仅靠"提示"生效,代码层面做了双重保险。在 run_action.py 的 apply_patch 函数(第 274–364 行)中,状态补丁的落地逻辑为:

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
        ...

即:当 discovered_clues_mode == "none" 时,无论 LLM 在补丁中给出了什么内容,代码都会无条件将其覆盖为空列表 []。这意味着即使模型偶尔违反提示词写入了线索,也不会进入新状态,从工程层面保证线索字段始终为空——提示词负责引导,代码负责兜底。

该函数的其余逻辑同样值得注意:它校验补丁中每个变量必须携带不可变的 id(Patched id {id} not found in base state. 报错),只允许更新 candidate、candidate_strength、discovered_clues 三个可变字段;每次补丁应用后 depth 递增,并生成新的状态 ID(f"{depth:03x}_{int(time.time()*100):08x}{secrets.token_hex(1)}"),检索证据 ID 也会合并累积。

四、三种线索模式的横向对比

deepsearch_run_action_clues_none.md 并非孤立文件,它与其他两个同族提示词构成完整的模式体系,三者由同一配置项 discovered_clues_mode 驱动(可选值见 config.py 第 312 行与 README_search_zh.md 参数表):

模式 对应提示词文件 线索语义 更新方式 适用场景
blacklist(默认) deepsearch_run_action_clues_blacklist.md 线索用于缩小候选池:排除具体候选或按属性排除候选组 替换(REPLACED,非追加),必须保留仍有效的旧线索 多候选、强约束、需要明确排除推理的复杂问答(如 BrowseComp+ 式谜题)
report deepsearch_run_action_clues_report.md 线索以研究报告形式记录调研历史与候选状态 替换,每个被更新变量必须恰好一个条目,结构为 History + Candidate + Sources 需要完整可追溯调研轨迹、便于校验器复核的场景
none 本文件 线索完全禁用,不记录任何调研信息 始终置空 [] 单轮核查型问答、上下文预算紧张、或不需要跨轮次线索记忆的简化场景

4.1 blacklist 模式:排除式推理

该模式要求线索格式为 "ELIMINATES: [candidate/group description] - [reasoning/evidence] | Sources: [URL1, ...]",典型示例如:

* "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"

它同时规定:若某个候选被线索排除,则该候选不得再出现在状态中("You cannot have a candidate that is eliminated in the discovered_clues and still be a candidate in the state")。这种模式适合候选集明确的排他性推理,是默认配置。

4.2 report 模式:报告式线索

该模式要求每个被更新变量恰好提供一个结构化的线索条目,包含:

  • History:对变量调研过程的高密度叙述——尝试过的研究方向与动作、早前考虑过的候选及其被拒绝/仍待验证的原因;
  • Candidate:当前候选的发现方式(关键搜索词、工具或页面)、对照问题线索(question_clues)的满足情况、以及候选唯一性评估,需要引用检索/抓取结果的原文片段;
  • 结尾以 | Sources: [URL1, URL2, ...] 附来源列表。

报告式线索允许"重写压缩"旧信息,不必逐字保留,适合需要给校验器(validator)提供完整复核依据的长链条推理。

4.3 none 模式(本文主体):纯候选维护

与前两者形成鲜明对比:none 模式不记录任何历史、排除依据或来源。Agent 只需要维护 candidate 与 candidate_strength,跨轮次的知识传递被有意切断。其收益是提示词更短、上下文更省、模型输出更简单稳定;代价是失去对"为什么排除某个候选"的记忆,可能造成重复探索。

五、配置与装配:discovered_clues_mode 的生效链路

5.1 配置位置与参数说明

该模式通过 SearchWorkflowConfig.state_creation_agent.discovered_clues_mode 配置(config.py 第 300–312 行):

class StateCreationAgentConfig(BaseModel):
    ...
    use_candidate_strength: bool = Field(default=True, ...)
    discovered_clues_mode: Literal["report", "blacklist"] = Field(default="blacklist", description="发现线索模式")

注意:在 config.py 中类型标注为 Literal["report", "blacklist"] 且默认 "blacklist",而 run_action.py 的 build_react_prompt_context 实际支持 "none" 并对其余非法值回退到 "blacklist"。从源码结构看,none 属于运行时已实现但配置类型标注尚未显式开放的模式,若要在配置中启用,需要在 YAML/代码中显式传入 "none"(并对齐类型校验约束)。配置示例如下:

service_config:
  search_workflow:
    state_creation_agent:
      use_candidate_strength: true
      discovered_clues_mode: "none"   # 可选 "report" / "blacklist" / "none"
      max_llm_calls_per_run: 100
      context_limit_reached_strategy: "reduced_retrieval_request"
      retrieval_settings:
        top_k: 3
        top_k_multiply_factor: 5
        mode: "hybrid"

5.2 提示词装配链路

discovered_clues_mode 的生效链路如下(见 run_action.py 第 689–880 行):

  1. run_action 入口读取 params.config.get("discovered_clues_mode", "report");
  2. 调用 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}")}
    
    即 none 模式会加载 deepsearch_run_action_clues_none.md 作为 CLUES_SECTION;
  3. 通过 template.py 的 apply_system_prompt(基于 Jinja2 渲染,模板目录即 prompts 目录)将 CLUES_SECTION 注入 deepsearch_run_action.md 的 {{CLUES_SECTION}} 占位符,同时注入 CURRENT_TIME 等上下文;
  4. LLM 输出经 parse_and_apply_llm_result 解析为 tool_calls / state / answer 三种模式之一,其中 state/answer 补丁再交由 apply_patch 落地——none 模式下在此强制清空 discovered_clues。

模板选择还有一个联动细节:use_candidate_strength=False 时会改用 deepsearch_run_action_no_cs.md(不含 candidate_strength 字段的变体模板),与线索模式相互独立。

六、none 模式下 Agent 的输出行为

在 none 模式下,Agent 执行 run_action 时仍须按 deepsearch_run_action.md 的约束在三种输出模式中选择一种:

  • TOOL CALL MODE:调用 web_search / web_fetch(search_fetch 模式)或 retrieve(retrieve 模式,限 1–3 条 query)收集证据;
  • STATE PATCH MODE:输出 <state>...</state> 包裹的 JSON 补丁,仅包含发生变化的变量,字段限定为 id、candidate、candidate_strength、discovered_clues,其中 discovered_clues 必须为 [];
  • FINAL ANSWER MODE:当证据足以满足全部问题约束时输出 <answer>...</answer>,含 answer 与 new_state。

none 模式的典型 state patch 形如:

<state>
{
  "new_states": [
    {
      "state": [
        {
          "id": 1,
          "candidate": "Augustus De Morgan",
          "candidate_strength": 0.82,
          "discovered_clues": []
        }
      ]
    }
  ]
}
</state>

对比 report 模式下同一补丁会携带结构化的 History/Candidate/Sources 线索条目,none 模式显著削减了每次状态更新的输出体积。

七、与校验器(Validator)的交互影响

Search Agent 的状态扩展并非终点,新的候选状态还会进入校验环节。validate_new_state.py 第 351–356 行的逻辑显示,校验器对每个有候选的变量调用 find_relative_info(candidate=..., clue_items=s.discovered_clues, ...),把线索作为补充证据拼接进 evidence 字段(" | ".join(discovered))再交给 Verify 工具复核:

discovered, in_tok, out_tok = await find_relative_info(
    candidate=s.candidate,
    clue_items=s.discovered_clues,
    model_name=validator_model_name,
)
...
focus_candidates.append({
    "variable_id": str(s.id),
    "type": s.type,
    "value": s.candidate,
    "evidence": " | ".join(discovered),
})

这意味着在 report / blacklist 模式下,discovered_clues 会直接参与候选校验的证据构造;而在 none 模式下该字段恒为空,校验器只能依赖 question_clues 与候选本身进行独立核查。因此选用 none 模式时,应确保问题约束(question_clues)足够自足,或者接受校验证据链的弱化。此外,main_graph_nodes.py 中 RunActionNode 在 LLM 调用预算将尽时(llm_budget <= 3)也会引导模型把相关发现写入各变量的 discovered_clues 列表,这条兜底引导在 none 模式下同样被 apply_patch 的清空逻辑覆盖,属于预期内的行为差异。

八、测试验证与使用建议

8.1 测试覆盖

Search Agent 的 run_action 编排逻辑在 tests/search_agent/test_run_action.py 有单元测试覆盖,包括:

  • test_run_run_action_success_path:验证 run_action 成功路径下 mode == "state"、token 累计正确;
  • test_run_action_retry_exhausted_returns_failure:验证 LLM 重试耗尽后跳转 end_node;
  • test_run_action_context_limit_reduced_retrieval_strategy:验证上下文超限后 top_k 与 top_k_multiply_factor 减半重试。

该测试夹具中 config 使用了 "discovered_clues_mode": "report",说明模式参数是 run_action 配置的关键入口;针对 none 模式的 apply_patch 清空行为,可以在 config 中切换为 "none" 后断言新状态的 discovered_clues 恒为 [] 来验证(此为从源码结构推断的测试路径,供自行补充用例时参考)。运行方式见 README_search_zh.md:

pip install .
pytest -q tests/search_agent -m "not llm"   # 默认跳过需要真实 LLM/联网的用例
export RUN_LLM_TESTS=1
pytest -q tests/search_agent                  # 含 llm 用例

8.2 选型建议

  • 需要多轮排除推理、候选集复杂:使用默认 blacklist,靠排除式线索高效收缩候选池;
  • 需要可追溯调研轨迹、供校验器复核:使用 report,线索条目含 History/Candidate/Sources,证据链最完整;
  • 单轮核查型问题、追求上下文精简与输出稳定:使用 none,彻底关闭线索记忆,但需注意校验证据链弱化与可能的重复探索问题,并确认运行时配置入口支持该值(run_action.py 已实现,config.py 类型标注尚为 Literal["report", "blacklist"])。

九、总结

deepsearch_run_action_clues_none.md 是 openJiuwen DeepSearch Search Agent 提示词体系中的"最小化记忆"方案:它通过三条简洁规则禁用 discovered_clues,配合 run_action.py 中 apply_patch 的无条件清空逻辑,实现提示与代码的双重保障。理解这一模式,就能在 blacklist(默认,排除式)、report(报告式)与 none(禁用式)三种线索策略之间做出合理选择,从而在上下文预算、推理可追溯性与搜索效率之间取得平衡。

登录后查看全文
deepsearch