pi-subagents
为 pi 带来类 Claude Code 的子代理与工作流编排：并行执行、实时小组件、Fleet 视图、自定义代理类型和可动态调整的工作流。
证据显示：扩展在用户本地权限下运行，SECURITY.md 明确说明子代理与用户同权限，无沙箱，且提示用户自行监控或容器化。工具限制（denylist、allowed_subagents）存在，但默认未启用，且用户确认机制（如停止代理需二次确认）仅部分场景。数据流透明度：README 详细描述了会话持久化、事件总线、RPC，但未明确说明数据流向何处（如是否上传）。敏感数据处理：未发现专门处理敏感数据的机制，但 SECURITY.md 将凭据泄露列为范围外。依赖安全：依赖列表简单，peerDependencies 有版本范围，CI 有兼容性测试，但未提供依赖漏洞扫描证据。外部影响：扩展会执行命令、写文件，但均在用户授权下，且 SECURITY.md 明确边界。回滚：会话恢复功能存在，但无显式回滚机制。来源归属：代码和文档明确归属 tintinweb，但发布者未验证。扣分原因：用户确认机制不全面，敏感数据处理缺乏专门措施，回滚机制不明确。
证据显示：README 与代码注释一致，测试覆盖了关键模块（如 abortable），CI 运行 lint、typecheck、test。依赖可用性：peerDependencies 声明了 pi 版本范围，CI 有兼容性测试，但未验证实际运行。失败消息：代码注释和测试表明有错误处理，但未提供用户可见的失败消息示例。扣分原因：静态审查无法验证运行时行为，失败消息的具体内容未在文档中展示。
证据显示：README 详细描述了多种使用场景（并行代理、工作流、调度等），并提供了配置选项。能力边界：文档明确说明了工具限制、嵌套子代理的深度限制、调度限制等。触发精度：@提及语法有明确规则，避免误触发。环境适配：支持 pi 0.84.0+，并有第三方适配器报告，但未测试。扣分原因：第三方适配器未经验证，环境适配仅基于文档声明。
证据显示：README 结构清晰，包含功能、安装、快速开始、UI 等章节。安装说明明确，提供了 npm 和开发模式。命名稳定：工具名称和配置项在文档中一致。示例和 FAQ：README 提供了多个示例，但无 FAQ 部分。已知限制：SECURITY.md 和 README 中提及了部分限制（如 headless 模式不等待调度）。许可证：MIT 许可证文件存在。版本变更日志：package.json 有版本号，但无 CHANGELOG 文件。维护责任：代码和文档显示活跃维护，但发布者未验证。扣分原因：无 FAQ 部分，无 CHANGELOG 文件。
证据显示：输出可用性：代理结果以通知和可展开形式呈现，支持 Markdown。边际价值：提供了 Claude Code 风格的功能，可能对 pi 用户有价值。成本效益：文档提到 token 计数和上下文窗口利用率，但未提供性能基准。扣分原因：静态审查无法评估实际效果，成本效益缺乏数据支持。
证据显示：README 中的功能描述与代码注释和测试一致，但未提供外部验证。跨来源佐证：无第三方独立验证。事实与推断分离：文档区分了功能描述和设计决策（如注释中的解释）。扣分原因：缺乏外部验证，部分声明（如第三方适配器）未证实。
- 子代理与用户同权限运行，无沙箱，需在可信环境中使用或自行容器化。
- 用户确认机制不全面，部分操作（如停止代理）需二次确认，但其他高风险操作可能无确认。
- 敏感数据处理缺乏专门措施，SECURITY.md 将凭据泄露列为范围外，需用户自行保护。
- 依赖安全未提供漏洞扫描证据，建议定期检查依赖。
- 发布者身份未验证，需谨慎评估信任。
这个 Agent 能做什么，适合哪些场景？
pi-subagents 是一个 pi 扩展，它向 pi 添加了受 Claude Code 启发的自主子代理和工作流编排。它允许用户生成在隔离会话中运行的专业代理，每个代理都有各自的工具、系统提示、模型和思考级别。代理默认在后台运行，支持并行执行，并可通过实时小组件和 FleetView 进行监控。该扩展支持自定义代理类型、运行中调整、会话恢复、优雅的轮次限制，以及一个名为 SubagentWorkflow 的确定性脚本化工作流工具。它需要 pi 0.84.0 或更高版本，并作为 npm 包安装。该扩展还包含用于持久代理内存、git worktree 隔离、技能预加载和跨扩展 RPC 的功能。
该扩展提供 Agent 工具，用于启动子代理，并支持 prompt、subagent_type 和 run_in_background 等参数。agents 在隔离会话中运行，具有自己的工具和模型。Agent 类型在 .pi/agents/ 下的 Markdown 文件中定义，包含 YAML frontmatter，用于指定工具、模型、思维和工具限制。交互式 /agents 菜单用于管理正在运行的代理、代理类型、计划任务和工作流。它提供了运行代理的实时小组件和 FleetView，并支持通过 @mention 与代理通信。SubagentWorkflow 工具通过确定性 JavaScript 脚本编排多个代理，该脚本使用 agent()、parallel() 和 pipeline() 等函数，在 node:vm 沙箱中执行。它支持时间表（cron、interval、one-shot）、从磁盘恢复会话，以及可配置的并发限制。完成的通知包含结果预览和结构化 XML。
- 需要以受控方式并行执行代码库探索、计划或重构等多个任务的开发人员，每个任务都有自己的模型和工具。
- 希望使用为代码审查、测试或审计设计的预定义专业代理（如 Explore、Plan、auditor）的 pi 用户，可通过简单的 /agents 菜单定制或创建自定义代理。
- 需要一个确定性、可重现的工作流来协调多个子代理的组织，例如两阶段安全审计，使用保存的脚本即可反复执行。
- 希望运行长时间后台代理（如每周代码审查）并安排其自动执行的开发团队，可通过 cron 或 interval 语法配置，成功后会收到通知。
- 需要在长会话期间控制和监控多个子代理的用户，并可通过实时 FleetView、对话查看器和 @mention 调整或停止它们。
- 希望通过运行中的实时工作流图、代理的对话视图以及暂停、跳过或重试单个代理的能力，获得高度可观测并行执行的开发者。
这个 Agent 有哪些优点和局限？
- 提供比零散的自定义脚本更完整的子代理抽象和能力，具有简洁的设计，借鉴了 Claude Code 的 Agent 工具和约定。
- 包含一个丰富的功能集，包括并行执行、计划任务、工作流脚本、@mentions、自定义 agent 类型和持久记忆，全部统一在一个包中。
- 提供全面的实时监控和交互：实时小组件、FleetView、对话查看器，以及运行中调整和停止功能，让用户拥有高度透明度和控制力。
- 支持可通过上下文继承或强制克隆父上下文启动的 agent，可自定义 agent 类型，并且可在项目或全局范围内进行自定义。
- 这是一个专用于 pi 的扩展；离开 pi 生态无法使用，需要特定的运行时和 UI 才能操作。
- 需要 pi 0.84.0 或更高版本，这可能要求升级现有安装以达到兼容性。
- 功能集的学习曲线较陡峭，有许多工具、设置和配置，需要阅读文档才能掌握。
- 虽然支持与其他 agent framework 的适配，但兼容性未经过完全测试，不受本项目维护，存在与上游 pi 版本一起变化的风险。
如何安装或部署这个 Agent？
确保 pi 版本不低于 0.84.0。通过命令 pi install npm:@tintinweb/pi-subagents 进行安装。如需开发环境，可使用 pi -e ./src/index.ts 运行。
如何使用这个 Agent？
安装后，子代理通过 Agent 工具启动。例如 Agent({subagent_type: "Explore", prompt: "Find all files that handle authentication", description: "Find auth files", run_in_background: true})。代理运行在后台，完成时会收到通知。在前台运行以获取内联结果：设置 run_in_background: false。通过在与 /agents 菜单中的配置相对应的 .pi/agents/ 或 .agents/agents/ 目录中创建 Markdown 文件，定义自定义代理类型。使用 @type handle 与运行中的代理交互。要运行一个工作流，请在 SubagentWorkflow 工具中使用脚本调用，或通过 /agents → Workflows 调用，并使用 --subagents-workflow-file=<path> 作为 CLI 参数。
这个 Agent 与同类方案有什么区别？
该扩展明确将自己的功能与 Claude Code 进行比较，表示支持“相同的工具名称、调用约定和 UI 模式”，目标是让使用 Claude Code 的用户能够熟悉使用。因此，自然可以将其与 Claude Code 的 Agent 工具和 Workflow 工具进行对比。