OpenRig World Pack 构建指南：用 build-your-world 约定为 Agent 搭建可验证的操作世界

本文以 world-public/build-your-world.md 为核心，讲解 OpenRig 中 World（世界）上下文包的作者约定：如何用最小的文件布局描述一个 Agent 所处的持久操作现实，如何用八区域标签组织信息而不沦为文件夹树，如何携带一张诚实覆盖图让 Agent 在正确时机读取正确地址，并通过 Book-world 练习把这一套迁移到软件工程世界。读完本文，你将能独立创建、安装、组合与验证一个属于自己的 World Pack。

OpenRig 是一个把 Claude Code 与 Codex 编排进同一系统的多 Agent 工作台（harness）。在这样一个系统里，Agent 常被投入一个陌生的工作区，它必须先回答"我在哪、这里有什么、该信什么、能做什么"，才能良好行动。World Pack 就是承载这类答案的上下文包：它是一组"世界声明"（authored world），描述 Agent 行动的持久操作现实——实体、关系、规则、历史、状态来源与可行动作（affordances）。公共包 world-public 的 manifest.yaml 将其定位为"一份可移植的操作世界入门指南，它派生易变事实，并教会 Agent 编写自己的世界"（purpose 字段原文）。

一、先认识公共 World Pack 的文件构成

在开始构建自己的世界前，先理解仓库里现成的参考实现 world-public。它由 manifest.yaml 声明以下文件：

文件	角色（role）	内容
start-here.md	orientation（入场）	派生"你在哪、该信什么、什么内容属于世界"
build-your-world.md	convention（约定）	最小作者约定与 Book-world 练习
boundaries.md	boundaries（边界）	本公共世界覆盖什么、排除什么、不能决定什么
claims.yaml	claims（声明账本）	每条作者声明映射到一个可失败的检查或显式诚实标记
verify-world.sh	verifier（验证器）	可移植的命名检查，失败与跳过都"出声"

manifest.yaml 还定义了四个原子（atom），它们是把世界内容组装进会话的单元：

• enter-the-world（start-here.md）：入场先派生而非猜测；
• author-a-world（本文档）：以最小 manifest 与作者文件起步，按区域打标签，并保持其他上下文种类分离；
• know-the-edges（boundaries.md）：区分公共结构、rig 本地事实、当前状态与不可逆判断；
• coverage-map：profile_only: true，仅参与 fresh 会话的覆盖图组合。

二、保持第一版小：最小 World 布局

构建世界的第一条纪律是不要让第一版膨胀。约定原文：

Start with a directory whose name says what world it serves.

即：用一个"名字即用途"的目录起步。最小布局只有三个文件：

book-world/
  manifest.yaml
  world.md
  boundaries.md

三者的分工是：

• manifest.yaml 命名文件：它声明包名、taxonomy、每个文件的 path/role/summary，以及原子（atom）的元数据。它不承载正文；
• world.md 陈述持久意图：用散文描述世界的持久目的、实体之间的关系、以及"什么值得信任"；
• boundaries.md 划清边界：说明这个世界覆盖什么、不覆盖什么、哪些判断不由这个世界负责。

约定继续给出"何时升级"的准则，原文为：

The manifest names the files. The prose states durable purpose, relationships, and what to trust. Add atoms when the same bytes need situation, runtime, order, or region metadata. Add a claim ledger and verifier when authored statements can drift into consequential lies. Do not add ceremony that has no reader yet.

翻译成决策规则就是：

• 加原子（atom）：当同一批字节需要在不同 situation（fresh/handover/post-compaction）、runtime（claude/codex/any）、order（顺序）或 region（区域）下以不同方式呈现时，才为它声明原子；
• 加声明账本与验证器：当作者声明可能漂移成"后果性谎言"（consequential lies，即会影响决策且无法自证）时，才引入 claims.yaml 与 verify-world.sh；
• 不加没有读者的仪式：任何"未来可能有用"的仪式，在没有真实读者之前一律不建。

这条"最小化"原则在仓库模板 world-example/manifest.yaml 中有直接体现——它只有 1 个文件（your-world.md）、1 个原子，是"展示一个 OpenRig world pack 解剖结构的最小填空模板"。

三、分离上下文种类：WORLD + LORE + SKILLS + MISSION

World Pack 的第一条顶层纪律是上下文种类的顶层分离：

WORLD + LORE + SKILLS + MISSION is the top-level separation of context kinds.

种类	含义
WORLD	Agent 身处何处——实体、关系、规则、历史、状态来源、可行动作（affordances）
LORE	某个席位（seat）/位置（position）在此生活的过程中学到的经验
SKILLS	可重复的程序性能力
MISSION	当前工作以及它为什么重要

注意 WORLD 与 LORE 的区分：世界是"这个地方本身是什么"，Lore 是"住在这里的人学会了什么"。世界不会因为某个席位的个人经验而改变；Lore 则绑定到位置。这条分离在 start-here.md 中还有一处互补表述：世界是对仓库指令（如 AGENTS.md）的补充而非替代——仓库指令解释"如何在这棵树里工作"，世界解释"包裹它的更大操作现实"。

四、八区域是标签，不是文件夹树

第二个关键纪律是八区域（regions）的用法：

The eight regions are metadata on atoms, not a required folder tree. Tag existing authored files with identity, ontology, terrain, actors, laws, history, state, and affordances. One coherent file may cover several regions; do not fork the same idea into eight copies.

即：identity（身份）、ontology（本体论）、terrain（地形）、actors（行动者）、laws（法则）、history（历史）、state（状态）、affordances（可行动作）这八个区域只是原子上的元数据，不是强制目录结构。做法是：

1. 给已有的作者文件打上区域标签；
2. 一个连贯的文件可以同时覆盖多个区域；
3. 绝不把同一个想法拆成八份副本。

从源码看，regions 作为字段真实存在于 manifest.yaml 的每个原子定义里，例如 author-a-world 的 regions: [ontology, laws, history, affordances]；world-example/manifest.yaml 的模板原子 your-world 甚至一次性声明了全部八个区域：regions: [identity, ontology, terrain, actors, laws, history, state, affordances]。这正是一个文件覆盖多个区域的范例。

模板 world-example/your-world.md 为每个区域给出了引导提示，供你替换为自己的事实：

• Identity：说出世界的名字与 Agent 在其中的位置；
• Ontology：定义这里重要的"东西的种类"以及每种是干什么用的；
• Actors：点名还有谁在场、他们拥有什么、如何联系他们；
• Terrain：标注代码、记录、文档与操作面（operational surfaces）所在位置；
• Laws：陈述约束此处行动的持久规则与优先级（precedence）；
• History：记录解释世界当前形态的过往决策与事件；
• State：指向能"派生"当前真相的命令或来源；
• Affordances：列出 Agent 能做什么，以及触达每种能力的时机。

五、携带一张诚实的覆盖图（Coverage Map）

世界写好后，Agent 如何知道"什么维度的问题该去哪里读"？答案是一张覆盖图。约定原文：

Each coverage entry names one dimension, one exact context address, and the task moment that should trigger the read. The address is the source: retrieve it with rig context get <address> before making a load-bearing decision in that dimension.

也就是说，覆盖图每条目必须满足三元组：一个维度 + 一个精确上下文地址 + 一个应触发读取的任务时刻。地址就是权威源本身——在做该维度的承重决策（load-bearing decision）之前，先用 rig context get <address> 把内容取回来。

build-your-world.md 给出了十维度的完整覆盖图（本文完整继承）：

Dimension	Exact address	What it contains	Read it when the task asks you to…
product	world-public/boundaries.md#this-pack-does-not-cover	The boundary of public guidance; the project must supply its actual purpose and product judgment.	choose a product outcome or tradeoff and locate the project authority that can decide it.
topology	skills/core/openrig-architect/SKILL.md	Portable topology authoring, role selection, validation and context guidance.	add, split, merge, or assign a seat, pod, edge, or responsibility boundary.
context	world-public/build-your-world.md#separate-kinds-tag-regions	The World/Lore/Skills/Mission separation and region-tagging rule.	decide where knowledge belongs or whether it should be preloaded.
skill	onboarding-width/public-reference-material.md#the-one-you-read-rather-than-consult	The operating-model entry point and how it differs from lookup references.	choose an operating model or repeatable procedure instead of improvising one.
queue/custody	onboarding-width/public-what-you-can-do.md#making-work-outlive-you	Durable queue ownership, state, blocking, and transactional handoff.	assign, claim, block, hand off, or close work that must survive a turn or occupant.
source/worktree	onboarding-width/public-reference-material.md#the-command-surface-docs-as-built-in-the-source-repo	The maintained as-built source map and its trust metadata.	locate the source owner, choose authoritative documentation, or separate branch state from running behavior.
proof/review	skills/process/verification-before-completion/SKILL.md	Evidence before claims, content checks and untested dimensions; apply the project-selected proof standard.	decide what evidence supports a change or design its negative control.
lifecycle/release	skills/core/rig-lifecycle/SKILL.md	Lifecycle mechanics and limits; release ownership must come from the actual project authority.	plan a lifecycle operation and resolve who may execute or publish it.
continuity/recovery	onboarding-width/public-what-you-can-do.md#when-something-is-broken	Recovery, handover, compaction, snapshot, and restore capabilities.	restore, hand over, compact, or recover a seat, rig, daemon, or host without losing continuity.
host-boundary	skills/core/cross-host-rig-commands/SKILL.md	Host addressing, transport and verification limits; local authority remains separately declared.	move an operation between hosts or determine which target and authority apply.

这张图的使用边界同样重要（原文要点）：

• 表中地址是公共入口（public entry points），不是本项目（rig）自己的决策；
• 当某行要求本地产品、发布或主机权威时，必须解析配置中的项目上下文并记录其精确地址再行动；
• 若没有作者写下的权威或不可用，报告缺失的决策，而不是把公共机制指南当成许可；
• 这张图的意义是"指出从哪里开始探索，而不替你编造一个内置的项目策略"。

六、检索、组合与验证：四条核心命令

构建与使用 World Pack 的四个关键命令如下（来自原文档的 world-claim 操作声明）：

1. 检索公共包

rig context get world-public

用 rig context get world-public 取回组装好的公共包字节。验证器 verify-world.sh 会检查输出中是否同时包含 # Enter the world、# Build your world、# Boundaries 三个标题（retrieve-public-pack 检查），确保整包内容可被组装取回。

2. 组合 fresh 会话剖面

rig context profile world-public --situation fresh

用 rig context profile world-public --situation fresh 组合其 fresh 会话原子图（atom graph）。从源码看，fresh 剖面会包含 enter-the-world、author-a-world、know-the-edges 三个原子（对应 manifest 中的 guided profile），并输出 totalEstimatedTokens 派生阅读成本。验证器的 compose-fresh-profile 检查要求该数值大于 0 且三个原子 ID 均出现在输出中。

3. 派生安装目录（而非硬编码路径）

rig context show world-public --json

用 rig context show world-public --json 派生已安装的包目录。该命令返回 sourceType: "builtin"、relativePath: "world-public" 与 sourcePath 字段；验证器用返回的 sourcePath 与自身所在目录比对（derive-pack-path 检查），保证"验证器确实从它声称的位置运行"。

4. 运行验证器

sh verify-world.sh

在派生目录中运行 sh verify-world.sh，而不是教给 Agent 某台机器上的具体路径。脚本是纯 POSIX sh，唯一的可选依赖是 rig 本身——若 rig 不存在，脚本输出 [skip] rig-command-surface 并以 0 passed · 0 failed · 1 skipped 退出（跳过也算诚实，不假装通过）。

安装与确认自己的世界

模板 world-example/your-world.md 给出了安装流程：

rig context add <pack-directory>   # 安装一个 world pack
rig context list                   # 确认其 ref 出现在列表中
rig config get context.root        # 仅在需要路径时派生配置的上下文存储

验证器的 world-example-install 检查会真实执行一次"安装探针"：以 world-public-verify-$$ 为临时 ref 安装示例包、确认 installedAt 与派生路径一致、rig context list 能列出该 ref、随后 rig context rm 清理，全程验证"类型化上下文存储与 add/list 效果为真"。

七、练习：Book World——把世界构建迁移到软件工程

原文为这个练习给出充分理由：

The exercise uses a book because the model's existing world-building fluency needs the least translation there, and a reader with no software context is the hardest stranger case.

用书作为练习题材，是因为模型已有的世界构建流利度在"书"这个领域需要的翻译最少；同时，一个毫无软件背景的读者，是"陌生人入场"的最难案例——能把世界写到让这样的人也能行动，就能写到让任何 Agent 也能行动。

步骤

rig context get world-example

取回已完成的 book-world 模板，然后"复制这个包、更新其 manifest、把下面每个提示替换成你世界的事实"（world-example-authoring）。

练习要求用几个连贯的文件描述：

• 作者是谁（who the writer is）；
• 存在哪些手稿与来源（what manuscripts and sources exist）；
• 它们住在哪里（where they live）；
• 适用哪些编辑规则（which editorial rules apply）；
• 哪些决策塑造了草稿（what decisions shaped the draft）；
• 当前状态如何派生（how current state is derived）；
• Agent 接下来能做什么（what the agent can do next）。

并附两条审美纪律：保持可读性（keep it pleasant to read）；如果组织方式感觉像"归档系统"而不是"一个地方"，就简化它（simplify it if the arrangement feels like a filing system rather than a place）。

检查（Checks）

模板的 Checks 一节给出世界声明的验证纪律（world-example-checks）：

For every checkable authored claim, add a named check that can fail; flag taste or genuinely unverifiable claims instead of dressing judgment up as a test; and derive paths, counts, inventories, and live state from commands rather than copying current answers into this file.

即三条规则：每条可检查的声明都有一个能失败的命名检查；品味或真正不可验证的声明要打诚实标记，而不是把判断伪装成测试；路径、数量、清单和实时状态一律从命令派生，绝不把当前答案复制进文件。

书到软件的映射

The book exercise maps its manuscript to a codebase, editorial rules to engineering laws and conventions, draft state to derived build and deploy state, and its writer to the team. Software worlds use the same moves.

映射关系一目了然：

书的世界	软件的世界
手稿（manuscript）	代码库（codebase）
编辑规则（editorial rules）	工程法则与约定（engineering laws and conventions）
草稿状态（draft state）	派生的构建与部署状态（derived build and deploy state）
作者（writer）	团队（team）

软件化桥接（software-shaped bridge）

为什么软件工程师构建世界有天然优势？原文给出了精辟的桥接论证：

Agents already know software-shaped building through specifications, verification loops, tooling, and the programming substrate. A world pack built this way uses named files and a manifest as the spec shape, per-claim checks and a verifier that can fail as the test suite, and derive-at-source commands as the feedback loop. A blank-slate reader therefore already knows how to build this kind of artifact: world-building supplies the information architecture while software-shaping supplies buildability.

对应关系如下：

• 命名文件 + manifest = 规格形态（the spec shape）；
• 逐声明的检查 + 能失败的验证器 = 测试套件（the test suite）；
• 从源头派生的命令 = 反馈回路（the feedback loop）。

结论：世界构建提供信息架构，软件塑形提供可构建性（buildability）——一个白板读者（blank-slate reader）早已知道如何构建这类产物。

八、声明账本与验证器：让"漂移"被当场抓住

世界中的作者声明会随维护漂移成与事实不符的"谎言"，因此 world-public 提供了完整的声明账本 + 验证器机制（原文档称其为"可选的声明检查爬升"——the optional claim-checking climb，完整公共包即其示范）。

claims.yaml 的结构

claims.yaml 的每条声明包含四个字段：

• id：声明唯一标识（如 author-derive-rule）；
• statement：声明的精确原文，须与正文逐字一致（验证器会做字符串匹配）；
• kind：声明的三种类型之一——judgment（判断/品味）、operational（操作命令）、structural（结构性约定）；
• disposition：要么是 check: <check-name>（映射到一个可失败的命名检查），要么是 flagged: "..."（显式诚实标记，说明该判断无法被机器扫描证明）。

例如：

- id: author-derive-rule
  statement: "Supply the authored relationships no inventory can discover, point at commands for facts that change, and do not memorize a roster, path, count, status, or command list when the live system can answer."
  kind: structural
  check: author-derive-rule

而纯判断类声明（如"用书做练习因为翻译最少"）则用 flagged 明示"这是作者意图与品味，没有实时扫描能证明它"：

- id: book-example-purpose
  statement: "The exercise uses a book because the model's existing world-building fluency needs the least translation there, and a reader with no software context is the hardest stranger case."
  kind: judgment
  flagged: "Authored purpose and taste; no live scan can prove it."

verify-world.sh 检查什么

verify-world.sh 以 [ok] / [FAIL] / [skip] 三种输出逐项检查，关键检查点包括：

• pack-taxonomy：manifest 声明 taxonomy: world；
• declared-files：每个随包文件存在且被 manifest 声明；
• atom-regions：原子元数据覆盖全部八个区域；
• coverage-map-contract：覆盖图十个维度各自带一个精确地址与任务触发文本；
• claim-coverage：声明的 id 清单与正文 <!-- world-claim: ... --> 标记一一对应、不重复、每条有且仅有一个 disposition，statement 逐字出现在正文中；
• rig-command-surface：文档教授的所有 rig 命令在真实 CLI 上都存在（rig --help、rig context get|show|profile|add|rm --help 等）；
• retrieve-public-pack / compose-fresh-profile：真实执行 rig context get 与 rig context profile 并核对输出；
• derive-pack-path / run-public-verifier：rig context show world-public --json 解析出的目录就是脚本自身所在目录；
• private-ref-boundary：builtin world-public 与 rig 本地世界命名空间互不遮蔽；
• world-example-install：真实走一遍 add → list → rm 的安装闭环。

脚本结尾输出 N passed · M failed · K skipped，并仅在 failed 为 0 时以 0 退出——这就是"能失败的验证器"：任何声明漂移都会让世界构建过程当场报错。

九、边界：公共世界包不能替你决定什么

世界的另一半是边界意识。boundaries.md 明确列出：

本包覆盖（仅公共结构）：

• world / lore / skills / mission 四种上下文种类的稳定分离；
• 八区域作为原子元数据；
• 作者 vs 派生（author-versus-derive）规则；
• 编写与检查世界的最小约定；
• 发现身份、拓扑、包与命令帮助所需的实时命令。

本包不覆盖（rig 特定现实、当前工作、本地 Lore、仓库指令、不可逆判断）：

• 某个具体 rig 的目的、行动者、拓扑、路径或当前状态；
• 你当前拥有的使命（mission）；
• 席位或团队挣得的本地 Lore；
• 特定 harness 的仓库指令；
• 不可逆的产品或操作者判断。

边界纪律原文：

These gaps are not omissions to fill with plausible prose: read the local world, mission, lore, repository instructions, and live command surfaces, then ask the decision owner when no source can answer.

即缺口不是用来用貌似合理的散文填充的——要去读本地世界、使命、Lore、仓库指令和实时命令面；没有任何来源能回答时，就去问决策所有者。

命名空间边界同样重要：私有世界安装保持 rig 本地、使用自己的 ref，永不被这个 builtin 遮蔽。world-public 是 builtin 的 ref；本地世界可以用不同 ref 携带实例特定内容，既不会继承、也不会被这些公共字节替换。

十、从入场到构建：整条路径回顾

把本文涉及的命令与文档串成一条完整路径：

# 1. 入场：派生身份、拓扑、可用上下文与命令面
rig whoami --json
rig ps --nodes --json
rig context list
rig --help

# 2. 阅读公共世界约定与边界
rig context get world-public
rig context profile world-public --situation fresh

# 3. 取回并复制 book-world 模板，填写自己的事实
rig context get world-example

# 4. 安装自己的世界并确认
rig context add <pack-directory>
rig context list

# 5. 派生安装目录并运行验证器
rig context show world-public --json
sh verify-world.sh

入口文档 start-here.md 中的"该信什么"表可作为收尾总结——它给出每个信任问题的权威来源：环境用途信作者的世界与治理意图；当下存在什么信列出实时系统的命令；此刻在做什么信当前使命与所拥有工作；重复任务怎么做信适用技能或命令帮助；本地例外为何存在信本地 Lore 与其引用证据。当作者意图与实时状态冲突时，规则是调查而非为方便而静默解决。这就是 OpenRig World Pack 的全部精髓：把该写下来的写下来，把会变的交给命令，把不能证明的如实标记，然后用一个能失败的验证器守住这一切。