跳转至

Evidence Registry：原始证据源契约

核心结论

Evidence Registry 是 P0 的原始证据层机器契约。它回答一个问题：某个 Markdown、Knowledge Card、ContextDocument、实验报告或检索投影，最早来自哪份原始材料，原始快照在哪里，hash 是否匹配，来源链接是否稳定，权限和脱敏要求是什么。

它不是搜索索引，也不是本体对象库。职责边界是：

```text Evidence Registry -> 保留 source snapshot、hash、source status、permission、PII/mask、attachment manifest -> 指向 downstream ontology artifact 或 runtime projection

ContextDocumentRecord -> 把已清洗材料投影成 SearchConnector 可检索文档

Ontology / Domain Topology -> 决定对象、关系、规则、动作、权限视图和 writeback ```

当前 demo registry 位于：

text domain/orgreorg-demo/evidence-registry.json

校验命令：

bash python scripts/evidence_registry_lint.py

为什么要单独做

此前 ContextDocumentRecord 已能表达检索投影前的文档结构，但它更靠近 Runtime Projection。缺少 Evidence Registry 时，会有几个问题：

  • 原始企微消息、会议、外部链接、代码包和业务系统对象没有统一快照清单。
  • 无法验证 source snapshot 是否被改过。
  • 临时公众号链接、分享票据和签名 URL 容易反复搜索或误提交。
  • restricted / task_only 材料是否带 PII 或 field mask 没有统一检查。
  • 下游 Markdown、ADR、实验报告、Knowledge Card 和 ContextDocument 很难回查原始证据。

Evidence Registry 把这些约束前置到进入本体层之前。

当前字段

每个 source 至少声明：

字段 作用
id 稳定证据源 ID
source_type wecom_message、meeting_note、external_reference、code_package、connector_callback、markdown_note、json_fixture、document
source_system 来源系统或来源类别
source_uri 稳定 URI；不能保存带短期票据的外部链接
source_statuses content_processed、source_original_unstable、search_keywords_saved、no_further_search 等状态
source_snapshot_path 仓库内快照路径
source_hash 快照文件 sha256
permission_scope public、team、task_only、restricted 或 namespaced scope
review_status pending、reviewed、rejected、expired
runtime_paths 运行时披露路径，通常至少包含 D4
pii_flags / field_mask 受限或任务级材料的敏感字段提示
attachments 附件路径、类型和 hash
downstream_artifacts 下游 wiki、docs、schema、fixture、report、ontology contract 等引用
provenance 临时链接封口、稳定镜像、搜索关键词和原始链接状态

当前校验

evidence_registry_lint 会检查：

  • registry JSON 不能有重复 key。
  • source ID、scope、runtime path 和状态值合法。
  • source_snapshot_path 必须存在。
  • source_hash 必须等于快照文件 sha256。
  • source_uri 不能带 pass_ticket、exportkey、sessionid、clicktime、scene、srcid、devicetype、wx_header 等临时、分享或设备上下文参数。
  • 标记 source_original_unstable 的来源必须同时保存 search_keywords_saved 和 no_further_search 状态，并在 provenance 中保存搜索关键词。
  • restricted / task_only source 必须声明 pii_flags 或 field_mask。
  • attachment 路径和 hash 必须可验证。
  • downstream artifact 路径必须存在。

当前 demo 覆盖

第一版 registry 先纳入四类已存在材料：

Source 类型 作用
Agentic Engineering / Palantir 外部参考 external_reference 验证外部临时来源封口、镜像来源和关键词回查
Loop Engineering 外部参考 external_reference 验证外部参考进入 Loop / Harness 方案的证据链
ContextDocument schema 讨论 markdown_note 验证团队讨论到 schema、fixture、发布页的沉淀链
task-only payment fixture json_fixture 验证 task_only 材料必须携带 PII 和 field mask

这只是 P0 seed，不是完整数据源接入。后续企微、会议、附件、GitHub、CRM、财务系统和文档系统 connector 都应该先写入 Evidence Registry，再进入 Ontology build 或 Runtime Projection。

Ingestion Quality Demo 也已经按同一 contract 生成实验级 registry：

bash python scripts/ingestion_quality_demo.py --write-report python scripts/evidence_registry_lint.py --registry vault/50-outputs/ingestion-quality-evidence-registry.json

该实验会为 8 条 synthetic source 写出独立 raw snapshot，并把 ContextDocumentRecord.raw_source_id/source_hash/source_uri 绑定到对应 Evidence source。

Connector Callback Ledger 也会生成实验级 registry：

bash python scripts/connector_callback_ledger_conformance.py --write-report python scripts/evidence_registry_lint.py --registry vault/50-outputs/connector-callback-evidence-registry.json

该实验只把通过签名、时间窗、必填字段和幂等校验且 recorded=true 的回调写入 Evidence；duplicate、invalid signature、stale timestamp 或缺字段回调不会沉淀成 Evidence source。

与其他模块关系

  • Ingestion Quality Demo 继续验证“清洗不能丢事实”；Evidence Registry 负责证明清洗前的 source snapshot 可追溯。
  • Connector Callback Ledger 负责外部回调的签名、幂等和安全落账；已把通过校验且 recorded 的回调投影为受限 Evidence source、raw snapshot 和 source hash。
  • Domain Topology 负责把 Evidence 编译成对象、关系、规则和动作边界。
  • SearchConnector 只消费已投影的 ContextDocument，不直接信任原始 Evidence。

下一步

  1. 为企微消息、会议纪要、附件、网页、代码包和业务系统对象补 source type adapter。
  2. 增加自动 PII / 合同号 / 客户名 / 财务字段识别和 field mask 建议。
  3. 在 No-WeCom MVP Demo 中加入 Evidence source 写入和 hash 校验步骤。