Skip to content

rycen7822/subagent-pi

v0.7.0MIT

Persistent Pi coding subagents for Codex: bounded inspection, steering, interruption and recovery through MCP and CLI.

GitHub

Subagent Pi — Codex 插件

Subagent Pi

MCP + 极薄 Skill + CLI + 一个持久化运行时。无 hooks。

让 Codex 把本地 Pi coding agent 当成可控制的外部子代理：异步启动、任务内消息和后续工作、检查工作轨迹、中断、卸载、恢复会话、收取结果。

这是完整源码版 0.7.0，针对 Linux / WSL2 / Windows 原生，Python 3.11+。运行时使用 Python 标准库、Node.js 22.19+ 和已安装 Pi ≥0.99.1 的 SDK，无额外 pip/npm 构建依赖；Pi 和 Codex 需要你已自行安装。它不进入 Codex 原生 /agents；父代理唤醒使用 Codex 官方消息队列，无需 hooks，适用范围见下文。

受管子进程使用原版 Pi 的公开 SDK，无需修改 Pi；版本证据和测试边界见 测试指南。主代理使用 V2 风格的消息、后续任务和软中断操作；中断通常保留进程，无法确认整个任务退出时核验并终止进程组或 Windows Job。空闲进程默认 30 分钟后自动卸载，session 和结果保留。详见 操作语义。

受管子代理加载 Pi 自身的全局/项目 extensions、packages、skills、prompt templates、themes 与 settings（SDK 的 settings 更新仅在子进程内存中保存）；ambient_extensions/ambient_skills 默认 true。上下文文件单独处理：保留 Pi 配置目录的全局 AGENTS.md，不加载子代理工作目录及其父目录的 AGENTS.md；改为读取打开 scope 的 Codex 工作目录下的 SUBAGENT-PI.md。新建与 respawn 时重新读取，即使子代理在另一个 cwd 执行也一样。Pi 配置目录沿用打开 scope 的客户端进程里的 PI_CODING_AGENT_DIR（未设置即 Pi 默认 $HOME/.pi/agent，跨 daemon 重启保持）。在此之上按需继承 Codex 全局 skills（~/.codex/skills）与 MCP（~/.codex/config.toml 的 mcp_servers）；普通 pi 不受影响。

同名 skills 由 Pi 自己在加载边界裁决：Pi 已加载的同名 skill 保留，Codex 版本不会被注册；每次 boot 都会把结果记进 inheritance_skills 事件（跳过的 Codex 路径 + 保留的 Pi 路径）。MCP 不按 server 名去重，因为 Pi 没有 MCP 体系、也不提供 server 注册表（只保证 (server, tool) 寻址：不同 server 的同名工具互不冲突）。access=read 只约束本插件控制的 builtin 与 MCP 暴露面，不声称"只具备只读工具"、也不是 OS 沙箱。详见 docs/inheritance.md。

安装

在 WSL/Linux 终端中解压，再执行：

cd subagent-pi
python3 --version
command -v pi
command -v codex
python3 scripts/install.py --pi "$(command -v pi)" --register
export PATH="$HOME/.local/bin:$PATH"
subagent-pi doctor

Windows PowerShell（安装 Node、Python、官方 npm 版 Pi 和 Codex 后）：

python scripts/install.py --pi (Get-Command pi.cmd).Source --register
$env:Path = "$HOME\.local\bin;$env:Path"
subagent-pi.cmd doctor

Windows 的 Codex、插件和 Pi 均原生运行；Pi 默认使用 Git Bash，也可配置 PowerShell 工具。安装、启动器和兼容边界见 入门指南。

然后在 Codex 输入 /plugins，从 Subagent Pi Local 安装 Subagent Pi，并开始一个新会话。脚本注册的是本地 marketplace，不会替你点击插件安装或授权。

安装脚本不直接改写 ~/.codex/config.toml，不修改 ~/.pi，也不安装任何 hooks。--register 仅调用你现有的 codex plugin marketplace add。不支持该命令的版本可采用 docs/getting-started.md 的 MCP+Skill 手动回退方式。

建议在项目目录中启动：

cd /absolute/path/to/project
subagent-pi codex

该可选启动器为本次工作创建 scope，并通过环境变量交给 MCP；也支持 subagent-pi codex -C /absolute/path/to/project。普通 Codex 会话可直接首次调用 pi_spawn_agent(cwd=实际工作区绝对路径, ...)，打开并绑定 scope；后续可省略 scope。显式 scope 用于恢复或选择另一份账本，不替换连接默认值。子代理 cwd 可不同于 scope 目录；worktree 绑定、升级和缓存刷新见 入门指南。

已实现

能力方式
当前项目异步启动pi_spawn_agent / subagent-pi spawn，记录明确的绝对 cwd
消息 / 后续任务pi_send_message / pi_followup_task，支持 ID 或 scope 内唯一名称；活动输入使用原生 steering
空闲消息写入 Pi history，不启动模型；后续任务自动唤醒已卸载 session
等待一个或多个任务pi_wait_agent，默认 any 逐批接收，显式 all 等选中任务全部终态；携带就绪结果与 hash
检查工作轨迹pi_inspect_agent，有界输出、增量 cursor、控制回执
中断 / 卸载pi_interrupt_agent 取消任务并尽量保留进程；CLI close 显式清理进程组
恢复 / respawn保留 agent ID，增加 generation，重新加载已持久化 Pi session
防重复执行scope + request_id + 参数摘要，持久保存已完成回执
结果交接wait / result 成功写出后自动消费通知；结果文件与 hash 保留供复核
MCP / CLI 互通同一个 daemon、同一个 SQLite 账本
父代理自动唤醒完成、失败、停止、问题 → Codex 持久消息队列；list 返回启用/失败摘要，inspect(detail=full) 提供详情
子代理询问父代理模型 ask_parent 或扩展 UI 请求 → wait 返回问题 → pi_answer_agent 显式回答
推理等级spawn thinking 按所选 Pi 模型校验；省略则继承 Pi 设置
文档按需读取subagent-pi guide TOPIC --section SECTION

使用示例

直接对 Codex 说：

使用 Subagent Pi，在当前项目创建一个只读子代理检查缓存失效逻辑。继续你的其他工作，必要时读取增量轨迹；完成后读取结果再确认收尾。

日常 MCP 发现 9 个工具；context、close、respawn、legacy send 保留为显式管理调用和 CLI 操作。pi_send_message 活动时使用原生 steering，空闲时只写入 history；pi_followup_task 活动时加入同一 run，空闲时开始新 run。

CLI 对等示例：

# 未给 scope 时按 cwd 打开 scope；保存返回的 scope / agent_id / run_id。
subagent-pi spawn --cwd /absolute/path/to/project --access read --name cache-review \
  --task '检查缓存失效逻辑，只报告问题，不修改文件' --request-id cache-review-1

# 使用上一条返回的真实 ID：
subagent-pi inspect AGENT_ID --scope SCOPE_ID
# 活动任务中接入消息；若已空闲，此操作只保存消息。
subagent-pi send-message AGENT_ID --scope SCOPE_ID --message '优先检查索引刷新路径' --request-id cache-priority-1
subagent-pi wait RUN_ID --scope SCOPE_ID --timeout-seconds 3600
# wait 正文完整时直接审核；需补读时可按名称取当前/最近任务。
subagent-pi result --agent cache-review --scope SCOPE_ID
subagent-pi list --scope SCOPE_ID --query cache --limit 10

AGENT_ID 等是示意占位符，需替换为实际值；较大结果按 next_offset 分页。继续工作用 followup-task；取消当前任务用 interrupt；明确卸载用 close，闲置进程也会自动卸载。脚本调用可用 subagent-pi call OP --json - 从 stdin 传 JSON。重试复用相同 request_id 和参数。

重要边界

  • Pi worker 不继承 Codex 的沙箱或逐工具批准机制。 它使用当前 OS 用户和 Pi 自身权限。受管子代理默认加载 Pi 自身 extensions/skills（可用 profile 的 ambient_extensions/ambient_skills 显式关闭）；access=read 只把本插件控制的 builtin 限制为 read/grep/find/ls（由 extensions/managed-surface.ts 按 Pi 报告的来源应用、并回读验证后才算生效；扩展注册的同名工具不受影响）并收窄继承 MCP 的暴露面，Pi 自己的扩展、其工具与代码不受约束，因此这不是 OS 安全隔离。
  • 不安装 hooks。打开 scope（含 spawn 隐式打开）时从 Codex 调用元数据绑定父会话；任务结束或提问时，通过官方 codex queue 入队提醒。仍在运行且空闲的父会话会自动续跑，跨进程通常约 10 秒检查一次；忙碌时排队，不强制打断。没有父会话身份的客户端仍使用 wait。
  • MCP 进程退出不终止 Pi。daemon 崩溃后不能重新接回旧 stdin/stdout；先确认并关闭遗留进程，再显式恢复。
  • interrupt 等待整个受管任务退出；不合作的 SDK hook 可触发硬清理。close 和自动卸载核验受管进程组；主动脱离该组的后代不受绝对保证。清理状态 unknown 时拒绝自动恢复。
  • 同一或嵌套 cwd 只允许一个受管理 writer；不能阻止 Codex 主 agent、编辑器或其他进程同时改文件。
  • 没有自动重试已执行的 shell，没有自动 model fallback，没有工作流脚本引擎、自动 review、worktree 管理或 clone。
  • 内部 SQLite/原始 Pi session/结果可能含敏感代码和文本。目录为当前用户私有；这不是对同一用户的恶意进程的安全边界。

验证

python3 -m pip install -r tests/requirements.txt
python3 scripts/validate_package.py
python3 -m unittest discover -s tests -v

默认测试使用确定性受管子进程和本地 MCP 服务。设置 SUBAGENT_PI_LIVE_PI=1 可运行已安装 Pi SDK 的隔离进程测试，使用离线 mock provider。命令、版本和验证边界见 测试指南；离线通过不等于真实模型或 Codex 安装联调通过。

本机可进行一次明确会调用模型、可能消耗额度的实测：

python3 scripts/live_smoke.py --allow-model-call

文档

docs/getting-started.md：安装与首轮使用；lifecycle.md：操作语义；configuration.md：模型与配置；recovery.md：恢复；troubleshooting.md：诊断；cli.md：命令；architecture.md：实现；testing.md：测试；sources.md：协议和源码参考。