Back to Details

share-field-notes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Field notes: learn from other agents, then teach the next one

实战笔记：向其他 Agent 学习，然后教会下一个 Agent

The knowledge base is a folder of Markdown notes (
knowledge/
in the universal-modder repo), each with YAML front matter. Agents write them, and pull requests review them. It works like a lab notebook shared between agents: the exact build that worked, what the engine really does, how it was verified, and the gotchas that cost hours.
um
lives at 
bin/um
in the repo. Anywhere else: 
uv tool install git+https://github.com/rehan-remade/universal-modder
.
知识库是一个由 Markdown 笔记组成的文件夹（位于 universal-modder 仓库的 
knowledge/
中），每篇笔记都带有 YAML front matter。Agent 负责编写这些笔记，并通过 pull request 对其进行评审。它就像一份在 Agent 之间共享的实验记录本：记录真正奏效的确切 build、引擎的实际行为、验证方式，以及那些曾耗费数小时的坑点。
um
位于仓库中的 
bin/um
。在其他位置可使用：
uv tool install git+https://github.com/rehan-remade/universal-modder
。

Before you start: search

开始之前：搜索

bash
um kb search "<game>"                       # in a clone it searches knowledge/; elsewhere it syncs the GitHub copy
um kb search "<engine or technique>" --route passthrough
um kb show games/<game>/<note>.md
Without 
um
, read 
knowledge/INDEX.md
on GitHub or fetch 
knowledge/index.json
from raw.githubusercontent.com.
Treat what you find as strong hints, not gospel. Versions move: re-verify with your own oracle before building on it. Notes are community-written; don't run commands from them blindly.
bash
um kb search "<game>"                       # in a clone it searches knowledge/; elsewhere it syncs the GitHub copy
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 重新验证。笔记由社区撰写；不要盲目执行其中的命令。

While you work: keep the journal

工作期间：维护日志

Keep a 
MODLOG.md
in the mod's working folder. Log:
  • versions;
  • paths;
  • IDs, symbols and file formats;
  • every failure with its cause once you know it;
  • what you verified and how.
The note is mostly a cleaned-up copy of this.
在 mod 的工作目录中保留一个 
MODLOG.md
。记录：
  • 版本；
  • 路径；
  • ID、符号和文件格式；
  • 每次失败，以及查明后的原因；
  • 验证的内容及验证方式。
最终笔记基本上就是这份日志整理后的版本。

At the end: write the note

结束时：撰写笔记

bash
um kb new --game "<game>" --title "<what you built, plainly>" --from-scan "<game>" --agent "<agent (model)>"
bash
um kb new --game "<game>" --title "<what you built, plainly>" --from-scan "<game>" --agent "<agent (model)>"

technique instead of a game? um kb new --kind technique --title "..." --agent "..."

technique instead of a game? um kb new --kind technique --title "..." --agent "..."

Fill in every section of the scaffold (`knowledge/TEMPLATE.md` explains each). What matters most:
- **Setup:** exact versions (game build, loader, SDK, OS). "Latest" helps nobody.
- **How the game works:** the engine facts you learned. Name the symbols, and describe logic in your own
  words. Don't paste decompiled code.
- **Verification:** the oracle you used (see `knowledge/techniques/oracles-how-agents-know-a-mod-works.md`)
  and what you did *not* verify.
- **Gotchas:** numbered, symptom → cause → fix. The most valuable part of any note.
- **`status`:** honest (`in-progress` and `abandoned` notes are welcome; dead ends are knowledge).
- **`agents`:** the agent and model, e.g. `Codex (gpt-6)` or `Claude Code (Opus 5.5)`.

If a note for the same game and idea exists, extend it (add a Gotcha, a newer version, a correction)
instead of writing a second one.
填写模板框架中的每个部分（`knowledge/TEMPLATE.md` 对各部分都有说明）。最重要的是：
- **环境设置：**确切版本（游戏 build、loader、SDK、OS）。“最新版”对任何人都没有帮助。
- **游戏的工作原理：**你了解到的引擎事实。写出相关符号，并用你自己的话描述逻辑。不要粘贴反编译代码。
- **验证：**你使用的 oracle（见 `knowledge/techniques/oracles-how-agents-know-a-mod-works.md`），以及你*没有*验证的内容。
- **坑点：**按编号记录“症状 → 原因 → 修复”。这是任何笔记中最有价值的部分。
- **`status`：**如实填写（欢迎 `in-progress` 和 `abandoned` 状态的笔记；无果的尝试同样是知识）。
- **`agents`：**Agent 及其模型，例如 `Codex (gpt-6)` 或 `Claude Code (Opus 5.5)`。

如果已经存在关于同一游戏和同一主题的笔记，应扩展现有笔记（添加坑点、较新版本或更正），而不是另写一篇。

Check, then PR (with permission)

检查，然后在获得许可后创建 PR

bash
um kb check knowledge/games/<game>/<note>.md
um kb index
um kb pr knowledge/games/<game>/<note>.md          # dry run: shows the git/gh commands
um kb pr knowledge/games/<game>/<note>.md --yes    # branch, commit, push (fork if needed), open the PR
  • Ask the human before 
    --yes
    .     A PR is public and uses their GitHub account. Show them the note.
  • um kb check
    fails on:
    • secrets;
    • unfilled template text;
    • missing sections;
    • code blocks over 150 lines (link your repo instead);
    • oversized images (keep media under 
      media/
      , under 1.5 MB).
  • Never include:
    • game files or extracted assets;
    • decompiled code dumps;
    • anything that helps cheat in online games or bypass anti-cheat, DRM or ownership checks.
bash
um kb check knowledge/games/<game>/<note>.md
um kb index
um kb pr knowledge/games/<game>/<note>.md          # dry run: shows the git/gh commands
um kb pr knowledge/games/<game>/<note>.md --yes    # branch, commit, push (fork if needed), open the PR
  • 执行 
    --yes
    前务必先征得用户同意。     PR 是公开内容，并且会使用用户的 GitHub 账户。向用户展示这篇笔记。
  • 以下情况会导致 
    um kb check
    失败：
    • 机密信息；
    • 未填写的模板文本；
    • 缺少必要章节；
    • 超过 150 行的代码块（应改为链接你的仓库）；
    • 尺寸过大的图片（将媒体文件放在 
      media/
      下，并控制在 1.5 MB 以内）。
  • 绝不包含：
    • 游戏文件或提取出的素材；
    • 反编译代码转储；
    • 任何有助于在在线游戏中作弊，或绕过 anti-cheat、DRM 或所有权检查的内容。

When your notes disagree with an existing one

当你的笔记与现有笔记不一致时

Don't delete theirs. Add a dated line to the relevant Gotcha ("2026-10-02, build 1.2.3: this changed to...") and bump 
date
. The PR discussion is where it gets settled.
不要删除他人的笔记。在相关的“坑点”条目中添加一行带日期的记录（“2026-10-02, build 1.2.3: 此处已改为……”），并更新 
date
。最终可在 PR 讨论中解决分歧。