理解 proof-sdk 的杀手锏：Provenance v2 语义溯源模型深度图解

【免费下载链接】proof-sdkProof SDK: open-source collaborative editor, provenance model, and agent HTTP bridge项目地址https://gitcode.com/gh_mirrors/pr/proof-sdk点击查看免费下载proof-sdk是一款开源的协作 Markdown 编辑器套件内置 AI Agent HTTP 桥接而其最核心、最独特的能力就是Provenance溯源模型——为文档中的每一段文字记录这段是谁写的、为什么写、审没审过。本文将带你深入理解其 v2 版本语义溯源Provenance v2 语义选择器看看它如何让AI 写了什么这件事变得完全透明、可验证、可追责。 上面的界面来自 Proof 编辑器左侧彩色边条就是溯源色带Gutter绿、紫等颜色区分人类与 AI 的内容Claude 的建议卡片会直接挂在对应段落旁接受/拒绝后溯源状态同步更新。一、为什么需要 Provenance v2 语义溯源先回忆一下传统做法的问题。旧版legacy溯源模型把每段文字记录为偏移量区间startOffset→endOffset见 src/formats/provenance-sidecar.ts 中的ProvenanceSpan定义文档前面一插入一个字后面所有偏移量全部错位溯源标记与文字脱钩静默失效却无人察觉审核等级只有一个A0~A4 单值无法表达多人先后审核的过程Provenance v2 的核心原则只有一句话Attestation follows meaning, not bytes.认证跟随语义而非字节位置。v2 用语义选择器作为唯一事实来源source of truth让溯源标记粘在含义上而不是粘在坐标上。完整规范见 docs/PROVENANCE-SPEC-v2.md。二、核心概念Origin / Basis / Review 三件套v2 把一句话的来龙去脉拆成三个正交维度这是整个模型最精华的设计 概念回答的问题取值Origin起源这段文字的思想是谁的human/aiBasis依据AI 凭什么写这段仅 AIdescribed/inferred/suggestedReview审核这段被谁验证过审核记录栈数组typed_by模式打字的人 ≠ 思想的人一个容易被忽略的巧妙设计当你口述、AI 代打字时物理输入者和思想来源是两个人。v2 用meta.typed_by区分场景origintyped_bybasis用户直接打字human省略无用户口述、AI 代打humanai:claude无AI 按描述写作ai省略describedAI 从上下文推断ai省略inferredAI 主动提议ai省略suggested⚠️ 关键规则Basis 只属于 AI 内容——人类内容永远没有 basis因为人就是自己的依据。三、五种语义选择器给 Agent 的找内容提示词选择器是 v2 的灵魂——本质上它们是给 Agent 的自然语言指令让 AI 重新定位内容Content内容选择器自然语言描述如content: 解释认证流程的那段话由 Claude 理解后定位Anchor锚点选择器结构化路径如heading:Authentication paragraph:firstQuote引用选择器精确文本匹配支持fuzzy: true模糊匹配Pattern模式选择器CSS 式批量匹配如all blockquotes所有引用块Composite组合选择器all/any/not逻辑组合例如两个日期写法的任一。这样设计的好处即使文档被大规模编辑、段落移动选择器依然能重新解析到正确位置。四、审核栈信任不是开关而是过程v2 把审核从单值等级升级为栈Stack——多个审核者可以先后审核同一段文字等级谁能加含义skimmedAI 或人类快速读过、基础检查flagged仅人类需要关注/讨论approved仅人类仔细审阅并批准三条硬性规则防止 AI自己审自己AI 不能批准自己的内容只能加skimmed空审核 未审核内容哈希变化后审核自动变为stale过期需重新审核UI 上会聚合为直观标签3 个以上 approved →Verified有 flagged →Needs Review无审核 →Unreviewed。五、解析机制缓存 哈希校验的快路径语义选择器虽强大但每次渲染都让 AI 重新定位会太慢。v2 采用双层架构语义选择器 → 唯一事实来源慢但永不过时 resolved.offset → 缓存快照快可能过期 content_hash → 校验缓存是否失效渲染时哈希匹配→ 直接用缓存偏移量瞬时渲染✅哈希不匹配→ 标记stale异步重新解析离线状态→ 用缓存数据渲染并视觉上标记过期片段解析结果还带confidence置信度分数状态可以是resolved / ambiguous / not_found让调用方对定位是否可靠有明确判断。六、如何存储与迁移存储格式溯源以 YAML 嵌在 Markdown 文件末尾的 HTML 注释中对正文零侵入Git diff 友好 !-- PROVENANCE version: 2.0 document: fingerprint: sha256:abc123... provenance: - selector: quote: The deadline is March 15, 2025. origin: human meta: typed_by: ai:claude --从 legacy 偏移量格式迁移只需 5 步提取旧偏移量处的文本 → 自动生成 quote 选择器 → 计算内容哈希 → 打上meta.migrated: true标记 → 下次保存时写入新格式。老文档无需手工改写平滑升级。另外v2 还引入Conventions约定系统文档可以引用外部 YAML 约定文件扩展自定义审核等级如legal_approved、fact_checked和新的选择器类型后加载的约定覆盖先加载的——为法律、媒体等垂直领域留足了扩展空间。七、小结与延伸阅读Provenance v2 语义溯源模型用三个动作重塑了人机协作写作的信任基础语义定位溯源跟随含义而非字节编辑不再让认证失效AI 自证basis强制 AI 交代我为什么这么写人类终审审核栈 哈希失效机制批准权永远在人想进一步动手可以从这些入口读起完整规范docs/PROVENANCE-SPEC-v2.md旧版格式实现迁移参照src/formats/provenance-sidecar.ts公共核心包拆分决策docs/adr/2026-03-proof-sdk-public-core.md溯源格式定义src/formats/核心模型包packages/doc-core赞分享【免费下载链接】proof-sdkProof SDK: open-source collaborative editor, provenance model, and agent HTTP bridge项目地址https://gitcode.com/gh_mirrors/pr/proof-sdk点击查看免费下载相关推荐拆开 Docling 引擎DoclingDocument 统一模型 TableFormer表格识别为何是它的杀手锏拆开 Docling 引擎DoclingDocument 统一模型 TableFormer表格识别为何是它的杀手锏 在 RAG 与 Agent 应用遍地AI 应用计算机视觉OCROpenCode V2 模式变更日志深度解读事件溯源 Session 的持久化契约、分页语义与工具 Schema 演进OpenCode V2 模式变更日志深度解读事件溯源 Session 的持久化契约、分页语义与工具 Schema 演进 本篇指南以 specs/v2/sche人工智能AI 应用AI Agent代码智能体CLI开发者工具推荐杀手锏应用Killergram - Telegram 广告消除神器推荐杀手锏应用Killergram Telegram 广告消除神器 在信息爆炸的时代保持清爽的聊天环境至关重要。当您在Telegram上享受高效沟通的同时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考