@zhushanwen/pi-subagent-workflow 5.0.2 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "5.0.2",
+  "version": "6.0.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",

package/src/execution/subagent-service.ts

@@ -599,7 +599,7 @@ export class SubagentService {
     //   - **不可作为后续 agent 的 cwd**——目录已删，复用会 ENOENT。
     //   - wave 内 worktree 复用（spec-w §2 "wave 内 8 action 共享 worktree"）在 pi 当前架构下
     //     不可行：worktree 绑定单次 agent() record，每次 executeAndAwait 结束 finalizeRecord
-    //     无条件 cleanup，worktree 无法跨 action 存活。wave 改用主 cwd（见 recursive-split.js）。
+    //     无条件 cleanup，worktree 无法跨 action 存活。wave 改用主 cwd。
     wfResult.worktreePath = record.worktreeHandle?.path;
     return wfResult;
   }

package/src/shared/__tests__/resource-discovery.test.ts

@@ -224,3 +224,94 @@ describe("discoverResources (async)", () => {
     expect(result).toHaveLength(2);
   });
 });
+
+// ============================================================
+// user-extension-paths (XYZ_EXTENSION_PATHS) — dev-link 扩展发现
+// ============================================================
+
+describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
+  let ws: string;
+  let agentDir: string;
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+    savedEnv = process.env.XYZ_EXTENSION_PATHS;
+  });
+  afterEach(() => {
+    if (savedEnv === undefined) delete process.env.XYZ_EXTENSION_PATHS;
+    else process.env.XYZ_EXTENSION_PATHS = savedEnv;
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("discovers agents from XYZ_EXTENSION_PATHS via pi.agents manifest", () => {
+    const pkgDir = path.join(ws, "my-ext");
+    writePackageJson(pkgDir, { agents: ["./agents"] });
+    writeFile(path.join(pkgDir, "agents"), "custom.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["custom.md"]);
+    expect(result[0]?.source).toBe("user-extension-paths");
+  });
+
+  it("discovers agents via convention dir (no manifest)", () => {
+    const pkgDir = path.join(ws, "my-ext");
+    writeFile(path.join(pkgDir, "agents"), "conv.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["conv.md"]);
+    expect(result[0]?.source).toBe("user-extension-paths");
+  });
+
+  it("multiple paths separated by delimiter", () => {
+    const pkg1 = path.join(ws, "ext1");
+    const pkg2 = path.join(ws, "ext2");
+    writeFile(path.join(pkg1, "agents"), "a1.md", "body");
+    writeFile(path.join(pkg2, "agents"), "a2.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = `${pkg1}${path.delimiter}${pkg2}`;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path)).sort()).toEqual(["a1.md", "a2.md"]);
+    expect(result.every((r) => r.source === "user-extension-paths")).toBe(true);
+  });
+
+  it("overrides npm on name clash (priority: user-extension-paths > npm)", () => {
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    writeFile(path.join(npmPkg, "agents"), "shared.md", "npm-body");
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "shared.md", "dev-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    const shared = result.find((r) => path.basename(r.path) === "shared.md");
+    expect(shared?.source).toBe("user-extension-paths");
+  });
+
+  it("project-agents overrides user-extension-paths (project wins)", () => {
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "x.md", "dev-body");
+    writeFile(path.join(ws, ".agents", "agents"), "x.md", "project-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    const x = result.find((r) => path.basename(r.path) === "x.md");
+    expect(x?.source).toBe("project-agents");
+  });
+
+  it("empty/unset env → no user-extension-paths source", () => {
+    delete process.env.XYZ_EXTENSION_PATHS;
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.filter((r) => r.source === "user-extension-paths")).toEqual([]);
+  });
+
+  it("async discoverResources also scans user-extension-paths", async () => {
+    const pkgDir = path.join(ws, "my-ext");
+    writePackageJson(pkgDir, { agents: ["./agents"] });
+    writeFile(path.join(pkgDir, "agents"), "async.md", "body");
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["async.md"]);
+    expect(result[0]?.source).toBe("user-extension-paths");
+  });
+});

package/src/shared/resource-discovery.ts

@@ -14,7 +14,7 @@
 import * as fsSync from "node:fs";
 import { access, readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join,resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 
 // ── 类型 ─────────────────────────────────────────────────────
 
@@ -32,7 +32,7 @@ export interface DiscoveredResource {
 }
 
 /** 资源来源层级 */
-export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "project-pi" | "project-pi-tmp" | "project-agents";
+export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "user-extension-paths" | "project-pi" | "project-pi-tmp" | "project-agents";
 
 /** 扫描配置 */
 export interface ScanConfig {
@@ -288,6 +288,24 @@ interface ScanTarget {
   enabled: boolean;
 }
 
+/**
+ * 读取 XYZ_EXTENSION_PATHS 环境变量（dev-link 写入的扩展源码路径）。
+ *
+ * delimiter 分隔（POSIX ':' / Windows ';'），trim + 过滤空 + ~ 展开。
+ * 每个路径是一个 extension 包目录（dev-link 指向源码），走 processPackage 发现其
+ * agents/workflows。解析逻辑与 extension-service.getUserExtensionPaths() 一致。
+ */
+function readExtensionPaths(): string[] {
+  const raw = process.env.XYZ_EXTENSION_PATHS;
+  if (!raw) return [];
+  const paths = raw
+    .split(delimiter)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0)
+    .map((p) => (p.startsWith("~") ? join(homedir(), p.slice(1)) : p));
+  return [...new Set(paths)];
+}
+
 /**
  * 构建所有扫描源（按优先级低→高排列）。
  *
@@ -306,6 +324,10 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
     { dir: join(agentDir, "npm", "node_modules"), source: "npm", enabled: true },
     // 4. npm dev symlink: agentDir/extensions/*/<pkg>/
     { dir: join(agentDir, "extensions"), source: "npm-dev", enabled: true },
+    // user extension paths (XYZ_EXTENSION_PATHS, dev-link): each path is a package dir,
+    // 走 processPackage 读 pi.{kind} manifest 或扫 {kind}/ 目录。优先级高于 npm/npm-dev
+    // （dev-link 是开发版 override），低于 project（项目正式资源优先）。
+    ...readExtensionPaths().map((dir) => ({ dir, source: "user-extension-paths" as const, enabled: true })),
     // 5. project .pi/{kind}/
     { dir: join(workspaceRoot, ".pi", kind), source: "project-pi", enabled: true },
   ];
@@ -354,6 +376,11 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
       // 覆盖 source 标签（scanNpmDir 内部统一标 "npm"，这里修正为实际源）
       const tagged = resources.map((r) => ({ ...r, source: target.source }));
       allBySource.push({ source: target.source, resources: tagged });
+    } else if (target.source === "user-extension-paths") {
+      // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录，走 processPackage
+      const resources = await processPackage(target.dir, config.kind);
+      const tagged = resources.map((r) => ({ ...r, source: target.source }));
+      allBySource.push({ source: target.source, resources: tagged });
     } else {
       // 普通目录：直接扫
       const files = await scanDirectory(target.dir, config.kind);
@@ -517,6 +544,10 @@ export function discoverResourcesSync(config: ScanConfig): DiscoveredResource[]
     if (target.source === "npm" || target.source === "npm-dev") {
       const resources = scanNpmDirSync(target.dir, config.kind);
       all.push(...resources.map((r) => ({ ...r, source: target.source })));
+    } else if (target.source === "user-extension-paths") {
+      // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录
+      const resources = processPackageSync(target.dir, config.kind);
+      all.push(...resources.map((r) => ({ ...r, source: target.source })));
     } else {
       const files = scanDirectorySync(target.dir, config.kind);
       all.push(...files.map((f) => ({ path: f, source: target.source, available: true })));

package/workflows/review-fix-loop-utils.cjs

@@ -1,6 +1,6 @@
 // review-fix-loop-utils.cjs — review-fix-loop.js 的可测纯函数模块
 //
-// 与 recursive-split-utils.cjs 同款模式：workflow 编排逻辑的纯函数抽到独立 .cjs，
+// workflow 编排逻辑的纯函数抽到独立 .cjs，
 // 供 vitest 单测直接 require（extensions/subagent-workflow/src/__tests__/review-fix-loop-utils.test.ts）
 // 与 worker 运行时共用（review-fix-loop.js 经 workerData.scriptPath 定位本文件）。
 //

package/workflows/review-fix-loop.js

@@ -34,8 +34,8 @@ function fail(msg) {
 
 // ── 可测纯函数模块 ────────────────────────────────────────────────
 // 参数校验（normalizeBool/normalizeInt/白名单）/批次解析/聚合结果解析/审查指令构建
-// 的纯函数在 review-fix-loop-utils.cjs（与 recursive-split-utils.cjs 同款模式，
-// vitest 单测见 src/__tests__/review-fix-loop-utils.test.ts）。
+// 的纯函数在 review-fix-loop-utils.cjs，
+// vitest 单测见 src/__tests__/review-fix-loop-utils.test.ts。
 // worker 运行时经 workerData.scriptPath 定位自身目录——内置 workflow 在 npm 包内，
 // process.cwd() 是用户项目目录，不能作为锚点；其他引擎无 workerData 时回退 cwd。
 const {
@@ -314,7 +314,7 @@ function buildReviewCall(def, round, max, batchIndex, roundDir, scoped) {
     schema: reviewerSchema,
     description: def.name,
     timeoutMs: 3_600_000, // 1h（只读审查 + retry 退避余量）
-    // returnMeta: true — 与 recursive-split 脚本的 executeActionAgent 对齐：失败时 resolve
+    // returnMeta: true — 失败时 resolve
     // {value, error}，raw.error 可检测（review- 前缀兜底/结构化终止可达）；成功时
     // value = parsedOutput ?? content，parseResult 作用于 raw.value（MF-1）。
     returnMeta: true,