@nicht_tintin: 动态工作流程。现在适用于@pidotdev 的@tintinweb/pi-subagents 中。与@claudeai Code兼容。被严重低估。感谢…

动态工作流。现已在 @tintinweb/pi-subagents 中支持 @pidotdev ♥️。兼容 @claudeai Code。价值被严重低估。感谢您关注可脚本化代理编排的相关事宜 🦅 pi install npm:@tintinweb/pi-subagents https://t.co/P2b7Ml9BIY https://t.co/nyi7x117RR — # tintinweb/pi-subagents 来源: https://github.com/tintinweb/pi-subagents # @tintinweb/pi-subagents 一个为 pi (https://pi.dev) 带来 Claude Code 风格的自主子代理与工作流编排 的扩展。生成在隔离会话中运行的专业代理——每个代理都拥有独立的工具、系统提示、模型和思考级别。默认以后台方式运行，也可阻塞等待，中途引导，恢复已完成的会话，并定义您自己的自定义代理类型。当编排不应临时起意时，向 SubagentWorkflow 工具传递确定性 JavaScript 脚本——agent()、parallel()、pipeline()——为 Claude Code 的 Workflow 工具编写的脚本可在此处原样运行。 https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543 ## 功能特性 - Claude Code 风格 — 相同的工具名称、调用约定和 UI 模式（Agent、get_subagent_result、steer_subagent）——感觉原生 - 并行后台代理 — 启动多个并发运行的代理，支持自动排队（可配置并发限制，默认为 10）和智能组加入（合并通知） - 实时小组件 UI — 编辑器上方的持久性小组件，带有动画旋转器、实时工具活动、令牌计数和彩色状态图标。可通过 /agents → Settings → Widget 配置：all（每个代理）、background（默认——隐藏前台运行，因为前台运行已作为 Agent 工具结果内联渲染）或 off - FleetView — Claude Code 风格的可导航列表，显示 main + 每个正在运行的子代理，渲染在编辑器下方（最早启动的在前）。在空提示符处按 ↓（或 ←）跳转进入，↑/↓ 移动选择，Enter 打开所选代理的实时、自动更新对话，Esc 返回。已完成的代理会短暂保留后退出，查看器会一直保持打开状态直到完成，以便您阅读最终输出。通过 /agents → Settings → Fleet view 切换 - 对话查看器 — 在 /agents 中选择任何代理，打开其完整对话的实时滚动叠加层（自动跟随新内容，向上滚动暂停）。通过按 Enter 打开编辑器来内联引导运行中的代理，输入消息，然后按 Enter 发送（Esc 或空提交返回）——消息将作为用户消息出现，并在代理完成当前工具后重定向代理。通过按 x（再次按 x 确认）停止仍在运行的代理——两者对后台代理也有效。助手文本渲染为 Markdown；m 在关闭、仅助手和全部之间切换（参见 查看器标记） - 自定义代理类型 — 在 .pi/agents/.md 或 .agents/agents/.md（项目级）或全局定义代理，使用 YAML frontmatter：自定义系统提示、模型选择、思考级别、工具限制和 Claude Code 兼容的彩色名称徽章 - 嵌套子代理 — 选择性启用、默认关闭的委派：设置 allowed_subagents 的自定义代理将获得其自身作用域限定的 Agent、get_subagent_result 和 steer_subagent 工具，深度从主会话限制（默认 2）。它只能控制自己的子代理，子代理在其完成时停止，其转录和令牌消耗会汇总到它。允许列表是一个权限边界——子代理使用自己的工具运行，因此像选择 tools: 本身一样谨慎选择 - 代理提及 — 子代理是一等公民：在提示符处输入 @explore also check the RPC path，它会发送给该代理而不是主模型，而不会有一句话进入聊天。一种语法覆盖整个生命周期——运行时向其发送消息，在其完成后恢复它，很久之后从磁盘重新打开其会话，或者如果它从未运行则启动它。提及未运行的代理会通过对话的非屏幕克隆启动它，这样它会获得 Claude Code 的上下文写入提示和真实的 Agent 工具调用，而不会有内容进入聊天；direct 模式从您的文本直接启动，完全不进行模型调用。编排器可以为代理 name，因此您用 @auth-audit 来称呼它，并在 steer_subagent/get_subagent_result 中也处理工作。@ 完成活动代理、可恢复代理和可启动类型，与 pi 的文件补全并列；@main 强制文本返回主模型。通过 /agents → Settings → Agent mentions 切换 - 脚本化工作流 — 一个 SubagentWorkflow 工具，运行编排多个子代理的确定性 JavaScript 脚本：agent()、parallel()、pipeline()、phase()、log() 和 args，以及声明阶段的纯字面 meta 块。pipeline() 在阶段之间没有屏障，因此一个项目可以在后期阶段而另一个仍在第一阶段——不同于 parallel()，它会让每个快速代理空闲直到最慢的完成。在后台运行，带有实时卡片，可通过 /agents → Workflows 或在 FleetView 中选择运行来检查。agent() 还接受 gate: "npm test" 通过运行命令（在其工作树内，隔离时）来验证子代理，而不是请求另一个模型，以及 resume: "" 来继续子代理而不是重新支付其上下文。脚本在工作线程上的 node:vm 沙箱中运行，其中 Date.now()、Math.random() 和 eval 会抛出错误。默认开启，但在公司环境下会停用：如果另一个扩展已经提供了 Workflow 或 SubagentWorkflow 工具，这个会发出警告并在会话中禁用自身，而不是为模型提供两个编排器。通过 subagents.json 中的 "workflowsEnabled" 或 /agents → Settings → Workflows 固定它。为 Claude Code 的 Workflow 工具编写的脚本可在此处原样运行：相同的全局变量，schema 返回验证后的对象，budget 存在且总是报告无令牌目标（pi 没有此类指令），因此其 budget.total 守护模式仍然走它们被编写的分支，嵌套的 workflow() 一级深度组合保存的工作流。完整指南 (https://github.com/tintinweb/pi-subagents/blob/master/docs/workflows.md) - 运行中引导 — 向运行中的代理注入消息以重定向其工作，无需重启 - 会话恢复 — 从代理离开的地方继续，保留完整的对话上下文。默认脱离恢复并在完成时通知您，就像新启动一样；传递 run_in_background: false 以阻塞并内联获取结果 - 优雅的轮次限制 — 代理在硬中止前获得“收尾”警告，产生干净的局部结果而不是被截断的输出 - 不区分大小写的代理类型 — "explore"、"Explore"、"EXPLORE" 都有效。一个无法精确解析到一个启用的代理的类型——未知、已禁用或在仅大小写不同的两个代理之间模棱两可——会回退到通用并带有注释，或者在 fallbackSubagent: none 下被直接拒绝 - 模糊模型选择 — 通过名称（"haiku"、"sonnet"）而不是完整 ID 指定模型，并自动过滤为仅可用/已配置的模型 - 上下文继承 — 可选地将父对话分叉到子代理中，使其知道已讨论的内容 - 持久代理内存 — 三个范围（项目、本地、用户），对于没有写入工具的代理具有自动只读回退 - Git 工作树隔离 — 在隔离的仓库副本中运行代理；更改在完成时自动提交到分支 - 技能预加载 — 向代理系统提示注入命名技能，从 .pi/skills/、.agents/skills/ 和全局位置发现（支持 Pi 标准 /SKILL.md 目录布局） - 工具拒绝列表 — 通过 disallowed_tools frontmatter 阻止特定工具 - 样式化完成通知 — 后台代理结果显示为主题化、紧凑的通知框（图标、统计、结果预览）而不是原始 XML。可展开以显示完整输出。组完成逐个渲染每个代理 - 事件总线 — 生命周期事件（subagents:created、started、completed、failed、steered、compacted）通过 pi.events 发出，使其他扩展能够对子代理活动做出反应 - 跨扩展 RPC — 其他 pi 扩展可以通过 pi.events 事件总线（subagents:rpc:ping、subagents:rpc:spawn、subagents:rpc:stop、subagents:rpc:consume）启动、停止和加入子代理。带有协议版本的标准回复信封。会话启动时发出 subagents:ready。完整参考 (https://github.com/tintinweb/pi-subagents/blob/master/docs/rpc.md) - 调度子代理 — 向 Agent 工具传递 schedule 以按 cron / 间隔 / 一次性触发。具有 PID 锁定持久性的会话范围作业；结果通过与手动后台完成相同的 subagent-notification followUp 路径到达；通过 /agents → Scheduled jobs 管理 - 模型范围强制 — 选择性验证子代理模型选择是否保持在您的 pi enabledModels 允许列表内（来自 /scoped-models，同时遵循全局和项目本地的 pi 设置）。调用者提供的超出范围 → 向编排器发出硬错误；frontmatter 固定的超出范围 → 警告 + 仍然运行（frontmatter 具有权威性）。通过 /agents → Settings → Scope models 切换 ## 安装 bash pi install npm:@tintinweb/pi-subagents 或直接加载用于开发： bash pi -e ./src/index.ts 需要 pi 0.84.0 或更新版本：SubagentWorkflow 工具基于 constrainedSampling (pi 0.82.0) 和 pi-tui 的 stripTerminalSequences (0.84.0) 构建。peerDependencies 范围声明了它，因此 npm 在安装时标记较旧的 pi。 ### 其他宿主 此扩展针对 pi (https://pi.dev) 进行开发和测试。第三方适配器报告可在其他地方运行。这些由独立维护：未在此处测试，不在我们的 CI 覆盖范围内，兼容性可能因任何发布而中断。 - DeepSeek Harness (dsh) — 通过将 pi 的主机 API 映射到原生 DSH 代理的适配器。详情和报告：#258 (https://github.com/tintinweb/pi-subagents/issues/258) ## 快速入门 父代理使用 Agent 工具生成子代理： Agent({ subagent_type: "Explore", prompt: "Find all files that handle authentication", description: "Find auth files", run_in_background: true, }) 代理默认在后台运行：调用立即返回一个 ID 并在完成时通知您，携带结果预览（使用 get_subagent_result 获取完整文本）。传递 run_in_background: false 以阻塞直到代理完成并内联获取其完整输出。 ### 调度 添加 schedule 字段以注册代理稍后触发而不是现在运行： Agent({ subagent_type: "Explore", prompt: "Look at recent commits and summarize what changed since last week", description: "Weekly commit review", schedule: "0 0 9 * * 1", // 9am every Monday (6-field cron) }) 调度格式： - Cron — 6 字段（秒 分 时 日 月 星期），例如 "0 0 9 * * 1" 每周一早上 9 点，"0 */15 * * * *" 每 15 分钟。 - 间隔 — "5m"、"1h"、"30s"、"2d"。按该间隔重复触发。 - 一次性相对 — "+10m"、"+2h"、"+1d"。在该未来时间触发一次。 - 一次性绝对 — 完整 ISO 时间戳，例如 "2026-12-25T09:00:00.000Z"。 当调度触发时，启动在后台运行，其完成通知通过与手动启动的后台代理相同的 subagent-notification followUp 路径到达对话——您的父代理以相同方式推理结果。调度是 会话范围：它们在 /new 时重置，在 /resume 时恢复。通过 /agents → Scheduled jobs 列表和取消（创建是 Agent 工具的任务——没有并行的手动创建向导）。存储在 /.pi/subagent-schedules/.json，使用基于 PID 的文件锁定以实现跨实例安全。 完全禁用该功能：/agents → Settings → Scheduling → disabled 从 Agent 工具规范中移除 schedule（无 LLM 上下文成本），隐藏菜单项，并停止任何活动的调度器。模式级别的移除在下一个 pi 会话生效；运行时终止立即生效。从同一菜单重新启用。 限制： - schedule 不能与 inherit_context（触发时不存在父对话）或 resume（调度创建新代理）结合使用。 - run_in_background: false 被拒绝——计划任务始终在后台运行。省略它，或传递 true，是可以的。 - 计划触发绕过 maxConcurrent 队列，因此 5 分钟间隔不会被长时间运行的手动代理推迟。 - 无头 pi -p 不等待计划的子代理。 ## UI 该扩展在编辑器上方渲染一个持久性小组件，显示活动代理。默认仅显示后台运行（widgetMode: background）——前台代理已作为 Agent 工具结果内联渲染，因此小组件否则会重复渲染它们。通过 /agents → Settings → Widget 切换为 all（每个代理）或 off（隐藏小组件）： ● Agents ├─ ⠹ Agent Refactor auth module · ↻5≤30 · 5 tool uses · 33.8k token (62%) · 12.3s │ ⎿ editing 2 files... ├─ ⠹ Explore Find auth files · ↻3 · 3 tool uses · 12.4k token (8%) · 4.1s │ ⎿ searching... ├─ ⠹ Agent Long-running task · ↻42 · 38 tool uses · 91.0k token (84% · ⇊2) · 2m17s │ ⎿ reading... └─ 2 queued 令牌字段在括号内注释有两个可选信号： - NN% — 上下文窗口利用率（颜色编码：<70% 暗淡，70–85% 警告，≥85% 错误）。当模型没有声明的 contextWindow 时省略，或在压缩后短暂省略。 - ⇊N — 会话被压缩的次数，当 > 0 时。保持暗淡；百分比的颜色表示紧急程度。 ### FleetView 当子代理正在运行时，Claude Code 风格的可导航列表渲染在 编辑器下方： esc to interrupt · ← for agents · ↓ to manage ● main ○ workflow audit-src 12/40 agents · 32s · ↓ 26.4k tokens ○ general-purpose Sleep then report 1 11s · ↓ 13.1k tokens ○ general-purpose Sleep then report 2 11s · ↓ 13.1k tokens ↓ 3 more 运行中的 工作流 作为单个 workflow 行显示在代理上方，携带其代理计数作为描述。按 Enter 打开与 /agents → Workflows 相同的双窗格检查器，而不是对话叠加层。运行自身的代理 不 单独列出——它们属于运行，运行会代表它们报告，因此它们被过滤出舰队列表、编辑器上方小组件、/agents 菜单和 @handle 解析，就像嵌套子代理一样。它们也在 maxConcurrent 池之外：运行有自己的并发限制，通过会话池路由扇出会让一个工作流饿死其他所有内容。代理按最早启动的顺序排序，只显示您实际可以打开的代理（尚无会话的待处理/排队代理在启动后出现）。在 空提示符 处，按 ↓（或 ←）将焦点从提示符移动到列表中——所选行标记为 ●，其余为 ○。所选行以主题的主要文本颜色渲染，而不是其他行的柔和/暗淡处理；具有配置 color 的代理也显示其徽章，加粗。↑/↓ 移动选择，Enter 打开所选代理的实时对话叠加层（它在代理工作时自动更新），Esc（或在 main 上方按 ↑）返回到提示符。选择 main 返回正常视图。在叠加层内，按 Enter 引导运行中的代理——输入消息并按 Enter 发送（Esc 或空提交返回），它以与 steer_subagent 工具相同的方式重定向代理。当代理完成时，查看器保持打开，以便您阅读最终输出。