feat(research): 持久化并重载 Deep Research 报告的统一证据 bundle - #105
Open
Theater-ahyeon wants to merge 2 commits into
Open
Conversation
新增 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。
This was referenced Sep 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
改了什么
这是 #100 的第二个增量 PR(stacked,依赖 #104——
buildReportEvidenceBundle直接使用 #104 引入的统一契约与投影函数),把证据契约接进 Deep Research 的生产持久化路径:新增
buildReportEvidenceBundle(report: ResearchReport): EvidenceBundle(packages/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 收尾「生产接线」的最小切片。
兼容性
getEvidenceBundle返回undefined,报告读取路径不变;没有任何 schema 迁移。research/evidence/<id>.json,不触碰现有文件。saveReport一起失败(与 index 写入同一失败面);读取侧永不抛错。验证
环境:Bun 1.4.2 / Windows 10 (10.0.26200)
与改动对应的验证:
evidence-bundle.test.ts覆盖生产路径 ID 稳定性(save → reload → rebuild 深相等)、重复保存再推导一致性、跨 section 论点合并、旧格式报告兼容、损坏文件容错、非法 ID 拒绝、空报告空 bundle。无可见 UI 变化
纯持久化与投影层新增,不改任何 UI、IPC 或报告结构。
已知未完成项