English | 简体中文

Pi Smart Subagents

在 Pi 中运行独立子代理和托管 shell 命令。子代理模型由 Jev 选择；普通命令任务直接使用现有的 bash 工具，不调用模型选择器。

本项目是 Luke Parke 的 @parke.dev/pi-subagent 的独立社区分支，上游来自 LukasParke/pi-extensions。保留命名代理、并行与后台任务、工作树隔离和用量统计，增加 Jev 模型路由与子代理能力检查。

安装

需要 Node.js 22.19.0 或更高版本及 Pi。不要同时启用本分支和 @parke.dev/pi-subagent，两者会注册相同的工具。

pi install npm:@cr1ms0n/pi-subagent

首次使用子代理前，在 ~/.pi/subagent.json 中配置 TypeSafe API key 和候选模型。参阅配置示例，妥善保管凭据；已有配置时，请合并修改，不要直接覆盖。

独立的 task 工具需要 Pi 1.2.0+ 和可调用的 bash，不需要 Jev 配置。本包包含两个扩展入口，也支持分别加载。

命令任务

在当前目录运行非交互式构建、命令或脚本时，使用 task：

{ "command": "npm run build" }

默认最多等待 30 秒，然后返回同一个 task ID，原命令继续在后台执行。设置 "background": true 可立即返回回执，timeout_ms 可调整本次等待时间。原生 bash.timeout 仍然是硬性停止期限。

保留完整 task ID，通过 list、status、output、wait 和 cancel 管理。日志保留在配置的会话目录下，输出支持可重复读取的 UTF-8 字节游标。后台完成时通知所属会话，除非关闭了通知。退出、重新加载、分支或会话替换会请求取消；任务不是持久守护进程。详见命令任务示例与限制。

子代理使用

直接对 Pi 说，例如：

用只读子代理查看这个项目的目录结构，并总结主要模块。

Jev 选择模型，不逐个选择工具。本地策略控制允许的工具集，启动时检查子代理实际可用的能力。显式请求的工具必须可用，详细规则见工具策略与路由参考。

默认的 compact（精简） 模式保留常规委派、并行与后台任务、预算和工作树管理。如需恢复会话、汇总、结构化输出等高级请求参数，请将以下字段合并到 ~/.pi/subagent.json，等活动任务结束后重新加载或重启 Pi：

{ "toolMode": "full" }

参数划分和升级行为见工具模式说明。

子代理的 timeout_ms 是提醒阈值，不再是停止期限。达到阈值时，前台调用返回 run ID，同一任务继续在后台执行。通过 status、wait、steer 或 cancel 决定下一步。已有时间设置也改为此提醒语义；轮数、费用预算和独立故障检查仍保留。详见预算与重试说明。

本包启动的每个子代理都会自动收到一条包内置的强制规则：不得运行测试或测试命令，也不得创建或修改测试代码。子代理只做实现和静态审查，并如实说明未测试的部分；可执行的测试工作只归顶层主代理（TOP-LEVEL main agent），任何子代理都不拥有测试权，中间层委派代理同样是子代理。日志和备份在既有任务范围与工具权限内仍然允许。这是提示词层面的指令，不是沙箱；它只对更新后的包代码加载之后新启动的子代理生效，不追溯已运行的子代理，也不覆盖独立启动或自定义后端的进程。详见委派测试边界。

• 使用 /subagents 查看和管理子代理运行。
• 使用 /subagent-cost 查看用量。
• 命名代理、并行任务、后台执行、工作树和结构化结果见使用参考，键盘操作见 TUI 指南。

模型执行与 Jev 选择可能分别产生费用。规划操作也会调用 Jev；max_cost 不限制 TypeSafe 选择器费用。详见费用统计说明。

路由会向选择器发送任务文本和候选模型信息。仅将 jevRouting.baseUrl 设置为受信任的端点，因为它会改变路由数据和路由凭据的接收方。详见安全说明。

许可证

MIT。Copyright (c) 2026 Luke Parke。社区分支由 cr1ms0n（awoaCrim）维护。重新分发时请保留原始版权声明和许可证。

译自 README.md，英文文件 blob：2bdbbd761b0f180eb910a268534dcafffbde2989。中英文内容如有差异，以英文为准。

感谢 Linux.do。