@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/workflows/README.md

@@ -1,6 +1,6 @@
 # 内置通用编排 Workflow
 
-4 个开箱即用的通用 subagent 编排 workflow，覆盖日常常见的多 agent 协作模式。每个脚本用 `agent()`/`parallel()` 自包含实现，`workflow run <name>` 直接执行，无需额外定义子 workflow。
+5 个开箱即用的通用 subagent 编排 workflow，覆盖日常常见的多 agent 协作模式。每个脚本用 `agent()`/`parallel()` 自包含实现，`workflow run <name>` 直接执行，无需额外定义子 workflow。
 
 ## 文件清单
 
@@ -56,26 +56,26 @@ workflow run map-reduce --args itemsJson=/path/to/items.json --args operation=".
 
 ```
 workflow run review-fix-loop --args targetType=git-diff target=main \
-  --args batch1=fallow-scan --args batch2=reviewer --args autoCommit=true
+  --args fallowScan=true --args batch1=/path/to/reviewer.md --args autoCommit=true
 workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
-  --args batch1=doc-reviewer
+  --args batch1=/path/to/doc-reviewer.md
 ```
 
 - `targetType` 枚举：`git-diff`（target=base ref）/ `file`（target=路径）/ `dir`（target=目录）/ `text`（target=自由描述）
 - `batch1..batchN`：批串行，批内并行 review → aggregate → fix → 重审直到 clean；批次用于前置依赖（如 `fallow-scan` 静态分析先行，后续审查才有意义）
 - 批内某 agent 无 must-fix 后后续轮跳过（`skipCleanAgents` 默认 true + `recheckAfterFix` 默认 false）：clean agent 下轮跳过不重派；显式传 `recheckAfterFix=true` 启用强回归模式——fix 后重派全批，clean agent 走限定 prompt（只审 modifiedFiles ∪ 自检关联点，不诱导全量重扫）
-- agent 项支持：AgentRegistry 名（如 `reviewer`）/ 自定义 .md 文件路径（如 `batch1=/path/to/reviewer.md`）/ 内置 `fallow-scan` / **内置 `doc-reviewer`**（文档场景推荐：`targetType=file/dir` + `batch1=doc-reviewer`，四遍审查方法论：事实锚点核实/逻辑断言验证/落地清单完备性/边界与迁移；无 write 工具，报告经 schema 返回由 workflow 落盘）
-- `fixAgent`（可选）：fix 阶段加载指定 agent（内置名或 .md 路径）；代码场景可在该 agent.md 内写 verify 命令（typecheck/test 实测）当轮拦截编译类回归。⚠️ agent.md 内写的 verify 命令**必须确认能在目标项目可运行**（target 的包管理器/目录结构未知），否则命令失败会误报 fix 状态
+- agent 项仅支持 .md 文件绝对路径（如 `batch1=/path/to/reviewer.md`，`~/` 前缀可展开；内置角色取 <available_subagents> 注入的 <location> 路径，名字只是展示标签，裸名会被拒）；`fallow-scan` 静态分析不走 agent 项——由独立参数 `fallowScan=true` 前置插入首批（不占 batchN）；**内置 `doc-reviewer`**（文档场景推荐：`targetType=file/dir` + `batch1=<doc-reviewer.md 的注入路径>`，四遍审查方法论：事实锚点核实/逻辑断言验证/落地清单完备性/边界与迁移；不写文件，报告经 schema 返回由 workflow 落盘）
+- `fixAgent`（可选）：fix 阶段加载指定 agent（.md 绝对路径，值语义同 batchN 的 agent 项）；代码场景可在该 agent.md 内写 verify 命令（typecheck/test 实测）当轮拦截编译类回归。⚠️ agent.md 内写的 verify 命令**必须确认能在目标项目可运行**（target 的包管理器/目录结构未知），否则命令失败会误报 fix 状态
 - `maxFixAttempts`（可选，默认 2）：needs-redesign 阈值。问题经 maxFixAttempts 次修复仍未收敛（regressed）→ 终止该批，terminated="needs-redesign"（结构性问题需人工介入，非继续补丁能解决）
 - `convergeNewIssues`（可选，默认 1）+ `convergeRounds`（可选，默认 2）：新发现率收敛阈值。连续 convergeRounds 轮新发现问题 ≤ convergeNewIssues **且**无 open/regressed 活跃条目 → terminated="converged"（推进下一批）。收敛不等于问题全清——需同时满足无活跃条目才终止
 - ⚠️ **fix 阶段会修改文件；`autoCommit` 默认 false（不 commit）**，需要提交时显式 `autoCommit=true`
 
 ## 编排 API
 
-这些 workflow 内部使用的编排函数（`agent()` / `parallel()` / `pipeline()` / `workflow()`）由 worker 线程注入，完整 API 参考见 `skills/workflow-script-format/SKILL.md`。
+这些 workflow 内部使用的编排函数（`agent()` / `parallel()` / `pipeline()` / `workflow()`）由 worker 线程注入，完整 API 参考见 workflow-script-format SKILL.md——该文档位于 pi 侧 subagent-workflow extension 内（`extensions/universal/subagent-workflow/skills/workflow-script-format/SKILL.md`，相对 pi extension 包根解析），**不是本包资产**，本包内无对应路径。
 
 ## 相关文档
 
-- `skills/workflow-script-format/SKILL.md` — workflow script 完整 API（agent/parallel/pipeline/workflow 签名、$ARGS/$BUDGET、lint 规则）
-- `docs/extensions/adr/pi-ext-030-subagents-workflow-merge.md` — 合并决策（决策 3 分层配额 + workflow 嵌套）
-- `docs/extensions/adr/pi-ext-032-builtin-orchestration-workflows.md` — 从"参考模板"改为"内置通用编排 workflow"的决策
+- workflow-script-format SKILL.md（位于 pi 侧 subagent-workflow extension，`extensions/universal/subagent-workflow/skills/workflow-script-format/`，非本包资产）— workflow script 完整 API（agent/parallel/pipeline/workflow 签名、$ARGS/$BUDGET、lint 规则）
+- `docs/extensions/adr/pi-ext-030-subagents-workflow-merge.md`（位于 workspace 仓根，非本包内路径）— 合并决策（决策 3 分层配额 + workflow 嵌套）
+- `docs/extensions/adr/pi-ext-032-builtin-orchestration-workflows.md`（位于 workspace 仓根，非本包内路径）— 从"参考模板"改为"内置通用编排 workflow"的决策

package/workflows/chain.js

@@ -4,7 +4,8 @@
 // 适用于需要"先分析、再变换、最后综合"的多阶段任务。
 //
 // 用法：
-//   workflow run chain --args task="把这段需求文档拆成技术任务：..."
+//   workflow run chain --args task="把这段需求文档拆成技术任务：..."（pi 宿主语法）
+//   zsw workflow --workflow chain --task "<任务书>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 //
 // ⚠️ lintScript 约束（本脚本已遵守）：
 //   - 含 agent() 入口
@@ -25,7 +26,8 @@ usage: |
   ## 使用说明
   - 顺序三步链：analyze（提取要点）→ transform（产出方案）→ synthesize（合成结论）
   - agents：逗号分隔的 agent .md 绝对路径，按顺序对应三步（少于 3 个尾部用默认执行者）
-  - 示例：workflow run chain --args task="<任务描述>" agents="/path/analyzer.md,/path/planner.md"
+  - 示例（pi 宿主语法）：workflow run chain --args task="<任务描述>" agents="/path/analyzer.md,/path/planner.md"
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow chain --task "<任务描述>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 */
 
 // ── 入参（$ARGS）──────────────────────────────────────────────────

package/workflows/map-reduce.js

@@ -8,8 +8,9 @@
 // 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="..."
+//   workflow run map-reduce --args 'items=["file1.ts","file2.ts","file3.ts"]' --args operation="审查代码风格"（pi 宿主语法）
+//   workflow run map-reduce --args itemsJson=/path/to/items.json --args operation="..."（pi 宿主语法）
+//   zsw workflow --workflow map-reduce --task "<任务书>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 //
 // ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
 
@@ -32,7 +33,8 @@ 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"
+  - 示例（pi 宿主语法）：workflow run map-reduce --args operation="<对每个 item 做什么>" itemsJson="/path/items.json" agents="/path/mapper.md,/path/reducer.md"
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow map-reduce --task "<任务书>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 */
 
 const fs = require("fs");

package/workflows/parallel.js

@@ -4,8 +4,9 @@
 // 适用于需要多维度评估（安全/性能/可维护性等）的场景。
 //
 // 用法：
-//   workflow run parallel --args target="src/auth/login.ts"
-//   workflow run parallel --args target="..." --args 'perspectives=["security","readability"]'
+//   workflow run parallel --args target="src/auth/login.ts"（pi 宿主语法）
+//   workflow run parallel --args target="..." --args 'perspectives=["security","readability"]'（pi 宿主语法）
+//   zsw workflow --workflow parallel --task "<分析目标>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 //
 // ⚠️ 分层配额规则（来源：ADR-030 决策 3）：
 //   - 全局并发上限 maxConcurrent = 6
@@ -29,7 +30,8 @@ usage: |
   ## 使用说明
   - 多视角并行分析后聚合；perspectives 缺省用 3 个默认视角
   - agents：逗号分隔的 agent .md 绝对路径；1 个应用于所有视角，N 个一一对应视角数
-  - 示例：workflow run parallel --args target="<分析目标>" agents="/path/analyst.md"
+  - 示例（pi 宿主语法）：workflow run parallel --args target="<分析目标>" agents="/path/analyst.md"
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow parallel --task "<分析目标>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 */
 
 // ── 入参（$ARGS）──────────────────────────────────────────────────

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

@@ -310,10 +310,16 @@ function normIssueId(s) {
  * fix 阶段（fix-attempted/deferred 标记）与 ES3 校验共用——精确键查表会把
  * "mf-1"/"MF-1 (fixed)" 等漂移 ID 判为未追踪，导致 fix-attempted → fixed/regressed
  * → needs-redesign 状态链静默失效；deferred 侧漂移则创建幽灵条目（原条目仍 open 阻塞收敛）。
+ *
+ * 首查必须 Object.hasOwn（上收 zsw 侧同款修复）：truthy 查表（issues[issueId]）会让
+ * 原型链键（"__proto__"/"toString"/"constructor"）误命中——ID 来自 LLM 产出，攻击面
+ * 真实存在；误命中会把非 own 键当台账键返回，后续 issues[key].severity 读取原型
+ * 成员（undefined 或函数）污染 fix 对账。归一化回退段的 Object.keys 只枚举 own 键，
+ * 本就无此问题。
  */
 function findIssueKey(issues, issueId) {
   if (!issues || typeof issueId !== "string" || !issueId) return undefined;
-  if (issues[issueId]) return issueId;
+  if (Object.hasOwn(issues, issueId)) return issueId;
   const norm = normIssueId(issueId);
   if (!norm) return undefined;
   for (const key of Object.keys(issues)) {
@@ -785,7 +791,9 @@ function resolveIssueIdentity(entry, { issues, dormant }) {
  */
 function translateId(idMap, id, issues) {
   if (typeof id !== "string" || !id) return id;
-  if (issues && issues[id]) return id;
+  // Object.hasOwn：truthy 查表会让原型链键（"__proto__"/"toString"）误判为台账键
+  // 直接返回，跳过 idMap 翻译（与 findIssueKey 同款加固，nextFreeId 键空间同理）。
+  if (issues && Object.hasOwn(issues, id)) return id;
   if (idMap && Object.prototype.hasOwnProperty.call(idMap, id)) return idMap[id];
   return id;
 }
@@ -1417,7 +1425,10 @@ const FALLOW_DEF = { name: "fallow-scan", title: "FALLOW STATIC ANALYSIS", repor
  *
  * - def 只含标识（path/name/report/title），**不读文件**——agent 内容的加载与 systemPrompt
  *   注入由主线程 resolveAgentOpts（agent-call 按 path 加载）统一完成
- * - `fallow-scan` 是脚本内部保留字（fallowScan 参数前置插入的首批），非用户参数值域
+ * - `fallow-scan` 是脚本内部保留字（fallowScan 参数前置插入的首批），非用户参数值域：
+ *   本函数对字面值仍静默映射 FALLOW_DEF（fallowScan 前置批与 batchN 兼容形态依赖此
+ *   映射），用户参数侧的拒收在脚本层——fixAgent=fallow-scan 由 review-fix-loop.js
+ *   在调用本函数前 fail-fast（RX2-F2），防 fix 派发静默退化为通用 subagent
  * @param batchNames 批内 agentRef 路径数组
  */
 function resolveAgentDefs(batchNames) {

package/workflows/review-fix-loop.js

@@ -22,9 +22,10 @@
 //
 // 用法：
 //   workflow run review-fix-loop --args targetType=git-diff target=main \
-//     batch1="/path/reviewer-a.md,/path/reviewer-b.md" autoCommit=true
+//     batch1="/path/reviewer-a.md,/path/reviewer-b.md" autoCommit=true（pi 宿主语法）
 //   workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
-//     batch1="/path/doc-reviewer.md" autoCommit=false
+//     batch1="/path/doc-reviewer.md" autoCommit=false（pi 宿主语法）
+//   zsw workflow --workflow review-fix-loop --task "<任务书>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag --target-type/--target/--batch1 等，语义见 @pi-meta parameters）
 //
 // S4 路径统一：batch1..batchN/fixAgent 值 = agentRef（.md 绝对路径，<available_subagents> 的
 // <location>）；fallowScan=true 独立参数前置插入静态分析批次（不占 batchN）。
@@ -75,7 +76,8 @@ usage: |
   - batch1..batchN 与 agents 互斥（至少传一个 batchN）；值 = agentRef（.md 绝对路径，<available_subagents> 的 <location>）
   - fixAgent：fix 阶段执行者（agentRef），缺省用通用 subagent + 内联 fixPrompt
   - fallowScan=true 仅 targetType=git-diff 合法（前置静态分析批次，不占 batchN）
-  - 示例：workflow run review-fix-loop --args targetType=git-diff target=main batch1="/path/fallow-agent.md,/path/reviewer.md" autoCommit=true
+  - 示例（pi 宿主语法）：workflow run review-fix-loop --args targetType=git-diff target=main batch1="/path/fallow-agent.md,/path/reviewer.md" autoCommit=true
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow review-fix-loop --task "<任务书>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag --target-type/--target/--batch1 等，语义见 @pi-meta parameters）
 */
 
 // ── 参数解析 + 白名单校验（fail-fast） ────────────────────────────
@@ -187,11 +189,18 @@ const skipCleanAgents = coerceBool($ARGS.skipCleanAgents, true);
 // RC-5（fix 后全批全量重审放大 token）在默认场景消失。传 true 启用可选强回归模式：fix 后重派
 // 全批，clean agent 走限定 prompt（buildScopedRecheckPrompt，只审 modifiedFiles，5.5）。
 const recheckAfterFix = coerceBool($ARGS.recheckAfterFix, false);
-// fixAgent（5.3）：值语义同 batchN 的 agent 项（内置名 / agent.md 路径），解析复用
-// resolveAgentDefs 白名单与加载逻辑。传入时 fix 阶段用 agent({agent: ...}) 派发（代码场景
-// 的 verify 命令写在该 agent.md 内）；未传保持现状（通用 subagent + 内联 prompt）。
+// fixAgent（5.3）：值 = .md 绝对路径（同 batchN 的 agent 项值域）；`fallow-scan` 是
+// fallowScan 参数的内部保留字，显式拒收（RX2-F2）——resolveAgentDefs 对它会静默映射
+// 为内置工具型 FALLOW_DEF（无 path），fix 派发即退化为通用 subagent + 内联 prompt，
+// 与「不属于 fixAgent 值域」相悖，故在解析前 fail-fast。其余合法值解析复用
+// resolveAgentDefs 白名单与加载逻辑：传入时 fix 阶段用 agent({agent: ...}) 派发
+// （代码场景的 verify 命令写在该 agent.md 内）；未传保持现状（通用 subagent + 内联 prompt）。
 const FIX_AGENT_RAW = typeof $ARGS.fixAgent === "string" && $ARGS.fixAgent.trim()
   ? $ARGS.fixAgent.trim() : undefined;
+if (FIX_AGENT_RAW === "fallow-scan") {
+  fail("fixAgent=fallow-scan 是内部保留字：fallow-scan 是 fallowScan 前置批次的内部标记，不属于 fixAgent 值域。" +
+    "要跑 fallow 静态分析前置批请用参数 fallowScan=true（需 targetType=git-diff）；要指定 fix 执行者请传 agent .md 绝对路径。");
+}
 const FIX_DEF = FIX_AGENT_RAW ? resolveAgentDefs([FIX_AGENT_RAW])[0] : null;
 // 5.7 收敛终止参数：maxFixAttempts（needs-redesign 阈值，RC-7）/ convergeNewIssues +
 // convergeRounds（新发现率收敛阈值）
@@ -1039,7 +1048,9 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       const r1IdMap = {};
       for (const entry of agg.must_fix_ids) {
         const id = typeof entry === "string" ? entry : entry && entry.id;
-        if (!id || state.issues[id]) continue;
+        // Object.hasOwn：truthy 查表会让原型链键（"__proto__"/"toString"）误判已登记
+        // 而 continue 跳过真实条目（与 utils findIssueKey 同款加固；id 来自 LLM 产出）。
+        if (!id || Object.hasOwn(state.issues, id)) continue;
         if (!activeIds.has(id)) continue;
         const resolved = resolveIssueIdentity(
           typeof entry === "string" ? { id } : entry,

package/workflows/scatter-gather.js

@@ -8,7 +8,8 @@
 // 适用于"任务太大需要先拆分再并行处理"的场景。
 //
 // 用法：
-//   workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"
+//   workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"（pi 宿主语法）
+//   zsw workflow --workflow scatter-gather --task "<大任务描述>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 //
 // ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
 
@@ -26,7 +27,8 @@ usage: |
   ## 使用说明
   - scatter 拆解大任务 → process 并行处理 → gather 聚合结果
   - agents：逗号分隔的 agent .md 绝对路径，按顺序对应 scatter/process/gather 三段
-  - 示例：workflow run scatter-gather --args task="<大任务描述>" agents="/path/splitter.md,/path/processor.md"
+  - 示例（pi 宿主语法）：workflow run scatter-gather --args task="<大任务描述>" agents="/path/splitter.md,/path/processor.md"
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow scatter-gather --task "<大任务描述>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 */
 
 // ── 入参（$ARGS）──────────────────────────────────────────────────

package/dist/chunk-3VOERJPJ.js

@@ -1,22 +0,0 @@
-// src/execution/engine/engines/zcode/constants.ts
-var ZCODE_ENGINE_ID = "zcode";
-var ZCODE_ADAPTER_VERSION = "1.0.0";
-var ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
-var ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"];
-var ZCODE_POOL_CONFIG_SUFFIX = [".zcode", "cli", "config.json"];
-var ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
-var ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
-var ZCODE_KILL_GRACE_MS = 5e3;
-var ZCODE_ERROR_TAIL_CHARS = 2e3;
-
-export {
-  ZCODE_ENGINE_ID,
-  ZCODE_ADAPTER_VERSION,
-  ZCODE_CLI_DEFAULT_PATH,
-  ZCODE_V2_CONFIG_PATH_SUFFIX,
-  ZCODE_POOL_CONFIG_SUFFIX,
-  ZCODE_POOL_DB_RELATIVE_PATH,
-  ZCODE_FALLBACK_DEFAULT_MODEL,
-  ZCODE_KILL_GRACE_MS,
-  ZCODE_ERROR_TAIL_CHARS
-};