Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat(research): 持久化并重载 Deep Research 报告的统一证据 bundle - #105

Open
Theater-ahyeon wants to merge 2 commits into
helsome:mainfrom
Theater-ahyeon:feat/research-evidence-bundle
Open

feat(research): 持久化并重载 Deep Research 报告的统一证据 bundle#105
Theater-ahyeon wants to merge 2 commits into
helsome:mainfrom
Theater-ahyeon:feat/research-evidence-bundle

Conversation

@Theater-ahyeon

Copy link
Copy Markdown

改了什么

这是 #100 的第二个增量 PR(stacked,依赖 #104——buildReportEvidenceBundle 直接使用 #104 引入的统一契约与投影函数),把证据契约接进 Deep Research 的生产持久化路径:

新增

  • buildReportEvidenceBundle(report: ResearchReport): EvidenceBundlepackages/shared/src/evidence/contract.ts):把报告各 section 的 EvidenceRef 确定性投影为统一契约 bundle —— 每条引用拆成一个 tool 来源 + 一条 tool_result 证据 + 一条 unverified 论点;不同 section 相同表述的论点按 claimId 合并并并集 evidenceIds(多对多映射在生产数据上成立)。
  • packages/shared/src/research/evidence-bundle.test.ts:7 个聚焦测试。

修改

  • packages/shared/src/research/repository.ts
    • saveReport 在保存报告的同时自动派生并落盘 research/evidence/<id>.json。bundle 只是报告的确定性投影,每次保存重新推导,永不与报告内容漂移;正常完成(service.ts:212)与恢复(service.ts:263)两条路径自动覆盖,调用方零改动。
    • 新增 getEvidenceBundle(reportId):文件缺失(旧格式报告)或损坏时容错返回 undefined —— bundle 永远可以从权威的报告文件重建,读取失败不应该打断消费方。
    • 布局注释同步更新。
  • packages/shared/src/evidence/index.ts:1 行导出。

为什么要改

#104 验收标准中「evidenceId / sourceId 在生产路径的组装 → 持久化 → 重新加载过程中保持稳定」目前只有单元级 round-trip 验证。本 PR 让每个新保存的 Deep Research 报告自动拥有统一证据 bundle,评测(#14/#15)、来源检查器(#30)和后续的 claim 验证(#13)可以直接按 reportId 读取,无需各自解析报告 JSON。这是 #100 收尾「生产接线」的最小切片。

兼容性

  • 完全向后兼容:旧报告没有 evidence 文件,getEvidenceBundle 返回 undefined,报告读取路径不变;没有任何 schema 迁移。
  • 存储布局仅新增一个文件族 research/evidence/<id>.json,不触碰现有文件。
  • bundle 写入失败会随 saveReport 一起失败(与 index 写入同一失败面);读取侧永不抛错。

验证

环境:Bun 1.4.2 / Windows 10 (10.0.26200)

bun test packages/shared/src/research/ packages/shared/src/evidence/
→ 83 passed / 0 failed(12 files)

bun test packages/shared packages/core
→ 961 passed / 0 failed(90 files,3713 expect calls)

cd packages/core && bun run typecheck  → exit 0
cd packages/shared && bun run typecheck → exit 0

与改动对应的验证:evidence-bundle.test.ts 覆盖生产路径 ID 稳定性(save → reload → rebuild 深相等)、重复保存再推导一致性、跨 section 论点合并、旧格式报告兼容、损坏文件容错、非法 ID 拒绝、空报告空 bundle。

无可见 UI 变化

纯持久化与投影层新增,不改任何 UI、IPC 或报告结构。

已知未完成项

新增 folio-evidence-contract/v1 统一契约(core 类型 + shared 投影),
把 FinancialEvidenceEnvelope、EvidenceRef、NewsItem 三套并行证据抽象
投影到同一条 Source → Evidence ↔ Claim 关系链:

- core/evidence-contract.ts: EvidenceSource / EvidenceItem / EvidenceClaim /
  EvidenceBundle 类型,全部 ID 确定性派生(sha256,键序无关),
  组装 → 持久化 → 重载全程稳定
- shared/evidence/contract.ts: 四个投影函数(结构化金融事实 / 研究论点 /
  新闻 / 通用文档备案)+ buildEvidenceBundle 多对多合并 + 序列化往返守卫
- 结构化金融来源不伪造 canonicalUrl;authority 元数据只在已知时填写;
  投影只读输入,现有持久化记录无需迁移
- docs/evidence-contract.md: 身份与生命周期语义文档

对应 helsome#100(契约整合部分;claim verifier / Source Inspector 接入留作
后续增量 PR)
- evidence/contract.ts 新增 buildReportEvidenceBundle:把报告各 section 的
  EvidenceRef 确定性投影为统一契约 bundle(tool 来源 + tool_result 证据
  + unverified 论点),仅依赖报告本身,可随时重建
- ResearchReportRepository.saveReport 保存报告时自动派生并落盘
  research/evidence/<id>.json,正常完成与恢复两条路径自动覆盖,调用方
  零改动;旧报告无 bundle 文件时读取返回 undefined,完全向后兼容
- 新增 getEvidenceBundle(reportId):损坏/缺失文件容错返回 undefined,
  报告本身始终是权威数据源
- 新增 7 个聚焦测试:生产路径 ID 稳定性、跨 section 相同论点合并、
  旧格式兼容、损坏容错、非法 ID、空 bundle

对应 helsome#100 增量(生产路径组装→持久化→重载稳定性),依赖 helsome#104
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant