OpenRig context pack上下文包完整指南：打包、安装与ref安全校验
【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig
OpenRig 是一个让 Claude Code 与 Codex 协同工作的多智能体运行框架（multi-agent harness）。它的context pack（上下文包）机制允许你把参考文档、世界设定、操作约定等打包成一个带manifest.yaml的目录，通过rig context命令打包、安装到本地库，并支持按段落地址按需加载。本文带你走完「打包 → 安装 → ref 安全校验」的完整流程，帮你在多 Agent 团队中安全地分发上下文。
一、什么是 context pack 上下文包
一个 context pack 就是一个普通目录，核心是一份 manifest.yaml 清单文件，它声明了包的名称、版本、分类（taxonomy）以及每个文件的角色与摘要。以项目内置的参考包为例：
- name / version：包名与版本，是库中的唯一身份标识
- taxonomy：包的分类（如
world、reference），决定它在语义上"是什么" - files：文件清单，每个文件必须声明
path（包内相对路径）与role（角色），可选summary摘要 - atoms / profiles（可选）：把文件进一步切分为可寻址的"原子"，按 situation（fresh / handover / post-compaction）和运行时（claude / codex）组合投放，参考 world-public/manifest.yaml
所有内置包的清单源码都放在 context-packs-src/ 目录，是学习格式的最好范本。
二、如何打包：从零创建并查看你的上下文包
所有操作都围绕rig context命令族（实现见 context.ts），典型工作流是：
1. 本地编写包目录
在context.root配置指向的目录下新建一个文件夹，放入manifest.yaml和若干.md/.yaml/.txt/.sh等文件。manifest 必须是合法 YAML 对象，且name、version、taxonomy、files四个字段缺一不可——缺失时校验器会给出带修复指引的错误提示。
2. 同步索引并查看
| 命令 | 作用 |
|---|---|
rig context sync | 重新扫描发现根目录，刷新库索引 |
rig context list | 列出所有包：ref、版本、分类、文件数、预估 token |
rig context show <name-or-ref> | 查看 manifest 与逐文件元数据 |
rig context preview <name-or-ref> | 组装出完整 bundle 预览（不投递），并报告缺失文件 |
rig context compose --out <ref> --from <files...> | 把多个有序文件合成为一个新的持久 ref |
3. 按需拉取（pull 语义）
rig context get <ref>是面向 Agent 的拉取动词：输出就是组装后的 bundle 原文，支持<pack-ref>/<file>#H2-slug/H3-slug形式的段落实地址，让 Agent 只加载需要的部分而不是整个包。
三、安装 context pack：目录、URL 与 Git 三种方式
rig context add <source>是唯一的安装入口（context.ts），支持三种来源：
- 本地目录：
rig context add ./my-pack。要求源目录不是符号链接、必须包含manifest.yaml，安装名默认取 manifest 的name，可用--name覆盖。同名包已存在时会明确拒绝，避免静默覆盖。 - URL：
rig context add https://.../manifest.yaml。先抓取并校验 manifest，再逐个拉取声明的文件，全程先落到临时目录、最后一步 rename 原子发布——manifest 格式错误、URL 不可达或文件缺失都不会留下半个包（atomic by construction，见 installPackFromUrl）。 - Git 仓库：
rig context add <repo> --git。用你现有的 Git 凭据克隆仓库、发现其中的包快照并保留更新关系；之后rig context source inspect/update <ref>可查看本地修订、显式 fetch/merge 上游并选择更新，冲突时保留旧选择，绝不 push 或 reset。
安装成功后 CLI 会自动触发一次 daemon 库同步，让新包立即可被list/get检索。
四、ref 安全校验：为什么这些规则如此严格
这是 OpenRig 上下文包最值得新手理解的部分：每个 ref 都会被当作潜在的敌对输入处理。
逐段字符白名单
ref 采用路径式多段格式（如packs/compaction-restore），每一段必须匹配正则[A-Za-z0-9][A-Za-z0-9._-]{0,63}（见 ref-safety.ts）。这条白名单一次性封死了：
./..路径穿越（首字符必须是字母数字，点文件直接被拒）- 绝对路径、空段（双斜杠/尾斜杠）
- 空白、引号、冒号等 YAML / ID 注入字符
版本字段同样受约束：单个无分隔符 token、≤32 字符，防止伪造<name>:<version>存储 ID 或撑爆操作系统文件名长度限制（manifest-parser.ts）。
安装边界的三重防线
CLI 侧在写入任何本地文件之前执行与 daemon 镜像一致的校验（context-install.ts）：
- ref 逐段校验（
assertSafeInstallRef）——不安全的安装名在创建目录前就被拒绝； - 符号链接扫描（
assertTreeHasNoSymlinks）——包目录内任何符号链接直接拒绝，防止用链接把文件指向包外； - 命名空间包含检查（
assertDestinationNamespaceContained）——即使 ref 在词法上合法，只要目标路径的某个父目录段是符号链接或非目录，复制就会逃逸出上下文存储根，同样拒绝。
manifest 中的文件路径也受限：必须是包内相对路径（禁止..、禁止前导/），且后缀必须在允许清单内（.md、.markdown、.yaml、.yml、.txt、.sh、.ts等），未登记的扩展名会在摄取期响亮失败，而不是静默服务一个不完整的 bundle。
URL 安装还有一层同源边界：manifest 声明的每个文件 URL 必须解析到 manifest 自身目录之下，陌生 manifest 无法让安装器跨源抓取或"爬出"包目录。
错误可见性
daemon 侧（context-pack-library-service.ts）对每个写/解析点执行同样的校验顺序：不安全的 ref 抛出结构化的unsafe_ref错误，在任何文件系统操作之前失败，错误信息直接告诉你哪条规则被触发、如何修复。相关行为由 context-pack-ref-safety.test.ts 与 context-pack-add-ref-safety.test.ts 两测试文件持续守护。
五、上手清单
- ✅ 先读一个内置 manifest.yaml 抄结构
- ✅
rig context sync→list→preview三连，确认 token 预算再投放 - ✅ 安装优先用
--git方式，保留可审计的更新关系 - ✅ 收到外部包时，把 ref 当作不可信输入——校验器会替你把关，但你也应先看
show输出 - ✅ 用
get的段落实地址做按需加载，控制每个座位（seat）的上下文开销
context pack 让"给 Agent 发文档"从一次性拷贝变成了带版本、带校验、可寻址的持续供给。理解了 ref 安全规则，你就掌握了这个机制中最能防止上下文污染的一道闸门。
【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
