企业官网建设流程全解析

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI

OpenRig 是一个将 Claude Code 与 Codex 编排为统一多 Agent 系统的协作框架（harness）。本篇文章围绕 v0.5.15 版本展开，重点讲解本次发布的三大主线：启动与恢复体验（含--existing名称消歧、可执行的恢复指引、首次启动受控重试）、面向持续运行软件团队的 OpenRig Software Factory 指南（手动团队工作 / 队列编排 / 显式 Workflow 三条路径），以及用户自选命令权限的落地方法，同时给出 macOS arm64 上 Node 版本选择建议与 Pi 回复可见性、终端输入处理的修复细节。读完本文，你将掌握 v0.5.15 的升级要点、配套技能文件的读取命令，并能依据源码与测试理解这些能力背后的实现边界。

版本概览：v0.5.15 改了什么

v0.5.15 是 OpenRig 的一个修复与引导增强版本，核心变化如下：

• 启动与恢复更清晰：启动器同时识别原生 Codex（通过 shell 与 Node launcher）；启动错误现在同时描述问题本身与对应的恢复动作；名称同时命中 starter 与已停止 rig 时，rig up <name> --existing可显式选择既有 rig。
• 新增软件工厂公共指南：面向持续运行的软件团队（Software Factory），覆盖角色分工、上下文、工作归属、独立评审、并发与成本，并区分"修改运行中的团队"与"保存更新后的 RigSpec"。
• 用户自选命令权限：通过rig context get skills/applying-a-permission-policy/SKILL.md获取维护中的权限策略应用流程，选择保留提示、记住选定命令或更宽泛的放行。
• Pi 修复：Pi 回复与工具进度可见（受支持的 RPC 事件形态）；shell 工具保留 OpenRig 管理上下文；错误信息有界截断，重试耗尽后不再重复打印；粘贴内容需显式提交，终端 runner 突破 canonical buffer 限制并支持恢复。
• 已知兼容性限制：macOS arm64 + Node 24 下安装 SQLite 依赖可能失败，官方建议该平台暂时使用Node 22。

发布状态与日期记录在 GitHub release 与 npm 上；项目根目录的 README 与 CHANGELOG 保持同步描述。

启动与返回：更清晰的指引与恢复路径

启动前必读与版本核对

v0.5.15 明确指出：启动前应先阅读 README 中 "what OpenRig changes on your machine" 一节。原因是 provider 集成会配置可执行 hooks 与工作区信任——只修改OPENRIG_HOME并不能隔离 provider 配置。完整的首次任务引导见 getting-started 指南，其中同样强调：启动 rig 会写入 provider hooks 与 workspace trust 设置，动手前应备份相关文件。

安装完成后，用三条命令核对本机可用命令：

rig --version rig --help rig up --help

启动与恢复的语义

• 启动与恢复识别原生 Codex（经由 shell 与 Node launchers）；当进程身份无法确立时，系统如实报告不确定性，而不是猜测。
• 识别到的更新通知会被跳过，不会擅自安装 provider 更新；认证与信任选择始终归用户所有。
• 启动错误现在同时输出问题描述 + 恢复动作。
• 若一个名称同时匹配 starter 与已停止的 rig，rig up <name> --existing会选择既有 rig；在继续分配工作前应先检查其上报状态。

这一名称消歧逻辑在 CLI 实现中有据可查：up.ts 中--existing选项的定义为"将<source>视为既有 rig 名称，绕过 library-spec 名称解析"；当名称同时命中 library 匹配与既有 rig 恢复目标时，命令会打印歧义提示并指引使用rig up <name> --existing恢复既有 rig，而不是静默导入 starter。若名称既非 library spec 也非既有 rig，则继续走既有 rig 名称路径并打印 "Recovering ..." 提示。相关行为在 up.test.ts、up-restore-decision.test.ts 与 restore-check.test.ts 中有测试覆盖。

首次启动失败后的受控重试

v0.5.15 为"新增座位首次启动失败"引入守卫式重试（guarded retry）：当座位在资源投影（resource projection）阶段失败、启动上下文尚未保存时，可在修正配置问题后重试。使用上需要遵守：

• 保留完整的原始 member 片段及其 source root——仅凭快照无法重建缺失的启动配置；
• 一次只重试一个（Use one retry at a time）；
• 普通会话恢复（ordinary conversation resume）是另一条独立路径。

服务端实现位于 rigspec-instantiator.ts，测试 retry-first-start.test.ts 详尽验证了守卫语义：

• 投影失败、启动上下文（node_startup_context）未保存、launchHarness未调用的节点，在修正后可通过/api/rigs/:rigId/nodes/:nodeId/launch传入retryStartupFrom: { member, rigRoot }重试；成功后节点状态为launched，且不触碰兄弟节点、不改变历史、不产生 resume token；
• 已就绪（ready）的 occupant 永远不会被重分类为"失败的首次启动"——重试请求返回409；
• liveness 检查期间（present / transport_unavailable）同样409 拒绝且无副作用；
• 异步 liveness 检查期间座位被变更（如模型被改写）时返回 "Seat changed during recovery checks; inspect it before retrying."，拒绝执行；
• 存在 resume token、native session、late-failure、spec 变更、member 变更或 overrides 时，一律拒绝投影与启动。

这套守卫保证"重试"只作用于真正的"首次启动未完成"场景，避免误伤正常会话。

继续有用且经过评审的工作：OpenRig Software Factory

v0.5.15 随包提供OpenRig Software Factory食谱：给 Agent 一个真实仓库、一个目标结果、以及你想保留的决策，即可支撑直接团队协作、队列编排、或可选的显式 Workflow三种工作方式。

读取随包技能：

rig context show skills/core/openrig-software-factory --json rig context get skills/core/openrig-software-factory/SKILL.md rig context get skills/core/openrig-software-factory/references/worked-example.md

仓库中的规范副本位于 skills/_canonical/core/openrig-software-factory/SKILL.md（发布镜像在 packages/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md），配套工作示例为 references/worked-example.md。

选择团队的工作方式：三条递进路径

关键提醒：路线图、YAML 文件或 wake 并不会执行工作或授权新结果。

建立工作约定（working agreement）

• 读取仓库说明、当前工作与用户期望的可见结果；核实目标实例、代码/工作根目录、真实 seat 地址与原生就绪状态。
• 复用合适的小团队；现有 agent 可以引导（bootstrap）新团队。kernel operator 是可选的，且并不自动成为项目 owner。
• 约定：工作边界、时间/花费上限、未决选择由谁回答、何时停止（检查通过 / 无授权后续工作 / 预算耗尽 / 真实的用户-权限-provider 阻塞）。
• 成本意识：后台 daemon 检查本身不是 model turn，但已投递的 wake 与被唤醒恢复的工作会消耗 token；优先采用事件驱动等待，而非频繁的空提醒。wake 无法回答用户问题、清除权限提示或保证进度。
• 启动或分配工作前先选好权限：保留普通提示、为选定命令建立持久规则、或刻意放宽访问，三者皆可；跟随 Applying a permission policy 执行用户的选择并在目标会话中验证。放宽整个rig家族意味着允许每个 verb（不只读取），但它不授予新产品权限，也不改变其他人的默认值。
• 把目的、验收、决策与证据保留在既有项目文件中；"检索到上下文"不等于"peer 已送达"。owner 携带候选成果走完选定的检查与有界修复，报告如何试用，并保留下一项授权任务或如实报告没有。

扩容你的工厂（Grow your factory）

1. 使用双 Agent 起点：保持既有 owner 与独立 checker，直到该组合无法承受工作负载。owner 可同时负责实现与协调。

2. 向运行中的 rig 增加一到两个座位：这是常规下一步。跟随 worked-example 的 "Grow the running team" 使用rig grow，无需 YAML、无需 down/up 重建既有会话。命令层面见 grow.ts（"Add one or more seats to a running rig"）。典型命令：

   rig grow "$RIG_ID" a b --pod dev --runtime codex --cwd "$PROJECT_ROOT" --json

   --pod加入既有 pod，--new-pod build建立新 pod，二者互斥；runtime 默认claude-code、cwd 默认调用者当前目录，因此示例刻意显式选择了 Codex 与仓库目录。新座位不会继承owner 的自定义 agent、模型、上下文、原生权限 profile 或会话，必须显式分配职责。

3. 自定义 rig：需要不同结构时，可读取 OpenRig Architect 技能，通过rig context get skills/core/openrig-architect/SKILL.md获取；请求语例如"Design a user-owned rig for [outcome] using the compatible RigSpec/AgentSpec guidance…"。

扩容语义提醒：增加座位不会自动分配工作、改变权限或创造并行；需在既有项目文件中显式记录分工、文件/worktree 边界与集成归属，并把活跃并发控制在用户的时间/花费预算内。两个座位是入口点，不是成品工厂，也不是上限。扩容后可用rig export "$RIG_ID" -o ...保存展开后的拓扑为独立文件，并用rig spec validate与rig doctor --spec核对成员一致性（注意 export 并非对每个原始 authoring 字段无损）。

读取兼容版本指引

安装前，应在与所选包相同的发布 tag 或 commit下使用该技能文件与配套文档；安装后核对：

rig --version rig context list --json rig context show skills/core/openrig-software-factory --json rig context get skills/core/openrig-software-factory/SKILL.md

不仅要比较版本号，还要比较构建身份。缺失、不可读或更旧的食谱结果应如实保留，不要静默替换为较新的 main 或跳过缺失的配套文档。

兼容的权限指南在哪里

检索维护中的流程：rig context get skills/applying-a-permission-policy/SKILL.md。源码/归档读者的路径对照如下（这些路径相对于命名根，而非本技能文件）：

对于已安装的指引，使用提供所选rig可执行文件的 npm 安装；另一个 prefix 或本地项目可能含有不同版本。配套指南或章节缺失时，先报告缺口再继续，不要用当前 main 或另一安装的指南替代。

给 Agent 的标准请求

Help me achieve [observable change] in this repository. Read the compatible Software Factory recipe, choose the lightest useful team/queue/Workflow path, and keep the next owner visible. Preserve existing files and permissions. Agree time/spend limits, perform the authorized work and chosen independent check, and ask only about unresolved decisions or effects outside that scope. Keep publication and destructive changes out of this task.

选择命令权限：Applying a permission policy

v0.5.15 强调：由用户选择权限范围，Agent 负责检查目标 harness、解释可用范围、在保留既有规则的前提下落地选择。取回维护中的流程：

rig context get skills/applying-a-permission-policy/SKILL.md

仓库中的规范副本位于 packages/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md。

三选一：保留提示 / 记住命令 / 更宽泛放行

放行整个rig家族覆盖其所有 verb——包括生命周期、拓扑/配置变更，以及能启动其他进程的命令，绝非只读授权。请求更窄时提供rig ps、rig queue list之类前缀。不要把选择扩大到任意 shell 执行、整个解释器或通用 shell 包装。

落地流程六步

1. 定位目标座位、可执行文件/版本、启动设置与配置根：HOME、CODEX_HOME或CLAUDE_CONFIG_DIR（operator、daemon、seat 三者可能不同）；
2. 读取既有权限规则与管理限制，选定范围（单项目或用户全部会话）；
3. 准备具体 diff，保留 deny/ask 规则、审批/sandbox 姿态、hooks、auth、MCP、模型设置与无关值；allow 不得抹掉更严规则或管理要求；遇到真实冲突要报告而非静默绕过；
4. 备份被改文件，仅合并被授权的增补，避免重复；Agent 负责执行编辑；
5. 回读 diff、验证格式，确认该版本如何加载变更（若需新会话，则保留工作并走受支持的 resume 路径；文件写入不能证明既有会话已加载）；
6. 在目标会话中两次验证一次普通匹配操作，并确认无关命令未获得匹配规则；用无害读取而非破坏性探测。

回滚时只移除本次设置的增补，保留后续无关编辑。内置 policy spec 保持只读，自定义应在用户空间进行。

Codex 与 Claude 的命令规则

Codex：命令规则可在 sandbox 之外放行匹配命令而不再次提示，且不改变其他 sandbox/网络设置。目的地按范围二选一：

• 仅此项目：验证已安装版本支持项目规则、推导实际项目/worktree 配置根与信任状态；仅当<repo>/.codex/rules/层受支持、已激活且被信任时使用；否则报告限制并保持用户层规则不变，绝不静默标记项目为可信或代以用户级放行。
• 明确用户级：使用目标用户实际CODEX_HOME（通常~/.codex/rules）下的rules/——这会波及使用该 home 的其他项目。TUI 的 remember-allow 动作同样写入用户层规则，不能用来实现仅项目的请求。

规则片段（前缀本身没有项目限制，即使项目层规则也不限制被放行的rig命令影响哪些目标）：

prefix_rule(pattern = ["rig"], decision = "allow")

更窄可用["rig", "ps"]或["rig", "queue", "list"]。绝对路径调用需推导目标座位实际rig可执行文件并单独加一条精确前缀。验证用：

codex execpolicy check --pretty --rules /absolute/path/to/openrig.rules -- rig ps --json codex execpolicy check --pretty --rules /absolute/path/to/openrig.rules -- printf permission-check

注意检查匹配结果而非仅退出码；prompt/forbidden匹配优先于 allow。codex execpolicy check是独立求值器，只校验给定 argv；原生 shell 解析可能先拆分普通命令/链，因此zsh -lc不匹配不能证明原生rig && rig会失败，需要两个表面都验证，且不要把规则放宽到bash、sh、node等通用包装。

Claude Code：把所选条目合并进既有permissions.allow（该片段不是替换性 settings 文件）：

{ "permissions": { "allow": ["Bash(rig *)"] } }

当前语法用*表示命令族，Bash(rig:*)同样受支持；更窄示例为Bash(rig ps *)、Bash(rig queue list *)。保留deny/ask与defaultMode，不要为了消除不匹配而添加Bash(*)或切到 bypass。范围选择：.claude/settings.local.json（个人项目设置）、.claude/settings.json（刻意共享的项目设置）或目标CLAUDE_CONFIG_DIR（通常~/.claude）下的settings.json。

项目级权限的边界

项目级配置要求"受支持、已激活、被信任"：仅当项目配置可用时才能做 project-only 设置；若不可用，Agent 应解释限制，而不是代之以用户级权限。备份被改文件，并在实际会话中验证所选规则。v0.5.15 明确：随包提供的 sandbox、审批与权限默认值不变——选择规则或更宽模式不会改变出厂默认。

配套细节见 getting-started 指南的 Opt-in permissive operation 一节：例如 Codex 命名 profile 的sandbox_mode = "danger-full-access"+approval_policy = "never"、成员级codex_config_profile字段、以及permission_policy: builtin:yolo（选择-s danger-full-access -a never）与 Claude--dangerously-skip-permissions的对应关系。权限模式是原生执行选择，工作姿态是项目指引，二者分离；rig seat set-permissions ... --mode full_bypass|floor|inherit记录 actor、理由与新旧选择，但不重新启动座位、不改变兄弟座位、不编辑规则/hooks。

已知兼容性限制：macOS arm64 请用 Node 22

v0.5.15 记录了一个已知兼容性限制：在 macOS arm64 + Node 24 环境下，安装 SQLite 依赖可能在以下情形失败：

• 合适的预编译二进制不可用，且本机无编译能力（compilation is not available）；
• 编译构建的 SQLite 也曾在运行时数据库清理（database cleanup）期间失败。

官方建议：macOS arm64 暂时使用 Node 22。该建议不改变已声明的 Node 支持范围，本版本也未升级 SQLite。

入门指南 getting-started.md 与之呼应：支持 Node.js 22 或 24 与 tmux，macOS/Linux；Apple silicon 的 Mac 请使用 Node.js 22；原生 Windows 尚不支持，WSL2 未经测试，Node 20 不再受支持，Node 26 及其他版本未经测试。README 同样将 兼容性历史 指向本小节。

Pi 回复、输入与恢复：本次修复细节

Pi 回复与 shell 上下文

• Pi 回复与工具进度可见：对受支持的 RPC 事件形态生效。修复来自社区 PR（见下文 Contributors）。
• Shell 工具保留受管理的 OpenRig 上下文：身份与路由所需的上下文不再丢失。
• Provider 错误有界显示：错误以受限文本（bounded text）呈现；重试耗尽后不再重复打印同一错误。

终端输入处理

• 粘贴的消息等待显式提交（explicit submission），不会自动执行。
• 终端 runner 接受超出终端 canonical buffer 上限的输入，保留编辑与取消能力，并在拒绝超大 framed 消息后能够恢复。
• 官方明确这不是通用延迟保证或不受限输入大小的承诺。

首次启动失败后的受控重试（Pi 相关）

新增座位若在资源投影阶段、启动上下文保存之前首次启动失败，可在修正 setup 问题后使用受控重试。要点已在前文展开：保留完整原始 member 片段与 source root（快照不足以重建缺失的启动配置）、一次只重试一个、普通会话恢复独立。服务端守卫与 409 拒绝语义见 retry-first-start.test.ts。

Pi 支持是有资质且受监督的（qualified and supervised）

v0.5.15 如实声明 Pi 支持的验证范围：

• 已用Pi 0.87.1与 OpenRouterz-ai/glm-5.3-flash验证：受控编码、追问、汇报与对话连续性；普通座位（ordinary-seat）的身份、工具与回复也可用。
• 未验证：完成一个普通有用任务、无人值守的团队操作（unattended team operation）。
• 上下文 profile 选择与 hook 生成的覆盖有限——不要假定与每个 Codex 或 Claude 集成对等；Software Factory 指南同样不构成完全无人值守运行的保证。

这些限定说明 Pi 路径当前适合受监督的实验性使用，而非生产无人值守。

贡献者与本次包含的 Pull Requests

感谢社区与维护者的贡献：

• [@danielkuykendall23-boop]：Pi 回复修复（#37）；
• [@mvschwarz]：Codex 启动与恢复指引（#38）、Software Factory 与权限指引（#39）、贡献与支持指引（#45）、首次使用 README（#46）。

此外本版本还包含上述启动身份细化、守卫式首次启动重试、Pi shell/错误处理与终端输入修复。项目工作策略特性（project work-policy features）与 Node 22/SQLite 13 升级不在本版本范围内——升级到更高版本前，请以对应版本的发布说明为准。

小结

v0.5.15 的定位是"把启动与恢复做扎实、把持续协作的方法论落到技能文件里、把权限选择明确交还给用户"，并顺带修复 Pi 与终端输入的一批实际问题。升级后建议按序执行：核对rig --version→ 阅读 README 的机器变更说明 → 走一遍 getting-started 首次任务 → 用rig context get skills/core/openrig-software-factory/SKILL.md与rig context get skills/applying-a-permission-policy/SKILL.md引入协作与权限约定；在 macOS arm64 上保持 Node 22。所有关键行为的边界（守卫重试、名称消歧、权限三选一）都能在本仓库的源码与测试中找到对应实现，便于你在实际部署中验证与排障。

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI