#OKF 知识包

OKF（Open Knowledge Format） 是面向人和 Agent 的开放知识包格式：just Markdown, just files, just YAML frontmatter。A3S Use 只接受 OKF v0.2；该格式把可共享领域知识组织成带类型、可交叉链接、可增量索引的概念图。

在 A3S Use 中，OKF 是与 Tool、MCP、Flow、Skill、UI 并列的一等认知表面，但它不是可执行 workload。

当前状态：standalone lifecycle 已包含跨平台 bundled SQLite/FTS5 Knowledge 后端、完整 User/Workspace 隔离、事务化 stage/promote/remove、基于精确 projection 授权的带引用搜索、重启恢复、有界 quota/retention/GC、scope-local integrity audit、verified database backup 与 exact-plan oldest-first rotation、只重建派生 FTS 的 repair、authority-bound database 与 exact-subset missing-binding restore，以及 signed real-process 覆盖。精确匹配 version/OS/architecture 的 reviewed whole-installation restore 也已实现。A3S Code 托管的 leased-query 资格验证、缺失 Registry/package/lifecycle/Grant authority 与 clean-machine 恢复、跨平台运营演练、rollback-evidence retention policy 和 whole-product disaster recovery 仍待完成；没有精确 promoted evidence 就不会发布该表面。

#Bundle 结构

一个 OKF bundle 是一个有界目录。每个非保留 Markdown 文件代表一个概念，去掉 .md 的 bundle-relative path 是 concept ID；可选 index.md 提供层级导航，可选 log.md 可在任意层级记录历史。

okf/domain-knowledge/
├── index.md
├── concepts/
│   ├── index.md
│   ├── package-lifecycle.md
│   └── runtime-boundary.md
├── decisions/
│   ├── index.md
│   └── no-provider-fallback.md
└── log.md

概念使用标准 Markdown links，而不是私有 wikilink 语法：

See [Runtime boundary](/concepts/runtime-boundary.md).

#Concept contract

每个非保留概念必须是 UTF-8 Markdown，并以正确分隔的 YAML frontmatter block 开头。OKF 只强制一个字段：非空标量 type。

---
type: Architecture Decision
title: No provider fallback
description: Why plugin workloads require one explicit Runtime provider.
resource: docs/adr-001-plugin-runtime-broker-boundary.md
tags: [runtime, security, plugins]
generated:
  by: a3s-okf-compiler/1.0
  at: 2026-07-31T00:00:00Z
sources:
  - id: runtime-boundary
    resource: docs/adr-001-plugin-runtime-broker-boundary.md
    title: Runtime Broker ADR
---

title、description、resource、tags 是推荐字段。OKF v0.2 还定义了可选 provenance、trust、lifecycle 与 attested-computation 字段族。Producer 扩展字段和未知 concept type 仍然合规，消费者必须保留它们。A3S Use 不会把旧版 timestamp 或 # Citations 布局重新解释为 v0.2 权威内容。

index.md 和 log.md 是保留文件，不是普通 concept。只有 bundle 根 index.md 可以包含 frontmatter，且仅用于声明 okf_version。缺少 index 或安全的 dangling link 仍然合规，应报告诊断而不是拒绝 bundle。

#与其他表面的关系

OKF v0.2 可以描述 Attested Computation、executor 与 attester。A3S Use 只把这些内容视为惰性 metadata，绝不会把它们转换成执行权限；可运行行为仍必须来自单独声明并授权的 Tool 或宿主 binding。

#安装与索引边界

生命周期复用 A3S Use 的 package identity、plan、receipt 和 capability generation：

signed catalog
  → review exact OKF digest, concept count, bytes, provenance
  → verify package and bounded OKF conformance
  → stage exact package generation
  → A3S Knowledge builds/stages its deterministic index
  → atomically promote the candidate OKF generation
  → publish the shared capability snapshot

A3S Use 负责包与 bundle 完整性；Knowledge host 负责合规后的 promotion、索引和带引用检索。当前结果引用精确 package、surface、generation、projection receipt、index、concept path 与 source digest，不宣称行级引用。Candidate 验证或索引失败时，最后一个成功 generation 继续可搜索。

冻结的宿主边界使用三种 canonical record：

• a3s.use.okf-projection-receipt.v2：精确、完整 scope 的 staged candidate；
• a3s.use.okf-knowledge-observation.v2：完整 scope 的 staged、promoted、failed、removed 状态与 last-good selection；
• a3s.use.okf-capability-projection.v2：可安全发布的精确、完整 scope promoted evidence。

Standalone 后端为每个完整 scope 使用独立 SQLite/FTS5 数据库。当前 capability snapshot 选择新提升的 generation；已经打开且持有精确旧 projection 的 session 可在 drain 期间继续查询，receipt-owned removal 后该 projection 立即失效。由于尚未发布稳定 Knowledge 数据库格式，未知 user_version 会被直接拒绝，不迁移也不改写。

#存储策略与恢复

默认 standalone policy 把每个完整 User 或 Workspace scope 限制为 512 MiB retained expanded OKF content、256 个 retained projection、每个 surface 32 个 generation，以及 256 个 scope-wide removal tombstone。以下命令检查用量与 完整性，并创建、离线验证一个不覆盖现有文件的 scope snapshot：

a3s-use knowledge usage \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge audit \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge verify-backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup-retention ./backups \
  --scope-kind user --scope-id user/current --json

未启用的 Control Store 验收层现在会在更严格的 owner snapshot 中复用该格式。 它在一个排他 installation maintenance fence 下把 archive 绑定到规范 Control export digest，计算精确 retained-binding/selection inventory 的摘要，并在发布前 对包含 header 的完整 archive 执行注册大小上限。数据库缺失时会产生显式零文件 manifest，且不会创建 live Knowledge state。这还不是 CLI 或生产 backup 路径； 实时与离线验证还会要求精确绑定的 Control export、精确 prepare/bundle 来源、匹配的 applied observation/projection evidence，以及为已删除或缺失的 applied payload 提供 remove effect。Control 对账会在 目标 archive 写入前针对临时 SQLite snapshot 完成，因此语义失败不会留下 archive 或 receipt。Deferred effect 仅保留为 safe-no-effect 调度证据；claimed 与 unknown effect 仅保留为 reconciliation evidence， 三者都不能选择 desired state。通过验证的 owner snapshot 现在可以在 clean target 的 state root 下暂存并重新审计精确数据库，且不修改 live Knowledge。激活要求对应 target 的排他 maintenance fence，拒绝非 owner、已有或含糊状态，并通过一次原子 rename 发布。结果无路径且绑定 snapshot；仅在 保留同一个 staged attempt 与 fence 时，rename 后的重试才是幂等的； 私有 complete-set snapshot coordinator 现在会把这份精确 Knowledge snapshot 与 Control export 及所有 已注册 owner 一起放入同一个规范单文件 archive，并在 no-clobber 发布前复用此 offline verifier。 通过验证的聚合现在会在接触 target 前预检精确 Knowledge policy，把它绑定到一个无路径 complete-attempt descriptor，并在同一个排他 fence 下把该数据库与 Control 和所有 owner candidate 一起暂存。Live Knowledge root 保持不变。Complete-set activation、持久化跨 owner 恢复与生产 backup/restore 接线仍未完成。

backup-retention 会针对最多 4,096 个 directory entry、一个完整 scope 和 有界 backup count/byte policy 返回 canonical plan。它完整验证 managed candidate，只选择满足限制所需的最旧前缀，并保留最后一份已验证 scope backup。 删除必须同时提供 --yes 与未变化的 --plan-digest；其他 scope、无关文件、 linked candidate 和 stale plan 都不会被删除。

只有 audit 报告派生 FTS 不一致时，才能从已验证 document 明确重建索引：

a3s-use knowledge repair-search-index \
  --scope-kind user --scope-id user/current --yes --json

不要把 backup 直接复制到 live state。先生成无路径审查计划，再只执行精确 digest：

a3s-use knowledge plan-restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current \
  --plan-digest sha256:<reviewed-plan-digest> \
  --yes \
  --json
a3s-use knowledge restore-status \
  --scope-kind user --scope-id user/current --json

Planning 会验证 backup、完整 package/lifecycle/Registry/Grant authority 与当前 exact-subset binding inventory，并绑定该状态以及当前 main database、WAL 和 SHM。确认执行会重新验证同一份 authority，只创建缺失的精确 binding 文件、 保留精确旧 database 文件，并在进程退出后续跑 durable operation。冲突或更新 的 binding evidence 绝不会被覆盖。它不能重建缺失的独立 authority、恢复 clean machine 或其他 state family，也不是 whole-product disaster recovery。 Scope-local backup rotation 不会轮换 restore rollback evidence 或其他 state family。完整边界见 OKF Knowledge operations runbook。

restore-status 不需要 backup path 或 plan digest。它返回有界、无路径的 diagnostic，报告 global active phase、requested scope 的已验证 operation history、marker handoff directory 数量与剩余容量；它不会轮换、删除或改写 recovery evidence。

#编译不属于安装

PDF、Office、图片、邮件、归档和网页是 compiler input，不是 OKF 搜索权威。独立 knowledge compiler 可以把这些来源标准化为 OKF，但安装计划必须审查最终 normalized bundle；安装阶段不会临时下载或执行一个 compiler 来改变已审查内容。

#安全与卸载

• 概念文本、frontmatter、links 和 compiler provenance 都不能修改 ACL policy 或 grant。
• 所有 path、file count、expanded bytes、document bytes 与单文档 link 数都必须有界。安全 dangling link 只产生诊断；解析到包边界外的 reference 会被拒绝。
• Search 只接纳宿主原子 promotion 的合规 generation，不从 staging 目录推断成功。
• Disable 只隐藏新会话中的 OKF capability。
• Uninstall 只移除 package receipt-owned projection/index，不删除个人笔记、raw sources 或另一个包的 index。

实现顺序见 路线图 的 M0K，以及仓库中的 OKF contribution workstream。