企业官网建设流程全解析

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 把"一句话的来龙去脉"拆成三个正交维度，这是整个模型最精华的设计 👇

typed_by模式：打字的人 ≠ 思想的人

一个容易被忽略的巧妙设计：当你口述、AI 代打字时，"物理输入者"和"思想来源"是两个人。v2 用meta.typed_by区分：

⚠️ 关键规则：Basis 只属于 AI 内容——人类内容永远没有 basis，因为"人就是自己的依据"。

三、五种语义选择器：给 Agent 的"找内容提示词"

选择器是 v2 的灵魂——本质上它们是"给 Agent 的自然语言指令"，让 AI 重新定位内容：

1. Content（内容选择器）：自然语言描述，如content: "解释认证流程的那段话"，由 Claude 理解后定位；
2. Anchor（锚点选择器）：结构化路径，如heading:Authentication > paragraph:first；
3. Quote（引用选择器）：精确文本匹配，支持fuzzy: true模糊匹配；
4. Pattern（模式选择器）：CSS 式批量匹配，如all blockquotes（所有引用块）；
5. Composite（组合选择器）：all/any/not逻辑组合，例如"两个日期写法的任一"。

这样设计的好处：即使文档被大规模编辑、段落移动，选择器依然能重新解析到正确位置。

四、审核栈：信任不是开关，而是过程

v2 把审核从"单值等级"升级为栈（Stack）——多个审核者可以先后审核同一段文字：

三条硬性规则（防止 AI"自己审自己"）：

• 🚫AI 不能批准自己的内容（只能加skimmed）
• 空审核 = 未审核
• 内容哈希变化后，审核自动变为stale（过期），需重新审核

UI 上会聚合为直观标签：3 个以上 approved →Verified；有 flagged →Needs Review；无审核 →Unreviewed。

五、解析机制：缓存 + 哈希校验的"快路径"

语义选择器虽强大，但每次渲染都让 AI 重新定位会太慢。v2 采用双层架构：

语义选择器 → 唯一事实来源（慢，但永不过时） resolved.offset → 缓存快照（快，可能过期） + content_hash → 校验缓存是否失效

渲染时：

1. 哈希匹配→ 直接用缓存偏移量，瞬时渲染✅
2. 哈希不匹配→ 标记stale，异步重新解析
3. 离线状态→ 用缓存数据渲染，并视觉上标记过期片段

解析结果还带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 语义溯源模型用三个动作重塑了"人机协作写作"的信任基础：

1. 🎯语义定位：溯源跟随含义而非字节，编辑不再让认证失效
2. 🧠AI 自证：basis强制 AI 交代"我为什么这么写"
3. 🤝人类终审：审核栈 + 哈希失效机制，批准权永远在人

想进一步动手，可以从这些入口读起：

• 完整规范：docs/PROVENANCE-SPEC-v2.md
• 旧版格式实现（迁移参照）：src/formats/provenance-sidecar.ts
• 公共核心包拆分决策：docs/adr/2026-03-proof-sdk-public-core.md
• 溯源格式定义：src/formats/
• 核心模型包：packages/doc-core