feat(evidence): 统一 Source → Evidence ↔ Claim 证据契约 - #104
Open
Theater-ahyeon wants to merge 1 commit 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)
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.
改了什么
按 issue #100 的「版本化、增量式证据契约」方向,新增统一契约的第一个增量切片:契约类型 + 三条既有证据路径的确定性投影 + bundle 组装/序列化。不改动任何现有类型、持久化格式与生产路径。
新增文件
packages/core/src/evidence-contract.tsEvidenceSource/EvidenceItem/EvidenceClaim/EvidenceBundle契约类型与folio-evidence-contract/v1版本常量packages/shared/src/evidence/contract.tsbuildEvidenceBundle+ 序列化/守卫packages/shared/src/evidence/contract.test.tsdocs/evidence-contract.md修改文件(各 1 行导出接线)
packages/core/src/index.ts、packages/shared/src/evidence/index.ts为什么要改
当前存在三套并行演化的证据抽象:Copilot 的
FinancialEvidenceEnvelope(结构化金融事实)、Deep Research 的EvidenceRef(论点引用)、NewsItem(网页/新闻)。同一事实/来源因来自不同子系统而获得不同身份与元数据(语义碎片化)。本 PR 用一条 Source → Evidence ↔ Claim 关系链统一它们,且是投影整合而非新框架:现有类型仍是生产方的权威表示。对应 Issue
#100(契约整合部分)。claim verifier(#13)、Source Inspector UI(#30)、检索去重(#39)的接入留作后续增量 PR。
设计要点
sourceId/evidenceId/claimId全部由 sha256 确定性派生(截断 24 位,src_/ev_/claim_前缀,与现有fe_风格一致);哈希输入经键排序的stableJson序列化,身份永不依赖对象键序。sourceId不含检索时间:同一文档/查询被再次观察仍是同一来源evidenceId含检索时间:同一事实稍后再次观察是同源新 observation,保留各自 provenanceclaimId由表述 + instrument 作用域派生:不同 run 的相同论点在 bundle 中合并并并集 evidenceIds —— 多对多映射由此自然成立evidenceIds[],Evidence 不反向命名 Claim;一条证据可支撑多个论点。structured_finance来源无公开文档,canonicalUrl恒为空,身份由 publisher + dataset + query 承担;authority元数据只在实际已知时填写(如监管备案)。availability枚举值,不允许静默丢弃。验证
环境:Bun 1.4.2 / Windows 10 (10.0.26200)
验收标准覆盖情况:
evidence-contract.ts+docs/evidence-contract.md)projectFinancialEvidence/projectNewsItems/projectTextEvidence;研究论点路径projectEvidenceRefs覆盖 tool 证据)mixed-source integration用例在单个 bundle 同时携带结构化金融证据、tool 论点证据、新闻摘录、监管备案摘录并验证重载一致无可见 UI 变化
纯契约/共享层新增,不改任何 UI、IPC 或持久化行为。
已知未完成项(后续增量 PR)
verification/verifiedBy,契约不变)