Domain Knowledge Compiler

§ 00

一页速览

问题

几乎每个 agent 产品都说自己有"知识库"，但这个词可以指文件夹、向量索引、团队 wiki、长期 memory、SOP 或某个 SaaS 连接器。定义一旦模糊，讨论就把 source、索引、审计、发布、权限、运行时 context 混在一起，最后退化成"把资料接进来，让模型搜一下"。

立场

检索能找回材料；长期知识还需要边界、版本、provenance、review、依赖关系和消费形态。 DKC 把问题收窄到一个明确对象上，而不是笼统地做"一个知识库"。

核心产物

一个由 domain documents（markdown）组成的 published bundle。向量库、cue cards、context packs、task packs 都是从 bundle 派生的 serving projection，权威层始终是 bundle。

五条设计边界

全文所有决策都从这五条推出

1

source-agnostic

本地文件、会议转写、应用数据、设备上下文、第三方系统都可以进入 Source Layer。

2

consumer-agnostic

桌面 agent、云端 agent、移动端问答、可穿戴设备高速 RAG，都只从 published bundle 派生的 projection 取用上下文。

3

domain documents as authority

长期知识以文档形式保存，带版本、来源、审查状态和依赖关系。

4

precompiled dependency

workspace 可以 pin 其他已发布知识包，通过 BundleReference 作为只读 dependency 参与编译。

5

provenance before projection

只有 published / fresh、可溯源（或明确标记 inferred）的知识进入 production projection。日常的编译、合并、冲突、维护由 agent 自治完成；human-in-the-loop 是业务扩展点，不是管线阶段。

§ 01

问题与目标场景

问题来自很具体的日常材料：本地文件、会议记录、聊天摘录、上传文档、应用数据、项目记录、客户上下文、个人偏好、待办和决策。目标是让它们被持续编译成有边界、可追溯、可交换的领域知识，而不停在"能被搜到"。

两个场景贯穿全文，后面每个设计决策都可以拿它们来检验。

场景 A

个人电脑上的个人知识库

输入

本地 Markdown / PDF / 网页剪藏、研究材料、项目日志、已有 Obsidian 库。

编译

用自己的 Claude Code / Codex 订阅在个人电脑上跑 deep compile——离线、夜间、低优先级都行。产物是 per-user 的 canonical knowledge bundle。

消费

桌面端继续用 Claude Code / Codex 做高质量 agentic 问答；高频搜索走向量 projection；临时研究、写作、会议准备用 task pack。

场景 B

办公助手里的工作知识库

输入

会议纪要、客户资料、CRM 导出、项目文档、邮件摘要、任务系统。团队与组织知识以只读 BundleReference 引入。

编译

低价值材料用云端低成本模型批量跑低 effort；高价值客户、关键项目走高 effort 深度整理；敏感内容、身份合并、客户承诺按 policy 标记 escalation，由业务决定是否接入人工。

消费

电脑端 agentic 问答与材料准备；移动端消费 context pack；可穿戴设备消费高速 RAG projection 或 cue cards。

§ 02

职责划分

三方边界先划清，后续讨论才不会漂移：库提供抽象，宿主应用管接入与人，OKF 只管交换格式。

DKC 库

本文档设计的对象——库层抽象与编译能力

workspace · domain · source · compile · provenance
escalation / decision 原语
bundle 与 dependency（BundleReference · manifest · lockfile）
projection · DomainCompileSkill
materialized indexes 与 serving projections

宿主应用

接入、身份、计费与人的体验

authentication / authorization
user / team / org / tenant 到 workspace 的映射
provider key 与计费
产品 UI、escalation 的人工介入体验
存储加密备份、bundle registry 权限与访问控制

OKF

知识包的交换格式，仅此而已

目录树
markdown documents
YAML frontmatter
links
citations

DKC 的 dependency manifest、lockfile、escalation / decision state、内部索引和 projection metadata 都写在 producer metadata 或 workspace state 里，留在 OKF 标准字段之外。OKF 版本升级由 importer / exporter adapter 消化，与 bundle 的内容版本互相独立。

§ 03

一份会议纪要的生命周期

进入抽象架构之前，先用一个具体例子把整条管线走通。假设 workspace 已有一个 work-memory domain，DomainCompileSkill 是 v3。

Day 1 · 15:00

输入 — 落为不可变快照

用户与客户 ACME 开完会，转写文本进入系统，落为一条 append-only 的 SourceSnapshot。

source_id: src-20260702-091

source_type: meeting_transcript

sensitivity_hint: client_confidential

checksum: sha256:9f2c…

Day 1 · 15:05

调度编译

调度器按 workspace policy 创建一个 CompileJob（effort: standard，绑定 skill v3，dependency scope 挂上只读的 team/sales-playbook@2026-07）。

Day 1 · 15:12

产出候选 patch — 全程无人参与

编译器读取 snapshot 和 dependency context，产出一个 KnowledgePatch，内容是若干文档 diff。事实更新、身份合并、冲突改写都由 agent 按 skill v3 的 policy 自治完成，每步都留下可追溯、可回滚的记录。

KnowledgePatch kp-4471

modified

companies/acme.md — "Q3 预算冻结，采购决策推迟到 9 月" [¶14]

created

people/alice-chen.md — Person，ACME 采购负责人 [¶3]

modified

projects/phoenix.md — Commitment："我方承诺 7/15 前交付 POC 报告" [¶22]

merged

"Alice Chen" ↔ 已有节点 "A. Chen (ACME)"，相似度 0.87 → 自动合并，产生 MergeRecord mr-0092（可逆）

conflict

旧 claim "Q3 预算已确认充足" 与新证据矛盾 → 按 merge policy（新证据优先）改写，旧 claim 保留在 disputed 记录里

Day 1 · 15:14

Escalation — 本例未触发，机制在此

假如 skill v3 声明了"客户承诺金额超过 10 万美金时 escalate"，编译器会产生一个 EscalationCase，文档带 open question 标记照常发布，不阻塞管线。业务若接入人工，裁决以 DecisionRecord 作为新输入回流，下一轮 compile 将其当作高权威证据消化。

Day 1 · 15:16

发布 — 本地 bundle v7 → v8

bundle 的 producer metadata 记录 skill v3、dependency lock（sales-playbook@2026-07 sha256:…）、merge records、model / provider lineage。

Day 1 · 15:17

重建 projection — 只动受影响的三个文档

增量编译索引标记出受影响的三个文档，只重建这三个文档对应的向量分片和 cue card。

Day 2 · 09:40

消费 — 会前 briefing 与会中召回

下一场 ACME 会议前 20 分钟，系统生成一个 MeetingPack（TTL 24h）：briefing.md 里有"上次要点 + 未兑现承诺 + Alice Chen 画像"。会议中口头问"上次他们预算怎么说的"，fast RAG 从 v8 bundle 的 projection 毫秒级返回带 citation 的答案——读到的是 projection，不是 raw transcript。

眼镜端 · 会中实时 cue card 未兑现承诺 · 7/15 前交付 POC 报告

Day 2 · 11:00

回流 — 循环继续

这场会议结束，新 transcript 作为新的 SourceSnapshot 回到 Source Layer，循环继续。MeetingPack 到期后按 disposal policy 清理。

§ 04

设计立场

4.1

文档优先

权威层由 domain documents 承担；database rows 和 vector chunks 只服务索引、权限或细粒度处理。

Source→ Document Draft→ Patch（diff）→ Published OKF Bundle→ Serving Projections

Evidence、Claim、DomainNode、Patch 是文档内部按需物化的 facets。只有细粒度追溯、冲突检测、身份合并、权限控制或高速索引需要它们独立存在时，库才把这些 facets 物化为记录；否则，文档本身就是最小可读权威层。

4.2

Meta-skill 优先

核心抽象是生成、演化领域编译规则的 DomainCompileSkill，而非某个固定 schema。用户或宿主从领域目标起步（"销售工作知识库""产品项目知识库"），Skill Builder 生成初始 skill，在真实 source 上 dry run，再通过反馈和 patch 收紧边界。

skill 必须版本化：ontology、prompt、policy、layout 或 eval 的任何变化都产生新 version；旧版本不可变，后续调整通过 migration 或 recompile 表达。

4.3

构建与消费分离

Construction Plane 慢、深、可审计、可离线、可预算；Consumption Plane 快、薄、标准化、可投影。构建追求质量、溯源、审计和可复现，消费追求低延迟、可控上下文和运行环境适配。

Fast RAG 的输入边界是 published projection，raw source 留在 construction 与 provenance 路径里。消费侧让出一点新鲜度，换来可追踪的长期知识边界；慢的那半拍由 task pack 的临时 context 补上。

4.4

Agent 自治与统一输入

直接借鉴 LLM Wiki 的核心洞察：LLM 不会厌倦维护、不会忘记更新交叉引用、可以一次编辑很多文件——让人放弃个人 wiki 的那些簿记工作，恰好是 agent 擅长的。

agent 是知识库的第一管理者。编译、合并、冲突处理、周期性 lint 都是 agent 的常规职责，管线上没有强制人工关卡。可逆性替代事先审批：canonical layer 是版本化的 markdown，任何写入都可回滚，比"写之前先让人看"便宜得多。

human-in-the-loop 是业务扩展点，不是管线阶段。框架只把"agent 无法自行解决"定义为一等概念（EscalationCase）；业务可选择接入人工，不接入时 agent 按 policy 携带 open question 继续推进。

一切对 agent 透明。人的裁决以带 provenance 的 DecisionRecord 进入系统，与其他输入走同一条编译路径。系统之外不存在隐蔽变更，可复现性不会被人的参与破坏。

§ 05

总体架构

五层，从原始输入到消费投影。每层给出核心对象的唯一规范定义，后文只引用。

图 5 · 编译管线五层权威层 = Canonical；其余都是从它派生的投影

LAYER 01
Source Layer

接收与标准化输入，落为不可变、append-only 的快照

SourceSnapshot SourceProducer sensitivity_hint retention_policy
LAYER 02
Compile Plane

慢、深、可审计、可离线、可预算的知识构建

CompileJob DomainCompileSkill KnowledgePatch EffortProfile
LAYER 03 · 权威
Canonical Layer

版本化、可 diff 的 markdown 目录，索引可从文档全量重建

DomainDocument Claim EvidenceSpan MergeRecord EscalationCase DecisionRecord
LAYER 04
Publication / OKF

发布为 OKF 兼容、可交换的知识包

PublishedBundle OkfDocument Manifest Version
LAYER 05
Serving Projection

从 published bundle 派生消费侧结构，可重建、可失效、按环境裁剪

VectorProjection KeywordIndex GraphProjection CueCard ContextPack

消费面 → Agentic · 桌面高质量问答 / 跨文档推理 Fast RAG · 移动 / 可穿戴毫秒级召回 TaskPack · 短生命周期任务包

消费投影始终守三条约束：只有 published / fresh 的知识进入 serving projection；向量库只是投影，权威始终在 canonical documents 和 published bundle； raw source 留在 construction 与 provenance 路径里，不绕过权威层。代价是消费侧读到的投影会比最新 source 慢半拍，这半拍由 task pack 的临时 context 补上。

§ 06

依赖模型：预编译知识包

Workspace 可以在构建阶段引用其他已发布知识包——机制上像 package manager 的 dependency lock：pin 一个版本，只读参与编译。

KnowledgeWorkspace
  sources/   domain skill/   local bundle/
  dependencies/
    - bundle ref: org/product-knowledge@v12  sha256:…
    - bundle ref: team/sales-playbook@2026-07  sha256:…

6.1

BundleReference · 三种状态

当前 workspace 对已发布知识包的只读依赖。三种状态间的转换全部通过显式命令，不存在隐式转换：

reference

默认 · 只读

编译器读它作 context，可在新文档中引用它的 documents / claims，引用时保留来源 bundle、path 和版本。内容始终留在外部 bundle。

import

转本地 · 断开上游

需要修改内容时执行。内容转为本地知识、与上游断开，并记录来源。此后由本地 skill 编译。

vendor

复制快照 · 继续追踪

需要长期可复现、或不信任上游 registry 存续时执行。复制版本快照到本地，同时继续追踪上游更新。

reference 绑定不可变版本或 digest，浮动 latest 只用于发现更新。可复现性要求：相同 source + 相同 skill version + 相同 dependency lock，应当解释同一个 published bundle。依赖关系记录在 dependencies/manifest.yaml、lock.yaml 和导出 bundle 的 producer metadata 里，全部在 OKF 标准字段之外。

6.2

三个互相独立的版本维度

OKF version

交换格式版本（okf 0.1）。决定 markdown bundle 的最低结构与兼容性。format migration 由 importer / exporter adapter 消化。

Bundle version

知识包内容版本（product-knowledge@v12）。BundleReference pin 的就是它和 digest。单调版本号 + content digest，不做 semver 式兼容承诺。

Skill version

领域编译语义版本（work-memory skill v3）。决定如何从 sources 和 dependencies 生成文档。升级走 recompile / migration。

6.3

依赖更新如何传播

registry 检测到 v13→ 创建 ReferenceUpdate→ 按 update policy 处理→ 评估受影响 workspace / domain / task pack / projection→ recompile 受影响 bundle→ 发布 refreshed bundle

manual

只提示用户，由用户决定是否升级。

auto-minor

自动接受兼容更新，生成 refresh patch；"兼容"由 registry 的兼容性声明判定。

pinned

永不自动更新，只记录有新版本。

vendor-on-update

新版本先复制为本地快照，再走正常 compile 路径。

refresh 只通过 manifest 更新 + recompile 生效；v12 → v13 的更新可追踪、可回滚；自动更新只在 policy 明确允许的范围内发生。

§ 07

四个难题与默认方案

这四个问题决定系统在真实使用中会不会退化。方案是设计的一部分，不是实现细节。

难题 01

人工介入：扩展点，而非 review 管线

问题

若把人工 review 做成管线强制阶段，活跃 workspace 每天产生几十上百条待审项，review 疲劳会让用户全选通过，gate 名存实亡；但完全不留人工介入途径，企业敏感场景又无法接入。

默认方案 · agent 全自治发布

默认路径零人工。所有 patch 由 agent 按 policy 自治发布；patch 本就是 diff，配合版本化 bundle，任何发布都可回滚——可逆性替代事先审批。
EscalationCase 是唯一人工介入原语，触发条件由 skill 的 escalation_policy 声明，默认非阻塞：文档带 open question 照常发布。
人的裁决以 DecisionRecord 进入系统，走同一条编译路径。审计视图替代审批队列——事后抽查，不事前把关，冷启动 bulk import 因此不再积压。

难题 02

冲突与身份合并：agent 处理，可逆，可见

问题

两个 source 说法矛盾、两个名字疑似同一个人——编译类系统最难的部分。但它不需要人：矛盾本身是需要被记录和维护的知识，而不是需要人来裁决的阻塞项。

默认方案

Conflict 是一等对象，由 agent 写回文档。merge policy 声明自动裁决规则（如"新证据优先"），裁决后旧 claim 不删除，保留在 disputed 记录里：

## 预算状态
Q3 预算已冻结。 [cite: src-091, 2026-07-02]

<!-- disputed: 与早前证据矛盾，按 recency 规则改写 -->
<!-- superseded: "Q3 仍有 5 万美金余量" [cite: src-104] -->

无法自动裁决的矛盾并列写为 open question，按需产生 EscalationCase，文档照常发布。
周期性 Lint。agent 定期对整个 bundle 做健康检查——页间矛盾、过期 claim、断链、孤儿节点——产出 lint patch 走同一路径，把冲突处理从"一次性动作"变成"持续维护"。
身份合并自动执行、永远可逆。高置信合并产生 MergeRecord；撤销时按 citation 归属把 claim 拆回——因此 citation 必须落在 claim 级别。

难题 03

增量编译：source→document 依赖索引

问题

"持续编译"若意味着每个新 snapshot 都触发全量 deep compile，成本模型撑不住。

默认方案

库维护一张 source→document 依赖索引：记录哪些 snapshot 的哪些 span 支撑了哪些 document 的哪些 section（这本就是 citation 数据的反向视图）。
新 snapshot 进入时先做影响范围计算：实体识别 + 索引查询，标记 dirty documents，compile 只作用于 dirty 集合及其一跳关联。
深度分摊：日常增量走 quick / standard；deep（跨文档综合、冲突扫描、eval）在 dirty 累积到阈值或按 schedule 触发。
skill 升级触发的全量 recompile 是显式 migration job，不与日常增量混在一条路径。

难题 04

删除与传播：tombstone + 降级

问题

强调 provenance 的系统必须回答：source 被删除后，引用它的 claim、已发布 bundle、下游 dependency 怎么办？（GDPR 类场景下这是硬要求。）

默认方案 · 删除如何向下传播

删除 SourceSnapshot→ 转为 tombstone（留 id / checksum，清 body）→ 依赖索引找出受影响 claims→ 每条按剩余证据处理：有其他 citation 则保留，否则降级 inferred 或删除→ 生成 deletion patch→ 发布新 bundle，下游按 update policy 处理

历史 bundle version 是否物理清除，由宿主的合规策略决定（库提供 purge 接口）。
tombstone 保证"曾经存在过一条来源"可审计，但内容不可恢复。

§ 08

消费面

两类消费接口从 canonical layer 和 published bundle 的可解释表面读取；raw source 留在 source registry 和 provenance 路径里。

8.1 · Agentic

可追踪、结构化、预算可控

桌面端高质量问答、复杂计划、长上下文准备、跨文档关系推理，以及"为什么知道这个"的追问。

get_context_pack(objective, budget, filters)
read_document(path) / read_node(node_id)
trace_claim(claim_id) / list_related(node_id)
inspect_bundle(path)
list_escalations(domain_id)
explain_merge(record_id)

8.2 · Fast RAG

低延迟，走预构建 projection

移动端快速问答、可穿戴实时提示、会中 cue、autocomplete、quick recall。输入永远是 published projection。

search(query, filters, latency_budget)
retrieve_chunks(query, top_k)
get_precomputed_projection(type)
get_cue_cards(context)
get_task_brief(pack_id)

8.3

TaskKnowledgePack · 短生命周期

读取已结构化知识 + 临时 context，生成 task-specific briefing、小型向量索引、cue cards、source windows 和 agent context pack。§03 的 MeetingPack 就是实例。

输入

用户选择的 knowledge nodes、系统建议的相关 nodes、只读 dependency 中的相关 documents、临时 context（议程、参会人、目标）、时间 / 地点 / 设备上下文。

生命周期

临时 context 只存在于 pack 内部，不写入 canonical layer；pack 过期按 disposal policy 清理（默认硬删内容，留归档 metadata 供审计）；任务产生的新长期材料回到 Source Layer 成为新 SourceSnapshot。

§ 09

Workflows

把前面的机制串成几条可执行路径。所有路径最终都汇到同一个 compile / publish 出口。

创建新 domain skill

描述领域需求→ Meta-skill 访谈 / 观察示例→ 起草 ontology + policies→ 样本 source dry-run→ 用户校正边界→ 发布 DomainCompileSkill v1

稳态编译

新 SourceSnapshot→ 影响范围计算→ 调度 CompileJob（effort / budget）→ 起草 / 更新 dirty documents→ 生成 KnowledgePatch→ 按 escalation policy 标记未决项→ 发布 bundle→ 重建受影响 projection

周期性 Lint

schedule / dirty 阈值触发→ agent 全库健康检查→ 矛盾 / 过期 claim / 断链 / 孤儿节点→ lint patch→ 正常 compile / publish 路径

Escalation 与回流

compile 触发 escalation policy→ EscalationCase（带 open question 照常发布）→ 宿主（可选）呈现给人→ DecisionRecord 作为一等输入回流→ 下一轮 compile 消化，open question 关闭

§ 10

存储目录

canonical store 为 directory-first：权威层是版本化的 markdown 目录，索引是可从文档全量重建的派生物。

workspaces/{workspace_id}/
  policies/
  dependencies/
    manifest.yaml   lock.yaml   updates/
  sources/snapshots/
  domains/{domain_id}/
    skills/domain-skill.v{n}.yaml
    evidence/   claims/   nodes/
    patches/    escalations/   decisions/
    bundles/published/   bundles/okf/
    projections/{vector,bm25,graph,cue}/
    task-packs/{pack_id}/

§ 11

落地路线

每个 MVP 标注它验证的核心假设。

MVP 1

Local Workspace Prototype

验证 · 管线成立

上传 markdown / transcript 成为 SourceSnapshot；手写 work-memory skill；quick / standard 两档 compile；source → draft → patch → OKF export；patch 历史 + 版本回滚（无人工关卡）；agent context pack。

MVP 2

Work-Memory Pilot

验证 · 真实工作流价值 + §7.1 / §7.3

会议转写与上传文件 adapter；work-memory ontology；周期性 Lint 上线；escalation 扩展点上线（非阻塞，含 DecisionRecord 回流）；增量编译索引上线；Prep Note、Cue Card projection；MeetingPack；用户可控 compile effort。

MVP 3

Meta-Skill Generation

验证 · §4.2 的 meta-skill 立场

用户描述领域 → 起草 ontology 和 policies → 样本 dry-run → 用户校正边界 → 发布 skill v1。同期落地 §7.2 的 MergeRecord 与 disputed section。

MVP 4

Shared Knowledge 与生产集成

验证 · §6 依赖模型与生产化

BundleReference / manifest / lockfile；只读共享知识包；依赖更新传播；budget enforcement；宿主 auth 与 provider key；eval / freshness gates；escalation 宿主 UX（含可选阻塞）；projection 访问策略；audit log；§7.4 删除传播。

附录 A

模块划分与对象索引

面向工程分工：每个模块对应一个 package 和一名 owner。对象的规范定义在"章节"列所指位置。

模块	职责边界	核心对象	章节	阶段
Workspace & Policy	workspace 生命周期；预算 / 隐私 / 保留策略；依赖声明	KnowledgeWorkspace · WorkspacePolicy · BudgetPolicy	§5, §6	MVP 1
Source Registry	source 接入、标准化、去重、tombstone 与保留	SourceSnapshot · SourceProducer · SourceIdentity	§5.1, §7.4	MVP 1 / 4
Domain Skill	skill 的定义、版本化与生成	DomainCompileSkill · OntologySpec · PolicySpec · EvaluationCase	§4.2, §5.2	MVP 1 / 3
Compile Orchestration	调度、effort / budget、checkpoint、增量索引	CompileJob · CompilePlan · EffortProfile · CompileCheckpoint	§5.3, §7.3	MVP 1–2
Knowledge Construction	文档起草、合并、冲突、lint	DomainDocument · Claim · EvidenceSpan · DomainNode · KnowledgePatch · Conflict · MergeRecord	§5.4, §7.2	MVP 1–3
Escalation & Decision	escalation 原语、人工裁决回流、审计	EscalationCase · DecisionRecord · AuditRecord	§4.4, §7.1	MVP 2 / 4
Dependency	BundleReference、manifest / lockfile、更新传播	BundleReference · DependencyManifest · DependencyRegistry · ReferenceUpdate	§6	MVP 4
Publication / OKF	bundle 发布、OKF 导入导出、多版本映射	PublishedBundle · OkfDocument · BundleVersion · ExportPolicy · ImportPolicy	§5.5	MVP 1 / 4
Serving Projection	projection 构建、失效、按环境裁剪	VectorProjection · KeywordIndex · GraphProjection · CueCard · PrepNote · ContextPack	§5.6, §8	MVP 1–2
Task Pack	短生命周期任务包与回流	TaskKnowledgePack · TemporaryContext · DisposalPolicy · PromotionPolicy	§8.3	MVP 2

参考：Karpathy LLM Wiki（agent 自治维护 markdown wiki、ingest 时标注矛盾与周期性 lint、版本历史作安全网）· Google Open Knowledge Format v0.1（交换用 markdown-bundle 格式）· atomicstrata/llm-wiki-compiler（local-first 参考实现）。