openJiuwen DeepSearch 用户素材（User Materials）机制全解析：从接口契约到溯源写作

人工智能大模型AI AgentRAG深度研究搜索引擎后端代码智能体【免费下载链接】deepsearchopenJiuwen DeepSearch是一款知识增强的深度搜索与研究框架有业界领先的片段级引用和溯源推理能力提供精准Agentic搜索与研究能力项目地址https://gitcode.com/openJiuwen/deepsearch点击查看免费下载用户素材User Materials是 openJiuwen DeepSearch 面向基于用户已有资料做深度研究场景提供的核心能力调用方把论文、报告、本地文档等既有素材的正文直接传入请求系统在意图识别、提纲、规划与写作全链路中将这些素材作为可溯源证据使用并自动补齐网页检索缺口。读完本文你将掌握 user_materials 的接口契约与字段校验规则、素材预处理管线的去重/摘要/预算降级实现、material_first 使用策略的判定逻辑以及素材证据如何进入专业版与 Brief 报告的写作阶段。本指南以 docs/feature/algorithm/user-materials.md 为骨架结合仓库源码与测试用例逐层展开。一、核心概念素材是已有信息不是检索目标用户素材机制解决的是一类典型需求用户手里已经有若干份资料论文 PDF、行业报告、内部文档希望研究报告以这些资料为主体来撰写而不是从零开始全网检索。与普通网页检索的差异体现在三个方面正文必须由调用方直接传入系统不依据 URL 或标题抓取正文。每条素材的content是唯一的信息来源url仅作为展示、去重与引用校验的统一来源标识本地绝对文件路径或安全的 HTTP(S) 链接。素材是已有证据而非待检索目标在意图识别阶段被固化为既有证据只对素材未覆盖的主张或研究缺口补充网页检索。素材覆盖的章节可以跳过联网检索在明确要求基于/总结所提供素材即material_first时若素材分析已覆盖章节主张且无研究缺口系统允许空检索直接进入素材合并与写作。二、接口契约如何启用与传参在 run 请求的metadata中同时传入user_materials_enabled: true与user_materials列表即可启用。最小可用示例如下{metadata:{user_materials_enabled:true,user_materials:[{url:D:\\materials\\paper.pdf,content:...}]}}2.1 UserMaterial 字段表对应源码模型 material_processing.py 中的 UserMaterial字段定义如下字段必填说明url是素材来源标识本地绝对文件路径或 HTTP(S) 链接用作去重与溯源标识系统不据此抓取正文content是素材正文调用方直接传入strip 后为空同样拒绝material_id否调用方自定义素材 ID用于全程追踪与去重缺省时系统按M1/M2/...自动分配title否素材标题publish_time否素材发布/数据时间content_time否素材内容覆盖的时间范围2.2 校验与开关规则总量上限启用时所有素材content的总长度不得超过 500 万字符。关闭开关user_materials_enabled为 false默认时即使传入user_materials也会被忽略。对应 main_graph_nodes.py StartNodeStartNode只转存原始素材到search_context.user_materials发现传了素材但开关关闭时记录告警日志[StartNode] user_materials provided (...) but user_materials_enabled is false, ignored.。URL 安全校验非本地绝对路径的 url 必须通过validate_url_scheme的 HTTP(S) 安全检查javascript:等危险 scheme 直接抛错见 UserMaterial 模型校验 与对应单测test_requires_content。配置映射user_materials_enabled/user_materials同时存在于 config/config.py 的运行时配置中search_context侧字段定义见 search_context.py。三、素材生命周期总览素材从进入请求到出现在报告正文共经历四个阶段无独立信息盘点节点StartNode只把原始素材转存进search_context.user_materials不做校验、去重、摘要或筛选。IntentRecognitionNode集中完成校验、去重、数量限制、摘要与相关性分析产出search_context.material_analysis。Outliner / Planner提纲为每章写入material_bindingsPlanner 声明use_material_ids规划补充检索范围。Collector / Writer按章节绑定把素材合并为可溯源证据进入写作Supervisor把绑定素材当作既有证据只补缺口不新增 LLM 调用。四、预处理管线源码深读校验、去重与摘要预处理核心实现位于 algorithm/query_understanding/material_processing.py入口函数为prepare_material_analysis。它依次完成四件事规范化与去重 → 摘要带缓存→ 注入预算降级。4.1 校验与去重三键判重软上限 50 条normalize_user_materialsL201-L265对每条素材逐一校验并按下述三个键判定重复任一命中即丢弃显式material_id重复duplicate_material_id规范化 URL 重复duplicate_url本地路径原样使用HTTP(S) 链接经canonicalize_url规范化正文哈希重复duplicate_contentcontent_hash取正文 SHA-256 前 16 位关键设计是**标题相同但正文不同的素材会保留**——因为标题不是判重依据只有显式 ID、规范化 URL 或正文哈希相同才视为重复。这正是文档所述规则的源码落地对应测试 test_material_processing.py::TestNormalizeUserMaterials 中的test_keeps_same_title_when_contents_differ。去重后按输入顺序保留前 50 条常量MATERIAL_MAX_COUNT 50超出部分记入dropped观测记录仅含index/reason/has_url/has_title/has_content不落原文不报错、不阻断主流程。4.2 不以词面零重叠删除素材filter_materials_by_queryL362-L371当前实现为保留全部素材、返回空丢弃列表——它故意不删除任何素材。原因是词面零重叠不能证明素材与 query 无关同义改写或跨语言素材如中文 query 配英文论文在语义判断前被删除是错误行为。词面相关性仅保留在rank_materials_by_query按 query 与素材的 token 重叠度打分 0~1中只在超出注入预算时用于排序。对应测试test_keeps_cross_language_materials_for_intent_recognition与test_keeps_lexically_unrelated_materials_for_semantic_assessmenttest_material_processing.py。4.3 摘要分流直通 / 单篇摘要 / 篇内 map-reduce摘要按素材 token 长度分三条路径prepare_material_analysis 摘要段原文直通≤ 4000 tokensummary_kind fulltext不调用 LLM原文直接注入。对应测试test_short_content_direct_fulltext_without_llm断言mock_invoke.assert_not_called()。单篇摘要≤ 96000 token 输入预算summary_kind summary一次 LLM 调用完成。篇内 map-reduce超过单次上限按 64000 token 分块、512 token 重叠切分逐块摘要后调用material_reduce_summaries合并成最终摘要。摘要永远单篇独立调用绝不跨篇混合。相关的关键常量material_processing.py 头部常量默认值含义MATERIAL_DIRECT_TOKEN_LIMIT4000原文直通阈值MATERIAL_SINGLE_CALL_TOKEN_LIMIT96000单次 LLM 摘要调用输入上限MATERIAL_CHUNK_TOKEN_LIMIT64000map-reduce 单块 token 上限MATERIAL_CHUNK_OVERLAP_TOKENS512分块重叠 token 数MATERIAL_SUMMARY_MAX_TOKENS4000摘要输出上限MATERIAL_INJECTION_BUDGET_TOKENS200000素材注入 prompt 的总预算MATERIAL_MAX_CONCURRENCY5多篇素材摘要并发上限MATERIAL_MAX_COUNT50去重后保留条数软上限MATERIAL_DIGEST_CHARS160digest 降级单行保留字符数4.4 摘要缓存与降级兜底content_hash 跨轮复用_merge_cached_summaries按正文哈希命中上一轮MaterialAnalysis.items的摘要多轮澄清、大纲交互、用户反馈重新进入意图识别时不重算摘要。对应测试test_reuses_cached_summary_by_content_hash断言 mock 未被调用。预算降级 digest当注入 token 总量超过 200000 预算时按与 query 相关性排序落选素材被确定性降级为 160 字符的单行 digestsummary_kind digest不依赖 LLM素材 ID 记入downgraded_ids。测试test_downgrades_over_budget_to_digest验证了降级行为。摘要失败兜底 truncatedLLM 摘要异常时改为头部截断summary_kind truncated绝不阻断主流程敏感日志模式下错误详情被脱敏。4.5 manifest 永不压缩build_material_prompt_contextL406-L456生成两类注入内容manifest 清单区每条素材的[ID] title... | url... | publish... | content...逐字保留永不摘要压缩保证标题、链接、时间等逐字标识符不丢失分析区注入各素材的 summary 正文。消费方若只需清单与结论如大纲、规划可传include_analysisFalse避免摘要正文占用 prompt 预算——这也是 main_graph_nodes.py L1212-L1218 中大纲/规划消费路径的做法。五、意图识别material_relevance_map 与使用策略5.1 零额外调用的相关性分析意图识别的既有 LLM 调用同时输出material_relevance_mapintent_recognition.py 工具 schema为每条相关素材输出relevancedirect/partial/contextual/irrelevantsupported_claims可支持的论点含 claim、scope、evidence_excerpt、confidencelimitations范围/局限research_gaps待补研究缺口由于挂接在既有意图调用上不增加额外 LLM 调用次数。apply_material_relevance_map会按已知素材过滤映射并把evidence_quality标注为素材实际注入形态fulltext/summary/digest/truncated。5.2 保守回退映射当意图工具未返回material_relevance_map时build_fallback_material_relevance_mapL495-L511为保留素材生成保守回退记录relevance 一律contextual、无supported_claims、research_gaps标记为需要验证。回退记录不会被build_section_material_coverage判定为覆盖充分见测试test_fallback_relevance_does_not_mark_coverage_sufficient从而避免在缺少语义验证的情况下跳过检索。5.3 material_first明确肯定才启用is_material_first_requestL459-L483只在用户以明确肯定方式要求基于/总结所提供素材时返回 True中文标记如基于我提供/基于提供/提供的论文/所提供的材料/总结里面的内容/仅根据英文覆盖美式与英式拼写provided material / summarize the provided / summarise the provided。判定逻辑会检查标记词前 32 字符内是否出现否定词不要/不用/不基于/并非/而不是/拒绝/排除/忽略 / do not / dont / rather than / without using 等——不要基于提供素材这类否定表达不会启用。对应测试test_negated_material_first_request_is_not_required与test_material_first_markers_cover_british_and_american_spellingtest_material_processing.py。resolve_material_usage_mode将策略固化为三态none无素材/required素材优先/supplementary补充使用并随material_analysis一起透传给 Planner、Collector Supervisor 与写作阶段。六、从提纲到写作素材证据的流转与规范化6.1 提纲material_bindings 是素材使用的唯一事实来源预处理结果写入search_context.material_analysis后直接透传到专业版和 Brief 的提纲、章节规划及报告写作。提纲阶段brief_report/outline.py调用normalize_material_bindings清洗 LLM 输出的章节绑定过滤未知素材 ID、按已知清单白名单校验、去重并派生use_material_ids。outliner/brief_outliner的 prompt 通过user_materials count{{ materials_count }}区块注入素材清单见 prompts/outliner/user.md。6.2 ID 规范化[M1]还原为M1大纲生成后的素材 ID 会按预处理清单规范化normalize_material_idL609-L622剥离一个或多个外层方括号对[M1]→M1仅接受与已知 ID 的无歧义精确匹配避免 LLM 把 prompt 中的括号写法带进结构化输出。6.3 Planner只声明已知 use_material_idsPlanneralgorithm/query_understanding/planner.py的generate_plan工具 schema 始终声明use_material_ids字段无素材时提示留空有素材时提示Only choose from the provided material IDs (...); do not invent IDs。三重重保底逻辑L296-L301幻觉过滤LLM 输出的 ID 若不在已知清单中会被清除test_planner_filters_hallucinated_material_ids无声明清空未声明素材时幻觉输出统一清空而非报错test_planner_clears_material_ids_without_declaration绑定继承模型漏声明时若存在章节绑定bound_material_idsPlanner优先继承章节绑定test_planner_uses_bound_material_ids_when_model_omits_them。对应测试文件为 tests/algorithm/query_understanding/test_planner_materials.py。6.4 写作阶段把声明素材合并为可溯源证据专业版写作节点algorithm/report/report.py L486-L541通过resolve_material_evidence按规划声明解析素材优先使用 Planner 的use_material_ids否则从章节material_bindings派生 ID 并精确过滤没有绑定时不并入素材避免把无关素材塞进章节证据。合并后以user_material为source、url/publish_time/content_time保留溯源元数据的证据条目进入写作上下文。同时format_section_material_bindings把当前章节的素材使用契约role、allowed claims渲染给 writer promptwriter.py。build_section_material_coverageL514-L571为章节生成确定性的覆盖审查素材可用有注入内容、有可用论点、无研究缺口、且相关性为direct/partial四项同时满足才判为covered任一不满足即needs_reviewPlanner 只对这些缺口发起检索。无效绑定不会静默导致空素材章节——素材覆盖章节会回退注入可用素材。七、专业版 vs Brief联网检索的取舍规则两种报告形态对素材优先的处理略有差异共同目标是不增加 LLM 调用次数Brief 报告brief_report/collector.pymerge_material_evidenceL268-L317按章节material_bindings精确并入素材证据素材文档以user_material:{id}作为source_id进入selected_docs并置顶evaluation_rank1网页证据作为补充保留无绑定的章节不使用用户素材。对应测试 tests/brief_report/test_material_merge.py 的test_merge_routes_relevant_materials_and_appends_registry验证了素材优先、网页补充、无绑定不注入三条行为。查询生成阶段若material_first且无网页缺口直接返回空查询并记日志[MATERIAL_FIRST] no web gaps found; skip web search and write from user materials.collector.py L69-L73随后initialize_empty_web_evidence为素材章节预置空网页证据允许空检索并直接进入素材合并和写作。专业版只有同时满足以下条件才允许跳过联网检索main_graph_nodes.py 意图后处理material_first成立即使用策略为required章节绑定素材的相关性为direct或partial素材具备可用论点没有研究缺口。否则Supervisor 将绑定素材作为既有证据只对素材未覆盖的缺口补充网页检索不会增加新的 LLM 调用。八、可观测性MATERIAL_ROUTE 日志与验证8.1 日志字段系统在素材路由关键节点输出[MATERIAL_ROUTE]日志便于验证素材是否实际进入写作[IntentRecognitionNode] materials prepared: items%d cached_reuse%s downgraded%d[MATERIAL_ROUTE] intent omitted relevance map; generated %d fallback records.[MATERIAL_ROUTE] section%s declared%d resolved%d material_docs%d web_docs%d ids%sBrief collectorcollector.py L311-L317[MATERIAL_ROUTE] material-bound outline produced no selected material evidence.绑定后无素材证据时的错误级告警日志包含每章节声明、解析到的素材数、素材/网页证据数和素材 ID可据此验证素材是否真正进入写作。8.2 官方验证命令uv run pytest tests/algorithm/query_understanding/test_material_processing.py uv run pytest tests/algorithm/query_understanding/test_planner_materials.py uv run pytest tests/brief_report/test_material_merge.py其中test_material_processing.py共覆盖 token 估算与哈希、素材校验、去重与 50 条软上限、prompt 上下文构建、usage 策略判定、证据条目构建、分块切割CJK/混合文本/超长句保真、缓存复用、预算降级与失败兜底等场景prompt 契约测试 tests/algorithm/prompts/test_deepresearch_prompt_contracts.py 还验证了planner/outliner/brief_collector_query_generation/dep_driving_planner等模板的素材相关字段完整性。九、设计要点与边界防提示注入素材文本仅作为资料注入prompt 声明不执行素材中的指令见 material_processing.py 模块 docstring。无信息盘点节点提纲和规划直接使用已筛选的素材清单并按需补充检索没有盘点状态机。不新增 LLM 调用相关性分析挂接既有意图调用Supervisor 只补缺口摘要缓存跨轮复用均为零额外调用设计的落地。确定性降级预算超限的 digest 降级、摘要失败的 truncated 兜底均不依赖 LLM 二次调用保证主流程健壮。权限边界素材正文以调用方传入为准url仅作标识从源头规避了依据 URL 抓取正文带来的安全与合规风险URL 同时接受本地绝对路径与经过 scheme 校验的 HTTP(S) 链接两种形态共用同一套去重与溯源机制。整体而言用户素材机制把用户已有资料以证据形式无缝接入 openJiuwen DeepSearch 的深度研究管线既保证了素材在提纲、规划、写作各阶段的可溯源性又通过 usage 策略与缺口审查在素材优先与联网补全之间取得平衡是一套可直接用于生产的知识增强研究输入方案。赞分享人工智能大模型AI AgentRAG深度研究搜索引擎后端代码智能体【免费下载链接】deepsearchopenJiuwen DeepSearch是一款知识增强的深度搜索与研究框架有业界领先的片段级引用和溯源推理能力提供精准Agentic搜索与研究能力项目地址https://gitcode.com/openJiuwen/deepsearch点击查看免费下载相关推荐openJiuwen DeepSearch 全局溯源 Citation 校验机制解析从引用解析、LLM 验证到前端数据组织openJiuwen DeepSearch 全局溯源 Citation 校验机制解析从引用解析、LLM 验证到前端数据组织 全局溯源是 openJiuwen人工智能大模型AI AgentRAG深度研究搜索引擎后端代码智能体openJiuwen DeepSearch 来源匹配Source Matching机制深度解析从句子到证据的精准溯源openJiuwen DeepSearch 来源匹配Source Matching机制深度解析从句子到证据的精准溯源 本篇技术指南围绕 openJiuwe人工智能大模型AI AgentRAG深度研究搜索引擎后端代码智能体openJiuwen DeepSearch 局部溯源Local Source Trace改写后差异感知 citation 更新机制深度解析openJiuwen DeepSearch 局部溯源Local Source Trace改写后差异感知 citation 更新机制深度解析 导读 局部溯源人工智能大模型AI AgentRAG深度研究搜索引擎后端代码智能体上一篇MoveCertificate常见问题解决20个疑难杂症处理方法下一篇WebLlama错误处理与调试解决常见问题的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考