Grounded knowledge field manual

klode
实战指南

先记住这一句

它解决什么问题

常见知识库

搜索到相似内容

回答看起来合理，但你很难知道摘要是否来自当前版本、引用是否已经漂移。

→

klode 的约束

每个关键主张都带原文锚点

卡片里的 (grep: …) 必须在指定 source 中解析；失效、缺源或歧义都会被显式报告。

Input

原始资料

PDF / EPUB / DOCX / HTML / TXT

Normalize

干净文本

统一成 grep-ready source

Encode

知识卡片

摘要 + 原文锚点 + 层级

Verify

失效检查

引用是否仍存在且唯一

Consume

人 / Agent

CLI、JSON、MCP、Python

Loop A · 稳定核心

编码专业知识

导入 source，制作带 verbatim anchor 的 cards，搜索、consult、zoom、verify，并用 klode check 阻止引用腐烂。

Loop B · 实验层

监督工作产出

用 CriterionSpec rubric 评审草稿，输出 Go / Recycle / Unavailable。机制已实现，但尚未做人类评分校准，所有 verdict 都标记为 non-production。

5 分钟跑通最小闭环

先用一个小型 TXT 跑通，再导入复杂 PDF。这样最容易分辨“配置问题”与“抽取问题”。

安装并确认版本

正式使用建议隔离环境；只是体验可直接安装。源码开发模式用 pipx install -e .。

TerminalPython 3.11+python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip klode
klode --help

初始化知识库

--shelf 可重复。shelf 是资料分类，不是权限边界。

TerminalCreates library.tomlmkdir my-klode && cd my-klode
klode init . --shelf books --shelf papers --shelf notes

先导入一个简单文件

格式由内容签名识别，不依赖扩展名。--id 决定稳定 card/source id。

TerminalOne sourceklode -c library.toml ingest ./sources/note.txt \
  --shelf notes --id grounded-writing

生成卡片骨架，再人工写 Thin / Full

build 生成 card 与 index，但不会替你凭空总结。关键主张后必须附 literal anchor。

TerminalScaffold cardsklode -c library.toml build
$EDITOR library/cards/grounded-writing.md

执行 fail-closed 检查

严格模式会把“一句话在 source 中出现多次”的裸锚点标成 warning，提醒你增加上下文或指定第几次出现。

TerminalQuality gateklode -c library.toml check --strict

检索与原文复核

搜索负责发现，verify 负责证明某个 exact phrase 是否存在；两者不要混为一谈。

TerminalDiscover → verifyklode -c library.toml search grounding
klode -c library.toml zoom grounded-writing --level thin
klode -c library.toml verify grounded-writing "exact source phrase"

知识库的目录与卡片模型

source 留在本地，card 适合版本控制；这正是 klode 把“版权内容”和“可共享知识结构”分开的方式。

DirectoryRecommendedmy-klode/
├── library.toml
├── .gitignore
└── library/
    ├── BIBLIOGRAPHY.md
    ├── PROVENANCE.jsonl
    ├── books/
    │   └── source-id.txt      # 本地、默认忽略
    ├── papers/
    └── cards/
        ├── INDEX.md
        └── source-id.md       # 可审查、可提交

Four levels of zoom

不要让每次查询都吞下全文

L0 · meta：id、标题、shelf、aliases 等导航信息
L1 · thin：1–3 句核心机制，关键主张带锚点
L2 · full：较完整的结构化观点，仍须逐条引用
L3 · content：原始 clean text，用于精确验证与取证

一个合格 card 的最小形态

Markdownlibrary/cards/source-id.md---
id: source-id
shelf: books
file: library/books/source-id.txt
aliases: [替代叫法, 核心概念]
source_sha256: …
---

# Source title

## Thin
一个关键结论（grep: `原文中逐字存在的短语`）。

## Full
- 第二个主张（grep: `唯一原文片段`）。
- 若片段重复，增加上下文（grep: `target` before `prefix` after `suffix`）。
- 或精确指定第 2 次出现（grep: `target` #2）。

锚点要“短到稳定，长到唯一”

太长，source 的标点或排版小改就容易断；太短，可能在全文出现多次。优先选择 6–16 个有辨识度的词，并用 before / after / #n 消除歧义。

日常使用：发现、阅读、验证

把 klode 当成一条检索链：先缩小范围，再读取 lens/card，最后对关键句做 exact verification。

列出可用内容

先确认 KB、card 与 lens 是否存在。

klode kbs
klode -c library.toml cards
klode -c library.toml lenses

全文检索卡片

默认偏向 L0/L1；只有确实需要更深召回时才加 --full。

klode -c library.toml search narrative pacing
klode -c library.toml search --full --limit 8 narrative pacing

按层级阅读

先 Thin，信息不够再 Full，最后才触碰 Content。

klode -c library.toml zoom brevity --level meta
klode -c library.toml zoom brevity --level thin
klode -c library.toml zoom brevity --level content --grep "exact phrase"

咨询与诊断

consult 读一个维度 / 作者 / framework；diagnose 用自然语言症状路由到该看的 lens。

klode -c library.toml consult pacing
klode -c library.toml consult pacing --section options
klode -c library.toml diagnose "the reveal feels flat"

机器消费

对 read verbs 加全局 --json；JSON 携带 op、KB 与 provenance，不要再从人类文本输出里做脆弱解析。

klode --json -c library.toml search pacing
klode --json -c library.toml verify brevity "exact quote"

资料导入：从 TXT 到复杂 PDF

EPUB / DOCX / HTML / TXT 走标准库实现；PDF 的难点是 OCR、双栏阅读顺序与表格结构。

格式	建议路径	关注点	结论
TXT / HTML	`--format auto`	编码、导航噪声、重复页眉	Start here
EPUB / DOCX	默认 stdlib handler	章节顺序、脚注、嵌套表格	Low friction
文本型 PDF	`--tier auto`	文字层质量、页覆盖、阅读顺序	Measure
扫描 / 双栏 PDF	remote docling	OCR、双栏、超时、上传边界	Prefer remote
表格密集 PDF	docling + 人工逐表复核	cell value transposition 无法被现有完整性信号捕获	Human gate

导入命令

klode -c library.toml ingest report.pdf \
  --shelf papers --id report-2026 \
  --tier auto --lang eng

用户级设置

TOML~/.klode/settings.toml[ingest]
tier = "auto"
verify = true
docling_url = "http://private-host:15001"
marker_url = "http://private-host:15002"
marker_mode = "fast"

↯

为什么仓库建议 remote backend

远程转换有随文档规模调整的 deadline；本地 in-process kreuzberg / docling 没有 wall-clock bound，病态 PDF 可能长期卡住。远程还让 klode 客户端继续保持零依赖。服务应绑定在私有接口，不能靠 URL 难猜来当安全控制。

避免

只看文件扩展名，不看内容签名
把 marker 默认塞入 auto ladder；当前测量不支持
在 settings 文件保存 API key
把 “integrity verified” 误读成“每个数字都正确”

多知识库与 MCP：接入 AI 工作台

一个 engine 可以服务单 KB，也可以用 registry 挂载多个 KB；CLI 与 MCP 共享同一个 operations core。

Registry manifest

TOML~/.klode/registry.toml[[kb]]
id = "writing"
path = "~/kbs/writing/library.toml"

[[kb]]
id = "product"
path = "~/kbs/product/library.toml"

查找顺序：显式 --registry → 当前项目 ./.klode/registry.toml → 用户级 ~/.klode/registry.toml。

按 KB 地址使用

klode kbs
klode --kb writing search pacing
klode --kb product consult positioning

# 单库 MCP
klode-mcp -c ~/kbs/writing/library.toml

# 多库 MCP
klode-mcp --registry ~/.klode/registry.toml

JSONIllustrative client config{
  "mcpServers": {
    "klode": {
      "command": "klode-mcp",
      "args": ["--registry", "/absolute/path/to/.klode/registry.toml"]
    }
  }
}

Agent tool

发现

list_kbs、list_lenses、search_sources

Agent tool

深入

consult_dimension、consult_framework、zoom_card

Agent tool

取证

verify_quote、diagnose；所有 grounded result 都标注所属 KB。

◎

给 Agent 的推荐工作协议

先 list_kbs 定边界 → search_sources 找候选 → zoom_card 读 Thin / Full → 对最终答案中的关键证据调用 verify_quote。不要让 Agent 从搜索摘要直接跳到结论。

0.4.x 的重要变化：没测到，不再伪装成通过。CI 应区分“测量失败”和“无法测量”。

0工作确实执行且通过

可以继续 pipeline。

1测量完成，但不通过

例如 anchor 断裂或 check 发现错误。

2无法完成测量

例如 corpus 未安装、backend 不可用、没有匹配文件。

CIFail closed by defaultklode -c library.toml check --strict
case $? in
  0) echo "verified" ;;
  1) echo "measured and failed"; exit 1 ;;
  2) echo "abstained: measurement did not happen"; exit 2 ;;
esac

Use consciously

`--allow-unmeasured` 是接受缺口，不是修复缺口

只有当某个环境“按设计就没有本地 corpus”且你明确接受无法检查时再使用。不要为了 CI 变绿而全局追加；否则引用可能全部腐烂，pipeline 仍然放行。

最佳实践：把库做成长期资产

好用的 klode 库不是一次性 ingest 出来的，而是围绕稳定 id、证据粒度、人工审查和自动门禁持续维护。

01 · Stable identity

id 一旦公开就别随意改

card id、MCP 引用与外部链接都会依赖它。用语义化、与文件名解耦的 slug，例如 cooper-stage-gate。

02 · Source of truth

card 不复制全文

source 只保留一份 clean text；card 写 Thin / Full 与 anchors。减少重复、漂移和版权暴露。

03 · Retrieval budget

Thin 优先，Full 按需

让人和 Agent 先消费 L1；只有结论需要更多语境时才加载 L2/L3，降低 token 与注意力成本。

04 · Exact evidence

锚点逐字引用，不要改写

05 · Deliberate ambiguity

主动消除重复命中

持续运行 check --strict，使用 before / after / #n。歧义不是小瑕疵，而是证据对象不明确。

06 · Human review

表格、数字、否定词人工抽查

优先核对金额、日期、状态、列对应关系，以及 approved / rejected 这类一字翻转结论。

07 · Copyright boundary

提交 cards，不提交 corpus

保留 [copyright].guard = true 和 managed .gitignore。执行 init 增加 shelf 后会刷新受管 ignore block。

08 · Config hygiene

设置可解释，密钥只进环境

使用 klode settings --explain 与 --lint；ANTHROPIC_API_KEY 不进入 settings、仓库或备份。

↻

排错手册

先判断问题属于配置、资料抽取、知识建模还是运行环境；不要一上来切 OCR backend。

症状	最可能原因	检查 / 处理
anchor ambiguous	短语出现多次	用更有辨识度的片段，或增加 `before / after / #n`。
PDF 文字乱序	双栏 / layout-heavy 文档被普通 text layer 顺序误导	切到 remote docling；抽查每页 reading order；表格仍人工核对。
`--tier auto` 拒绝结果	所有候选都没达到 auto 自己的质量门槛	不要盲目 `--force`；检查 scan 质量、语言与 backend。强制 tier 代表你主动承担该结果。
settings 看似没生效	参数或环境变量优先级更高	运行 `klode settings` 查看每个值的来源，再运行 `klode settings --lint`。
MCP 能启动但无 KB	registry 为空 / 路径错误 / 客户端 args 不正确	先在终端运行同一条 `klode-mcp` 命令，随后用 `klode kbs --registry …` 验证 catalog。
live review 没运行	未显式加 `--live-judge`，或缺 model / API key	这是安全设计：配置模型不等于同意产生 billed calls。先设置 model 与环境密钥，再显式调用。

进阶：监督 Agent 的正确预期

Loop B 很有潜力，但截至 0.4.2，它是“可研究、可试验”，不是可直接替人拍板的生产审批器。

Real

CriterionSpec v1

rubric 有稳定 id、行为锚定等级、字段级 epistemics、corpus fingerprint 与人工批准门。

Real

Fail-closed grounding

任一 criterion 的 evidence 失效就返回 Unavailable，不会偷偷丢掉该项后重新平均。

Not done

人类评分校准

没有任何 rubric 做过 judge-vs-human calibration；所有 verdict 明确标成 non-production。

ExperimentalCost-aware# rubric authoring tool（不是稳定 klode CLI 子命令）
python3 -m klode.gate -c library.toml derive pacing
python3 -m klode.gate -c library.toml check pacing
python3 -m klode.gate -c library.toml approve pacing

# 默认不发网络请求；live judge 必须显式同意
klode -c library.toml review draft.md pacing
klode -c library.toml review draft.md pacing --live-judge

Production boundary

Agent 给建议，人做承诺

当前只实现 should-meet score；must-meet knockout 与 Hold 仍未实现。即使未来完成校准，最终 Go / Recycle 也应由人确认，尤其是客户交付、合规、财务与公开发布。

上线路线图：从试验到可依赖

不要一开始导入几千份资料。用一个高价值、可人工核验的 shelf 建立质量基线。

Day 1

跑通 3 份资料

1 个 TXT、1 个普通 PDF、1 个复杂 PDF。完成 ingest → card → check → verify。

Week 1

形成 20 张高价值 cards

每张至少有可用 Thin，核心 claim 全有 anchor；为 AI Agent 接上单 KB MCP。

Week 2+

再扩 registry 与 CI

拆分领域 KB，加入 check --strict，建立 source 更新与人工复核节奏。

交付前检查清单

Python 版本 ≥ 3.11，klode --help 正常

library.toml 路径、shelves 与 copyright guard 正确

source 使用稳定 id，原始文件不被 Git 跟踪

每个核心 card 已完成 Thin，重要主张有 verbatim anchor

klode check --strict 返回 0，不把 exit 2 当通过

表格、金额、日期、状态和否定词完成视觉复核

klode settings --lint 通过，密钥仅在环境变量

MCP 用绝对路径启动，并通过 list → search → verify 闭环

CI 明确区分 0 / 1 / 2，不滥用 --allow-unmeasured

Loop B verdict 没有被当成 production approval

证据来源与适用边界

本指南以官方仓库与源码行为为依据，命令通过本地 checkout 实跑核验；不是第三方转述。

它解决什么问题

搜索到相似内容

每个关键主张都带原文锚点

原始资料

干净文本

知识卡片

失效检查

人 / Agent

编码专业知识

监督工作产出

5 分钟跑通最小闭环

安装并确认版本

初始化知识库

先导入一个简单文件

生成卡片骨架，再人工写 Thin / Full

执行 fail-closed 检查

检索与原文复核

知识库的目录与卡片模型

不要让每次查询都吞下全文

一个合格 card 的最小形态

锚点要“短到稳定，长到唯一”

日常使用：发现、阅读、验证

列出可用内容

全文检索卡片

按层级阅读

咨询与诊断

机器消费

资料导入：从 TXT 到复杂 PDF

导入命令

用户级设置

为什么仓库建议 remote backend

推荐

避免

多知识库与 MCP：接入 AI 工作台

Registry manifest

按 KB 地址使用

发现

深入

取证

给 Agent 的推荐工作协议

--allow-unmeasured 是接受缺口，不是修复缺口

最佳实践：把库做成长期资产

id 一旦公开就别随意改

card 不复制全文

Thin 优先，Full 按需

锚点逐字引用，不要改写

主动消除重复命中

表格、数字、否定词人工抽查

提交 cards，不提交 corpus

设置可解释，密钥只进环境

推荐维护节奏

排错手册

进阶：监督 Agent 的正确预期

CriterionSpec v1

Fail-closed grounding

人类评分校准

Agent 给建议，人做承诺

上线路线图：从试验到可依赖

跑通 3 份资料

形成 20 张高价值 cards

再扩 registry 与 CI

交付前检查清单

证据来源与适用边界

`--allow-unmeasured` 是接受缺口，不是修复缺口