pi-runner

Pi Runner

先使用 shared/references/model-preview.md 选择分支。确定性检查无需选择模型。实际调度使用一个具体且已批准的快照；嵌套调用会沿用该快照，不会重新解析或启动额外工作线程。

通过 Pi (pi) 以非交互模式执行提示词。严格的请求控制使用带启动握手的 RPC；旧版调用保留打印模式。每次调用都通过 --provider 和 --model 固定网关和模型，或通过 --seat 选择一个中央命名席位。凭据来自网关环境或 Pi 身份验证存储。精确的模型选择不会限制推理时的提供商回退；请通过 --provider-routing 传递这项独立策略。

原生路由

选择外部路由前，请阅读 shared/references/host-model-execution.md。如果当前宿主可以在原生子 Agent 或任务线程中，按要求的推理力度、隔离和回执策略调度所选的精确提供商模型，请使用该路由。宿主技能描述符不会调度原生模型。

命名席位

命名席位及其精确模型 ID 位于 shared/model-routing.json 中。 --seat 会读取这些固定配置以进行直接选择，并为信封添加标签。工作流 调度使用已批准快照中的显式 --provider、--model、推理力度和策略， 不会再次解析席位固定配置。如果存在已批准计划，显式指定的 --model 必须与其匹配。只能在中央文件中更改维护中的固定配置。如果 CLI 或密钥缺失， 则报告 status: seat_unavailable；不会回退到其他席位。

网关和能力

中央运行器配置会选择默认网关。OpenRouter 使用 OPENROUTER_API_KEY 或 Pi 的身份验证存储。使用 --provider 可显式 选择网关。若模型 ID 不在捆绑目录中，则需要经过验证的能力元数据；仅传入该字符串并不能证明模型可访问、支持图像、工具或推理力度控制。

从中央模型条目读取支持的推理力度和运行时推理力度。明确传入 所选的可控推理力度。GLM 接受 low、high 和 max； 省略该值或传入无法识别的原生值可能会选择 max。应拒绝不支持的 值，而不是将通用的 medium 或 xhigh 映射到它。对于不支持 可选推理力度的模型，保留运行时可控的推理力度，不要虚构 级别。使用新路由前，先捕获序列化设置。

提供商请求策略

经批准的 provider_routing 对象会通过 --provider-routing 以紧凑 JSON 的形式传入。对于严格的 OpenRouter 路由，该对象包含 gateway: openrouter、zdr: true、data_collection: deny 和 require_parameters: true。对于选定的推理提供商允许列表，请包含 only；如果计划有要求，还要包含 allow_fallbacks。 在已批准集合内切换提供商，与切换到其他模型是两回事。切勿移除隐私控制来恢复可用性。严格调用会独立于模型注册表绑定网关 URL。指向其他 URL 的提供商标签会在任务内容释放前遭到拒绝。

如果某个席位的模型条目在选定网关上有经验证的隐私标记（shared/model-routing.json 中的 zdr_available: true），那么省略 --provider-routing 时，默认使用中央的 profile_policy.provider_routing；显式策略仍会在每次调用时优先生效。中央策略仅固定隐私控制。网关会在其零数据保留端点中进行选择，不会固定推理提供商。

请使用配置限定于本次运行的打包请求强制执行路径。它必须在每次初始请求、工具请求、修复请求和恢复请求中保留完全相同的选定策略。应禁用无关的扩展发现；不要依赖可变的全局模型注册表。若缺少强制执行机制或网关错误，则会在发送仓库内容前阻止严格路由。仅有源代码共享元数据并不代表请求策略已得到强制执行。

严格执行要求使用运行时适配器声明的最低稳定版 Pi 或更新的稳定版本。请求钩子必须在发送任务内容前确认就绪。已安装的运行时会在请求钩子之外压缩会话，因此严格运行会在压缩前停止，并等待 settled 事件后才接受完成结果。上下文用尽时，必须使用经批准的新上下文数据包；不得通过未受保护的请求静默生成摘要。

仅在观察到请求强制执行后，才保留包含 status: enforced、gateway、 policy_sha256 和正数 request_count 的 provider_policy_receipt。捕获合成的本地请求，以验证确切的模型、推理设置、提供商控制、工具和图像载荷，同时不记录源代码或密钥。缺少回执无法证明严格路由已被接受。省略策略时，仅对没有经验证隐私标记的模型保留旧版行为，且不能将其报告为严格隐私。

先决条件

• 已安装 pi CLI，且已在 PATH 中；未安装属于准备工作缺失，不代表可以进行全局安装
• 环境中提供服务的提供商 API 密钥（默认提供商使用 OPENROUTER_API_KEY）

隔离运行

每次运行都会禁用无关的扩展、技能、提示词模板、主题和项目指令发现。针对所选策略显式打包的请求钩子是受控例外。请显式传入角色简介、允许访问的文件、驱动程序指令和图像工件。启用工具时，工具读取和允许的附件都可能扩展输入；不要将提示词描述为完整输入。

工具模式

• act（写入角色、--allow-write 或未指定角色）：Pi 的完整内置工具集（读取、bash、编辑、写入）。
• restricted（--restrict-tools，分析角色的默认模式）：仅启用文件读取工具。此模式下没有搜索工具，也没有只读 Shell。
• no_tools（--no-tools）：原生禁用工具；席位根据提供的输入作答。轮询模式的议会席位使用此模式。
• browser（--tool-policy browser）：为选定的驱动程序提供文件／图像读取和 Shell 访问权限。请传入 --browser-mechanism playwright-cli 或 agent-browser，并通过 --browser-preflight <file> 提供捕获的就绪状态证据。Shell 访问权限不会强制执行仅限浏览器的沙箱，也不会授权修复产品。

外部 Pi 工作进程不会继承主机的浏览器工具。进行视觉工作前，请通过适配器使用合成图像，预先验证模型的图像支持、驱动程序的产物路径以及类型化图像内容。显式附加文件时使用 --image-file <path>；允许多张图像时可重复使用该参数。文本中的屏幕截图路径不足以满足要求。 每个流程只使用一个驱动程序，每个角色使用一个隔离会话。缺少驱动程序、工具、图像或隐私能力时，该路径不可用。

共享封装器参考

支持的选项、角色、--json 封装和返回码见 shared/references/runner-common.md。封装会报告 runner=pi 或席位名称，以及 effective_runner=pi。model_author 描述供应商；gateway 描述 API 路由。inference_provider 需要实际的上游证据；没有证据时保持未知。旧版 effective_provider 供应商字段无法标识推理主机。终端 native_model_id 可生成客户端报告的模型回执，但这并非推理供应商的独立证明。请将请求策略回执与模型回执分开。

用法

从已加载的技能中解析 SKILL_DIR，并从运行快照中复制精确选项。对于可选择推理力度的模型：

SKILL_DIR="<absolute path of this skill directory>";
python3 "$SKILL_DIR/scripts/run_pi.py" --prompt-file <role-brief.md> \
  --provider <approved-gateway> \
  --model <approved-model-id> --thinking <selected-effort> \
  --session <unique-role-session-file> \
  --provider-routing '<approved-provider-routing-json>' --disable-fallback --json

对于由运行时控制推理力度的模型，请使用所选模型支持的运行时路径；不要自行编造 high 值。仅当所选路由没有供应商策略时才省略 --provider-routing；具有已验证隐私限制的席位默认应用中央严格策略。对于仅提供简报的角色，请使用 --no-tools；对于文件或浏览器工作，请使用明确选定的工具策略。

注意事项

• 缺少凭据时退出码为 0。 如果所选供应商没有密钥，pi 会打印“Use /login ...”提示并正常退出，但不会生成 Agent 事件。封装器会检测到这一情况，并报告 success: false、status: auth_missing、auth_ok: false——切勿相信 Pi 单独返回的退出码。
• 没有原生架构切换。 --output-schema 会将契约附加到提示词中，并在本地强制执行：如果最终答案不完全是一个符合架构的 JSON 值，运行会以 status: malformed_output 失败。
• 增量流经过压缩。 Pi 的 --mode json 会为每个 token 输出 message_update 行；封装器会从存储的 stdout 中移除这些行，并保留终端事件。这些事件包含完整消息和服务回执（供应商、模型、用量、stopReason）。请读取 agent_message，而非 stdout。
• 没有原生超时标记。 封装器的 --timeout 会在子进程层面强制执行；超时时报告 return_code -1。
• 会话恢复使用原生 --session <id|path>；--no-session-persistence／--ephemeral 会映射为原生 --no-session。Pi 的 --mode json 流不会公布会话 ID，因此封装中的 session_id 仅反映调用方传入的值。

按需加载

• references/continuation.md：当角色需要再进行一轮 Pi 调用，或工作流需要文本交接时使用。