夜雨聆风Codex 的深度调研插件，连一行代码都没有
约 2304 字·阅读 6 分钟
打开 deep-research 插件的目录，我找了个遍——没有 scripts 文件夹，没有 .mjs，没有 .py，没有任何可执行代码。
只有一个 SKILL.md 和两份 references 文档。
7 个插件里，它是唯一一个零代码的。不操控浏览器，不操控桌面，不生成 HTML，不编译 LaTeX。它做的事情是——让 AI 像真人分析师一样做多轮深度调研，最终交付一份有出处、可审计的 DOCX 报告。
没有代码，全靠一份方法论文档把 AI 训练成分析师。
· · ·
01
协调者加 worker，关注点分离
SKILL.md 里最关键的设计是主从 agent 架构。协调 Agent 负责拆解问题、定边界、写 worker 的任务书、关键论点抽检、调和矛盾、最终综合加生成 DOCX、渲染校验。调研 worker 专职做多轮搜索、维护证据账本、标记矛盾和不确定性，返回草稿加账本加信心度。worker 被明确禁止生成最终 DOCX。
为什么不让一个 AI 一口气干完？因为单 AI 容易"沉没成本"——搜了几条就开始写。拆成两层后，worker 专心搜，不受"要交差"的压力影响，能反复迭代到证据充分。coordinator 专心综合，抽检关键论点，防止 worker 被某个错误来源带偏。
这其实是软件工程里 关注点分离 在 AI 工作流里的应用。
· · ·
02
至少两轮，用信号判断什么时候停
SKILL.md 里有一条硬性规定：
Require at least two passes: broad discovery, then targeted follow-up on gaps, contradictions, recency, and stronger primary evidence.
第一轮广度发现，摸清楚这个领域有哪些主张、哪些利益方、哪些术语、哪些分歧。建立一个 gap matrix——每个论点对应的当前证据、置信度、缺什么、下一步查什么。第二轮定向追查，针对 gap matrix 里最薄弱的点，去找更强的原始证据、更新的数据、不同角度的来源。
什么时候停？research-method.md 给了一个非常工程化的判据——当所有章节都有充分证据、关键论点都有原始来源、剩余矛盾已解决或已明确划界、最近几轮定向查询大多返回重复或更弱的来源、再来一轮不太可能改变结论时，停止。
用可观察的信号判断"够了"，而不是凭感觉。让 AI 在长任务里有明确的停止判据，否则它要么过早收尾，要么无限搜下去。
· · ·
03
证据分级：来源等级不等于契合度
research-method.md 给了来源等级表——原始研究和官方数据集排第一，高质量独立分析排第二，专家评论排第三，论坛和社交帖子只能当"标注过的轶事"。
但有一句话特别重要：
Source rank is not a substitute for claim fit.
来源等级不能代替"来源是否契合论点"。一个不契合的原始来源，可能比一个契合的二级来源更弱。你要查"2024 年某政策的影响"，找到一份 2018 年的原始法规文件——它是原始来源，但时间不对，反而不如一份 2024 年的靠谱分析报告。教 AI 评估信息可信度时，不仅要分等级，还要教它判断时间、地域、口径、版本是否对得上。
· · ·
04
双轨引用：机器账本加人类脚注
deep-research 把引用分成两套。
内部账本 report-source.md 是给机器和审计用的——每个有出处的论点都能追溯到来源，保留原始的工具引用语法（比如搜索工具的内部 ID），是评估审计回溯用的侧车，不交付给用户。
DOCX 里的引用是给人看的——用 Word 原生的脚注或尾注，包含来源标题、出版方作者、日期、可点击的 URL，绝不泄露内部工具引用 ID。
机器审计需要工具 ID 方便回溯到具体哪次搜索，人类读者只关心可读的出处。把两类信息物理分离，既保证可审计性，又保证可读性。
· · ·
05
保留矛盾，不要和稀泥
LLM 有个倾向：看到互相矛盾的来源，会自动"和稀泥"，编出一个看似合理的折中答案。deep-research 明确禁止这么做：
Preserve material disagreements, inaccessible evidence, stale evidence, and uncertainty instead of smoothing them away.
对每个实质性矛盾，先核对两个来源用的是否是同样的定义和时间窗口，检查是否一个来源更新或取代了另一个，识别动机、方法、样本量、缺失的上下文，明确说哪种解释最被支撑、为什么。无法解决时就保留分歧。
让 AI 输出研究报告时，诚实标注"我不知道"和"这里存在分歧"，比编造一个自信的答案更有价值。这种诚实不是靠模型自觉，是靠工作流强制实现的。
· · ·
06
渲染后逐页 100% 缩放检查
这一段让我眼前一亮。SKILL.md 要求：
Render the DOCX and inspect every page at 100% zoom. Iterate until clean.
AI 不能"写完 DOCX 就交"，必须把 DOCX 渲染成一页一页的图片，然后真的"看"一遍，检查有没有文字溢出、表格断裂、奇怪的换页、缺字符、引用错位。如果 LibreOffice 不可用无法渲染，要走结构化 QA 兜底，并且必须明确告诉用户"视觉校验没完成"。
生成文档类产物时，让 AI 自己渲染成图片再检查一遍，是发现排版问题的最佳手段。校验没做完就要明说，不要含糊其辞。
· · ·
07
失败契约：诚实降级
SKILL.md 末尾有一段 Failure Contract——DOCX 生成失败就报告阻塞点加保留笔记，不许静默替换成别的格式（比如偷偷给个 Markdown）。研究访问不完整还是出 DOCX 但标注限制加降低置信度。没真渲染过就不许说"已视觉验证"。
给 AI 写一份失败契约，明确各种失败场景下应该怎么诚实降级，比让 AI 自己决定怎么处理失败可靠得多。
还有个微妙的细节——SKILL 提到理想情况下调研 worker 也应该用最高推理强度 xhigh，但如果底层 API 不支持给子 agent 单独设推理强度，AI 绝不能谎称"子 agent 也用了 xhigh"。让 AI 不要谎称自己用了某种它实际没用的能力，这种诚实声明是建立用户信任的关键。
deep-research 自己不生成 DOCX，依赖另一个叫 $documents 的技能。插件要 _单一职责_，能力互补靠组合，而不是每个插件都自己造一遍轮子。
· · ·
08
为什么这篇文章值得你转发
deep-research 插件整个目录里没有一行可执行代码。它用一份纯文本的工作流方法论，通过主从架构、强制多轮迭代、来源分级、双轨引用、矛盾保留、渲染校验、失败契约七层设计，把 AI 训练成一个可信、可审计、不幻觉的研究分析师。
它证明了一件事：在 AI 应用里，清晰的规范本身就是一种产品。
如果你在做需要 AI 输出研究报告或长文档的产品，这套方法论直接抄作业就行。你的 AI 产品里，怎么防止 AI 幻觉和和稀泥？ 评论区聊聊。顺手转发给也在搞 AI agent 工作流的朋友。
· · ·
「拆解 Codex 7 大插件」系列 · 第 7 篇 · 共 9 篇下一篇：Codex 的 latex 插件自带了一个编译器，但克制才是它真正的设计。
感谢关注