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

OpenRig 中，一个 agent 启动后能否立刻高效工作，取决于它拿到手的启动上下文是否准确、新鲜、聚焦——本指南围绕agent-startup-and-context-ingestion技能展开，讲解 AGENTS.md 覆盖层、角色文件、技能、rig spec、workflow spec、启动清单、refocus 消息与rig context检索面的正确组织方式。读完本文，你将掌握 OpenRig 启动上下文的 4 种典型失败模式与规避手段、rig whoami --json驱动的任务级启动解析链路、启动文件与技能的边界划分，以及 7 层叠加启动模型在实际 rig 中的落地方法。

为什么启动上下文是协调成败的第一道关口

在 OpenRig 的“context engineering and retrieval”体系里，agent 启动是第一个具体的落点：启动决定了一个 seat（席位）以什么初始形态进入工作；而更广义的上下文工程，则解决 seat 在当前工作中持续获得正确上下文的问题。

核心判断是：大多数协调失败不是工具失败，而是上下文失败。Agent 需要知道自己的角色、当前运行模式、协调约定、边界以及当前的产品意图（product intent）。如果启动上下文散落各处或者已经过期，agent 会以极高的效率执行错误的事情。因此，启动上下文设计的优先级远高于接入更多工具。

适用场景（Use this when）

• 为新 agent 编写启动文件（role / culture / startup-context）；
• 刷新一个一直运行在过期指引上的 seat；
• 审计 agent 是否拿到了当前运行模式（而不只是旧文件里写了什么）；
• 设计 orchestrator → 下一个 agent 的上下文传递形态；
• 为 OpenRig 自举（构建 OpenRig 的 rig）绘制启动地图。

不适用场景（Don't use this when）

• agent 通过 Agent Starter 创建——此时 starter manifest 已携带启动上下文（见 agent-starters/SKILL.md）；
• 工作是基于 packet 的 artifact 化心智模型重建——那属于 session-compaction-and-restore；
• 目标是发布可复用的启动内容为技能——那属于writing-skills-for-openrig技能。

启动失败的 4 种模式：审计时的排查清单

原文档明确定义了 4 种让启动上下文失效的模式，也是任何启动审计首先应检查的四个方向：

1. 新 agent 从旧 rig spec 启动，错过了当前运行模式。Spec 会过期；启动时必须让当前状态可见，而不是只依赖历史配置。
2. 指引被写进文件，未来的 agent 会读到，但当前在跑的 agent 从未被告知。文件编辑不会传播到运行中的会话。文化类内容的推广需要配套文化广播（broadcast + fleet-changes-feed），而不只是改文件。
3. 启动文件变成大杂烩，丢掉了“指向权威源”的角色。启动文件应该指向权威来源（point AT），而不是试图成为权威来源（TRY to be one）。
4. orchestrator 只传递实现指令，没有保留产品意图。指令会衰减，而意图应当随行传递。

任务级启动（Task-scoped startup）：从 whoami 到选中路径的解析链

启动不应是“读一堆文件”，而是解析出当前这个任务真正需要的输入。原文档给出了明确的命令链路：

rig whoami --json → project.yaml → mission.yaml → active slice.yaml → 选中的 component 或 wave map → addressed context（被寻址的上下文）

完整的查找与优先级规则见 docs/reference/product-journey-sdlc.md#resolve-the-selected-path（安装到本地后为$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path）。该参考文档将“解析选中路径”细化为五步：

1. 用rig whoami --json推导身份；用rig config get workspace.root定位工作根目录（可能与 seat 的代码检出目录不同）；
2. 读取project.yaml及其项目权威上下文，沿 mission root 到被指派的mission.yaml，再沿 composition ref 到活动slice.yaml；不要从旧 onboarding packet 或目录新鲜度去选 mission；
3. 按“项目默认 → mission 默认 → 活动 slice 显式选择/覆盖”的顺序解析 SDLC 选择；更窄的显式选择替换更宽泛的组件列表，而不是追加每个祖先的 gate；
4. 只读被选中的组件与被额外寻址的上下文：仓库引用从代码仓库根解析，安装引用从$OPENRIG_HOME/reference解析，context-pack 引用用rig context get获取；Markdown#section地址应使用loading-addressable-markdown技能而非加载整本无关手册；
5. 简要陈述用户成果、当前角色、候选方案、选中路径与下一个完成边界。

任务级启动还有三条重要原则：

• 启动文件是地址地图（address maps），不是普适的阅读强制令；不要预载无关的规划/评审教义，也不要要求逐文件 ACK 和测验；
• 技能可用（skill availability）不等于加载其全文；profile 里可用的技能是能力清单，不是强制阅读清单；
• 旧的 packet 不能决定当前工作；缺失被选中的上下文是一个需要解决的具名缺口（named gap），而不是“没有选择”的证据——不要静默地从显式选中的严谨路径回退。

源码佐证：rig whoami --json到底返回什么

packages/cli/src/commands/whoami.ts 是这条解析链的第一环。值得注意的实现细节：

• 默认输出是compact（紧凑）投影：通过projectCompactWhoami（whoami.ts#L78-L104）将 payload 收窄到身份恢复 ALLOWLIST——identity（rigName/nodeId/logicalId/podId/memberId/sessionName/runtime）、peers、edges、transcript。注释明确：这是一个 allowlist 而非 denylist，未来新增字段默认进--full，不会悄悄让每次启动的调用膨胀。
• 身份解析遵循固定优先级链（whoami.ts#L151-L193）：--node-id→--session→OPENRIG_NODE_ID/OPENRIG_SESSION_NAME环境变量 → tmux@rigged_node_id元数据 →@rigged_session_name元数据 → tmux 原始会话名 → 失败。
• --json是面向 agent 的机器可读输出；--full/--verbose才展示 contextUsage 等完整负载（紧凑模式下连 Context 行都省略，如需用量请用rig context或rig whoami --full）。

这解释了为什么技能文档把rig whoami --json放在任务级启动的第一步：它同时给出身份、同 rig 对等体（peers，含rig send所需的 sessionName）、拓扑边（edges）与 transcript 路径，是启动解析的权威锚点。

证明标准（Proof standard）

评估启动上下文是否生效，原文档要求在一次性干净会话中观察真实的读取行为与由此产生的下一步动作，并测试三类用例：

• 无选择（no-selection）场景；
• 显式严谨（explicit rigor）场景；
• wave 边界（wave-boundary）场景。

关键约束：一次编辑不能证明已经在运行的 seat 采纳了它——采纳需要经过授权的刷新或下一次启动的观察。不要仅仅为了测试文案而清空或重新预热一个在线 seat。

跨运行时启动路径（5 条，不可折叠）

当 seat 的启动属于 artifact 支撑的心智模型重建（active-work 重入场场景，区别于可复用的 Agent Starter / priming pack）时，遵循cross-runtime restore/reentry packet 标准 v0，并使用以下源信任排序：

rig whoami > target rigspec > bounded latest transcript > full transcript > touched-files > restore-summary.json

即：身份命令的当前现实优先于一切历史产物；越接近“当前权威状态”的源越可信，越靠后的源只作为兜底证据。这个排序也呼应了“当前命令/源码现实胜过过期 YAML 作为事实主张”的原则（见 product-journey-sdlc.md#L324-L329）。

启动时消费的内存表面（Memory surfaces）

启动时应盘点选中的启动输入清单：AGENTS/role/CULTURE 覆盖层、replay 上下文，以及任何声明的 restore packet 或 starter。对每一项记录：它来自哪里、是否当前有效、为什么本任务需要它。注意：可用技能或旧 packet 不能替当前工作做选择。

权限边界也要清晰：能读某个输入不等于能改写其源；写入必须遵循活动项目/rig 的策略与指派。当需要判断持久化上下文应放在哪里时，用rig context get加载skills/openrig-operating-model/SKILL.md来裁决。

启动文件 vs 技能：边界在哪

这是最容易混淆的一处。按产品参考文档 docs/reference/agent-startup-guide.md 与团队手册的界定：

两条红线：不要把技能内容塞进启动文件，也不要把身份内容写进技能。分层问题由下面要讲的 7 层叠加启动模型处理。

7 层叠加启动模型

docs/reference/agent-startup-guide.md（产品参考文档，非技能）给出了启动内容的叠加模型——各层按交付顺序累加，后层不替换前层，而是追加：

1. Agent 层 —— 来自 AgentSpec 顶层 startup block 2. Profile 层 —— 来自活动 profile 的 startup block 3. Rig 层 —— 来自 RigSpec 顶层 startup block 4. Culture 层 —— 来自 RigSpec 的 culture_file 5. Pod 层 —— 来自 pod 的 startup block 6. Member 层 —— 来自 RigSpec 中 member 的 startup block 7. Operator 层 —— 运行时注入（openrig-start overlay、context collector 等）

每层的用途可概括为：Agent 层承载随 agent 类型迁移的核心身份与能力（角色指引、默认技能）；Profile 层做 profile 变体（如 default vs minimal 的不同技能集）；Rig 层承载全 rig 共享的项目背景与团队规范；Culture 层承载 rig 宪法（CULTURE.md——沟通、质量、运作哲学）；Pod 层承载 pod 内协调上下文（pod SOP、pod 内工作流）；Member 层承载成员级覆盖；Operator 层由 OpenRig 系统注入（openrig-start.md、context collector）。

实践建议：多数 rig 只需要三层——agent（role.md）、rig（culture）、operator（openrig-start）。先从简单开始，只有当同 pod 内 agent 确实需要不同启动内容时才加 pod 层和 member 层。Culture 层价值高却常被跳过——没有CULTURE.md的 rig 只能靠 agent 猜测团队如何沟通协调。Member 层是例外手段而非常规：如果每个 member 都有独立 startup block，说明分层模型被当成了配置倾倒场，应把共享内容上提到 pod 或 rig 层。

交付机制与时机

启动文件如何到达 agent，由交付提示（delivery hint）决定：

时机是关键：guidance_merge与skill_install在 harness 启动前交付，agent 一启动就能看到，属于初始上下文的一部分；send_text在 harness 就绪后送达，适合身份接地、加载技能的指令，以及“像 operator 简报而非预载内容”的场景。applies_on字段进一步控制生效范围：fresh_start（仅首次启动）、restore（仅从快照恢复）、默认[fresh_start, restore]（两者）——用它可以避免向已恢复对话的 agent 重复发送它已持有的上下文。

实战：用 demo rig 串起启动链路

仓库中的 demo/rig.yaml 是一个真实的 rig 定义，可作为观察启动层叠的样例：它声明了culture_file: culture.md（Culture 层），并按 pod 组织成员——orchpod 的lead（claude-code）、devpod 的impl/qa/design（qa 为 codex）、revpod 的r1/r2（r2 为 codex）以及infrapod 的 terminal daemon，成员均引用local:agents/<id>的 agent spec（如 demo/agents/lead/agent.yaml）。每个 agent spec 通过 profile 的uses.skills声明技能可用性，rig 的culture_file注入团队宪法，运行时再由 Operator 层注入openrig-start接地信息——三层最小模型在这里完整可见。

对应地，docs/reference/agent-startup-guide.md 给出的最小有效启动是：

agent.yaml → guidance/role.md rig.yaml → culture_file: CULTURE.md profile → uses.skills: [openrig-user]

再配上启动清单中的系统检查（identity recovery 后执行rig ps --nodes确认 rig 在跑、rig env status确认服务健康、核对工作目录与所需工具），agent 便能在启动后自证环境就绪。

常见反模式（避免重蹈）

• 把所有内容倒进一个巨型 CLAUDE.md——用分层模型拆开，否则任何内容都无法复用；
• 在 guidance 文件里复制技能内容——技能会被投影，guidance 应引用它们而非复制；
• 用 send_text 传本该预载的内容——agent 开始推理前就需要的内容用guidance_merge；
• 过度指定 member 级启动——共享内容应上提，member 层只做小覆盖；
• 把关键 setup 押在确定性 hooks 上——若 hook 静默失败 agent 无从知晓，确定性配置必须搭配启动指令或系统检查来验证结果。

相关技能导航

启动上下文并非孤岛，它与以下技能协同工作（详见各 SKILL.md 的 sibling_skills 关系）：

• mission-slice-sop——开始被指派的 mission/slice 工作时加载；提供 SPEC.md、NOTES.md、PROGRESS.md 与 proof 的轻量工件与交接流程，但不替任务选择 SDLC；
• writing-skills-for-openrig——技能内容（不属于启动文件的部分）的编写纪律；
• forming-an-openrig-mental-model——新 agent 的定向引导；
• session-compaction-and-restore——恢复期的启动摄取；
• agent-starters——可复用的 starter manifest，组合启动上下文（captured → named → inspectable → used → promoted → deprecated 六态生命周期）；
• composable-priming-packs——产出已预热会话的 manifest；
• openrig-operating-model——持久上下文的放置与权威裁决。

小结

OpenRig 的启动上下文设计可以浓缩为三个动作：解析（用rig whoami --json沿 project/mission/slice 链路解析当前权威路径）、分层（按 7 层叠加模型把身份、文化与项目背景各归其位）、指向（启动文件是指向权威源的地址地图，而非内容倾倒场）。记住“启动文件 vs 技能”的边界、4 种失败模式和源信任排序，你的 agent 就能在启动时拿到正确的角色、运行模式与产品意图——而不是在错误方向上高效狂奔。

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