beam-ai-team/reduce-hallucination-archived

Reduce Hallucination — 审讯式 Agent 审计

Archived duplicate. Kept for reference only; the active maintained version lives at skills/beam/beam-tools/reduce-hallucination.

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

Safety Contract

This skill is read-only for Beam state. Before fetching task evidence or writing an audit report, show the workspace, agent ID, API host, task sample size, destination path, and whether customer/task data will be included. Require explicit user approval in the current turn before exporting reports outside the local workspace. Do not create tasks, update prompts or schemas, publish graphs, trigger runs, or modify Beam data from this skill.

理论与实证基础（先读，按需深入）：

• 03-projects/06-reduce-hallucination/04-outputs/checklist.md — 12 条 production checklist + 5 禁用
• 03-projects/06-reduce-hallucination/04-outputs/transfer-map.md — 技巧映射 + 关键不对称
• 03-projects/06-reduce-hallucination/04-outputs/case-study-favorite-cv.md — 本 skill 的母案例（2,818 tasks 回溯）
• 03-projects/06-reduce-hallucination/02-resources/research-report.md — 引用与效应量

⛔ 铁律

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

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

凭证：.env 的 BEAM_{EU,US,BID}_API_BACKEND / _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 的机制知识参考 beam-agent-builder（只读它的文档，不执行 build）： skills/general/beam-agent-builder/references/node-authoring.md（节点/参数机制）、 references/_steering/topology-shapes.md（拓扑）、prompt-best-practices.md（Beam prompt 约定：JSON 例子双花括号、变量 pill 三反引号）、beam-reality.md（平台坑：published vs draft、linked-param 字段、conditionNode 限制）。

层 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} 三件套

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

放置位置：产出最终用户可见内容的节点之前。失败路径：写 fallback 字段/标记，由后续节点改发开放问题或转人工（注意 beam-reality.md：条件分支在 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 — 审计报告

写到调用方指定位置（默认当前项目 03-working/ 或新建 03-projects/.../）。结构：

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

提醒

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