@zhushanwen/subagent-core 0.2.0

package/workflows/map-reduce.js

@@ -0,0 +1,180 @@
+// map-reduce.js — 映射-归约（通用 subagent 编排）
+//
+// 模式（两段）：
+//   段 1 map:    parallel() 对每个 item 并行执行 operation
+//   段 2 reduce: agent() 把所有 map 结果归约成单一结果
+//
+// 与 scatter-gather 的区别：scatter-gather 强调"拆分"（scatter 决定子任务数）；
+// map-reduce 强调对"已知 items 数组"的变换+聚合（items 已有，map 变换、reduce 归约）。
+//
+// 用法：
+//   workflow run map-reduce --args 'items=["file1.ts","file2.ts","file3.ts"]' --args operation="审查代码风格"
+//   workflow run map-reduce --args itemsJson=/path/to/items.json --args operation="..."
+//
+// ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
+
+/* @pi-meta
+name: map-reduce
+description: 通用编排：parallel map → reduce 两段，处理已知 items 数组
+phases: [map, reduce]
+parameters:
+  type: object
+  properties:
+    items: { type: array, items: { type: string } }
+    itemsJson: { type: string }
+    operation: { type: string }
+    agents: { type: string }
+  required: [operation]
+  oneOf:
+    - required: [items]
+    - required: [itemsJson]
+usage: |
+  ## 使用说明
+  - items 与 itemsJson 至少一个：items 直接传字符串数组，itemsJson 传文件路径（内容为 JSON 数组）
+  - agents：逗号分隔的 agent .md 绝对路径，按顺序对应 map/reduce 两段
+  - 示例：workflow run map-reduce --args operation="<对每个 item 做什么>" itemsJson="/path/items.json" agents="/path/mapper.md,/path/reducer.md"
+*/
+
+const fs = require("fs");
+
+// ── 入参（$ARGS）──────────────────────────────────────────────────
+const operation = $ARGS.operation;
+if (!operation) {
+  throw new Error(
+    'map-reduce 缺少必需参数 operation。用法：workflow run map-reduce --args operation="<对每个 item 做什么>"',
+  );
+}
+
+// items 来源：直接数组 或 itemsJson 文件路径（二选一）
+let items = $ARGS.items;
+if (!items) {
+  const itemsPath = $ARGS.itemsJson;
+  if (!itemsPath) {
+    throw new Error(
+      'map-reduce 需要 items（直接数组）或 itemsJson（JSON 文件路径）参数',
+    );
+  }
+  if (!fs.existsSync(itemsPath)) {
+    throw new Error("itemsJson 文件不存在: " + itemsPath);
+  }
+  items = JSON.parse(fs.readFileSync(itemsPath, "utf-8"));
+}
+
+if (!Array.isArray(items) || items.length === 0) {
+  throw new Error("items 不是数组或为空");
+}
+
+log("map-reduce 开始，items=" + items.length + " 个，operation=" + operation);
+
+// S4：agents 参数 = 逗号分隔的 agentRef 路径数组，按顺序对应 map/reduce 两段
+// worker 沙箱为 eval 模式：require 相对路径以 cwd 为基准（非脚本目录），
+// 必须用 workerData.scriptPath 锚定脚本目录（review-fix-loop 同模式）；
+// scriptPath 注入是 worker 契约的显式前提（D1 加固），缺席即 fail-fast，
+// 不回退 cwd——消除从用户目录误加载/被植入同名 _shared/agent-refs.cjs 的代码加载面。
+if (typeof workerData === "undefined" || !workerData || typeof workerData.scriptPath !== "string") {
+  throw new Error("map-reduce: core_module_load_failed: workerData.scriptPath 缺失，无法定位 workflows/_shared/agent-refs.cjs。" +
+    "恢复动作：worker 宿主（WorkerHost）启动 worker 时必须经 workerData 注入 scriptPath" +
+    "（指向本脚本真实路径，注入点见 src/orchestration/worker-host.ts 的 workerData 组装处），" +
+    "禁止依赖 process.cwd() 巧合。");
+}
+const SCRIPT_DIR = require("path").dirname(workerData.scriptPath);
+const { parseAgentRefs, agentRefAt } = require(SCRIPT_DIR + "/_shared/agent-refs.cjs");
+const agentRefs = parseAgentRefs($ARGS.agents);
+const stepAgent = (i) => { const ref = agentRefAt(agentRefs, i); return ref ? { agent: ref } : {}; };
+
+let currentPhase = "init";
+let outcome;
+
+try {
+  // ── 段 1：map（parallel 对每个 item 并行变换）────────────────────
+  phase("map");
+  currentPhase = "map";
+
+  // 每个 item 字符串化，便于拼进 prompt
+  const mappedRaw = await parallel(
+    items.map((item, idx) =>
+      agent({
+        prompt:
+          "对以下 item 执行操作：\n\noperation：" + operation +
+          "\nitem：" + (typeof item === "string" ? item : JSON.stringify(item)),
+        schema: {
+          type: "object",
+          properties: {
+            itemIndex: { type: "number", description: "item 序号" },
+            mapped: { type: "string", description: "map 后的结果" },
+          },
+          required: ["itemIndex", "mapped"],
+        },
+        description: "map-reduce-map-" + idx,
+        ...stepAgent(0),
+      })
+    ),
+  );
+
+  const mapped = [];
+  let mapFailed = 0;
+  for (let i = 0; i < mappedRaw.length; i++) {
+    const r = mappedRaw[i];
+    if (!r || r.status === "failed" || r.error) {
+      mapped.push({
+        itemIndex: i,
+        item: items[i],
+        status: "failed",
+        error: r ? (r.error || "agent 返回 failed 状态") : "agent 无返回",
+      });
+      mapFailed++;
+    } else {
+      mapped.push({
+        itemIndex: i,
+        item: items[i],
+        status: "ok",
+        mapped: (typeof r.mapped === "string" ? r.mapped : "(无结果)"),
+      });
+    }
+  }
+  if (mapFailed === items.length) {
+    throw new Error("全部 map 失败（" + mapFailed + "/" + items.length + "）");
+  }
+  log("map 完成：ok=" + (items.length - mapFailed) + " failed=" + mapFailed);
+
+  // ── 段 2：reduce（agent 归约所有 map 结果）──────────────────────
+  phase("reduce");
+  currentPhase = "reduce";
+
+  const reducedResult = await agent({
+    prompt:
+      "以下是对 " + items.length + " 个 item 执行「" + operation + "」的结果，请归约成单一结论：\n\n" +
+      JSON.stringify(mapped, null, 2),
+    schema: {
+      type: "object",
+      properties: {
+        reduced: { type: "string", description: "归约后的最终结果" },
+        stats: { type: "string", description: "统计摘要（成功率/共性发现等）" },
+      },
+      required: ["reduced", "stats"],
+    },
+    description: "map-reduce-reduce",
+    ...stepAgent(1),
+  });
+
+  outcome = {
+    status: mapFailed > 0 ? "partial" : "ok",
+    phases_run: ["map", "reduce"],
+    items_total: items.length,
+    items_mapped: items.length - mapFailed,
+    reduced: {
+      reduced: (reducedResult?.reduced ?? "(归约无结果)"),
+      stats: (reducedResult?.stats ?? "(归约无结果)"),
+    },
+    message: "map-reduce 完成：map " + items.length + " 项（失败 " + mapFailed + "）→ reduce",
+  };
+} catch (err) {
+  outcome = {
+    status: "error",
+    phase: currentPhase,
+    error: err && err.message ? err.message : String(err),
+    message: "map-reduce 在 " + currentPhase + " 段失败",
+  };
+}
+
+return outcome;

package/workflows/parallel.js

@@ -0,0 +1,154 @@
+// parallel.js — 并行多视角分析（通用 subagent 编排）
+//
+// 模式：N 个 agent 从不同角度并行分析同一目标 → 汇总聚合。
+// 适用于需要多维度评估（安全/性能/可维护性等）的场景。
+//
+// 用法：
+//   workflow run parallel --args target="src/auth/login.ts"
+//   workflow run parallel --args target="..." --args 'perspectives=["security","readability"]'
+//
+// ⚠️ 分层配额规则（来源：ADR-030 决策 3）：
+//   - 全局并发上限 maxConcurrent = 6
+//   - parallel() 内的 agent() 调用共享配额池，超出自动排队（不报错）
+//   - 本脚本默认 3 视角并行，配额充足
+//
+// ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口，禁止 bare IIFE
+
+/* @pi-meta
+name: parallel
+description: 通用编排：多视角并行分析同一目标，再聚合汇总
+phases: [parallel-analyze, aggregate]
+parameters:
+  type: object
+  properties:
+    target: { type: string }
+    perspectives: { type: array, items: { type: string } }
+    agents: { type: string }
+  required: [target]
+usage: |
+  ## 使用说明
+  - 多视角并行分析后聚合；perspectives 缺省用 3 个默认视角
+  - agents：逗号分隔的 agent .md 绝对路径；1 个应用于所有视角，N 个一一对应视角数
+  - 示例：workflow run parallel --args target="<分析目标>" agents="/path/analyst.md"
+*/
+
+// ── 入参（$ARGS）──────────────────────────────────────────────────
+const target = $ARGS.target;
+if (!target) {
+  throw new Error("parallel 缺少必需参数 target。用法：workflow run parallel --args target=\"<分析目标>\"");
+}
+const perspectives = Array.isArray($ARGS.perspectives) && $ARGS.perspectives.length > 0
+  ? $ARGS.perspectives
+  : ["security", "performance", "maintainability"];
+if (perspectives.some((p) => typeof p !== "string")) {
+  throw new Error("parallel 参数 perspectives 必须是字符串数组，实际含非字符串元素");
+}
+
+// S4：agents 参数 = 逗号分隔的 agentRef 路径数组；1 个 = 所有视角，N 个 = 一一对应
+// worker 沙箱为 eval 模式：require 相对路径以 cwd 为基准（非脚本目录），
+// 必须用 workerData.scriptPath 锚定脚本目录（review-fix-loop 同模式）；
+// scriptPath 注入是 worker 契约的显式前提（D1 加固），缺席即 fail-fast，
+// 不回退 cwd——消除从用户目录误加载/被植入同名 _shared/agent-refs.cjs 的代码加载面。
+if (typeof workerData === "undefined" || !workerData || typeof workerData.scriptPath !== "string") {
+  throw new Error("parallel: core_module_load_failed: workerData.scriptPath 缺失，无法定位 workflows/_shared/agent-refs.cjs。" +
+    "恢复动作：worker 宿主（WorkerHost）启动 worker 时必须经 workerData 注入 scriptPath" +
+    "（指向本脚本真实路径，注入点见 src/orchestration/worker-host.ts 的 workerData 组装处），" +
+    "禁止依赖 process.cwd() 巧合。");
+}
+const SCRIPT_DIR = require("path").dirname(workerData.scriptPath);
+const { parseAgentRefs, agentRefAt } = require(SCRIPT_DIR + "/_shared/agent-refs.cjs");
+const agentRefs = parseAgentRefs($ARGS.agents);
+const agentFor = (i) => {
+  if (agentRefs.length === 1) return { agent: agentRefs[0] };
+  const ref = agentRefAt(agentRefs, i);
+  return ref ? { agent: ref } : {};
+};
+
+log("parallel 开始，target=" + target + " perspectives=" + JSON.stringify(perspectives) + (agentRefs.length ? " agents=" + agentRefs.join(",") : ""));
+
+let currentPhase = "init";
+let outcome;
+
+try {
+  // ── 段 1：parallel-analyze（多视角并行分析）──────────────────────
+  phase("parallel-analyze");
+  currentPhase = "parallel-analyze";
+
+  // parallel() 接受 Promise 数组；agent() 返回 Promise。allSettled 语义。
+  const perPerspectiveRaw = await parallel(
+    perspectives.map((p, i) =>
+      agent({
+        prompt:
+          "从「" + p + "」角度分析以下目标，给出评分和发现的问题：\n\n" + target,
+        schema: {
+          type: "object",
+          properties: {
+            perspective: { type: "string", description: "视角名称" },
+            score: { type: "number", description: "0-10 评分" },
+            findings: {
+              type: "array",
+              items: { type: "string" },
+              description: "发现的问题",
+            },
+          },
+          required: ["perspective", "score", "findings"],
+        },
+        description: "parallel-" + p,
+        ...agentFor(i),
+      })
+    ),
+  );
+
+  // 收集结果，标记成功/失败
+  const perPerspective = [];
+  let failedCount = 0;
+  for (let i = 0; i < perPerspectiveRaw.length; i++) {
+    const r = perPerspectiveRaw[i];
+    if (!r || r.status === "failed" || r.error) {
+      perPerspective.push({
+        perspective: perspectives[i],
+        status: "failed",
+        error: r ? (r.error || "agent 返回 failed 状态") : "agent 无返回",
+      });
+      failedCount++;
+    } else {
+      perPerspective.push({
+        perspective: perspectives[i],
+        status: "ok",
+        score: typeof r.score === "number" ? r.score : undefined,
+        findings: Array.isArray(r.findings) ? r.findings : [],
+      });
+    }
+  }
+  if (failedCount === perspectives.length) {
+    throw new Error("全部视角分析失败（" + failedCount + "/" + perspectives.length + "）");
+  }
+  log("parallel-analyze 完成：ok=" + (perspectives.length - failedCount) + " failed=" + failedCount);
+
+  // ── 段 2：aggregate（汇总多视角结果）────────────────────────────
+  phase("aggregate");
+  currentPhase = "aggregate";
+
+  // 纯代码合并：拼接各视角发现的问题（不调用 LLM）
+  const aggregateResult = perPerspective
+    .map((p) => "[" + (p.perspective || "?") + "] " + (p.findings ? p.findings.join("; ") : "(no findings)"))
+    .join("\n");
+
+  outcome = {
+    status: failedCount > 0 ? "partial" : "ok",
+    phases_run: ["parallel-analyze", "aggregate"],
+    perspectives_analyzed: perspectives.length,
+    per_perspective: perPerspective,
+    aggregate: aggregateResult,
+    message: "parallel 完成：" + perspectives.length + " 视角（失败 " + failedCount + "）→ 聚合",
+  };
+} catch (err) {
+  outcome = {
+    status: "error",
+    phase: currentPhase,
+    error: err && err.message ? err.message : String(err),
+    message: "parallel 在 " + currentPhase + " 段失败",
+  };
+}
+
+return outcome;