【免费下载链接】open-knowledge-format项目地址：https://gitcode.com/gh_mirrors/op/open-knowledge-format点击查看免费下载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 答案：你要回答的问题v0.2 提供的字段这条知识从哪来？（provenance 溯源）sources应该相信多少？（trust 信任）generated/verified现在还新鲜吗？（freshness 新鲜度）stale_after是当前版本吗？（lifecycle 生命周期）status数字是按规范算出来的吗？（attestation 认证）Attested Computation概念类型版本差异的权威出处是官方规范 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 批启用，每批独立可回滚：批次字段族关键字段解决的问题规范位置1来源溯源sources（含author、usage_count、last_modified）+ 兄弟字段usage_window知识从哪来、来源是否权威§5.12信任generated、verified谁写的、谁核实过§5.23生命周期status（draft / stable / deprecated）、stale_after是否现行、何时过期§5.4–5.54可验证计算新类型Attested Computation：runtime、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/步骤 2：timestamp→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.md（status: 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，建议迁移时放在手边。❓ 五、常见问题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赞分享【免费下载链接】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），仅供参考
【免费下载链接】open-knowledge-format项目地址：https://gitcode.com/gh_mirrors/op/open-knowledge-format点击查看免费下载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 答案：你要回答的问题v0.2 提供的字段这条知识从哪来？（provenance 溯源）sources应该相信多少？（trust 信任）generated/verified现在还新鲜吗？（freshness 新鲜度）stale_after是当前版本吗？（lifecycle 生命周期）status数字是按规范算出来的吗？（attestation 认证）Attested Computation概念类型版本差异的权威出处是官方规范 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 批启用，每批独立可回滚：批次字段族关键字段解决的问题规范位置1来源溯源sources（含author、usage_count、last_modified）+ 兄弟字段usage_window知识从哪来、来源是否权威§5.12信任generated、verified谁写的、谁核实过§5.23生命周期status（draft / stable / deprecated）、stale_after是否现行、何时过期§5.4–5.54可验证计算新类型Attested Computation：runtime、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/步骤 2：timestamp→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.md（status: 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，建议迁移时放在手边。❓ 五、常见问题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赞分享【免费下载链接】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），仅供参考