企业官网建设流程全解析

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具

本文基于 Ouroboros 仓库的官方运行时指南 docs/runtime-guides/pi.md 与对应源码实现，讲解如何在本地安装的 Pi CLI 之上运行 Ouroboros 工作流。读完后你将掌握：Pi 运行时适配器的三层架构心智模型、pi --mode json子进程契约与参数探测机制、JSONL 事件流的归一化解析，以及ooo技能指令在 Ouroboros 控制 Pi 与 Pi 反向拉起 Ouroboros 两个方向上的完整打通方式。

"Pi 作为 Ouroboros 运行时"到底意味着什么

Ouroboros 把 Pi CLI 当作一个子进程适配器（subprocess adapter）：Ouroboros 自己拥有工作流引擎、Seed 分解、checkpoint、评估交接与ooo技能分发；对于每个运行时任务，它向 Pi 的 JSON 模式发起 shell 调用，并把 Pi 输出的 JSONL 事件归一化为 Ouroboros 的AgentMessage值。

指南给出的分层心智模型如下：

User / CLI / MCP | | 1. Selects runtime_backend: pi, or sends an ooo shortcut v Ouroboros runtime adapter | | 2a. ooo shortcut? handle inside Ouroboros before Pi starts | 2b. normal task? spawn Pi JSON mode v pi --mode json <prompt> | | 3. Pi loads its own settings, packages, extensions, tools, model auth v Pi model turn and JSONL events

这个模型划清了三条边界：

• "Pi is an Ouroboros runtime" 只意味着步骤 2b 存在且可被选择（runtime_backend: pi），并不表示 Pi 的包被导入到 Ouroboros 内部；
• Pi 的交互式命令 UI 也不进入 Ouroboros 命令路由——除非由 setup 安装了托管的 Pi bridge 扩展；
• 反过来，Pi 自己加载包、扩展、工具与模型鉴权（步骤 3）时，Ouroboros 不介入也不依赖其内部细节。

在源码中，这一层由 PiRuntime 实现，其类属性声明了运行时标识（_runtime_backend = "pi"）、CLI 默认名（_default_cli_name = "pi"）以及一组超时参数：启动输出等待 120 秒、stdout 空闲 600 秒、进程关闭 5 秒、stderr 最多保留 512 行。它通过 runtime factory 被orchestrator.runtime_backend: pi选中构造。

前置条件

一个容易踩坑的点：对于 OpenAI 订阅背书的 Codex 模型，请使用 Pi 的openai-codex登录/模型路径。普通的openai提供方路径是面向 API key 的，二者不是同一套鉴权面。这一点在 Troubleshooting 一节还会再出现。

快速开始

# 1. Install and authenticate Pi npm install -g --ignore-scripts @earendil-works/pi-coding-agent pi # In the interactive Pi session, run /login and select openai-codex. # 2. Point Ouroboros at Pi and install the Pi-side ooo bridge ouroboros setup --runtime pi # 3. Run a workflow through the configured runtime ouroboros run workflow seed.yaml # 4. In Pi or roach-pi/custom Pi, restart Pi or run /reload, then: ooo auto build a small CLI

第 2 步ouroboros setup --runtime pi做两件事：把 Ouroboros 指向 Pi，并在 Pi 侧安装ooobridge 扩展。第 4 步要求重启 Pi 或执行/reload，因为 Pi 是从扩展目录自动加载扩展的。

如果 Pi 安装在PATH之外，有两种显式指定方式：

export OUROBOROS_PI_CLI_PATH=/absolute/path/to/pi

或者写入配置文件：

orchestrator: runtime_backend: pi pi_cli_path: /absolute/path/to/pi

从源码看，解析优先级由 get_pi_cli_path 实现：环境变量OUROBOROS_PI_CLI_PATH优先，其次读取config.yaml中orchestrator.pi_cli_path（对应 OrchestratorConfig 的pi_cli_path字段，并会经expanduser展开~），最后都取不到时在运行时从PATH解析pi。配置中缺失时，PiRuntime._resolve_cli_path 会用shutil.which("pi")定位，定位不到则原样传"pi"并在启动时报Pi not found。

运行时契约：Ouroboros 如何拉起 Pi

对普通执行任务，Ouroboros 组装并启动如下命令（见 _build_command）：

pi --mode json [--model <MODEL>] [--session <SESSION_ID>] [--append-system-prompt <SYSTEM>] [--tools <TOOLS>] [--no-tools] <PROMPT>

工具名映射表

映射逻辑集中在 _PI_TOOL_FLAG_NAMES：

_PI_TOOL_FLAG_NAMES: dict[str, str] = { "Read": "read", "Write": "write", "Edit": "edit", "Bash": "bash", "Command": "bash", "Execute": "bash", "Glob": "find", "Grep": "grep", "LS": "ls", "Ls": "ls", }

Ouroboros 讲的是 Claude 风格的大写工具词汇，而 Pi 内建工具是小写（read、bash、edit、write、grep、find、ls）。未知名称保持不变，因此扩展/自定义工具名可以继续工作；白名单里匹配不上的条目对 Pi 是惰性的。该映射有专门的单元测试覆盖，例如 test_pi_runtime.py 中的test_glob_maps_to_pi_find_builtin、test_command_and_execute_map_to_pi_bash_builtin、test_all_known_ouroboros_builtins_map_to_valid_pi_tools。

参数能力探测：一次pi --help，三个独立结论

原生参数 flag 只探测一次——_probe_pi_native_param_flags 运行pi --help（10 秒超时），在输出中分别查找--append-system-prompt、--tools、--no-tools三个子串，并各自独立保留探测结果。这样能力协商就能区分"一个有工具能力但缺少成对参数路径的旧版 CLI"与"一个全新的支持全部三个 flag 的 CLI"。

两个关键行为：

1. 降级为translated：只有当--append-system-prompt与--tools同时可用时，系统提示词与非空工具白名单才走原生投递；否则这两个参数会被拼进用户消息（## System Instructions/## Tooling Guidance段落），并在能力契约中报告为translated。
2. --no-tools单独谈判：空列表强制能力被单独暴露为empty_tool_restriction_support，并纳入持久的运行时能力契约。因此一个只有--no-tools的 Pi 二进制与一个无法禁用工具的 Pi 二进制，具有不同的"谈判 + 执行语义"指纹。

tools=[]是一条安全边界。execute_task 中的处理是：如果请求tools=[]而本机 Pi 不支持--no-tools，Ouroboros 在拉起 Pi之前就返回ToolRestrictionUnenforced错误（error_type: "ToolRestrictionUnenforced"，effective: "unrestricted"），而不是把空列表悄悄放宽为不受限的默认工具集——因为任何提示词层面的翻译都无法让"不受限的 Pi 默认"等价于"显式无工具"。

相关能力声明见 PiRuntime.capabilities：skill_dispatch=True、targeted_resume=True（经由--session）、structured_output=True，以及基于探测结果的system_prompt_support/tool_restriction_support/empty_tool_restriction_support。

JSONL 事件流解析

Pi JSON 模式的事件生命周期（见 PiRuntime 类文档）：

• 首行：session头事件{"type":"session","id":"<uuid>",...}，被解析进RuntimeHandle（backend="pi"、native_session_id、cwd），支撑后续的--session定向恢复；
• message_update：流式内容增量。_extract_content_delta 从assistantMessageEvent中读取text_delta的delta/text/content，并保留对旧版/过渡版 Pi 构建的兼容回退路径；
• 终态文本：从message_end、turn_end或agent_end事件中读取最终 assistant 文本（_extract_final_content），agent_end会从messages数组倒序找最后一条有文本的 assistant 消息。

一个重要的防御性设计：Pi 可能把 provider/模型故障报告为带stopReason: "error"的 assistant 消息，而进程仍以状态码0退出。_extract_error_content 因此扫描message_start/message_end/turn_end/agent_end中的这类消息，Ouroboros 把这些事件当作运行时错误处理，而不只依赖进程返回码。agent_end事件同样不能掩盖非零退出码——这两条路径分别有测试test_agent_end_does_not_mask_nonzero_exit与test_agent_stop_reason_error_overrides_zero_exit守护。

ooo在 Pi 语境下的两条入口路径

ooo技能指令有两条受支持的入口路径，方向相反。

路径一：Ouroboros 拉起 Pi

当 Ouroboros 已处于控制中且选中runtime_backend: pi时，ooo <skill>会在 Pi 子进程启动之前被 Ouroboros 处理。

Pi 运行时会话在PiRuntime.execute_task()顶部调用共享的 SkillInterceptor：如果提示词是 Ouroboros 技能快捷键（如ooo interview或/ouroboros:ouroboros-run），拦截器解析技能并调用对应的 Ouroboros MCP 处理器，Pi 根本不会收到这条提示词作为普通聊天输入。也就是说：

• 在 Ouroboros 控制的 Pi 运行时里，ooo interview表示"由 Ouroboros 处理 interview 命令，使用已配置的 LLM 后端做创作"；
• Pi 只在该分发路径判定输入不是ooo快捷键之后，才运行普通的 Seed 执行提示词。

路径二：Pi（或 roach-pi）拉起 Ouroboros

ouroboros setup --runtime pi同时安装一个托管的全局 Pi 扩展：

~/.pi/agent/extensions/ouroboros-ooo-bridge.ts

Pi 会从该目录自动加载扩展。重启 Pi 或执行/reload之后，交互式 Pi 会话（包括 roach-pi 等定制 Pi 形态）可以输入：

ooo auto build a small CLI ooo interview clarify this feature /ooo status auto --resume auto_...

扩展拦截精确前缀的ooo ...输入，并执行：

ouroboros dispatch --runtime pi --cwd <pi-session-cwd> "ooo ..."

这个隐藏的dispatch入口与运行时适配器使用同一套共享技能解析器与 MCP 处理器组合。指南特意强调：这不是一个 roach-pi 专属适配器——roach-pi 仍然是由 Pi 加载的 Pi 定制，Ouroboros 只拥有把ooo命令转发进 Ouroboros 的这座桥。

从源码看，bridge 扩展的 TypeScript 模板由 pi_bridge.py 渲染，setup 决定安装位置与启动器。模板中内置了一份可分发子命令清单（auto、interview、run、seed、status、ralph，均为声明了mcp_toolfrontmatter 的技能），并配有注释说明该清单由单元测试与分发端保持同步。

bridge 还有三个值得注意的行为细节：

1. 不支持分发时确定性回落：bridge 只消费隐藏分发器能通过 MCP 支持的技能 frontmatter 执行的命令。像ooo help或裸ooo这类没有声明 MCP 分发目标的一方快捷键，会以确定性的"不支持分发"退出码返回给 Pi，让普通 Pi 会话继续处理输入，而不是让 bridge 硬失败。
2. TAB 参数补全：注册的/ooo命令通过 Pi 原生getArgumentCompletions面提供补全：/ooo <TAB>列出带一行描述的可分发子命令；ooo run <TAB>把~/.ouroboros/seeds/中的 Seed 文件以绝对存储路径列出（用 POSIX 单引号包裹并处理内嵌单引号），使补全值无论 Pi 会话目录在哪都能执行（相对 seed 路径是相对会话 cwd 解析的）。补全是确定性且离线完成的，子命令清单镜像分发器自己判定合格的技能集合，单元测试通过resolve_skill_dispatch派生该集合，保证两处不会漂移。含空白的 Seed 名被跳过，因为分发器按空白 token 化命令。
3. ooo auto的后台作业生命周期：分发器拥有后台作业的生命周期管理。ouroboros_start_auto返回job_id之后，dispatch 进程轮询ouroboros_job_wait，并在作业到达终态后取回ouroboros_job_result。这保证通过 Pi 输入的ooo auto与正常的ooo auto契约对齐：用户不会因为命令从 Pi 进入而需要手动轮询后台作业。

ooo auto --runtime pi的执行语义

ooo auto的完成语义：

Pi 的模型选择默认来自 Pi 自己的默认值，除非执行路径传入模型覆盖。为了可复现的冒烟测试，指南建议：

export OUROBOROS_EXECUTION_MODEL=openai-codex/gpt-5.4-mini

此时 Pi 运行时启动命令变成：

pi --mode json --model openai-codex/gpt-5.4-mini <PROMPT>

另一个实操要点：auto 通常在 Ouroboros 管理的任务 worktree 中运行，因此一次成功的写文件冒烟测试可能把文件创建在~/.ouroboros/worktrees/...下，而不是 shell 原来的 checkout 里——这与 OrchestratorConfig 中use_worktrees: bool = True、worktree_root: str = "~/.ouroboros/worktrees"的默认值一致。

Pi 包与 roach-pi：边界合同表

Pi 包与扩展由Pi 自己加载。如果用户在 Pi 的设置里安装了某个包（例如git:github.com/tmdgusya/roach-pi），Ouroboros 拉起的 Pi 子进程会通过 Pi 正常的扩展加载器加载它。这与"roach-pi 是 Ouroboros 运行时适配器"是两回事：

一句话总结：runtime_backend: pi选择 Pi CLI 作为执行引擎。定制的 Pi 发行版可以影响该 Pi 进程内部发生的事情，但 Ouroboros 在运行时执行上只依赖 Pi 的 JSON 模式子进程契约，在交互式ooobridge 上只依赖 Pi 文档化的全局扩展加载器。

Pi 作为 LLM 后端（与运行时后端相互独立）

除了orchestrator.runtime_backend，Pi 还可以被选为创作、打分、抽取等补全流程的 LLM 后端：

llm: backend: pi

这两者是彼此独立的配置面。源码中由 PiLLMAdapter 实现——它复用了 Codex CLI 适配器的子进程基础（同一 JSONL 事件流家族），但作为纯 LLM provider 暴露，供 interview/planning/evaluation 等角色选择--llm-backend pi。

关于结构化输出，Pi LLM 适配器通过软强制支持response_format：Ouroboros 注入严格的 JSON/schema 指令、从 Pi 的响应中抽取 JSON 负载，并在返回前对json_schema负载做校验（build_response_format_directive/validate_response_format_payload）。由于 Pi JSON 模式目前没有 Codex 风格的原生--output-schema硬强制 flag，格式错误的结构化响应会被重试，随后作为 provider 错误暴露。另外，模型名为哨兵值"default"时不会转发给 Pi，而是让 Pi 使用自己的后端默认（见 PiLLMAdapter._build_command）。

选型建议：想让 Pi 执行 Seed 任务时用运行时后端；当创作/评估流程可以接受适配器层的 JSON 抽取与校验（而非 provider 原生 schema 强制）时，用llm.backend: pi。

能力矩阵

故障排查

Pi not found安装 Pi、把pi放到PATH，或设置OUROBOROS_PI_CLI_PATH。

OpenAI OAuth 在 Pi 里正常，但 Ouroboros 仍然失败检查模型字符串。对 Pi 中订阅背书的 OpenAI Codex 模型，使用openai-codex/...模型/提供方路径，而不是普通的 OpenAI API-key 提供方路径。

roach-pi 的某个 slash 命令看起来没反应该命令可能依赖 Pi 的交互式 UI 上下文。Ouroboros 以一次性 JSON 模式运行 Pi，交互式 slash 命令体验不保证。对 Ouroboros 工作流，优先使用普通 Seed 执行提示词或兼容无头模式的 Pi 扩展。

Pi 内部的ooo ...被当作普通聊天发给了模型运行ouroboros setup --runtime pi，然后重启 Pi 或执行/reload。确认~/.pi/agent/extensions/ouroboros-ooo-bridge.ts存在。

Active Conductor 与 Synapse

Pi CLI 是一个经过验证的 Synapseinform/after_turn后端，使用完全相同的 Pi 项目会话 ID。它不宣称实时的 checkpointredirect或强replace能力。

运行期间，一个独占的只读观察者会中继当前运行时/模型、效率保证、有界 Discover 目标、依赖/并行级别、首个被调度的 AC、注意力与终态保证；主会话保持可用，并按语义选择相关 AC，而不是向用户索要 ID。英语是规范指令语言，宿主按当前会话语言自然渲染 UX。

进一步验证：从测试看契约边界

如果你希望深入本运行时的实现边界，tests/unit/orchestrator/test_pi_runtime.py 是最直接的入口，其中与本文对应的关键用例包括：

• test_build_command_uses_documented_json_prompt_argument：任务提示词以位置参数而非 stdin 传递（Pi JSON 模式文档化的契约）；
• test_capabilities_follow_probed_native_param_support/test_capabilities_preserve_positive_and_empty_tool_authority_independently：能力声明跟随--help探测结果，且"非空白名单"与"空列表强制"两项工具权威独立保留；
• test_no_tools_only_capability_changes_durable_execution_fingerprint：只有--no-tools的 CLI 会改变持久执行指纹；
• test_execute_task_dispatches_ooo_skill_before_spawning_pi：技能分发先于 Pi 子进程发生；
• test_execute_task_tools_none_omits_all_tool_flags：tools=None时省略所有工具 flag（"用默认"语义）；
• test_execute_task_streams_delta_and_final_result/test_agent_end_does_not_mask_nonzero_exit/test_agent_stop_reason_error_overrides_zero_exit：事件流解析与"退出码不能掩盖错误"的两条防御路径。

小结

Pi 运行时集成的核心是三条清晰边界：Ouroboros 拥有工作流与分发逻辑，只依赖 Pi 的 JSON 模式子进程契约（含一次性的--help参数探测与tools=[]安全边界）；Pi 拥有自己的设置、包、扩展与鉴权，其内部定制对 Ouroboros 是透明但允许的；ooo双向打通则分别靠 Ouroboros 侧的SkillInterceptor与 Pi 侧 setup 安装的 bridge 扩展实现。按"前置条件 →ouroboros setup --runtime pi→ worktree 中验证产物"的顺序操作，并用OUROBOROS_EXECUTION_MODEL固定模型，即可得到一条可复现的 Pi 运行时执行链路。

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具