@maplezzk/pi-dynamic-workflows 1.0.0 → 1.1.1

package/README.md

@@ -10,19 +10,19 @@ Claude-Code-style dynamic workflow orchestration for Pi.
 - Static validation of workflow scripts via acorn AST parsing
 - Optional subagent backend via `pi-interactive-subagents` for real tool access per agent
 - Async background execution mode with live status widget
-- Configurable via `/workflow-config` slash command (persisted to JSON)
+- Configurable via `/config:workflow` slash command (persisted to JSON)
 
 ## Installation
 
 ```bash
-pi install @maplezzk/pi-dynamic-workflows
+pi install npm:@maplezzk/pi-dynamic-workflows
 ```
 
 ## Configuration
 
-Run `/workflow-config` to interactively configure:
+Run `/config:workflow` to interactively configure:
 
-- **Execution backend**: `workflow` (built-in in-process agent) or `subagent` (requires `pi-interactive-subagents`)
+- **Execution backend**: `workflow` (built-in in-process agent) or `subagent` (requires `pi-interactive-subagents` to be installed and loaded; each agent gets a real tool session)
 - **Async mode**: run workflows in the background with a live status widget
 
 Config is persisted to `~/.pi/agent/extensions/pi-dynamic-workflows/config.json`.
@@ -36,6 +36,32 @@ Environment variables are supported as fallback only:
 
 JSON config takes priority over environment variables.
 
+> **Note:** The `subagent` backend depends on the `pi-interactive-subagents` extension injecting its capabilities into `globalThis.__pi_subagents` at runtime. If the backend is set to `subagent` but that extension is not installed/loaded, every `agent()` call in the workflow will fail.
+
+## Troubleshooting
+
+### Error: the subagent execution backend requires the pi-interactive-subagents extension, which is not currently loaded
+
+**Cause**: the workflow execution backend is set to `subagent`, but the `pi-interactive-subagents` extension is not installed or not loaded, so `globalThis.__pi_subagents` is not injected.
+
+The `subagent` backend can be activated by either of:
+
+- The `PI_WORKFLOW_BACKEND=subagent` environment variable
+- The persisted config written by `/workflow-config` (`~/.pi/agent/extensions/pi-dynamic-workflows/config.json`)
+
+**Fix (choose one)**:
+
+1. Install and load the extension (keep using the subagent backend):
+
+   ```bash
+   pi install npm:@maplezzk/pi-interactive-subagents
+   ```
+
+2. Switch back to the built-in `workflow` backend: run `/config:workflow` and set the execution backend to `workflow`. The persisted config takes priority over environment variables, so this overrides `PI_WORKFLOW_BACKEND`.
+3. If you enabled it via an environment variable, remove `export PI_WORKFLOW_BACKEND=subagent` from your shell config (e.g. `.zshrc` / `.zshenv`) and restart pi.
+
+`/workflow-config` and `/pi-workflow-config` remain available as compatibility aliases.
+
 ## Usage
 
 ```js

package/README.zh-CN.md

@@ -10,19 +10,19 @@
 - 通过 acorn AST 解析对 workflow 脚本进行静态校验
 - 可选 subagent 后端（依赖 `pi-interactive-subagents`），每个 agent 拥有真实工具访问
 - 异步后台执行模式，带实时状态 widget
-- 通过 `/workflow-config` 斜杠命令配置（持久化到 JSON）
+- 通过 `/config:workflow` 斜杠命令配置（持久化到 JSON）
 
 ## 安装
 
 ```bash
-pi install @maplezzk/pi-dynamic-workflows
+pi install npm:@maplezzk/pi-dynamic-workflows
 ```
 
 ## 配置
 
-运行 `/workflow-config` 进行交互式配置：
+运行 `/config:workflow` 进行交互式配置：
 
-- **执行后端**：`workflow`（内置进程内 agent）或 `subagent`（需安装 `pi-interactive-subagents`）
+- **执行后端**：`workflow`（内置进程内 agent）或 `subagent`（需安装并加载 `pi-interactive-subagents`，每个 agent 拥有真实工具会话）
 - **异步模式**：后台运行 workflow，带实时状态 widget
 
 配置持久化到 `~/.pi/agent/extensions/pi-dynamic-workflows/config.json`。
@@ -36,6 +36,32 @@ pi install @maplezzk/pi-dynamic-workflows
 
 JSON 配置优先级高于环境变量。
 
+> **注意**：`subagent` 后端依赖 `pi-interactive-subagents` 扩展在运行时向 `globalThis.__pi_subagents` 注入能力。若后端被设为 `subagent` 但该扩展未安装/未加载，workflow 中的每个 `agent()` 都会失败。
+
+## 常见问题
+
+### 报错：subagent 执行后端需要 pi-interactive-subagents 扩展，但当前未加载
+
+**原因**：workflow 的执行后端被设为 `subagent`，但 `pi-interactive-subagents` 扩展未安装或未加载，导致 `globalThis.__pi_subagents` 未注入。
+
+`subagent` 后端可能由以下任一来源触发：
+
+- 环境变量 `PI_WORKFLOW_BACKEND=subagent`
+- `/workflow-config` 写入的持久化配置（`~/.pi/agent/extensions/pi-dynamic-workflows/config.json`）
+
+**解决方式（任选其一）**：
+
+1. 安装并加载扩展（继续使用 subagent 后端）：
+
+   ```bash
+   pi install npm:@maplezzk/pi-interactive-subagents
+   ```
+
+2. 切回内置 `workflow` 后端：运行 `/config:workflow`，将执行后端改为 `workflow`。持久化配置优先级高于环境变量，可覆盖 `PI_WORKFLOW_BACKEND`。
+3. 若是通过环境变量启用，移除 shell 配置（如 `.zshrc` / `.zshenv`）中的 `export PI_WORKFLOW_BACKEND=subagent` 后重启 pi。
+
+`/workflow-config` 和 `/pi-workflow-config` 仍作为兼容别名保留。
+
 ## 用法
 
 ```js

package/locales/index.json

@@ -72,7 +72,7 @@
     "en-US": "📄 Result: {path}"
   },
   "subagentRequired": {
-    "zh-CN": "PI_WORKFLOW_BACKEND=subagent 需要 pi-interactive-subagents 扩展。\n安装: pi install pi-interactive-subagents",
-    "en-US": "PI_WORKFLOW_BACKEND=subagent requires the pi-interactive-subagents extension.\nInstall: pi install pi-interactive-subagents"
+    "zh-CN": "subagent 执行后端需要 pi-interactive-subagents 扩展，但当前未加载。\n\n解决方式（任选其一）：\n1. 安装扩展：pi install npm:@maplezzk/pi-interactive-subagents\n2. 运行 /workflow-config 将执行后端切回 workflow\n\n说明：subagent 后端由环境变量 PI_WORKFLOW_BACKEND=subagent 或 /workflow-config 持久化配置触发。",
+    "en-US": "The subagent execution backend requires the pi-interactive-subagents extension, which is not currently loaded.\n\nFix (choose one):\n1. Install the extension: pi install npm:@maplezzk/pi-interactive-subagents\n2. Run /workflow-config to switch the execution backend back to workflow\n\nNote: the subagent backend is activated by the PI_WORKFLOW_BACKEND=subagent environment variable or the /workflow-config persisted setting."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplezzk/pi-dynamic-workflows",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi. Fork of michaelliv/pi-dynamic-workflows.",
   "type": "module",
   "main": "./index.ts",

package/src/config.ts

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 /**
  * Workflow 运行时配置。
  *
- * 优先级：JSON 配置文件（由 /workflow-config 斜杠命令写入）> 环境变量兜底 > 默认值。
+ * 优先级：JSON 配置文件（由 /config:workflow 斜杠命令写入）> 环境变量兜底 > 默认值。
  * 环境变量仅作为兜底支持（PI_WORKFLOW_BACKEND / PI_WORKFLOW_ASYNC）。
  */
 export type WorkflowBackend = "workflow" | "subagent";

package/src/extension.ts

@@ -101,9 +101,9 @@ export default function extension(pi: ExtensionAPI) {
   });
 }
 
-/** /workflow-config 交互式配置命令：切换执行后端与异步模式，持久化到 JSON。 */
+/** /config:workflow 交互式配置命令；旧名称保留为兼容别名。 */
 function registerConfigCommand(pi: ExtensionAPI) {
-  pi.registerCommand("workflow-config", {
+  const command = {
     description: i18n.t("commandDescription"),
     handler: async (_args, ctx) => {
       if (!ctx.hasUI) return;
@@ -132,5 +132,8 @@ function registerConfigCommand(pi: ExtensionAPI) {
         }
       }
     },
-  });
+  };
+  for (const name of ["config:workflow", "workflow-config", "pi-workflow-config"] as const) {
+    pi.registerCommand(name, command);
+  }
 }