企业官网建设流程全解析

open-knowledge-format（OKF）是一个把数据目录知识表示为「Markdown 文件 + YAML frontmatter」的开放、厂商中立格式：人类可手写、Agent 可生成、任意系统可消费。如果你手里的知识包（Knowledge Bundle）还停留在 v0.1，升级到OKF v0.2需要处理2 个破坏性变更（旧字段被取代），并可按清单分批启用4 组新增字段（来源溯源、信任、生命周期、可验证计算）。本文是一份可直接照做的完整升级清单，全程不需要任何专用工具——能cat一个文件，就能完成迁移。

📌 一、升级前 30 秒：v0.2 到底改了什么

v0.2 的设计目标是让「由 Agent 持续维护的知识库」变得可信。当大多数文档由机器生成时，消费者需要快速回答 5 个问题，v0.2 正好为每个问题给了一个 frontmatter 答案：

版本差异的权威出处是官方规范 SPEC.md，其中「§13 Changes from v0.1」就是本文所有内容的索引。

⚠️ 二、2 个破坏性变更：迁移必做项

变更 1：timestamp被generated取代

• v0.1：用顶层timestamp记录文档最后修改时间。
• v0.2：改为generated: { by: <actor>, at: <ISO 8601> }，同时回答「谁生成」和「何时生成」，规范见 SPEC.md §5.2 Trust。
• 兼容策略：v0.2 消费者在缺少generated时允许回退读取旧timestamp，所以旧 bundle 不会立刻失效；但迁移完成后应删除旧字段。

# v0.1（旧写法，见 SPEC.md 附录 A 的 v0.1 示例） timestamp: '2026-05-28T22:53:05+00:00' # v0.2（新写法） generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }

by的值遵循 actor 命名约定（SPEC.md §7）：Agent 用<producer>/<version>，个人用human:<id>，自动化流程用process:<id>。

变更 2：正文# Citations列表被sourcesfrontmatter 取代

• v0.1：引用来源以 URL 列表形式写在正文末尾的# Citations章节里（v0.1 示例见 SPEC.md 附录 A）。
• v0.2：来源统一提升到 frontmatter 的sources列表，每条可带可信度信号author/usage_count/last_modified；正文里对具体论断用 markdown 脚注[^id]关联到sources[].id，详见 SPEC.md §5.1 Provenance。
• 为什么要挪：来源从「正文装饰」变成可查询、可过滤的元数据，消费者无需解析正文即可评估可信度。

💡 官方参考 Agent 的提示词已同步更新——明确禁止再生成# Citations章节，见 reference_instruction.md；工具层校验也做了同样约束，见 bundle_tools.py。

🧩 三、4 组新增字段：按需启用的升级清单

v0.2 的新增内容全部是可选字段：一个字段都不加，文档依然合规。建议按下面 4 批启用，每批独立可回滚：

信任分级（trust tier）怎么推导（§5.3）：

• 无verified⇒unverified
• 仅process:/ Agent 验证过 ⇒machine-confirmed
• 出现human:<id>验证 ⇒human-reviewed

💡 建议节奏：先做第 1、2 批（成本最低、收益最大）；第 3 批适合财务口径、指标定义类文档；第 4 批只给营收、毛利这类关键指标配，仓库里的 acme_retail bundle 就是一个四批全开的完整示范。

✅ 四、6 步迁移操作清单

步骤 1：盘点存量

统计两个 v0.1 特征出现的范围：

grep -rl "timestamp:" bundles/ grep -rl "# Citations" bundles/

步骤 2：timestamp→generated

逐文档改写为generated: { by, at }，at用带 UTC 偏移的 ISO 8601 时间，然后删除timestamp行。

步骤 3：# Citations→sources

把正文末尾的引用列表搬进 frontmatter；给每条来源起一个稳定id，正文对应论断处加[^id]脚注，最后删除# Citations章节。

步骤 4：为关键文档补status与stale_after

status缺省即stable，只需显式标注草稿与废弃项；stale_after是绝对时间点，now >= stale_after即视为过期，消费端应提示复核而非直接报错。废弃写法参考 gross-margin-legacy.md（status: deprecated+ 正文说明保留原因）。

步骤 5（可选）：把关键指标升级为 Attested Computation

将「一个概念混装多个口径」拆成「叙述型 Metric 概念 + 独立计算概念」：Metric 只负责叙述并用 markdown 链接指向计算，计算概念自带runtime、参数、执行器与审核器。完整实例见 computations/revenue-ytd.md 与 metrics/revenue.md。

步骤 6：声明版本并做合规验收

1. 在 bundle 根index.md的 frontmatter 中声明okf_version: "0.2"——这是index.md唯一允许带 frontmatter 的位置（§12 Versioning）。
2. 按 §11 Conformance 验收：所有非保留.md都有可解析 frontmatter、type非空；且消费端不得因缺少可选字段、未知type、断链等理由拒读 bundle。
3. 把迁移记录写进log.md，日期分组、最新在前，格式见 acme_retail/log.md。

迁移前后的完整对照样例（一张损益表从 v0.1 单文档升级为「Metric + 两个 Attested Computation」）在 SPEC.md 附录 A，建议迁移时放在手边。

❓ 五、常见问题

Q：v0.1 的旧 bundle 会升级后直接失效吗？不会。v0.2 消费者带兼容回退：缺generated可回退读timestamp，仍可从旧# Citations解析来源（§13.1）。迁移是渐进的，不是「一刀切」。

Q：新字段必须全填吗？不必。type是唯一必填项，其余全部可选；消费端必须容忍未知 key 与缺失字段，因此可以按第三节的 4 批次慢慢上。

Q：用 reference agent 自动生成的 bundle 需要手动改吗？不用。生成端提示词已对齐 v0.2（来源写sources、自动生成generated），直接产出即新格式；复现命令见各样例配方，如 samples/stackoverflow/README.md。

📚 六、参考资料

• 官方规范（含 v0.1→v0.2 差异总表与 worked example）：SPEC.md
• 四族字段全开的示范 bundle：bundles/acme_retail/
• 其他样例 bundle：bundles/ga4/、bundles/stackoverflow/、bundles/crypto_bitcoin/
• 生成端提示词：prompts/reference_instruction.md