openJiuwen DeepSearch 线索禁用模式解析:deepsearch_run_action_clues_none 提示词与 discovered_clues 状态管理
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、已检索证据 IDretrieved_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.
discovered_cluesis DISABLED:声明本模式下线索字段整体停用,Agent 不应再把它当作可用的记忆载体。- 必须始终提供空列表
[]:在<state>/<answer>的状态补丁(state patch)中,只要涉及discovered_clues键,就必须显式给出[],这是对 LLM 输出格式的硬性约束,防止模型自行发挥写入内容。 - 禁止向该字段存储任何信息:从语义层面禁止 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 行):
run_action入口读取params.config.get("discovered_clues_mode", "report");- 调用
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; - 通过 template.py 的
apply_system_prompt(基于 Jinja2 渲染,模板目录即 prompts 目录)将CLUES_SECTION注入 deepsearch_run_action.md 的{{CLUES_SECTION}}占位符,同时注入CURRENT_TIME等上下文; - 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(禁用式)三种线索策略之间做出合理选择,从而在上下文预算、推理可追溯性与搜索效率之间取得平衡。