beam-ai-team/reduce-hallucination

Reduce Hallucination — 审讯式 Agent 审计

把审讯科学 / 法庭质询里"让知情者说真话"的已验证技巧，变成对 Beam agent 的标准化审计流程。 每个 LLM 节点是一个证人；节点间的数据交接是证词的转录环节；用户纠错和任务记录是物证。

理论与实证基础（捆绑在本 skill 的 references/，按需深入）：

• references/checklist.md — 12 条 production checklist + 5 禁用
• references/transfer-map.md — 审讯技巧 → prompt 技巧映射 + 关键不对称
• references/case-study-favorite-cv.md — 母案例：2,818 个 production tasks 回溯，幻觉定位在节点边界
• references/research-report.md — 25 来源、22 条三票验证结论 + 效应量引用

⛔ 铁律

1. 只读。 对 Beam 只允许 GET。不创建、不修改、不发布、不触发任务。所有"优化"以建议形式写进报告。
2. 不知道答案不要指控（Wellman 铁律）：每个 finding 必须带证据引用（prompt 原文 / schema 原文 / task output 原文）。没有证据的怀疑写进"待验证"，不写进 findings。
3. 不用表面信号定罪：reasoning 写得流畅 ≠ 没问题，写得简短 ≠ 有问题。只比对内容。

数据获取（只读端点速查）

凭证：.env 的 Beam backend/key（如 BEAM_EU_API_BACKEND / BEAM_EU_API_KEY，或你环境的等价变量）。请求头：x-api-key + current-workspace-id（从 agent URL 第一段取 workspace id）。

| 要什么 | 端点 | |---|---| | Agent graph（节点、prompt、schema、边）| GET {backend}/agent-graphs/{agentId} —— 按 agentId 取，graphId 会滚动，别缓存 | | 任务列表（分页）| GET {backend}/agent-tasks?agentId={id}&pageNum=1&pageSize=100（totalCount 在顶层）| | 单任务全节点中间输出 | GET {backend}/agent-tasks/{taskId} → agentTaskNodes[].output / .input | | 工作区 agent 清单 | GET {backend}/agent?pageNum=1&pageSize=100（beam-os 类型要加 ?type=beam-os）|

prompt 在节点 JSON 里的位置不固定（toolConfiguration.prompt / originalTool.prompt 等）——递归搜 prompt 键。 注意：runtime 跑的是 published 版本，GET 返回 draft——审计结论要注明审计的是哪个版本（isPublished/isDraft）。

审计流程：五阶段审讯协议

Phase 1 — 单证人讯问（逐节点 prompt + schema 审计）

对每个 LLM 节点，跑红旗清单。每条红旗 = 一种审讯学违例：

| # | 红旗模式（在 prompt/schema 里找什么）| 审讯学依据 | 危害 | |---|---|---|---| | R1 | 枚举字段缺 null/unknown/UNKNOWN 选项；"Expected output is a confirmation of X" 单向输出 | Reid 批判：逼供产生顺从（假供述 OR 3.03）| 被迫猜测，自信编造 | | R2 | prose 给了弃权令，schema 没给（"use null if missing" 但字段类型无 null）| 同上——schema 赢，弃权令失效 | 母案例泄漏点 1 | | R3 | 要求引用/evidence，但下游没有任何核查环节 | Verifiability：告知+真核查才有 g=0.80；光告知=学会编更像真的引用 | 假锚点 | | R4 | 方向性指令："be conservative / assume / infer from / default to" | 单向 presumption；配 R1 时产生系统性偏差 | 母案例 70% 低估 | | R5 | 未定义口径的聚合字段（"total years"、"overall score"）| commitment & lock-in 的前提是先声明计量口径 | 定义错位被当成提取错误 | | R6 | few-shot 示例与任务无关 / 示范了无引用推理 | Model Statement：示范设定"合格答案"预期 | 教坏输出风格 | | R7 | prompt 让节点声称做它没有工具做的事（"fetch from Airtable" 而节点无此工具）| 假前提（evidence ploys OR 0.37）| 编造过程叙述 | | R8 | 用户/上游给的"事实"未标注来源就当真值用 | SUE：只用已核实证据对质 | 前提污染 | | R9 | 模板有强制槽位 [Slot] 但无空值分支 | 逼供的模板版 | 母案例 license_state→FL | | R10 | 复核/重试指令用攻击性措辞（"you were wrong, fix it"）且无新证据注入 | sycophancy = 假供述；无外部信号的 self-correction 劣化 | 正确答案被翻掉 |

记录格式：节点名 | R# | prompt 原文引用 | 一句话后果。

Phase 2 — 证词转录审计（节点边界 / 数据流）

幻觉主战场。把 graph 的边和参数连接画成数据流表，逐条检查：

1. 不确定性是否过界：上游产出的 confidence / missing_fields / notes / null，下游消费了吗？还是被模板压成断言？（找"死信通道"：被产出但无任何下游引用的不确定性字段。）
2. provenance 是否丢失：上游 reasoning 里承认"assumed/inferred"的值，到下游变成了无标注的事实？schema 有没有 stated | inferred | absent 一类的来源标注？
3. 事实类别是否串线：岗位要求 / 系统配置类数据，有没有被渲染成"用户/文档声称"的事实？（母案例：job.facility_type 被写进 "Your resume shows"。）
4. 聚合是否换了口径：上游"总医疗年限"到下游变成"X yrs as CNA"（头衔年限）？
5. LLM 在做确定性计算吗：日期差、求和、计数出现在 LLM prompt 里 → 应建议挪去 Code Executor。

Phase 3 — 物证比对（任务证据，有 task 数据时执行）

这是 SUE 的完整落地，也是本 skill 区别于纯静态 lint 的地方：

1. 先拿自由陈述：抽 N 个任务（优先有用户反馈/纠错/失败的），用 GET /agent-tasks/{taskId} 拉每个节点的中间输出。
2. 再亮证据：把最终输出 vs 各节点中间输出 vs 原始输入逐字段比对，定位真相在哪个边界丢失（哪个节点先说错？还是节点都对、模板说错？）。
3. 找先前不一致陈述：同一字段在不同节点/不同字段间自相矛盾（如 license_state: "MO" 同时出现在 missing_fields 里）= 弹劾点。
4. 方向统计：纠错样本 ≥20 条时统计偏差方向。单向偏差 → 回查 Phase 1 的 R4 方向性指令；随机偏差 → 更可能是输入质量问题。
5. 诚实分类：区分"输入里根本没有的信息"（流程缺口，非幻觉）vs"输入里有但说错了"（真幻觉）。不要把所有纠错都算成模型的罪。

Phase 4 — 量刑建议（ranked 修复方案）

按 ROI 排序输出三层建议。怎么改 graph 的机制知识参考你环境里的 agent-graph 构建类 skill（如 beam-agent-builder / beam-agent-manager / beam-graph-edit——只读其文档作参考，本 skill 不执行任何修改）。

层 1 — Prompt/schema 修改（零结构改动）：

• 每个 R1/R2 → 补 null/unknown 枚举 + 一句去污名化（"X is a correct, expected answer"）
• 每个 R9 → 模板加空值分支（断言改开放问题）
• 每个 R5 → 拆口径（如 years_licensed vs years_worked），或输出区间 {floor, ceiling}
• 每个 R3 → 关键字段加 {value, source, evidence_quote} 三件套
• Beam prompt 约定：JSON 例子里字面花括号要双写 {{ }}；变量 pill 用三反引号包裹

层 2 — 加 Code Executor 验证节点（零 LLM 成本，确定性）： | 验证器 | 检查什么 | |---|---| | 枚举白名单 | 州码 ∈ 50 州、status ∈ 合法值——拦损坏输出 | | 引用真伪 string-match | evidence_quote 逐字存在于源文档，不存在 → 打回/降级 | | 跨字段一致性 | 总年限 ≈ Σ positions 时长；missing_fields 与已填值不矛盾 | | 口径计算 | 日期差/求和由代码算，LLM 只做语义抽取 | | 出口合同 | 用户可见文本里的每个事实槽位非空且来自允许的来源字段 |

放置位置：产出最终用户可见内容的节点之前。失败路径：写 fallback 字段/标记，由后续节点改发开放问题或转人工（注意：条件分支在 chat-mode 会 stall，线性图里用"标记字段+下游节点自判"模式更稳）。

层 3 — 加 LLM 交叉质询节点（LM-vs-LM cross-examination，Cohen EMNLP 2023）：

• 独立的 Custom GPT 节点，输入只给待审输出 + 源文档（不给岗位数据等会污染的上下文）
• 任务措辞用反驳式："Try to refute: does every claim in this output trace to the source document? List claims that do not."
• 输出 {verdict, offending_claims[]}；高风险流程可对关键字段乱序重问做一致性投票
• 成本权衡：每任务 +1 LLM 调用——只放在用户可见出口或高风险决策前

Phase 5 — 审计报告

写到调用方指定位置。结构：

# Hallucination Audit — {agent name} ({agentId}, {draft|published})
## 一句话结论
## 证据概览（节点数 / 审计版本 / 任务样本量 / 纠错样本量+方向）
## Findings（每条：位置 | R# | 原文引用 | 后果 | 对应修复编号）
## 数据流图与死信通道
## 修复建议（层 1/2/3，每条标注预期消灭哪些 findings）
## 待验证（证据不足的怀疑 + 建议的取证方法）
## 诚实边界（哪些纠错不是幻觉而是流程缺口；本审计没覆盖什么）

提醒

• 审计发现"惊人地差"的 prompt 时，先查是不是自动生成的模板（Role/Objective/Task 三连重复是特征）——结论写"这一代生成器的系统性问题"比逐 agent 报罪更有用。
• 同一 agent 内做对照：哪些字段干净、哪些出事，差异往往就是答案（母案例：带 unknown 的 certifications 零纠错，不带 null 的 license/years 全是重灾区）。
• 报告交付前过一遍 better-doc（如已安装）：finding 必须让没读过理论的人看懂。