Extraction & Evidence
Extraction & Evidence
1. 目标 & 范围
目标：为 AgentSurvey 提供可信、可审计的结构化抽取能力——每个输出字段携带置信度、原始证据引用及审核状态，使研究人员能追溯每条结论的来源，并在必要时进行人工修正。
核心价值：AgentSurvey 的差异化卖点之一是”带证据链的结构化研究输出”（见 00_overview 第 1 节），本模块是该卖点的技术落地。
范围：
- 抽取触发时机（real-time / checkpoint / post-session）
- 字段输出结构（
ExtractedField）与证据结构（EvidenceRef） - 置信度阈值与
needs_review判定规则 - 人工修正与修正历史记录
- 抽取可重跑（幂等性、schema version 绑定）
不在范围：
- 跨 session 的 Insight 聚合（属于结果展示，见 07_results_review）
- Output Schema 的创建与版本管理（见 03_study_builder）
- 结果导出格式（见 07_results_review）
2. 用户故事
作为 researcher，我希望每个抽取字段都能链接到原始对话 turn 或工具调用结果，以便在向团队汇报或复核时不必重看完整 transcript。
作为 researcher，我希望置信度低或证据薄弱的字段自动标记为 needs_review，以便集中精力修正最不确定的结论，而不是逐条翻看。
作为 researcher，我希望能对系统抽取的字段值进行人工修正并保留修正历史，以便保持输出的准确性，同时留下可追溯的 audit trail。
作为 researcher，我希望在 study schema 升级后能对已有 session 重跑抽取，以便新旧 session 的结果可以在同一 schema 下比较。
作为 admin / developer，我希望能查看每次抽取使用的模型与 schema 版本，以便排查结果异常时定位根因。
3. 功能需求
FR-06-1 实时抽取（Real-time Extraction）
优先级：P0
在每次用户消息处理后，Harness 触发轻量抽取，更新当前 SessionState 中的字段覆盖状态与 coverage 置信度。
验收要点：
- 仅更新 in-memory session state，不写入
extracted_fields表终态记录。 - 抽取结果反映到 coverage 判断，Agent 可据此决定是否追问（见 04_interview_runtime）。
- 实时抽取失败不阻断访谈流程，fallback 为 post-session 抽取。
FR-06-2 Checkpoint 抽取
优先级：P1
研究人员可在 output schema 字段上配置 extraction_hint 与所属 objective；当某 objective 状态变为 covered 时，Harness 触发 checkpoint 抽取，将该 objective 关联字段写入 extracted_fields（status = draft）。
验收要点：
- Checkpoint 抽取结果状态为
draft，不覆盖已有accepted记录。 - 同一字段在 post-session 抽取后，以 post-session 结果为准（status 可覆盖 draft）。
- Checkpoint 抽取绑定当前
schema_version_id，记录extracted_by = "agent"与model。
FR-06-3 Post-Session 终态抽取
优先级：P0
访谈结束后（session status = completed），系统对完整 transcript 执行一次终态抽取，为 output schema 中所有字段生成 ExtractedField 记录。
验收要点：
- 触发时机：session 进入
completed状态后自动触发，或研究人员手动触发。 - 所有
required = true的字段必须生成记录（即使 value 为 null，status 为needs_review）。 - 每条记录写入
extracted_fields表，并关联evidence_refs。 - 抽取完成后，session 对研究人员可见（结果状态）。
FR-06-4 ExtractedField 输出结构
优先级：P0
每个抽取字段须包含以下完整结构，与 04_structured_outputs_evidence 中 ExtractedField 类型定义一致，并持久化至 extracted_fields 表（见 03_data_model）：
| 字段 | 类型 | 说明 |
|---|---|---|
id | UUID | 记录主键 |
session_id | UUID | 所属 session |
study_id | UUID | 所属 study |
schema_field_id | TEXT | output schema 字段 ID |
field_name | TEXT | 字段名称 |
value | JSONB | 抽取原始值 |
normalized_value | JSONB | 规范化值（可选，用于 enum/数值类型） |
confidence | NUMERIC | 0–1 置信度 |
status | TEXT | draft / accepted / rejected / needs_review |
extracted_by | TEXT | agent / post_processor / human |
model | TEXT | 执行抽取的模型标识 |
schema_version_id | UUID | 绑定的 output_schema_versions.id |
reasoning_summary | TEXT | 抽取推理摘要（可选） |
验收要点：
- 所有字段均持久化，不仅存于 session state。
schema_version_id不得为空，确保可重跑时版本可追溯。reasoning_summary在 post-session 抽取时必须生成。
FR-06-5 EvidenceRef 证据结构
优先级：P0
每个 ExtractedField 至少关联零条或多条 EvidenceRef，证据记录持久化至 evidence_refs 表。
| 字段 | 类型 | 说明 |
|---|---|---|
id | UUID | 证据主键 |
extracted_field_id | UUID | 关联的字段 |
session_id | UUID | 所属 session |
turn_id | UUID | 关联的 transcript turn（可选） |
tool_call_id | UUID | 关联的工具调用（可选） |
quote | TEXT | 原始引用文本 |
evidence_type | TEXT | user_quote / tool_selection / system_observation / uploaded_artifact |
strength | TEXT | strong / medium / weak |
证据质量等级定义（来源：04_structured_outputs_evidence）：
| 等级 | 定义 |
|---|---|
strong | 用户明确表述或明确选择 |
medium | 可由上下文合理推断 |
weak | 间接或不完整证据 |
验收要点：
evidence_type与strength均不得为空。turn_id与tool_call_id至少一个有值（system_observation类型除外）。quote字段内容须与transcript_turns.content或tool_calls.tool_output中的文本可对应。
FR-06-6 置信度阈值与 needs_review 判定
优先级：P0
系统在生成 ExtractedField 时，依据以下任意一条规则将 status 设为 needs_review：
confidence低于该字段OutputSchemaField.confidence_threshold（默认 0.75）。required = true且evidence列表为空。- 所有关联
EvidenceRef的strength均为weak。 - 同一 session 中不同 turn 对该字段有明显矛盾表述（由抽取模型判断并在
reasoning_summary中说明）。 - 字段值不符合
OutputSchemaField.type或enum_options约束。 - 受访者在 summary confirmation 阶段明确否认该结论（turn 被标记）。
OutputSchemaField.review_policy = "always"。
验收要点：
- 上述 7 条规则中任意一条触发，status 必须为
needs_review，不得为accepted。 - 规则 1–6 须在 post-session 抽取时自动评估，不依赖人工触发。
review_policy = "never"时仅跳过规则 7，其余规则仍生效。
FR-06-7 人工修正与修正历史
优先级：P0
研究人员可在结果页对 ExtractedField 的 value / normalized_value / status 进行修正。修正操作须：
- 将
extracted_by更新为human，记录修正者与时间。 - 保留修正前的历史快照（audit log），使每次修正可回溯。
- 修正后 status 可设为
accepted或rejected。 - 人工修正不影响
evidence_refs（证据链保持原始状态）。
验收要点：
- 每次修正在
audit_logs表生成一条记录，包含before/after快照与操作者 ID。 - 研究人员可在 UI 查看某字段的完整修正历史（至少：时间、修正者、前后值）。
- 修正历史不可删除（append-only）。
FR-06-8 抽取可重跑（幂等性）
优先级：P0
研究人员可对已完成的 session 重新触发 post-session 抽取，支持以下场景：
- output schema 升级后，以新
schema_version_id重跑。 - 抽取模型更换后，以新模型重跑以对比结果。
- 某次抽取因模型异常导致字段缺失，手动补跑。
幂等规则：
- 重跑以新的
schema_version_id区分，不覆盖旧版本记录。 - 同一
(session_id, schema_field_id, schema_version_id)组合，重跑覆盖同版本的draft/needs_review记录，不覆盖accepted/rejected（需研究人员确认）。 - 人工修正记录（
extracted_by = "human"）在重跑时不被覆盖，须显式确认。
验收要点：
- 重跑产生的记录
schema_version_id与触发时选定的版本一致。 - 重跑前系统展示”将覆盖 N 条 draft 记录”确认提示。
- 重跑结果可与旧版本并排比较（结果展示见 07_results_review）。
FR-06-9 抽取触发节点与 Harness 集成
优先级：P0
Harness 在三类节点触发抽取，与 02_agent_harness Extraction 集成一节对应：
After user message -> lightweight extraction（更新 session state，不写终态）After objective covered -> checkpoint extraction（写 extracted_fields，status = draft）After session completed -> final extraction（写终态 extracted_fields + evidence_refs）验收要点：
- 三类节点触发时机须与 Harness 状态机节点（
EXTRACT、POST_SESSION_EXTRACTION）一一对应。 - 轻量抽取调用独立的轻量 prompt，不复用 post-session 抽取 prompt。
- 抽取调用须记录使用的
model与schema_version_id，写入对应字段。
4. 关键流程
4.1 Post-Session 终态抽取流程
session 状态 -> completed | v触发 POST_SESSION_EXTRACTION 节点 | v加载 output_schema_versions（绑定当前 study_version） | v遍历所有 schema 字段，执行抽取 LLM call（输入：完整 transcript + schema 字段定义） | v生成 ExtractedField（含 value / confidence / reasoning_summary）生成 EvidenceRef（turn_id / tool_call_id / quote / strength） | v评估 needs_review 规则（FR-06-6 的 7 条） | v写入 extracted_fields + evidence_refs 表 | v通知研究人员：结果可查看（见 07_results_review）4.2 人工修正流程
研究人员在结果页点击字段 -> 修正 value / status | v系统记录 before 快照 -> 写 audit_logs | v更新 extracted_fields（extracted_by = "human"，updated_at 更新） | vevidence_refs 保持不变4.3 重跑抽取流程
研究人员选择 session + 目标 schema_version -> 点击"重跑抽取" | v系统展示影响范围：将覆盖 N 条 draft/needs_review 记录，已 accepted/rejected 的 M 条需确认 | v确认后触发 POST_SESSION_EXTRACTION（schema_version_id = 新版本） | v幂等写入（不覆盖 accepted/rejected，除非二次确认）5. 数据
涉及实体均在 03_data_model 中定义：
| 实体 / 表 | 说明 |
|---|---|
extracted_fields | 每个 session × 字段的抽取记录，含 confidence / status / schema_version_id |
evidence_refs | 证据链记录，关联 extracted_field、turn、tool_call |
output_schema_versions | 字段定义快照，schema_version_id 的引用目标 |
transcript_turns | EvidenceRef.turn_id 的引用目标，原始事实源 |
tool_calls | EvidenceRef.tool_call_id 的引用目标，工具调用结果 |
audit_logs | 人工修正历史，append-only |
sessions | status 驱动抽取触发时机 |
关键约束：
extracted_fields.schema_version_idNOT NULL，与output_schema_versions.id外键约束。evidence_refs.extracted_field_id或evidence_refs.insight_id至少一个非空。extracted_fields(session_id, schema_field_id, schema_version_id)建议唯一索引（用于幂等重跑）。
6. 接口
6.1 内部触发（Harness → 抽取服务）
抽取由 Harness 内部节点调用，不暴露为独立 REST 端点；但以下操作暴露为 API（见 02_api_contracts）：
| 接口 | 方法 | 说明 |
|---|---|---|
GET /sessions/{id}/extracted-fields | GET | 获取 session 全部抽取字段（含 evidence） |
PATCH /extracted-fields/{id} | PATCH | 人工修正字段值 / status |
POST /sessions/{id}/re-extract | POST | 触发重跑抽取（body 含 schema_version_id） |
GET /extracted-fields/{id}/history | GET | 查看修正历史（audit log） |
6.2 AG-UI 事件
访谈过程中实时抽取结果通过 AG-UI SSE 推送（见 03_interactive_ui_protocol）：
| 事件 | 说明 |
|---|---|
extraction.field_updated | 实时抽取更新某字段 coverage 状态 |
extraction.session_complete | post-session 抽取完成，结果可查看 |
7. 验收标准
AC-06-01：session 进入 completed 状态后 60 秒内，output schema 中所有 required = true 的字段均生成 extracted_fields 记录（value 可为 null，但记录必须存在）。
AC-06-02：每条 extracted_fields 记录的 schema_version_id 与触发抽取时 study_version 绑定的 output_schema_version_id 一致，不得为空。
AC-06-03：confidence < confidence_threshold 的字段，status 为 needs_review，不得为 accepted（自动检查，可通过 DB 查询验证）。
AC-06-04：required = true 且 evidence 为空列表的字段，status 为 needs_review（可通过 JOIN evidence_refs 验证）。
AC-06-05：所有 EvidenceRef 的 strength 均为 weak 时，对应 ExtractedField.status = needs_review（可写自动化测试验证）。
AC-06-06：受访者在 summary confirmation turn 明确否认某结论，对应字段 status = needs_review，且 reasoning_summary 包含否认说明。
AC-06-07：人工修正触发后，audit_logs 中生成对应记录，包含 before 快照、after 快照、操作者 ID、时间戳；原 evidence_refs 不被修改。
AC-06-08：对同一 session 以相同 schema_version_id 重跑抽取两次，extracted_fields 记录数量不增加（幂等写入，覆盖而非新增）。
AC-06-09：以不同 schema_version_id 重跑时，新旧版本的 extracted_fields 记录共存，可通过 schema_version_id 区分查询。
AC-06-10：重跑时，status 为 accepted 或 rejected 的字段未经研究人员确认不被覆盖（API 返回 409 或在 UI 呈现确认弹窗）。
AC-06-11：实时抽取失败（LLM timeout / 异常）不中断访谈流程，session 仍可正常推进至 completed 并触发 post-session 抽取。
AC-06-12：GET /sessions/{id}/extracted-fields 响应中每个字段包含完整 evidence 数组，数组中每条 EvidenceRef 的 turn_id 或 tool_call_id 可与 transcript 对应。
8. 边界 & 非目标
明确边界：
- 本模块负责单 session 内的字段抽取与证据链；跨 session 的
StudyInsight聚合不在本模块范围（见 07_results_review）。 - 抽取由系统自动触发或研究人员手动触发，受访者不感知抽取过程。
confidence由抽取 LLM 给出，系统不做二次校准（MVP 阶段）。
非目标（MVP 不做）：
- 自动 calibration：用多模型对比校准置信度。
- Streaming extraction：边访谈边流式写入终态字段。
- 跨 session 自动去重与矛盾消解。
- 抽取结果的自动化质量评分（quality score by field）。
- 受访者可查看自己的抽取结果。
9. 依赖 & 风险
依赖
| 依赖 | 说明 |
|---|---|
| 03_study_builder | Output Schema 与字段定义（OutputSchemaField）由 Study Builder 模块提供 |
| 04_interview_runtime | session 状态流转与 Harness 触发节点 |
| 07_results_review | 抽取结果的展示、修正入口与导出 |
| 02_agent_harness | Harness 三类触发节点的具体实现 |
| 03_data_model | extracted_fields / evidence_refs 表结构 |
| LLM provider | post-session 抽取依赖外部 LLM；provider 不可用时无法完成终态抽取 |
风险
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| 抽取 LLM 幻觉：生成不存在于 transcript 的 quote | 证据链失真，影响可信度 | quote 须在 transcript 中可精确定位；MVP 阶段要求 start_char / end_char 或 turn_id 可验证 |
| Post-session 抽取延迟 | 访谈结束后研究人员等待过长 | 设定 SLA（60 秒内完成），超时告警；异步队列处理，失败可重试 |
| Schema 升级后重跑结果与旧版本不一致 | 跨版本比较困难 | schema_version_id 严格绑定，UI 明确区分版本；提供并排对比视图 |
| 人工修正与自动重跑冲突 | 修正被意外覆盖 | 重跑前检查 accepted/rejected 记录，需二次确认才能覆盖 |
| 实时抽取成本过高 | LLM 调用频次过高，成本不可控 | MVP 实时抽取使用轻量 prompt + 小模型；仅更新 state，不写持久化记录 |