@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/workflow-files.ts

@@ -3,7 +3,8 @@
  *
  * 历史：saveWorkflow 曾有两套实现——commands.ts 用 renameSync 仅 project scope，
  * WorkflowsView.ts 用 copyFileSync 支持 user scope。本次统一为 rename + 仅 project
- * scope（决策 2）：tmp 文件保存后自动消失，保存位置固定 .pi/workflows/。
+ * scope（决策 2）：tmp 文件保存后自动消失，保存位置缺省 DEFAULT_WORKFLOW_SAVED_DIR
+ * （pi 布局；W4/D-6 参数化后宿主经 WorkflowDirOptions 注入自有布局）。
  *
  * 代价：TUI 失去 user scope Tab 切换（功能倒退，已接受）；
  * Windows/跨设备 rename 可能失败（已知风险，接受）。
@@ -12,35 +13,58 @@
 import { existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 
+// ── 目录参数化（D-6：.pi 硬编码 → 宿主注入）──────────────────
+
+/**
+ * 缺省目录（pi 生态布局）。相对路径，调用时 resolve（相对当前 cwd）——与 pi
+ * 宿主现行为一致；宿主注入绝对目录（如 zsw 的自有 workflows 布局）即脱离
+ * pi 目录。全文件唯一的 .pi 路径来源即这两个缺省常量。
+ */
+export const DEFAULT_WORKFLOW_TMP_DIR = ".pi/workflows/.tmp";
+export const DEFAULT_WORKFLOW_SAVED_DIR = ".pi/workflows";
+
+/** 落盘目录注入参数：宿主覆盖缺省 pi 布局（两目录独立可选注入）。 */
+export interface WorkflowDirOptions {
+  /** 临时脚本目录（generate 产物落盘处）；缺省 DEFAULT_WORKFLOW_TMP_DIR */
+  tmpDir?: string;
+  /** 固化脚本目录（save 目标）；缺省 DEFAULT_WORKFLOW_SAVED_DIR */
+  savedDir?: string;
+}
+
 // ── Path helpers (computed at call time to respect cwd changes in tests) ──
 
-function getTmpDir(): string {
-  return resolve(".pi/workflows/.tmp");
+function getTmpDir(options?: WorkflowDirOptions): string {
+  return resolve(options?.tmpDir ?? DEFAULT_WORKFLOW_TMP_DIR);
 }
 
-function getSavedDir(): string {
-  return resolve(".pi/workflows");
+function getSavedDir(options?: WorkflowDirOptions): string {
+  return resolve(options?.savedDir ?? DEFAULT_WORKFLOW_SAVED_DIR);
 }
 
 // ── Save ──────────────────────────────────────────────────────
 
 /**
- * 保存临时 workflow：.pi/workflows/.tmp/{name}.js → .pi/workflows/{newName||name}.js
+ * 保存临时 workflow：{tmpDir}/{tmpName}.js → {savedDir}/{newName||tmpName}.js
  * 用 rename（tmp 文件保存后消失）。仅 project scope。
  *
  * 直接按路径查找 tmp 文件，不调 config-loader 全扫——save 只需知道 tmp 文件
  * 的路径，不需要 meta 提取或跨目录去重。
  *
+ * @param options 目录注入（缺省 pi 布局；pi 现两参调用形态行为不变，W4 向后兼容）
  * @throws 若 tmp workflow 不存在、目标已存在、或 rename 失败
  */
-export async function saveWorkflow(tmpName: string, newName?: string): Promise<string> {
-  const srcPath = resolve(getTmpDir(), `${tmpName}.js`);
+export async function saveWorkflow(
+  tmpName: string,
+  newName?: string,
+  options?: WorkflowDirOptions,
+): Promise<string> {
+  const srcPath = resolve(getTmpDir(options), `${tmpName}.js`);
   if (!existsSync(srcPath)) {
     throw new Error(`Temporary workflow '${tmpName}' not found`);
   }
 
   const destName = newName ?? tmpName;
-  const savedDir = getSavedDir();
+  const savedDir = getSavedDir(options);
   const destPath = resolve(savedDir, `${destName}.js`);
 
   if (existsSync(destPath)) {
@@ -57,18 +81,20 @@ export async function saveWorkflow(tmpName: string, newName?: string): Promise<s
 /**
  * 删除 workflow 脚本文件（tmp 或 saved）。
  * @param isRunning 回调，判断某 name 是否正在运行（运行中拒绝删除）
+ * @param options 目录注入（缺省 pi 布局；pi 现两参调用形态行为不变，W4 向后兼容）
  * @throws 若正在运行、或文件不存在
  */
 export function deleteWorkflow(
   name: string,
   isRunning: (name: string) => boolean,
+  options?: WorkflowDirOptions,
 ): string {
   if (isRunning(name)) {
     throw new Error(`Cannot delete '${name}': workflow is currently running. Abort it first.`);
   }
 
-  const tmpDir = getTmpDir();
-  const savedDir = getSavedDir();
+  const tmpDir = getTmpDir(options);
+  const savedDir = getSavedDir(options);
   const candidates = [
     resolve(tmpDir, `${name}.js`),
     resolve(savedDir, `${name}.js`),

package/src/orchestration/workflow-run-summary.ts

@@ -0,0 +1,69 @@
+/**
+ * WorkflowRun 摘要投影（设计 D8/B5 —— U7）。
+ *
+ * 「宿主各写一遍」域的收口：pi tool-workflow.toRunSummary 与 zsw
+ * orchestration-host 投影的字段集已实锤分叉（workflow vs name），本模块以 core
+ * WorkflowRun 为准提供单一投影，宿主可在此基础上扩展自己的投影字段
+ * （如 pi 版的 stateFile 需要 RunStore，归宿主扩展——core 不依赖具体 store 实例）。
+ *
+ * 层归属：Engine（纯投影，零 IO、零依赖）。字段名对齐 pi 版（name = scriptName）。
+ */
+
+import type { RunStatus, DoneReason } from "./models/types.ts";
+import type { WorkflowRun } from "./models/workflow-run.ts";
+
+/**
+ * WorkflowRun 的可序列化摘要（status action / 列表渲染用）。
+ *
+ * 字段与 pi tool-workflow.toRunSummary 一致（去除依赖 RunStore 的 stateFile——
+ * 宿主可扩展投影自行追加）。slug 旧持久化 run 可能缺失（undefined 保真透传）。
+ */
+export interface WorkflowRunSummary {
+  runId: string;
+  /** 脚本身份名（spec.scriptName）。 */
+  name: string;
+  /** run 级简短标签（可选，旧持久化 run 缺失）。 */
+  slug?: string;
+  status: RunStatus;
+  reason?: DoneReason;
+  /** ISO 时间戳，run 创建/启动时刻。 */
+  startedAt: string;
+  /** ISO 时间戳，transition("done") 时设置；running run 为 undefined。 */
+  completedAt?: string;
+  /** 失败/中止原因（state.error）。 */
+  error?: string;
+}
+
+/**
+ * WorkflowRun → 摘要投影。纯函数，不读 store、不发事件。
+ *
+ * @param run 聚合根（running 或 done 均可投影）
+ */
+export function runSummary(run: WorkflowRun): WorkflowRunSummary {
+  return {
+    runId: run.runId,
+    name: run.spec.scriptName,
+    slug: run.spec.slug,
+    status: run.state.status,
+    reason: run.state.reason,
+    startedAt: run.meta.startedAt,
+    completedAt: run.meta.completedAt,
+    error: run.state.error,
+  };
+}
+
+/**
+ * 判断是否存在指定名字、仍在 running 的 workflow script。
+ *
+ * pi 版遍历全部 session 的 runs（两层循环）；core 版收口为单 runs Map——
+ * per-session 隔离由调用方（宿主逐 session 调用或传入聚合 Map）负责。
+ *
+ * @param runs run 注册表（runId → WorkflowRun）
+ * @param name script 名（按 spec.scriptName 精确匹配）
+ */
+export function isScriptRunning(runs: Map<string, WorkflowRun>, name: string): boolean {
+  for (const run of runs.values()) {
+    if (run.spec.scriptName === name && run.state.status === "running") return true;
+  }
+  return false;
+}

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

@@ -29,6 +29,28 @@ import {
   type WorkflowScanConfig,
 } from "./config-loader.ts";
 
+// ── barrel 导出面（sink 设计 U1：WorkflowScript 实体 + 按路径加载工厂）──
+
+// WorkflowScript 类（实体：sourceCode/validate/toExecutable 收敛）导出给 barrel
+// re-export——第三宿主仅凭导出面即可消费实体（G3），不再鸭子复刻整类（§2.2 A2）。
+export { WorkflowScript };
+
+/**
+ * 按绝对路径加载单个 workflow 脚本的自由函数工厂（U1）。
+ *
+ * 与 `new WorkflowScriptRegistryImpl().getPath(path)` 等价的无状态形态：barrel
+ * 消费面（zsw vendor / 第三宿主）不暴露 registry 实例时的一次性加载入口。底层走
+ * getWorkflowByPath 的 60s TTL 缓存与 m5 mtime 缓存层，重复调用不重复读盘。
+ *
+ * 返回 undefined：引用非法（相对路径 / 非 .js / 含 `..` 段——normalizeRef 拒绝）。
+ * 返回 available=false 的 stub：文件不可读或 meta 提取失败（loader never throws）。
+ */
+export async function loadWorkflowScriptByPath(
+  path: string,
+): Promise<WorkflowScript | undefined> {
+  return new WorkflowScriptRegistryImpl().getPath(path);
+}
+
 // ── WorkflowScriptRegistryImpl ───────────────────────────────
 
 /**
@@ -40,7 +62,7 @@ import {
 export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
   constructor(private readonly config?: WorkflowScanConfig) {}
 
- /**
+  /**
 	 * 扫描所有 workflow 脚本（project + user + tmp），按 tmp>project>user 优先级
 	 * 去重，返回 WorkflowScript 实体数组（含 available=false 的解析失败项）。
 	 *
@@ -53,7 +75,7 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
     return metas.map((m) => this.toScript(m));
   }
 
- /**
+  /**
 	 * 按名查单个脚本。精确匹配。
 	 * 返回 undefined 当 name 不存在。
 	 *
@@ -70,7 +92,7 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
     return meta ? this.toScript(meta) : undefined;
   }
 
- /**
+  /**
   * 按绝对路径加载单个脚本（S2 路径统一）。任意路径（不限扫描源）。
   * 供 workflow tool 的 run/info（name 参数 = workflowRef）。
   */
@@ -79,12 +101,12 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
     return meta ? this.toScript(meta) : undefined;
   }
 
- /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
+  /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
   invalidate(): void {
     invalidateCache();
   }
 
- /**
+  /**
  * 把 CachedWorkflowMeta 转换为 WorkflowScript 实体。
  *
  * m2：整对象透传——m 已是 WorkflowMeta（CachedWorkflowMeta extends WorkflowMeta），
@@ -95,8 +117,8 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
  * available：meta 提取失败或文件不可读时为 false。
  */
   private toScript(m: CachedWorkflowMeta): WorkflowScript {
- // FR-2: registry 是唯一读文件处。readFileSync 填 sourceCode —— 这样 launcher/tool
- // 直接调 toExecutable/validate 即可，无需各自 readFile（避免重复读，60s TTL 缓存生效）。
+    // FR-2: registry 是唯一读文件处。readFileSync 填 sourceCode —— 这样 launcher/tool
+    // 直接调 toExecutable/validate 即可，无需各自 readFile（避免重复读，60s TTL 缓存生效）。
     let sourceCode = "";
     let available = m.available;
     if (available) {
@@ -111,8 +133,8 @@ export class WorkflowScriptRegistryImpl implements WorkflowScriptRegistry {
           sourceCode = cachedContent;
         }
       } catch {
- // 文件不可读（race condition 删除、权限等）——标 available=false，
- // 与 meta 提取失败的现有语义一致（loader "never throws"）。
+        // 文件不可读（race condition 删除、权限等）——标 available=false，
+        // 与 meta 提取失败的现有语义一致（loader "never throws"）。
         sourceCode = "";
         available = false;
       }

package/src/shared/__tests__/agent-ref.test.ts

@@ -1,11 +1,19 @@
 /**
- * displayAgentName 测试：agent ref 绝对路径 → UI 显示短名（basename 去 .md）。
+ * agent-ref 测试：displayAgentName 短名投影 + normalizeRef `..` 段拒绝（⛔2 样本集）
+ * + invalidAgentRefMessage 文案工厂 + normalizeWorkflowRef 三分裁决（sink 设计 U1）。
  *
  * 数据层不变式（displayAgentName 只服务显示出口）：非路径值原样返回。
  */
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 
-import { displayAgentName } from "../agent-ref.ts";
+import {
+  displayAgentName,
+  invalidAgentRefMessage,
+  normalizeRef,
+  normalizeWorkflowRef,
+} from "../agent-ref.ts";
 
 describe("displayAgentName", () => {
   it("mac/linux 绝对路径取 basename 并去 .md", () => {
@@ -32,3 +40,202 @@ describe("displayAgentName", () => {
     expect(displayAgentName("worker.md")).toBe("worker");
   });
 });
+
+// ── ⛔2：`..` 段拒绝（sink 设计声明行为变更——现状两宿主均放行，收紧为安全修复）──
+
+describe("normalizeRef `..` 段拒绝（⛔2 样本集）", () => {
+  it("agent .md 面：/x/../y.md 拒绝", () => {
+    expect(normalizeRef("/x/../y.md", ".md")).toBeNull();
+  });
+
+  it("workflow .js 面：/x/../y.js 拒绝（normalizeRef 为 agent/workflow 双消费面）", () => {
+    expect(normalizeRef("/x/../y.js", ".js")).toBeNull();
+  });
+
+  it("~/ 开头合法路径不误伤（展开后无 .. 段照常通过）", () => {
+    expect(normalizeRef("~/agents/worker.md", ".md")).toBe(join(homedir(), "agents/worker.md"));
+  });
+
+  it("~/ 展开后含 .. 段同样拒绝（收紧的一致延伸，显式声明）", () => {
+    expect(normalizeRef("~/../x.md", ".md")).toBeNull();
+  });
+
+  it("无扩展名校验面同样拒绝（收紧在 ext 校验之前）", () => {
+    expect(normalizeRef("/x/../y.md")).toBeNull();
+  });
+
+  it("中段/尾段/多段 .. 均拒绝", () => {
+    expect(normalizeRef("/a/../b/c.md", ".md")).toBeNull();
+    expect(normalizeRef("/a/b/..", ".md")).toBeNull();
+    expect(normalizeRef("/a/../b/../c.md", ".md")).toBeNull();
+  });
+
+  it("windows 反斜杠分隔的 .. 段同样拒绝", () => {
+    expect(normalizeRef("C:\\x\\..\\y.md", ".md")).toBeNull();
+  });
+
+  it(". 段与 .. 前缀文件名不误伤（最小收紧：只拒 .. 路径段）", () => {
+    expect(normalizeRef("/x/./y.md", ".md")).toBe("/x/./y.md");
+    expect(normalizeRef("/x/..foo.md", ".md")).toBe("/x/..foo.md");
+  });
+
+  it("既有行为保持：空/相对路径/扩展名不符仍 null，普通绝对路径通过", () => {
+    expect(normalizeRef("", ".md")).toBeNull();
+    expect(normalizeRef("worker.md", ".md")).toBeNull();
+    expect(normalizeRef("/x/y.js", ".md")).toBeNull();
+    expect(normalizeRef("/x/y.md", ".md")).toBe("/x/y.md");
+  });
+});
+
+// ── 报错文案工厂（sink 设计 U1：口径收敛单点）──
+
+describe("invalidAgentRefMessage", () => {
+  it("非 .. 形态：与 AgentRegistry.loadByPath 既有 throw 文案逐字一致（基准口径）", () => {
+    expect(invalidAgentRefMessage("worker")).toBe(
+      "Invalid agent ref: worker. Agent refs must be absolute paths to .md files (use <location> from <available_subagents>).",
+    );
+  });
+
+  it(".. 形态：附纠正指引（含 .. 段说明与注入段 location 指引）", () => {
+    const msg = invalidAgentRefMessage("/x/../y.md");
+    expect(msg).toMatch(/^Invalid agent ref: \/x\/\.\.\/y\.md\./);
+    expect(msg).toContain('without ".." path segments');
+    expect(msg).toContain("<location> from <available_subagents>");
+  });
+
+  it("howToList 注入：第三宿主清单段名替换缺省 <available_subagents>", () => {
+    expect(invalidAgentRefMessage("worker", { howToList: "<available_agents>" })).toContain(
+      "use <location> from <available_agents>",
+    );
+  });
+});
+
+// ── workflow ref 原语（sink 设计 U1：名/路径二分 + 保留字裁决 + 内置名优先）──
+
+describe("normalizeWorkflowRef 三分裁决", () => {
+  const knownNames = ["review-fix-loop", "chain", "my-user-wf"];
+
+  it("裸名分支：命中 knownNames → name（内置名优先——命中即用，不猜路径）", () => {
+    expect(normalizeWorkflowRef("review-fix-loop", { knownNames })).toEqual({
+      kind: "name",
+      name: "review-fix-loop",
+    });
+    expect(normalizeWorkflowRef("my-user-wf", { knownNames })).toEqual({
+      kind: "name",
+      name: "my-user-wf",
+    });
+  });
+
+  it("裸名分支：未命中 knownNames → invalid/unknown_name", () => {
+    expect(normalizeWorkflowRef("no-such-wf", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: "no-such-wf",
+      reason: "unknown_name",
+    });
+  });
+
+  it("裸名分支：缺省 knownNames → 无已知名，全部裸名 unknown_name", () => {
+    expect(normalizeWorkflowRef("review-fix-loop")).toEqual({
+      kind: "invalid",
+      ref: "review-fix-loop",
+      reason: "unknown_name",
+    });
+  });
+
+  it("保留字裁决：. 与 .. 拒绝（reserved）", () => {
+    expect(normalizeWorkflowRef(".", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: ".",
+      reason: "reserved",
+    });
+    expect(normalizeWorkflowRef("..", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: "..",
+      reason: "reserved",
+    });
+  });
+
+  it("保留字优先于 knownNames（宿主清单异常含保留字也不放行）", () => {
+    expect(normalizeWorkflowRef("..", { knownNames: ["chain", ".."] })).toEqual({
+      kind: "invalid",
+      ref: "..",
+      reason: "reserved",
+    });
+  });
+
+  it("空引用：empty（首尾空白 trim 后同判）", () => {
+    expect(normalizeWorkflowRef("")).toEqual({ kind: "invalid", ref: "", reason: "empty" });
+    expect(normalizeWorkflowRef("   ")).toEqual({ kind: "invalid", ref: "   ", reason: "empty" });
+  });
+
+  it("路径分支：绝对 .js 路径 → path", () => {
+    expect(normalizeWorkflowRef("/proj/wf.js", { knownNames })).toEqual({
+      kind: "path",
+      path: "/proj/wf.js",
+    });
+  });
+
+  it("路径分支：~/ 前缀展开为 homedir 绝对路径", () => {
+    expect(normalizeWorkflowRef("~/wf.js", { knownNames })).toEqual({
+      kind: "path",
+      path: join(homedir(), "wf.js"),
+    });
+  });
+
+  it("路径分支：.. 段拒绝（⛔2 同面——路径域收紧对 workflow 原语生效）", () => {
+    expect(normalizeWorkflowRef("/x/../y.js", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: "/x/../y.js",
+      reason: "parent_segment",
+    });
+  });
+
+  it("路径分支：相对路径 not_absolute、非 .js 扩展名 bad_ext", () => {
+    // "wf.js" 无分隔符是合法裸名形态（workflow 名可含点号）→ 走名分支不猜路径
+    expect(normalizeWorkflowRef("wf.js", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: "wf.js",
+      reason: "unknown_name",
+    });
+    // 显式相对路径形态（含分隔符）→ 路径分支
+    expect(normalizeWorkflowRef("./wf.js", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: "./wf.js",
+      reason: "not_absolute",
+    });
+    expect(normalizeWorkflowRef("/proj/wf.txt", { knownNames })).toEqual({
+      kind: "invalid",
+      ref: "/proj/wf.txt",
+      reason: "bad_ext",
+    });
+  });
+
+  it("路径分支失败原因优先级：.. 段先于扩展名判定", () => {
+    expect(normalizeWorkflowRef("/x/../y.txt")).toEqual({
+      kind: "invalid",
+      ref: "/x/../y.txt",
+      reason: "parent_segment",
+    });
+  });
+
+  it("路径分支失败原因优先级：.. 段先于绝对路径判定（重放顺序对齐 normalizeRef 判序）", () => {
+    // 相对路径 + 含 .. 段：normalizeRef 实际因 parent_segment 先判拒绝，归因
+    // 不得误报 not_absolute（否则指引改绝对路径后仍被 .. 段拒绝——两步误导）
+    expect(normalizeWorkflowRef("a/../b.js")).toEqual({
+      kind: "invalid",
+      ref: "a/../b.js",
+      reason: "parent_segment",
+    });
+  });
+
+  it("裸名与路径天然二分：名字是简单标识符，含分隔符即归路径分支（对齐 pi 现行为）", () => {
+    // 名字不撞路径：knownNames 命中不受路径分支影响
+    expect(normalizeWorkflowRef("chain", { knownNames: ["chain"] }).kind).toBe("name");
+    // 同串含分隔符后不再是名引用（绝对路径形态但缺 .js 后缀 → bad_ext）
+    expect(normalizeWorkflowRef("/chain", { knownNames: ["chain"] })).toEqual({
+      kind: "invalid",
+      ref: "/chain",
+      reason: "bad_ext",
+    });
+  });
+});