@zhushanwen/pi-subagent-workflow 9.2.0 → 9.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "9.2.0",
+  "version": "9.2.1",
   "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.",
@@ -58,12 +58,12 @@
     ]
   },
   "dependencies": {
-    "@zhushanwen/session-delivery": "1.0.0",
     "@zhushanwen/extension-protocol": "0.17.0",
+    "@zhushanwen/session-delivery": "1.0.0",
     "@zhushanwen/pi-ext-guards": "0.4.2",
-    "@zhushanwen/pi-notify-ledger-host": "0.2.3",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/subagent-core": "1.2.0",
+    "@zhushanwen/pi-notify-ledger-host": "0.2.4",
+    "@zhushanwen/subagent-core": "1.2.1",
     "@zhushanwen/pi-subagent-cli": "0.5.0",
     "@zhushanwen/zcode-subagent-cli": "0.4.4"
   },

package/src/host/__tests__/staged-discovery.test.ts

@@ -0,0 +1,147 @@
+// staged-discovery.test.ts — 打包态内置资产**发现结果**门禁（档 2，2026-10-03 B′）
+//
+// 为什么单独建这个文件：本次事故（打包版 `subagents` 批量工具报
+// "Built-in workflow 'fan-out' is not available"）的根因是**发现层面**——esbuild
+// 自包含 bundle 下 `require.resolve("@zhushanwen/subagent-core/…")` 必败，staged 布局
+// 又无 node_modules，于是孝在包里的 `workflows/` 无人能扫到。既有门禁全是“文件在不在”
+// 级断言（dry-run import 不调工厂、TC8 只比字节），对本类失效天然失明。
+//
+// 本文件的断言对象是**发现结果**（6 内置 workflow + 10 内置 agent 真的被列出来），
+// 而非“文件存在”：前者才能拦住“路径/产物层”回归。两条通路都被锁：
+//   ① 纯函数：bundle 形态模块路径 → scope 根；dev/异常形态 → undefined（不误触发）；
+//   ② 集成：以合成 bundle 模块路径调 `corePackageNpmRoot()`（resolve 必败 → 回退分支），
+//      再把回退根当 npm 槽根跑**真实** `discoverResources`，断言结果与源目录逐文件一致。
+//
+// 资产集不写死数量（口径：与 `packages/subagent-core/{workflows,agents}` 源目录集合比对，
+// 源增删自动跟随）。
+
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { discoverResources, isTargetFile } from "@zhushanwen/subagent-core";
+import { afterAll, describe, expect, it, vi } from "vitest";
+
+// pi 宿主协作件 mock：本文件只跑发现链，日志面给可调用桩（回退分支会走 debug）。
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => process.env.PI_CODING_AGENT_DIR ?? "/mock/agent-dir",
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+const { corePackageNpmRoot, stagedScopeRootFromModuleUrl } = await import("../pi-host.ts");
+
+/** 本仓 `packages/subagent-core`（源单源：断言口径由此推导，不写死数量）。
+ *  路径经与生产同一锚点解析得出（禁止手数 `..` 层级）。 */
+const CORE_PKG = dirname(
+  dirname(createRequire(import.meta.url).resolve("@zhushanwen/subagent-core/workflows/README.md")),
+);
+
+const tmpDirs: string[] = [];
+function makeTmp(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  tmpDirs.push(dir);
+  return dir;
+}
+afterAll(() => {
+  for (const d of tmpDirs) {
+    // teardown 递归删除补 maxRetries：与在途异步写竞争时 ENOTEMPTY 满载 flake
+    rmSync(d, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  }
+});
+
+/** 合成 staged 布局：<tmp>/@zhushanwen/pi-subagent-workflow/{index.js,workflows,agents}。 */
+function makeStagedLayout(): { scopeDir: string; moduleUrl: string } {
+  const root = makeTmp("staged-discovery-");
+  const pkgDir = join(root, "@zhushanwen", "pi-subagent-workflow");
+  mkdirSync(pkgDir, { recursive: true });
+  const indexJs = join(pkgDir, "index.js");
+  writeFileSync(indexJs, "// staged bundle placeholder\n", "utf8");
+  for (const kind of ["workflows", "agents"] as const) {
+    cpSync(join(CORE_PKG, kind), join(pkgDir, kind), { recursive: true });
+  }
+  return { scopeDir: join(root, "@zhushanwen"), moduleUrl: pathToFileURL(indexJs).href };
+}
+
+/** 源目录内可发现文件的集合——判据直接复用发现层导出的 isTargetFile（同一份
+ *  函数，发现层口径变化时期望集自动跟随，无双源）。 */
+function sourceExpected(kind: "workflows" | "agents"): string[] {
+  return readdirSync(join(CORE_PKG, kind))
+    .filter((f) => isTargetFile(f, kind))
+    .sort();
+}
+
+describe("B′：staged/bundle 形态的 core 资产发现根", () => {
+  it("stagedScopeRootFromModuleUrl：bundle 形态（<scope>/<pkg>/index.js）→ 返回 scope 目录", () => {
+    const { scopeDir, moduleUrl } = makeStagedLayout();
+    expect(stagedScopeRootFromModuleUrl(moduleUrl)).toBe(scopeDir);
+  });
+
+  it("stagedScopeRootFromModuleUrl：dev 形态（非 scope 布局）→ undefined（不误触发回退）", () => {
+    const devLike = pathToFileURL(join(CORE_PKG, "workflows", "fan-out.js")).href;
+    expect(stagedScopeRootFromModuleUrl(devLike)).toBeUndefined();
+  });
+
+  it("corePackageNpmRoot：dev/workspace 形态走 resolve 通路（不回退）", () => {
+    const root = corePackageNpmRoot();
+    expect(root).toBeDefined();
+    // workspace 形态：scope 根下必须有 subagent-core 包目录（resolve 命中锚点的上三级）
+    expect(readdirSync(root as string)).toContain("subagent-core");
+  });
+
+  it("corePackageNpmRoot：bundle 形态 resolve 必败 → 回退到 scope 根", () => {
+    const { scopeDir, moduleUrl } = makeStagedLayout();
+    expect(corePackageNpmRoot(moduleUrl)).toBe(scopeDir);
+  });
+});
+
+describe("B′：回退根下的**发现结果**（本批防复发的核心断言）", () => {
+  it("workflows：发现结果与源目录集合逐文件一致（内置模板全部可派发）", async () => {
+    const { scopeDir } = makeStagedLayout();
+    const found = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: scopeDir,
+      hostRoots: [{ dir: scopeDir, source: "npm" }],
+    });
+    // 只断言**回退根下**的发现结果（发现面还包括真实用户目录 ~/.agents/workflows
+    // 等宿主/约定根——本用例的主题是回退根本身，故按路径范围收窄，噪声不介入）
+    const names = found
+      .filter((r) => r.available && r.path.startsWith(scopeDir))
+      .map((r) => r.path.split("/").pop() as string)
+      .sort();
+    expect(names).toEqual(sourceExpected("workflows"));
+    // 回归锚：批量入口的固定执行体必须在列
+    expect(names).toContain("fan-out.js");
+  });
+
+  it("agents：发现结果与源目录集合逐文件一致（10 内置角色全部可选）", async () => {
+    const { scopeDir } = makeStagedLayout();
+    const found = await discoverResources({
+      kind: "agents",
+      workspaceRoot: scopeDir,
+      hostRoots: [{ dir: scopeDir, source: "npm" }],
+    });
+    const names = found
+      .filter((r) => r.available && r.path.startsWith(scopeDir))
+      .map((r) => r.path.split("/").pop() as string)
+      .sort();
+    expect(names).toEqual(sourceExpected("agents"));
+    expect(names).toContain("general-purpose.md");
+  });
+
+  it("负向：源资产缺席时发现结果为空（门禁失败方向正确，不会假绿）", async () => {
+    const root = makeTmp("staged-discovery-empty-");
+    const pkgDir = join(root, "@zhushanwen", "pi-subagent-workflow");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "index.js"), "// no assets\n", "utf8");
+    const found = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: join(root, "@zhushanwen"),
+      hostRoots: [{ dir: join(root, "@zhushanwen"), source: "npm" }],
+    });
+    expect(found.filter((r) => r.available)).toEqual([]);
+  });
+});

package/src/host/pi-host.ts

@@ -62,20 +62,34 @@ import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
  * realpath 去重吸收）。
  *
  * 每次调用现解析（不 memo）：发现调用点稀疏（session_start + 缓存 miss），解析
- * 成本可忽略；失败（异常布局/解析器不可用）降级为不注入并 warn——绝不因资产
- * 接线失败阻断发现主链。
+ * 成本可忽略；两种形态各有通路，都不阻断发现主链：
+ *   - **dev / npm 形态**：`require.resolve` 沿本包依赖解析链命中 core 包；
+ *   - **bundle / staged 打包形态**（2026-10-03 B′ 修复）：esbuild 自包含 bundle 把
+ *     core inline、staged 布局无 node_modules ⇒ resolve 必败（实证：pi-host 日志全天
+ *     202 条 'Cannot find module … workflows/README.md'，内置 6 workflow + 10 agent
+ *     整体不可发现、`subagents` 批量工具报 'Built-in workflow fan-out is not available'）。
+ *     此时回退到 staged scope 根（见 stagedScopeRootFromModuleUrl）——仅当回退也不
+ *     成立（异常布局/解析器不可用）才降级为不注入并 warn。
  */
-function corePackageNpmRoot(): string | undefined {
+export function corePackageNpmRoot(moduleUrl: string = import.meta.url): string | undefined {
   try {
     // createRequire 锚定本模块（jiti 加载器下 import.meta.url 可用；不可用则随
     // catch 降级）。require.resolve 沿 pi-sw 自身的依赖解析链——workspace 与发布态
     // 都从本包出发命中 core。
-    const require = createRequire(import.meta.url);
+    const require = createRequire(moduleUrl);
     const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
     return dirname(dirname(dirname(anchor)));
   } catch (err) {
-    // getLogger 惰性调用（catch 是冷路径——测试环境对 pi-extension-logger 的
-    // module-level mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+    const stagedRoot = stagedScopeRootFromModuleUrl(moduleUrl);
+    if (stagedRoot !== undefined) {
+      // getLogger 惰性调用（冷路径：测试环境对 pi-extension-logger 的 module-level
+      // mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+      getLogger("pi-host").debug(
+        "[pi-host] core 包经 staged scope 根注入（bundle 形态，无 node_modules 解析面）",
+        { root: stagedRoot },
+      );
+      return stagedRoot;
+    }
     getLogger("pi-host").warn(
       "[pi-host] core 包 agents/ 注入根解析失败——10 内置角色可能不可发现",
       { reason: toErrorMessage(err) },
@@ -84,6 +98,40 @@ function corePackageNpmRoot(): string | undefined {
   }
 }
 
+/**
+ * bundle / staged 形态的 core 资产注入根（2026-10-03 B′）。
+ *
+ * 打包态扩展被 esbuild 打成**自包含 index.js**（core 被 inline），staged 布局内无
+ * node_modules ⇒ `require.resolve` 锚点必败。但此时模块位置是
+ * `<stagedScope>/<pkg>/index.js`（如
+ * `<Resources>/extensions/@zhushanwen/pi-subagent-workflow/index.js`），其**父目录**
+ * 正是 `@zhushanwen` scope 目录——npm 槽语义（"一级子项 = 包目录"）恰好成立，
+ * 于是可直接当 npm 槽根用：约定目录扫描即命中
+ * `pi-subagent-workflow/{workflows,agents}`（两目录由 `scripts/bundle-extensions.mjs`
+ * 随包拷贝；`pi.agents`/`pi.workflows` manifest 约定及其"声明路径不存在 → 整包失败
+ * 占位"语义是 subagent-core resource-discovery 的 taiji 自建规则，权威源 =
+ * resource-discovery.ts processPackage——pi 上游 manifest 只有
+ * extensions/skills/prompts/themes 四字段，无 agents/workflows 概念。已核仓内无任何
+ * 包声明该字段，故扫描面内所有包都走约定目录分支，不进 manifest 失败分支）。
+ *
+ * 与 dev/npm 形态的既有语义一致：npm 槽根扫的就是 scope 下全部包目录（因此本包自带
+ * 的 workflows/agents 在 dev/npm 形态同样入发现面），非新增语义。
+ *
+ * 形态判据 = 父目录名以 `@` 开头：dev（模块在 `extensions/universal/...`）与 npm
+ * 安装形态都先走 resolve 成功分支，本回退不可达；仅 bundle/staged 形态命中。
+ */
+export function stagedScopeRootFromModuleUrl(moduleUrl: string): string | undefined {
+  try {
+    const pkgDir = dirname(fileURLToPath(moduleUrl));
+    const scopeDir = dirname(pkgDir);
+    if (scopeDir === pkgDir) return undefined;
+    const scopeName = scopeDir.split(/[\\/]/).pop() ?? "";
+    return scopeName.startsWith("@") ? scopeDir : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** agents/workflows 共享的 agentDir 派生根（末级目录名由 kind 决定）。
  *  顺序与 source 标签逐项对齐 resource-discovery.ts buildScanTargets 的
  *  user-pi → npm → npm-dev 段（根列表按优先级低→高排列，D2 语义边界）。