# Patchouli Handbook：面向 AI Agent 的渐进式知识系统

在构建能够处理复杂任务的 AI Agent 时，我们常常面临一个矛盾：一方面，Agent 需要充足的领域知识、判断规则和案例支撑才能做出正确决策；另一方面，如果一次性将所有参考资料塞入上下文，不仅会导致成本高昂，还容易引发信息过载和幻觉。

Patchouli Handbook 正是为了解决这一痛点而诞生的文件型知识系统。它借鉴了 “渐进式展开（Progressive Disclosure）” 的设计理念，专为 AI Agent 打造了一个结构化、可追溯且易于维护的知识库。

# 命名渊源：为什么叫 Patchouli？

“Patchouli” 这个名字源自于 Minecraft（我的世界）中著名的模组 Patchouli。在 Minecraft 的模组开发生态中，Patchouli 模组的作用是为其他模组提供一个极其便捷的方式来生成游戏内指导书（Guidebook）。它允许开发者通过简单的 JSON 和文本配置，就能在游戏中创建出包含目录、分类、条目、图片和合成表的精美手册，极大地降低了玩家的学习门槛。

Patchouli Handbook 继承了这一精神。它的目标是成为 AI Agent 世界的 “指导书生成器”—— 通过一套标准化的文件结构和 API，将庞杂的领域知识（如设计原则、开发规范、业务逻辑）组织成一本结构清晰、便于 Agent 随时查阅的手册。

# 核心设计理念：渐进式展开

当前的 AI Agent 在执行任务时，通常依赖于短小精悍的 Skill（技能）作为行为触发器或标准操作程序（SOP）。然而，当任务变得复杂，Agent 需要的不只是简单的流程，而是领域原则、判断规则、反模式以及可追溯的证据时，单一的 Skill 就显得捉襟见肘。

Patchouli Handbook 的核心理念是：先读轻量级入口，再按需深入展开。它不是把整本厚重的指导书一次性丢给 Agent，而是通过精心设计的文件结构，引导 Agent 像查阅字典一样，逐步定位并获取所需知识。

# 完整的 Handbook 结构

一个标准的 Patchouli Handbook 具有清晰且稳定的目录结构，兼顾了人类的可读性和机器的解析效率：

	<handbook_dir>/
	├── manifest.json # 机器可读的核心元数据（目录、路由规则、统计信息）
	├── GUIDE.md # 复杂任务的厚重指导书，说明如何使用该手册
	├── INDEX.md # 人类可读的全局路由映射，列出所有分类和条目
	├── entry_skill/
	│ └── SKILL.md # 兼容 Skill 系统的轻量级激活入口
	├── categories/ # 知识分类目录
	│ └── <category_slug>/
	│ ├── CATEGORY.md # 局部路由页，包含该分类的描述、适用场景和核心术语
	│ └── <entry_slug>.md # 可复用的知识条目页（核心知识单元）
	├── references/ # 跨条目的参考资料
	│ ├── glossary.md # 全局术语表
	│ └── source_index.md # 来源到条目的反向索引
	└── evidence/ # 来源证据页面（如原始视频记录、文档片段）
	└── <source_id>.md

在这个结构中，最核心的知识单元是 Entry（条目）。一个标准的 Entry 包含了 Summary （摘要）、 Use When （何时使用）、 Do This （操作指南）、 Checklist （检查清单）、 Anti-Patterns （反模式）、 Read Next （延伸阅读）和 Source Videos （证据来源）等字段。这种结构化的表达方式，使得 Agent 能够精准提取所需信息。

# Agent 读取协议与调用方法

为了高效利用 Handbook，Patchouli 定义了一套 Agent 协议，并提供了一个统一的 JSON CLI 接口。这被称为 ** 检索预算（Retrieval Budget）** 策略。

# 1. 发现与描述 (Discover & Describe)

首先，Agent 或外部程序可以通过 structure 和 describe 命令了解 Handbook 的能力和基本信息：

	# 获取系统支持的操作契约
	patchouli-handbook structure

	# 获取当前 Handbook 的元数据（分类数、条目数等）
	patchouli-handbook apply '{"action":"describe"}' --handbook example/masahiro-sakurai-on-creating-games

# 2. 挑选分类 (Pick a Category)

Agent 不应读取所有内容，而是通过列出分类，根据 description 、 when_to_read 和 core_terms 选择最相关的一个：

patchouli-handbook apply '{"action":"list_categories"}' --handbook example/masahiro-sakurai-on-creating-games

# 3. 读取特定条目 (Read an Entry)

在选定分类后，列出该分类下的条目，并获取特定条目的详细内容：

	# 列出分类下的条目
	patchouli-handbook apply '{"action":"list_entries","category_slug":"game-essence"}' --handbook example/masahiro-sakurai-on-creating-games

	# 获取条目详情
	patchouli-handbook apply '{"action":"get_entry","slug":"risk-and-reward"}' --handbook example/masahiro-sakurai-on-creating-games

# 4. 写入与校验 (Write & Validate)

Patchouli Handbook 也支持通过 API 进行修改（如创建新条目），并在修改后进行严格的结构校验：

	# 创建新条目
	patchouli-handbook apply '{
	"action": "create_entry",
	"payload": {
	"title": "Scope First",
	"category_slug": "planning",
	"summary": "Decide the scope before choosing tactics.",
	"use_when": ["The task is broad or under-specified."],
	"do_this": ["Name the goal.", "Name constraints.", "Pick the smallest useful next step."],
	"checklist": ["The scope is explicit.", "The next action is concrete."],
	"anti_patterns": ["Do not choose tactics before defining the target."]
	}
	}' --handbook output/studio-handbook

	# 每次修改后必须进行校验
	patchouli-handbook apply '{"action":"validate"}' --handbook output/studio-handbook

# 深入条目（Entry）：知识的最小单元与字段剖析

在 Patchouli Handbook 中，条目（Entry） 是承载具体知识的最小单元。为了确保 AI Agent 能够结构化地提取和应用这些知识，每个条目都被严格划分为多个字段。根据项目源码中的数据模型定义，一个完整的条目包含以下核心字段：

字段名称
字段含义与作用
Summary（摘要）
用一到两句话高度概括该条目的核心观点或目的，便于 Agent 快速判断是否需要深入阅读。
Use When（何时使用）
明确指出在何种任务或场景下应该应用该条目，充当知识的触发条件。
Do This（操作指南）
给出具体的行动建议或步骤，指导 Agent 或开发者如何将该知识付诸实践。
Checklist（检查清单）
提供用于在任务完成后进行自我校验的标准，确保操作没有遗漏。
Anti-Patterns（反模式）
指出常见的错误做法或思维误区，帮助 Agent 避开潜在的陷阱。
Read Next（延伸阅读）
指向其他相关的条目（Slug），用于引导 Agent 发现知识之间的依赖关系，甚至可以跨越分类边界。
Source Videos（证据来源）
指向证据文件夹中的原始资料 ID，用于知识溯源和查证，确保每一条指导都有据可查。

下面，我们通过三个真实的条目示例，来具体分析这些字段是如何在实际中发挥作用的：

# 示例 1：高度量化的 Checklist

在设计游戏失败后的重试机制时，“Make Retries Quick（让重试变得快速）” 条目给出了极其具体的量化指标。它的 Summary 强调了尽量减少失败后的停机时间，以保持玩家的参与度并提高对高难度的容忍度。

更值得注意的是它的 Checklist 字段，其中包含了诸如 “从死亡到重新控制的时间理想情况下应在 3 秒以内” 以及 “玩家可以无需过多的菜单导航即可重新开始” 等标准。这个例子展示了 Checklist 字段的强大之处。它不仅仅是概念上的提醒，更是可以直接用于代码审查或 QA 测试的具体标准。Agent 在评估一个游戏设计方案时，可以直接对比这个 “3 秒以内” 的硬性指标。

# 示例 2：跨分类的 Read Next 路由

“Let Them Skip, Let Them Pause（允许跳过，允许暂停）” 条目属于 UI/UX 设计分类，主要讲述了过场动画和 Logo 必须可以跳过或暂停。但它的 Read Next 字段非常特别，它指向了 “Teaching Players How to Play”（属于游戏设计原则分类）和 “Customization Lets Your Imagination Play”（属于设计细节分类）。

在 Patchouli Handbook 中，Read Next 不仅仅是相关文章的简单罗列，它承担着跨越分类边界的知识路由功能。当 Agent 正在处理 UI 交互（跳过 / 暂停）时，可能会自然地延伸到 “如何通过 UI 引导玩家（教程）” 或 “如何让玩家自定义 UI”。通过 Read Next，Agent 可以沿着逻辑依赖链条，突破当前分类的限制，获取更全面的视角。

# 示例 3：密集的 Do This 操作步骤

在讨论动作游戏中的 “受击停顿（Hit Stop）” 机制时，“Hit Stop Mechanics（受击停顿机制）” 条目的 Do This 字段给出了极其密集的实现细节。它明确要求实现受击停顿需要满足多个条件：受击者震动更大、受击判定框保持原位、地面震动仅限水平方向、振幅衰减、每次攻击的系数可调、受击者姿势在多帧内混合、攻击者在停顿期间轻微移动。

这个例子展示了 Do This 字段的实操性。它不是泛泛而谈 “要增加打击感”，而是直接给出了 7 个具体的编程与动画实现要求。结合其对应的 Anti-Patterns（如停顿期间判定框偏移导致幽灵判定），Agent 可以直接根据这些规则来指导动画师或程序员修改代码，或者在审查代码时逐一核对这些实现细节。

# 总结

Patchouli Handbook 为构建具备深厚领域知识的 AI Agent 提供了一种优雅的解决方案。它不仅是一个文件格式规范，更是一种系统化的知识工程方法论。通过渐进式的知识加载策略、统一的 API 接口以及严谨的条目字段设计，它在性能、成本和信息丰富度之间找到了完美的平衡。对于需要处理复杂逻辑和需要强证据支撑的 Agent 应用来说，Patchouli Handbook 无疑是一个值得尝试的强大工具。

project