Ouroboros Pi Runtime 集成指南：把 Pi CLI 变成可选择的 Agent 执行运行时

AI Agent人工智能代码智能体Agent 编排AI 评测CLI开发工具【免费下载链接】ouroborosAgent OS: the agent gets smarter on its own. We just hold the line: Interview-gated, staged evaluation, budgeted evolution loop. MCP server, 14 runtimes: Claude Code, Codex CLI, Gemini CLI, OpenCode, Copilot, Kiro and more.项目地址https://gitcode.com/gh_mirrors/ouroboros13/ouroboros点击查看免费下载本文基于 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 adapterOuroboros 自己拥有工作流引擎、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选中构造。前置条件要求原因piCLI提供方运行时安装 Pi 并保持pi在PATH上或配置显式路径Pi auth首次使用前先跑一遍 Pi 的提供方登录流程Ouroboros 基础包pip install ouroboros-ai一个容易踩坑的点对于 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_commandpi --mode json [--model MODEL] [--session SESSION_ID] [--append-system-prompt SYSTEM] [--tools TOOLS] [--no-tools] PROMPT参数作用--mode json请求 Pi 的无头 JSONL 事件流--model可选的模型覆盖由调用方传入--session可选的 Pi 原生 session id用于定向恢复resume源码中要求匹配^[A-Za-z0-9_-]$不合法直接抛ValueError防止参数注入--append-system-promptsystem_prompt参数的原生投递追加到 Pi 的基础编码提示词--tools原生工具白名单Pi 自身 flag 只启用列出的工具。Claude 风格命名Read、Bash、Glob、…会被映射为 Pi 的小写内建工具read、bash、find、…未知名称原样透传给扩展工具--no-tools显式无工具模式当 Ouroboros 请求tools[]时发出。用于区分用默认toolsNone省略 flag与禁用所有工具PROMPTOuroboros 组装好的任务提示词工具名映射表映射逻辑集中在 _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 --help10 秒超时在输出中分别查找--append-system-prompt、--tools、--no-tools三个子串并各自独立保留探测结果。这样能力协商就能区分一个有工具能力但缺少成对参数路径的旧版 CLI与一个全新的支持全部三个 flag 的 CLI。两个关键行为降级为translated只有当--append-system-prompt与--tools同时可用时系统提示词与非空工具白名单才走原生投递否则这两个参数会被拼进用户消息## System Instructions/## Tooling Guidance段落并在能力契约中报告为translated。--no-tools单独谈判空列表强制能力被单独暴露为empty_tool_restriction_support并纳入持久的运行时能力契约。因此一个只有--no-tools的 Pi 二进制与一个无法禁用工具的 Pi 二进制具有不同的谈判 执行语义指纹。tools[]是一条安全边界。execute_task 中的处理是如果请求tools[]而本机 Pi 不支持--no-toolsOuroboros 在拉起 Pi之前就返回ToolRestrictionUnenforced错误error_type: ToolRestrictionUnenforcedeffective: unrestricted而不是把空列表悄悄放宽为不受限的默认工具集——因为任何提示词层面的翻译都无法让不受限的 Pi 默认等价于显式无工具。相关能力声明见 PiRuntime.capabilitiesskill_dispatchTrue、targeted_resumeTrue经由--session、structured_outputTrue以及基于探测结果的system_prompt_support/tool_restriction_support/empty_tool_restriction_support。JSONL 事件流解析Pi JSON 模式的事件生命周期见 PiRuntime 类文档首行session头事件{type:session,id:uuid,...}被解析进RuntimeHandlebackendpi、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_contentagent_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拉起 Ouroborosouroboros setup --runtime pi同时安装一个托管的全局 Pi 扩展~/.pi/agent/extensions/ouroboros-ooo-bridge.tsPi 会从该目录自动加载扩展。重启 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 还有三个值得注意的行为细节不支持分发时确定性回落bridge 只消费隐藏分发器能通过 MCP 支持的技能 frontmatter 执行的命令。像ooo help或裸ooo这类没有声明 MCP 分发目标的一方快捷键会以确定性的不支持分发退出码返回给 Pi让普通 Pi 会话继续处理输入而不是让 bridge 硬失败。TAB 参数补全注册的/ooo命令通过 Pi 原生getArgumentCompletions面提供补全/ooo TAB列出带一行描述的可分发子命令ooo run TAB把~/.ouroboros/seeds/中的 Seed 文件以绝对存储路径列出用 POSIX 单引号包裹并处理内嵌单引号使补全值无论 Pi 会话目录在哪都能执行相对 seed 路径是相对会话 cwd 解析的。补全是确定性且离线完成的子命令清单镜像分发器自己判定合格的技能集合单元测试通过resolve_skill_dispatch派生该集合保证两处不会漂移。含空白的 Seed 名被跳过因为分发器按空白 token 化命令。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 的参与ouroboros auto --runtime pi ...Interview、Seed 生成、Seed QA 以及运行交接为 Pi 运行时启动执行交接最终产物可能仍为 pendingPi 的模型选择默认来自 Pi 自己的默认值除非执行路径传入模型覆盖。为了可复现的冒烟测试指南建议export OUROBOROS_EXECUTION_MODELopenai-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-piOuroboros 拉起的 Pi 子进程会通过 Pi 正常的扩展加载器加载它。这与roach-pi 是 Ouroboros 运行时适配器是两回事场景合同Ouroboros 拉起pi --mode json受支持的 Pi 运行时时路径Pi 在该进程中加载已安装的包/扩展Pi 允许Pi 运行可见包添加 Pi 模型轮次使用的、兼容无头模式的工具/hook可能工作因为它跑在 Pi 内部包添加交互式 slash 命令或 UI 提示在普通交互式 Pi 中可用在 Ouroboros 拉起的 JSON 模式下不保证交互式 Pi/roach-pi 用户在 setup 安装 bridge 后输入ooo ...通过托管 Pi 扩展支持roach-pi本身成为可选的 Ouroboros 运行时后端否那需要一个专属适配器或 bridge一句话总结runtime_backend: pi选择 Pi CLI 作为执行引擎。定制的 Pi 发行版可以影响该 Pi 进程内部发生的事情但 Ouroboros 在运行时执行上只依赖 Pi 的 JSON 模式子进程契约在交互式ooobridge 上只依赖 Pi 文档化的全局扩展加载器。Pi 作为 LLM 后端与运行时后端相互独立除了orchestrator.runtime_backendPi 还可以被选为创作、打分、抽取等补全流程的 LLM 后端llm: backend: pi这两者是彼此独立的配置面。源码中由 PiLLMAdapter 实现——它复用了 Codex CLI 适配器的子进程基础同一 JSONL 事件流家族但作为纯 LLM provider 暴露供 interview/planning/evaluation 等角色选择--llm-backend pi。关于结构化输出Pi LLM 适配器通过软强制支持response_formatOuroboros 注入严格的 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 --mode json技能快捷键分发支持在拉起 Pi 之前原生定向恢复支持经由--session id结构化事件流支持JSONL 由PiRuntime解析作为 LLM 后端的结构化 schema 响应软强制 校验Pi 扩展加载Pi 自有在兼容无头 JSON 模式时可用交互式 Piooo前门支持经由 setup 安装的托管扩展故障排查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 与 SynapsePi 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_flagstoolsNone时省略所有工具 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开发工具【免费下载链接】ouroborosAgent OS: the agent gets smarter on its own. We just hold the line: Interview-gated, staged evaluation, budgeted evolution loop. MCP server, 14 runtimes: Claude Code, Codex CLI, Gemini CLI, OpenCode, Copilot, Kiro and more.项目地址https://gitcode.com/gh_mirrors/ouroboros13/ouroboros点击查看免费下载相关推荐pi Coding Agent SDK 完全指南从 createAgentSession 到运行时替换的编程式集成pi Coding Agent SDK 完全指南从 createAgentSession 到运行时替换的编程式集成 本文以 SDK 示例文档 https://人工智能大模型AI Agent代码智能体AI 应用工具调用用 Feature List 约束 Agent 行为把 Harness 的完成标准变成可执行数据用 Feature List 约束 Agent 行为把 Harness 的完成标准变成可执行数据 本文是 learn harness engineerinPostHog 摄入警告 cannot_merge_already_identified 全解析为什么 identify/alias 被静默拒绝合并以及如何修复PostHog 摄入警告 cannot_merge_already_identified 全解析为什么 identify/alias 被静默拒绝合并以及如何AI Agent人工智能代码智能体Agent 编排AI 评测CLI开发工具上一篇WandEnhancer高效解锁WeMod专业版功能的终极解决方案下一篇如何用PyWxDump解密并导出微信聊天记录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考