@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/workflow-script-registry-impl.ts

@@ -0,0 +1,128 @@
+/**
+ * Workflow Extension — WorkflowScriptRegistryImpl
+ *
+ * WorkflowScriptRegistry port 的 Infra 实现。
+ *
+ * 职责：扫描 .pi/workflows/ + ~/.pi/agent/workflows/ 目录，按 regex 提取
+ * meta（不执行用户代码），按 tmp>project>user 优先级去重，60s TTL 缓存。
+ *
+ * 层归属：Infra（D-12）。implements Engine 层的 WorkflowScriptRegistry port。
+ *
+ * 设计：
+ * - WorkflowScriptRegistryImpl 是 port 的实现，但底层扫描/缓存/去重仍委托
+ * config-loader.ts 的 loadWorkflows/getWorkflow/invalidateCache 自由函数
+ * （config-loader 是稳定 Infra 工具，registry 在其上包装为 WorkflowScript 实体）。
+ * - 返回 WorkflowScript 实体（而非裸 CachedWorkflowMeta）。
+ * - get(name) 精确匹配；fuzzy 匹配由 Interface 层 tool 负责。
+ */
+
+import { readFileSync } from "node:fs";
+
+import {
+  type WorkflowMeta,
+  WorkflowScript,
+  type WorkflowSource,
+} from "./models/workflow-script.ts";
+import type { WorkflowScriptRegistry } from "./models/workflow-script-registry.ts";
+import {
+  discoverWorkflows,
+  getWorkflow,
+  invalidateCache,
+  loadWorkflows,
+  type WorkflowScanConfig,
+} from "./config-loader.ts";
+
+// ── WorkflowScriptRegistryImpl ───────────────────────────────
+
+/**
+ * WorkflowScriptRegistry port 的 Infra 实现。
+ *
+ * @param config 可选扫描配置。传入时 registry 只扫 config 声明的目录
+ *              （测试隔离用）；省略时走生产默认（全局 ~/.pi/agent/* 目录）。
+ */
+export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
+  constructor(private readonly config?: WorkflowScanConfig) {}
+
+ /**
+	 * 扫描所有 workflow 脚本（project + user + tmp），按 tmp>project>user 优先级
+	 * 去重，返回 WorkflowScript 实体数组（含 available=false 的解析失败项）。
+	 *
+	 * 60s TTL 缓存——同 workspace 60s 内重复调用走缓存。
+	 */
+  async loadAll(): Promise<WorkflowScript[]> {
+    const metas = this.config
+      ? await discoverWorkflows(this.config)
+      : await loadWorkflows();
+    return metas.map((m) => this.toScript(m));
+  }
+
+ /**
+	 * 按名查单个脚本。精确匹配。
+	 * 返回 undefined 当 name 不存在。
+	 *
+	 * 注：fuzzy 匹配由 Interface 层 tool-workflow负责——registry 只做精确查。
+	 *
+	 * 性能注记：无 config（生产路径）时走 getWorkflow 的 60s TTL 单条缓存。
+	 * 有 config（测试隔离）时退化为每次 discoverWorkflows 全扫——测试场景
+	 * 可接受，生产路径不受影响。
+	 */
+  async get(name: string): Promise<WorkflowScript | undefined> {
+    const meta = this.config
+      ? (await discoverWorkflows(this.config)).find((w) => w.name === name)
+      : await getWorkflow(name);
+    return meta ? this.toScript(meta) : undefined;
+  }
+
+ /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
+  invalidate(): void {
+    invalidateCache();
+  }
+
+ /**
+ * 把 CachedWorkflowMeta 转换为 WorkflowScript 实体。
+ *
+ * 字段映射：
+ * - name/path/source 直接传
+ * - meta 拆为 WorkflowMeta（name/description/phases）
+ * - sourceCode 在此 readFile 填充（FR-2：registry 是唯一读文件处，扫描+缓存+去重；
+ * 60s TTL 缓存避免重复读）。caller（launcher.runAndWait / tool-workflow.actionRun）
+ * 直接用 script.validate / script.toExecutable，不再各自 readFile。
+ * - available：meta 提取失败（config-loader 标 available=false）或文件不可读时为 false
+ */
+  private toScript(m: {
+    name: string;
+    description: string;
+    phases: (string | { title: string; detail?: string })[];
+    path: string;
+    available: boolean;
+    source: WorkflowSource;
+  }): WorkflowScript {
+    const meta: WorkflowMeta = {
+      name: m.name,
+      description: m.description,
+      phases: m.phases,
+    };
+ // FR-2: registry 是唯一读文件处。readFileSync 填 sourceCode —— 这样 launcher/tool
+ // 直接调 toExecutable/validate 即可，无需各自 readFile（避免重复读，60s TTL 缓存生效）。
+    let sourceCode = "";
+    let available = m.available;
+    if (available) {
+      try {
+        sourceCode = readFileSync(m.path, "utf-8");
+      } catch {
+ // 文件不可读（race condition 删除、权限等）——标 available=false，
+ // 与 meta 提取失败的现有语义一致（loader "never throws"）。
+        sourceCode = "";
+        available = false;
+      }
+    }
+    return new WorkflowScript({
+      name: m.name,
+      source: m.source,
+      path: m.path,
+      sourceCode,
+      meta,
+      available,
+    });
+  }
+}

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

@@ -0,0 +1,226 @@
+// src/shared/__tests__/resource-discovery.test.ts
+//
+// 统一资源发现模块测试（ADR-031）。
+// 验证：扫描源覆盖、优先级合并、manifest 校验、约定目录 fallback。
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  discoverResources,
+  discoverResourcesSync,
+  findWorkspaceRoot,
+  processPackageSync,
+} from "../resource-discovery.ts";
+
+// ============================================================
+// helpers
+// ============================================================
+
+function tmpWorkspace(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "res-disc-test-"));
+}
+
+function writeFile(dir: string, name: string, content: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, name);
+  fs.writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+function writePackageJson(pkgDir: string, pi: Record<string, unknown>): void {
+  fs.mkdirSync(pkgDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(pkgDir, "package.json"),
+    JSON.stringify({ name: "test-pkg", pi }),
+    "utf-8",
+  );
+}
+
+// ============================================================
+// findWorkspaceRoot
+// ============================================================
+
+describe("findWorkspaceRoot", () => {
+  it("returns cwd when no marker found", () => {
+    const ws = tmpWorkspace();
+    expect(findWorkspaceRoot(ws)).toBe(ws);
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("finds .git root", () => {
+    const ws = tmpWorkspace();
+    fs.mkdirSync(path.join(ws, ".git"));
+    const sub = path.join(ws, "sub", "deep");
+    fs.mkdirSync(sub, { recursive: true });
+    expect(findWorkspaceRoot(sub)).toBe(ws);
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+});
+
+// ============================================================
+// discoverResourcesSync — 扫描源覆盖 + 优先级
+// ============================================================
+
+describe("discoverResourcesSync", () => {
+  let ws: string;
+  let agentDir: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+    agentDir = path.join(ws, ".fake-agent");
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("discovers agents from project .pi/agents/", () => {
+    writeFile(path.join(ws, ".pi", "agents"), "worker.md", "body");
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["worker.md"]);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("discovers workflows from project .pi/workflows/", () => {
+    writeFile(path.join(ws, ".pi", "workflows"), "build.js", "const meta={name:'build'};");
+    const result = discoverResourcesSync({ kind: "workflows", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["build.js"]);
+  });
+
+  it("project .agents overrides project .pi on name clash (priority)", () => {
+    writeFile(path.join(ws, ".pi", "agents"), "worker.md", "pi-body");
+    writeFile(path.join(ws, ".agents", "agents"), "worker.md", "agents-body");
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result).toHaveLength(1);
+    expect(result[0]?.source).toBe("project-agents");
+  });
+
+  it("includes tmp source for workflows when includeTmp=true", () => {
+    writeFile(path.join(ws, ".pi", "workflows", ".tmp"), "temp.js", "const meta={name:'temp'};");
+    const result = discoverResourcesSync({
+      kind: "workflows",
+      workspaceRoot: ws,
+      agentDir,
+      includeTmp: true,
+    });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["temp.js"]);
+    expect(result[0]?.source).toBe("project-pi-tmp");
+  });
+
+  it("excludes tmp source when includeTmp omitted", () => {
+    writeFile(path.join(ws, ".pi", "workflows", ".tmp"), "temp.js", "x");
+    const result = discoverResourcesSync({ kind: "workflows", workspaceRoot: ws, agentDir });
+    expect(result).toEqual([]);
+  });
+
+  it("ignores _ prefix and .chain.md files", () => {
+    const dir = path.join(ws, ".pi", "agents");
+    writeFile(dir, "real.md", "body");
+    writeFile(dir, "_skip.md", "ignored");
+    writeFile(dir, "trace.chain.md", "ignored");
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result.map((r) => path.basename(r.path))).toEqual(["real.md"]);
+  });
+
+  it("nonexistent directories are silently skipped", () => {
+    const result = discoverResourcesSync({ kind: "agents", workspaceRoot: ws, agentDir });
+    expect(result).toEqual([]);
+  });
+});
+
+// ============================================================
+// processPackageSync — manifest 校验
+// ============================================================
+
+describe("processPackageSync", () => {
+  let pkgDir: string;
+
+  beforeEach(() => {
+    pkgDir = tmpWorkspace();
+  });
+  afterEach(() => {
+    fs.rmSync(pkgDir, { recursive: true, force: true });
+  });
+
+  it("loads from manifest directory declaration", () => {
+    writeFile(path.join(pkgDir, "agents"), "worker.md", "body");
+    writePackageJson(pkgDir, { agents: ["./agents"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("loads from manifest file declaration", () => {
+    writeFile(pkgDir, "worker.md", "body");
+    writePackageJson(pkgDir, { agents: ["./worker.md"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("manifest path not exists → available=false, no fallback", () => {
+    writePackageJson(pkgDir, { agents: ["./nonexistent"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(false);
+    // 不 fallback 到约定目录
+    writeFile(path.join(pkgDir, "agents"), "hidden.md", "body");
+    const result2 = processPackageSync(pkgDir, "agents");
+    expect(result2).toHaveLength(1);
+    expect(result2[0]?.available).toBe(false);
+  });
+
+  it("no manifest → fallback to convention dir", () => {
+    writeFile(path.join(pkgDir, "agents"), "worker.md", "body");
+    // 无 package.json 或无 pi.agents
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("no manifest and no convention dir → empty", () => {
+    writePackageJson(pkgDir, { extensions: ["./index.ts"] });
+    const result = processPackageSync(pkgDir, "agents");
+    expect(result).toEqual([]);
+  });
+});
+
+// ============================================================
+// discoverResources (async) — 基本冒烟
+// ============================================================
+
+describe("discoverResources (async)", () => {
+  let ws: string;
+
+  beforeEach(() => {
+    ws = tmpWorkspace();
+  });
+  afterEach(() => {
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("discovers agents from project .pi/agents/ (async)", async () => {
+    writeFile(path.join(ws, ".pi", "agents"), "worker.md", "body");
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      agentDir: path.join(ws, ".fake-agent"),
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]?.available).toBe(true);
+  });
+
+  it("discovers workflows with tmp source (async)", async () => {
+    writeFile(path.join(ws, ".pi", "workflows"), "build.js", "x");
+    writeFile(path.join(ws, ".pi", "workflows", ".tmp"), "temp.js", "x");
+    const result = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: ws,
+      agentDir: path.join(ws, ".fake-agent"),
+      includeTmp: true,
+    });
+    expect(result).toHaveLength(2);
+  });
+});

package/src/shared/agent-event.ts

@@ -0,0 +1,13 @@
+// src/shared/agent-event.ts
+//
+// AgentEvent 类型唯一出口（两包合并后 import 收口）。
+//
+// 合并前 AgentEvent 分别定义在 execution/types.ts（subagents 侧）和
+// orchestration/live/types.ts（workflow 侧）——两份定义完全一致但独立维护。
+// 合并后本文件是单一 source of truth——re-export execution/types.ts 的 AgentEvent，
+// orchestration 层通过本文件引用（替代 orchestration/live/types.ts 的旧副本）。
+//
+// wave-3 删 orchestration/live/types.ts 后，AgentEvent 的唯一定义在 execution/types.ts。
+// 本 re-export 保持「shared/ 是类型共享层」的架构约定。
+
+export type { AgentEvent } from "../execution/types.ts";