【免费下载链接】open-knowledge-format项目地址https://gitcode.com/gh_mirrors/op/open-knowledge-format点击查看免费下载open-knowledge-formatOKF是一个把数据目录知识表示为「Markdown 文件 YAML frontmatter」的开放、厂商中立格式人类可手写、Agent 可生成、任意系统可消费。如果你手里的知识包Knowledge Bundle还停留在 v0.1升级到OKF v0.2需要处理2 个破坏性变更旧字段被取代并可按清单分批启用4 组新增字段来源溯源、信任、生命周期、可验证计算。本文是一份可直接照做的完整升级清单全程不需要任何专用工具——能cat一个文件就能完成迁移。 一、升级前 30 秒v0.2 到底改了什么v0.2 的设计目标是让「由 Agent 持续维护的知识库」变得可信。当大多数文档由机器生成时消费者需要快速回答 5 个问题v0.2 正好为每个问题给了一个 frontmatter 答案你要回答的问题v0.2 提供的字段这条知识从哪来provenance 溯源sources应该相信多少trust 信任generated/verified现在还新鲜吗freshness 新鲜度stale_after是当前版本吗lifecycle 生命周期status数字是按规范算出来的吗attestation 认证Attested Computation概念类型版本差异的权威出处是官方规范 SPEC.md其中「§13 Changes from v0.1」就是本文所有内容的索引。⚠️ 二、2 个破坏性变更迁移必做项变更 1timestamp被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:0500:00 # v0.2新写法 generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }by的值遵循 actor 命名约定SPEC.md §7Agent 用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 批启用每批独立可回滚批次字段族关键字段解决的问题规范位置1来源溯源sources含author、usage_count、last_modified 兄弟字段usage_window知识从哪来、来源是否权威§5.12信任generated、verified谁写的、谁核实过§5.23生命周期statusdraft / stable / deprecated、stale_after是否现行、何时过期§5.4–5.54可验证计算新类型Attested Computationruntime、parameters、computation、executor、attester 正文约定章节# Computation关键数字是否按批准的 SQL/模型算出§10信任分级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/步骤 2timestamp→generated逐文档改写为generated: { by, at }at用带 UTC 偏移的 ISO 8601 时间然后删除timestamp行。步骤 3# Citations→sources把正文末尾的引用列表搬进 frontmatter给每条来源起一个稳定id正文对应论断处加[^id]脚注最后删除# Citations章节。步骤 4为关键文档补status与stale_afterstatus缺省即stable只需显式标注草稿与废弃项stale_after是绝对时间点now stale_after即视为过期消费端应提示复核而非直接报错。废弃写法参考 gross-margin-legacy.mdstatus: deprecated 正文说明保留原因。步骤 5可选把关键指标升级为 Attested Computation将「一个概念混装多个口径」拆成「叙述型 Metric 概念 独立计算概念」Metric 只负责叙述并用 markdown 链接指向计算计算概念自带runtime、参数、执行器与审核器。完整实例见 computations/revenue-ytd.md 与 metrics/revenue.md。步骤 6声明版本并做合规验收在 bundle 根index.md的 frontmatter 中声明okf_version: 0.2——这是index.md唯一允许带 frontmatter 的位置§12 Versioning。按 §11 Conformance 验收所有非保留.md都有可解析 frontmatter、type非空且消费端不得因缺少可选字段、未知type、断链等理由拒读 bundle。把迁移记录写进log.md日期分组、最新在前格式见 acme_retail/log.md。迁移前后的完整对照样例一张损益表从 v0.1 单文档升级为「Metric 两个 Attested Computation」在 SPEC.md 附录 A建议迁移时放在手边。❓ 五、常见问题Qv0.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 exampleSPEC.md四族字段全开的示范 bundlebundles/acme_retail/其他样例 bundlebundles/ga4/、bundles/stackoverflow/、bundles/crypto_bitcoin/生成端提示词prompts/reference_instruction.md赞分享【免费下载链接】open-knowledge-format项目地址https://gitcode.com/gh_mirrors/op/open-knowledge-format点击查看免费下载相关推荐Ragas v0.1 到 v0.2 迁移指南EvaluationDataset、新 Metrics API 与 Knowledge Graph 全面升级Ragas v0.1 到 v0.2 迁移指南EvaluationDataset、新 Metrics API 与 Knowledge Graph 全面升级 v0人工智能大模型AI 评测模型评测RAGCodeIgniter 4.2.2 升级指南从 4.2.1 升级的破坏性变更与迁移清单CodeIgniter 4.2.2 升级指南从 4.2.1 升级的破坏性变更与迁移清单 本篇升级指南以 CodeIgniter4 官方文档 upgrade_4后端Web框架Mbed TLS 3.0 迁移指南从 2.x 升级的破坏性变更清单与实战迁移路径Mbed TLS 3.0 迁移指南从 2.x 升级的破坏性变更清单与实战迁移路径 本篇指南以 Mbed TLS 官方 2.x→3.0 迁移文档为主体结合当前人工智能AI AgentAgent 框架多模态语音音频后端上一篇DEFT面向文本到图像模型的分解式高效微调PEFT 实现与实战指南下一篇pyenv-win企业级离线部署终极指南无网络环境下的Python版本管理实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考