用 LLM-wiki 编译 Harness Engineering：3 种开源方案横评
用同一批素材，喂给 3 种 LLM-wiki 实现，看谁编译出的知识库最靠谱——附完整上手教程。
一、背景：两个新概念的碰撞
2026 年初，AI 工程领域同时冒出两个有意思的概念：
Harness Engineering— Mitchell Hashimoto 在 2 月提出，核心公式是Agent = Model + Harness。Harness 指包裹 AI Agent 的完整控制系统：guides（前馈控制）、sensors（反馈控制）、数据上下文管线、编排逻辑。Martin Fowler 的网站随后发表了系统性长文，OpenAI 也披露了内部实践案例。
LLM-wiki— Andrej Karpathy 在 4 月提出，核心类比是"编译 vs 解释"。传统 RAG 像解释执行（每次查询从零检索），LLM-wiki 像编译执行（LLM 提前把素材编译成结构化 wiki，查询时在编译制品上推理）。
RAG: query → search chunks → answer → forget LLM-wiki: sources → compile → wiki → query → save → richer wiki这两个概念天然适合放在一起：用 LLM-wiki 来编译 Harness Engineering 的碎片知识。更有趣的是——构建 wiki 的过程本身就是 Harness Engineering。CLAUDE.md 是 Guide，lint 脚本是 Sensor，素材管线是 Data Context Layer。这个自指性我们在最后讨论。
二、实验设计
素材
从公开资料中选取 8 篇高质量素材，覆盖学术论文、权威博客、资源汇总、企业实践：
| # | 来源 | 类型 | 核心贡献 |
|---|---|---|---|
| 1 | Martin Fowler 长文 | 博客 | Guides + Sensors 分类体系 |
| 2 | arXiv 论文 | 学术 | Natural-Language Agent Harness 形式化 |
| 3 | awesome-harness-engineering | GitHub | 设计原语全景地图 |
| 4 | Red Hat Developer | 企业实践 | 两阶段结构化工作流 |
| 5 | SmartScope | 博客 | Harness ⊇ Context ⊇ Prompt 三层嵌套 |
| 6 | Louis Bouchard | 博客 | 历史脉络与三概念辨析 |
| 7 | Parallel.ai | 长文 | 五阶段生命周期、组件分类 |
| 8 | Atlan | 指南 | Agent=Model+Harness、数据质量 |
三个方案
选取类型差异最大的 3 种 LLM-wiki 开源实现：
| 方案 | 类型 | 仓库 | 一句话特点 |
|---|---|---|---|
| A | TypeScript CLI | atomicmemory/llm-wiki-compiler | 两阶段编译管线，跨源概念合并 |
| B | Shell 技能包 | sdyckjq-lab/llm-wiki-skill | 多平台适配，EXTRACTED/INFERRED 置信度标签 |
| C | 纯模板 | tonbistudio/llm-wiki | 一个 CLAUDE.md 就是全部，零代码 |
实验流程
同一批 8 篇素材（markdown） │ ├──→ 方案 A（CLI 编译器）──→ wiki_B/ 49 概念页 ├──→ 方案 B（技能包）────→ wiki_C/ 19 页（entity+topic+source） └──→ 方案 C（纯模板）────→ wiki_D/ 29 页（concept+entity+summary） │ ▼ 统一评估：30 核心概念覆盖率 + 交叉引用密度 + 可审计性三、方案 C：纯模板——5 分钟上手
适合：想零成本试试 LLM-wiki 的人。
方案 C 是最简单的起点——全部"代码"就是一个CLAUDE.md文件，告诉 LLM 如何组织知识库。
动手教程
第 1 步：克隆模板
gitclone https://github.com/tonbistudio/llm-wiki.git my-wikicdmy-wiki你会得到这个结构：
my-wiki/ ├── CLAUDE.md ← 核心：LLM 的工作指令 ├── raw/ ← 放原始素材（不可变） └── wiki/ ← LLM 生成的知识库 ├── concepts/ ├── entities/ ├── summaries/ ├── syntheses/ ├── index.md └── log.md第 2 步：放入素材
cpyour-articles/*.md raw/把你想整理的文章、笔记、论文放进raw/。支持 markdown、txt 等纯文本格式。
第 3 步：让 LLM 开始编译
在 Claude Code（或任何支持 CLAUDE.md 的 Agent）中打开这个目录，然后说：
帮我 ingest raw/ 下所有素材LLM 会按 CLAUDE.md 里定义的工作流，逐篇处理：
- 读取原始素材
- 创建
wiki/summaries/摘要页 - 提取概念 →
wiki/concepts/ - 提取实体 →
wiki/entities/ - 添加
[[wikilinks]]交叉引用 - 更新
index.md和log.md
第 4 步：用 Obsidian 浏览
直接用 Obsidian 打开wiki/文件夹——所有[[wikilinks]]都能点击跳转，Graph View 可以看到知识网络。
我们的实验结果
| 指标 | 数值 |
|---|---|
| 生成页面 | 35 个 .md |
| 概念页 | 16 |
| 实体页 | 5（Mitchell Hashimoto、Martin Fowler、OpenAI、Anthropic、LangChain） |
| 摘要页 | 8 |
| 交叉引用 | 184 个 wikilinks |
| 概念覆盖率 | 93%（30 项中覆盖 28 项） |
优缺点
优点：零依赖、零配置、5 分钟出结果、所见即所得
缺点：没有自动化（全靠 LLM 自觉）、来源标注粗糙（只到页面级）、质量完全取决于 LLM
四、方案 B：技能包——置信度标签是杀手特性
适合：用 Claude Code 做知识管理、需要区分"原文说的"和"AI 推断的"。
方案 B 是一个完整的技能系统，有初始化脚本、缓存去重、格式验证、多平台适配。它的独特亮点是EXTRACTED / INFERRED / AMBIGUOUS / UNVERIFIED四级置信度标签。
动手教程
第 1 步：克隆并安装
gitclone https://github.com/sdyckjq-lab/llm-wiki-skill.gitcdllm-wiki-skillbashinstall.sh--platformclaude安装器会把技能文件复制到~/.claude/skills/llm-wiki，之后 Claude Code 每次启动都能感知这个技能。
第 2 步：初始化知识库
在 Claude Code 里说：
帮我初始化一个知识库，主题是 Harness Engineering，语言用 English或者直接跑脚本：
bashscripts/init-wiki.sh ~/Documents/harness-wiki"Harness Engineering""English"生成的目录结构：
harness-wiki/ ├── raw/ │ ├── articles/ ← 网页文章 │ ├── tweets/ ← X/Twitter │ ├── pdfs/ ← PDF │ └── notes/ ← 笔记 ├── wiki/ │ ├── entities/ ← 实体页 │ ├── topics/ ← 主题页（跨素材聚合） │ ├── sources/ ← 素材摘要 │ └── synthesis/ ← 综合分析 ├── purpose.md ← 研究方向（LLM 每次 ingest 都参考） ├── index.md ├── log.md └── .wiki-cache.json ← SHA256 去重缓存第 3 步：填写研究方向
编辑purpose.md——这是方案 B 的灵魂。LLM 在每次 ingest 和 query 时都会先读取它：
## Core Goal Build a knowledge base on Harness Engineering — the discipline of designing control systems around AI agents. ## Key Questions 1. What are the core components of an agent harness? 2. How do different harness designs impact reliability? 3. What is the relationship between prompt/context/harness engineering?第 4 步：消化素材
cpyour-articles/*.md raw/articles/然后对 Claude Code 说：
帮我消化 raw/articles/ 下所有素材方案 B 的 ingest 是两步式的：
Step 1（结构化分析）： 素材 → JSON（entities, topics, connections, confidence） Step 2（页面生成）： JSON + 现有 wiki → source 摘要页 + entity 页 + topic 页第 5 步：查看置信度标签
生成的页面会带置信度注释：
<!-- confidence: EXTRACTED --> **Core formula**: Agent = Model + Harness (Mitchell Hashimoto, Feb 2026). <!-- confidence: INFERRED --> **Role shift**: Programmer's role shifting toward designing "habitats where agents can do useful work."- EXTRACTED：原文里字面能找到
- INFERRED：从多处原文推断出来
- AMBIGUOUS：原文说法不清楚
- UNVERIFIED：来自 LLM 背景知识，原文没有证据
第 6 步：健康检查
帮我做个知识库健康检查脚本会自动检查：孤立页面、断链、index 一致性。AI 会补充检查：矛盾信息、交叉引用缺失。
我们的实验结果
| 指标 | 数值 |
|---|---|
| 生成页面 | 20 个 .md |
| Entity 页 | 8 |
| Topic 页 | 3（Harness Design Patterns / Agent Reliability / Harness vs Prompt vs Context） |
| Source 摘要页 | 8 |
| 交叉引用 | 176 个 wikilinks |
| 概念覆盖率 | 83% |
优缺点
优点：四级置信度标签（独家）、Topic 页做跨素材聚合、SHA256 缓存避免重复处理、purpose.md引导研究方向
缺点：页面总数较少（粒度粗）、部分概念没有独立页面、依赖 LLM 交互
五、方案 A：CLI 编译器——3 条命令碾压全场
适合：有 API Key、追求最高质量 wiki 产出的人。
方案 A 是唯一全自动的方案——不需要 LLM 交互，不需要手动操作，三条命令出结果。
动手教程
第 1 步：安装
npminstall-gllm-wiki-compiler或者本地安装：
gitclone https://github.com/atomicmemory/llm-wiki-compiler.gitcdllm-wiki-compilernpminstall&&npmrun build第 2 步：配置 API Key
exportANTHROPIC_API_KEY=sk-ant-...# 或者如果你已经配置了 Claude Code，它会自动读取 ~/.claude/settings.json支持 Anthropic（默认）、OpenAI、Ollama 等多种 provider。
第 3 步：导入素材
mkdirmy-wiki&&cdmy-wiki# 方式一：从 URL 导入llmwiki ingest https://martinfowler.com/articles/harness-engineering.html# 方式二：从本地文件导入cpyour-articles/*.md sources/第 4 步：编译！
llmwiki compile这一条命令启动两阶段编译管线：
Phase 1（概念提取）： 逐篇读取 sources/ ──→ 每篇提取 6-8 个概念 Phase 2（页面生成）： 合并同名概念 ──→ 生成 wiki/concepts/*.md ──→ 解析 [[wikilinks]] ──→ 生成 index.md终端输出：
llmwiki compile ─────────────────── + 01-martin-fowler-harness.md [new] + 03-arxiv-agent-harness.md [new] ... * Extracting: 01-martin-fowler-harness.md * Found 7 concepts: Harness Engineering, Guides, Sensors, ... * Extracting: 03-arxiv-agent-harness.md * Found 7 concepts: NLAH, IHR, ... ... 🔗 Resolving interlinks... 🔗 Resolved links in 40 page(s) * Generating index... + Index updated with 49 pages. Compilation complete ──────────────────────── ✓ 8 compiled, 0 skipped, 0 deleted第 5 步：查询
llmwiki query"What are guides and sensors in harness engineering?"想把查询结果保存回 wiki（知识复合增长）：
llmwiki query"Compare NLAH with traditional code harnesses"--save第 6 步：增量更新
新加了素材？再跑一次compile，SHA256 哈希检测会跳过未变化的文件：
cpnew-article.md sources/ llmwiki compile# ✓ 1 compiled, 7 skipped, 0 deleted第 7 步（可选）：MCP Server
让 Claude Code 直接驱动 wiki：
llmwiki serve--root./my-wiki我们的实验结果
| 指标 | 数值 |
|---|---|
| 生成页面 | 51 个.md |
| 概念页 | 49 |
| 交叉引用 | 629 个wikilinks |
| 引用密度 | 12.3链接/页 |
| 概念覆盖率 | 100% |
| 编译耗时 | ~2 分钟 |
来看一段生成的页面：
**Harness Engineering** is a framework for designing reliable AI agent systems through environmental controls and mechanical validation rather than prompting alone.^[01-martin-fowler-harness.md, 06-smartscope-harness.md] The discipline addresses "problems prompts cannot prevent" by implementing mechanical systems—such as linters, CI/CD pipelines, hooks, and quality gates—that operate outside the language model itself.^[06-smartscope-harness.md]注意^[filename.md]——每一段都标注了出自哪篇素材。
优缺点
优点：全自动（3 条命令）、概念最全（49 页）、交叉引用最密（629）、段落级来源标注、增量编译
缺点：需要 API Key（消耗 token）、没有置信度标签、粒度可能过细
六、可视化对比
编译产出对比
概念覆盖率（30 核心概念）
三方案能力雷达图
编译质量 ★★★★★ A ★★★☆☆ C ★★☆☆☆ B │ 上手成本 ──────┼────── 可审计性 C ★★★★★ │ A ★★★★☆（段落级来源） B ★★★★☆ │ B ★★★★★（置信度标签） A ★★★☆☆ │ C ★★☆☆☆ │ 自动化程度 A ★★★★★（全自动 CLI） B ★★★☆☆（脚本辅助） C ★☆☆☆☆（纯手动）全维度对比表
| 维度 | 方案 A (CLI) | 方案 B (技能包) | 方案 C (纯模板) |
|---|---|---|---|
| 页面数 | 51 | 20 | 35 |
| 交叉引用 | 629 | 176 | 184 |
| 引用密度 | 12.3/页 | 8.8/页 | 5.3/页 |
| 概念覆盖率 | 100% | 83% | 93% |
| 来源追溯 | 段落级^[file] | 页面级 + 注释 | 页面级 |
| 置信度标签 | 无 | 四级标签 | 三级标签 |
| 前置依赖 | Node.js + API Key | Shell | 无 |
| 上手时间 | ~3 分钟 | ~5 分钟 | ~1 分钟 |
| 自动化 | 全自动 | 脚本辅助 | 手动 |
| 增量更新 | SHA256 自动 | SHA256 脚本 | 手动 |
| 独特特性 | 跨源概念合并 | purpose.md 引导 + topic 聚合 | 零依赖 |
七、关键发现
发现 1：两阶段编译是杀手级设计
方案 A 先从 ALL 素材中提取概念，再统一生成页面。这带来两个巨大优势：
- 消除顺序依赖：不管素材按什么顺序处理，结果都一样
- 自动合并：5 篇素材都提到 “Harness Engineering”，最终只生成一页，综合所有来源
方案 B/C 逐篇处理，先处理的素材会影响后续的概念组织。
发现 2：粒度是 Trade-off，不是越细越好
方案 A：49 个概念页 → 百科全书式，查找方便但信息分散 方案 C：21 个概念页 → 平衡点，阅读舒适 方案 B：11 个实体页 → 综合度高，但缺少细节如果你要做参考手册——选 A。如果你要做读书笔记——C 或 B 更合适。
发现 3：审计有两个独立维度
- 来源追溯：“这句话出自哪篇素材？” → 方案 A 无敌（段落级
^[file]） - 可信度判断：“这个信息有多可靠？” → 方案 B 无敌（EXTRACTED/INFERRED/AMBIGUOUS/UNVERIFIED）
理想的系统应该两者兼备——目前没有一个方案做到。
发现 4：构建 wiki 本身就是 Harness Engineering
这是最有趣的发现。每个 LLM-wiki 工具的组件，都能映射到 Harness Engineering 的概念：
| Wiki 工具组件 | Harness 概念 | 哪个方案做得最好 |
|---|---|---|
| CLAUDE.md / SKILL.md | Guides（前馈控制） | B（最详细的 SKILL.md） |
| lint 脚本 / validate-step1.sh | Sensors（反馈控制） | B（脚本验证 + AI 检查） |
| SHA256 缓存 | Memory & State | A（全自动增量） |
| 素材提取管线 | Data Context Layer | B（多平台适配器） |
| 两阶段编译 | Planning & Decomposition | A（compile 管线） |
| 人工审核节点 | Human-in-the-Loop | B（review 系统） |
方案 A 胜出不是因为用了更好的模型，而是因为它的harness 设计得最好——两阶段管线 + 跨源合并 + 自动链接解析。
这恰好印证了 Harness Engineering 的核心论点：Agent = Model + Harness。同一个模型（Claude），不同的 harness，结果天差地别。
八、选择指南
你有 API Key 吗？ ├── 有 → 追求最高质量？ │ ├── 是 → 方案 A（llm-wiki-compiler） │ └── 否 → 方案 B（llm-wiki-skill） └── 没有 → ├── 用 Claude Code？ → 方案 B（零 API 费用） └── 想最快上手？ → 方案 C（零依赖）一句话总结：
- 方案 A：编译质量最高，3 条命令出结果，需要 API Key
- 方案 B：可审计性最强，置信度标签是独家特色，适合严肃研究
- 方案 C：门槛最低，一个 CLAUDE.md 就是全部，适合快速体验
如果只能选一个——选 A。如果你关心"AI 说的到底靠不靠谱"——选 B。
本文的实验数据、评估清单和全部 wiki 产出都在 GitHub 仓库中开源。
