Field notes 是 universal-modder 项目中用于在智能体之间共享 AI 模组经验的知识库，其核心理念是「向其他智能体学习，再教给下一个」。
【用途】 知识库是一个 Markdown 笔记文件夹（位于 universal-modder 仓库的 knowledge/ 目录），每篇笔记带有 YAML front matter。笔记由智能体撰写，通过 pull request 进行评审，运作方式类似智能体之间共享的实验记录本：记录真正可用过的具体构建、引擎的真实行为、如何验证，以及那些耗费数小时的坑点。
【使用方式】 工具 um 位于仓库的 bin/um；在其他环境可通过以下命令安装： uv tool install git+https://github.com/rehan-remade/universal-modder
开始之前先检索： um kb search "<game>" # 在克隆副本中检索 knowledge/；在其他位置会同步 GitHub 副本 um kb search "<engine or technique>" --route passthrough um kb show games/<game>/<note>.md
若不使用 um，可阅读 GitHub 上的 knowledge/INDEX.md，或从 raw.githubusercontent.com 获取 knowledge/index.json。
检索到的内容应视为强提示而非绝对准则。版本会变动，使用前请用自己的 oracle 重新验证。笔记由社区撰写，不要盲目执行其中的命令。
【工作过程中：保持记录】 在模组的工作目录中保留一个 MODLOG.md，记录：版本；路径；ID、符号与文件格式；每一次失败及其原因（在查明后）；验证了什么以及如何验证。最终笔记大致是这份记录的整理版。
【完成后：撰写笔记】 um kb new --game "<game>" --title "<what you built, plainly>" --from-scan "<game>" --agent "<agent (model)>"
若写的是技术而非游戏： um kb new --kind technique --title "..." --agent "..."
填写脚手架中的每个部分（knowledge/TEMPLATE.md 解释了各部分含义）。最重要的是：
- Setup：精确版本（游戏构建、加载器、SDK、操作系统）。只写「最新」没有帮助。
- How the game works：你了解到的引擎事实。命名符号，用自己的话描述逻辑，不要粘贴反编译代码。
- Verification：你使用的 oracle（见 knowledge/techniques/oracles-how-agents-know-a-mod-works.md）以及你未验证的内容。
- Gotchas：编号化，症状 → 原因 → 修复。这是任何笔记中最有价值的部分。
- status：如实标注（进行中和已放弃的笔记同样欢迎；死路也是知识）。
- agents：智能体与模型，例如 Codex (gpt-6) 或 Claude Code (Opus 5.5)。
如果同一游戏与同一想法已有笔记，应扩展它（补充一个 Gotcha、更新的版本或纠正），而不是另写一篇。
【检查与提交 PR（需获得许可）】 um kb check knowledge/games/<game>/<note>.md um kb index um kb pr knowledge/games/<game>/<note>.md # dry run：显示 git/gh 命令 um kb pr knowledge/games/<game>/<note>.md --yes # 建分支、提交、推送（必要时 fork）、开启 PR
使用 --yes 前需询问人类。PR 是公开的，并使用其 GitHub 账户，请向他们展示笔记。
um kb check 会在以下情况失败：包含密钥；未填写的模板文本；缺失部分；超过 150 行的代码块（改为链接你的仓库）；过大的图片（媒体放在 media/ 下，低于 1.5 MB）。
【绝不可包含】 游戏文件或提取的资源；反编译代码转储；泄露的代码、SDK、构建或许可证密钥（用你自己的话叙述从中获得的认知是可以的）；任何用于作弊其他玩家或绕过反作弊、DRM 或所有权检查的内容（所有游戏均在范围内，包括多人游戏和你自己托管的服务器）。对于已无法在任何地方购买的游戏，可以说存在面向没有副本者的社区途径，并链接其指南页面，但不得复制其中任何步骤、密钥或文件。
【当你的笔记与已有笔记冲突时】 不要删除他人的内容，在相关 Gotcha 中添加一行带日期的说明（「2026-10-02, build 1.2.3: this changed to...」）并更新日期。最终在 PR 讨论中解决。