@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/shared/resource-discovery.ts

@@ -10,10 +10,10 @@
 // 4. manifest 路径存在性校验：声明的路径不存在 → 该包发现失败，不 fallback
 // 5. 废弃 discovery.json：扫描路径完全由代码内推导，无外部依赖
 //
-// 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev → project .pi → project .pi/.tmp(仅workflow) → project .agents
+// 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev → ext-paths(XYZ_EXTENSION_PATHS/dev-link) → project .pi → project .pi/.tmp(仅workflow) → project-host(宿主注入槽) → project .agents
 
 import * as fsSync from "node:fs";
-import { access, readdir, readFile, stat } from "node:fs/promises";
+import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { delimiter, join, resolve } from "node:path";
 
@@ -56,7 +56,19 @@ export interface DiscoveredResource {
 }
 
 /** 资源来源层级 */
-export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "user-extension-paths" | "project-pi" | "project-pi-tmp" | "project-agents";
+export type ResourceSource =
+  | "user-pi"
+  | "user-agents"
+  | "npm"
+  | "npm-dev"
+  | "user-extension-paths"
+  | "project-pi"
+  | "project-pi-tmp"
+  // project-host（W2②）：宿主注入的项目级根（如 zsw 的 <ws>/.zcode/agents）。
+  // 序位刻意压在 project-agents 之下——zsw 现语义项目 .agents > .zcode，
+  // project-host 承接 zcode 项目根，project-agents 仍是项目级最高逃生门。
+  | "project-host"
+  | "project-agents";
 
 /** 扫描配置 */
 export interface ScanConfig {
@@ -65,8 +77,14 @@ export interface ScanConfig {
   /** 项目根目录（findWorkspaceRoot 推导结果） */
   workspaceRoot: string;
   /** 宿主注入的发现根（DiscoveryRoot.dir 已含 kind 末级目录与安装布局，
-   *  source 为宿主语义标签——pi 壳 = user-pi/npm/npm-dev 三根）。buildScanTargets
-   *  按标签查表填充对应槽位，宿主未提供某标签根时该槽位条目整体缺席。 */
+   *  source 为宿主语义标签——pi 壳 = user-pi/npm/npm-dev 三根，zsw 壳可另注入
+   *  project-host 等）。buildScanTargets 按标签填充对应槽位，宿主未提供某标签
+   *  根时该槽位条目整体缺席。
+   *  同标签多根语义（W2④）：同标签多条目依注入序全部保留、同序位依次扫描——
+   *  宿主（zsw）把「目录 symlink 展开目标 + 本体根」按注入序注入同标签，core
+   *  合并 last-writer-wins 下靠后者胜，本体根必须注入在展开目标之后（本体胜，
+   *  红线 2）。user-agents/project-agents 硬编码槽与同标签注入合并时硬编码根
+   *  自动后置（同为「本体在后」语义）。 */
   hostRoots: DiscoveryRoot[];
   /** 是否包含 tmp 源（仅 workflow 用 .pi/workflows/.tmp/） */
   includeTmp?: boolean;
@@ -82,11 +100,12 @@ const MACHINE_SOURCES: ReadonlySet<ResourceSource> = new Set<ResourceSource>([
   "user-extension-paths",
   "project-pi",
   "project-pi-tmp",
+  "project-host",
   "project-agents",
 ]);
 
 /** 判断 source 是否属于机器源（安装拓扑常态，同名重复降 debug）。
- *  导出仅为测试穷举断言用（封闭 8 值枚举 × 分级边界）。 */
+ *  导出仅为测试穷举断言用（封闭 9 值枚举 × 分级边界）。 */
 export function isMachineSource(source: ResourceSource): boolean {
   return MACHINE_SOURCES.has(source);
 }
@@ -113,8 +132,8 @@ function isDirectChildOfWorkspaceRoot(dir: string, workspaceRoot: string): boole
 // ── 统一 mtime 缓存层（m5 IF10）────────────────────────────────────
 //
 // 模块级 Map<path, { mtimeMs, content }>：mtime 判变缓存文件内容。
-// - sync 实现（statSync/readFileSync）：agent-registry discoverAll 是同步路径，
-//   async 缓存无法被 await（m5 design-review A1 探针实证约束）
+// - sync 实现（statSync/readFileSync）：getCachedFile 同步返回，供 async 发现流程
+//   与 agent-registry loadByPath 在流程内同步读缓存
 // - stat 失败/ENOENT → 驱逐条目（mtime 缓存下文件删除不自愈——A3 修复）
 // - 已知局限（C3 记录）：内容变 mtime 未变（cp -p/rsync -t 保留源 mtime、
 //   2s 粒度文件系统）→ 漏判，invalidateCache/clearFileCache 兜底；
@@ -364,7 +383,7 @@ async function scanDirectory(dirPath: string, kind: ResourceKind): Promise<strin
 /**
  * 读取 package.json 的 pi.{kind} manifest（pi.agents / pi.workflows）。
  * 返回 undefined 表示无 manifest 声明（无 pi / pi[kind] 非数组 / 解析失败）。
- * 内部走 manifestCache（与 readPackageManifestSync 共享同一 Map，失败语义见声明处）。
+ * 内部走 manifestCache（失败语义见声明处）。
  */
 async function readPackageManifest(pkgDir: string, kind: ResourceKind): Promise<string[] | undefined> {
   const pkgJsonPath = resolve(pkgDir, "package.json");
@@ -458,9 +477,9 @@ async function scanNpmDir(
   }
 
   // [perf] 包级并行（swf-perf-impl cleanup TC2/IF2）：entries.map + Promise.all，
-  // perEntry.flat() 按原 readdir 序 concat——输出序与串行逐包 push 等价。
+  // perEntry.flat() 按原 readdir 序 concat——输出序与 readdir 包序一致。
   // 不加新增 catch：每包失败面由 processPackage 内部既有 catch 承担，未捕获异常
-  // 传播语义与串行版一致（Promise.all 整体 reject ↔ 串行版向上抛）。
+  // 经 Promise.all 以首个 reject 整体向上抛。
   const perEntry = await Promise.all(
     entries.map(async (entry): Promise<DiscoveredResource[]> => {
       const entryPath = resolve(nodeModulesDir, entry);
@@ -518,38 +537,44 @@ function readExtensionPaths(): string[] {
  * 构建所有扫描源（按优先级低→高排列）。
  *
  * agent 和 workflow 共享相同的前缀体系。宿主注入根（config.hostRoots）按 source
- * 标签查表填充三个槽位条目——标签字面是 core 编排的槽位键（同时是 ResourceSource
+ * 标签填充槽位条目——标签字面是 core 编排的槽位键（同时是 ResourceSource
  * 枚举成员，报告输出与历史值逐字一致）；宿主未提供某标签根时该条目跳过（该源在
  * 遮蔽序中自然缺席），其余条目（core 自建：homedir/env/workspaceRoot 推导）留原位
  * 原序，遮蔽优先级语义与注入化前逐字一致。
+ *
+ * 同标签多根（W2④，Map→列表）：同标签多条目依注入序全部保留、同序位依次扫描
+ * （旧实现 Map(source→dir) 同标签靠后者整体覆盖，多根语义缺失）。硬编码槽
+ * （user-agents/project-agents）与 hostRoots 同标签注入合并——硬编码根（本体根）
+ * 排在注入条目之后：core 合并 last-writer-wins 靠后者胜，本体在后 = 本体胜（红线 2
+ * 「注入/合并序语义」）。pi 单条目形态（每标签恰好一条或无注入）下 targets 序与
+ * 旧实现逐项一致（回归红线，见 __tests__ pi 单条目形态快照用例）。
  */
 function buildScanTargets(config: ScanConfig): ScanTarget[] {
   const { kind, workspaceRoot, hostRoots, includeTmp } = config;
   const home = homedir();
 
-  // 同标签多条目时取列表靠后者（hostRoots 按优先级低→高，靠后 = 宿主侧更高优先级）
-  const hostDirBySource = new Map<string, string>(
-    hostRoots.map((root): [string, string] => [root.source, root.dir]),
-  );
+  // 同标签多条目依注入序全部保留（W2④ 列表语义）：宿主把「展开目标 + 本体根」
+  // 按注入序注入同标签，core 同序位依次扫描；本体靠后 → last-writer-wins 本体胜。
+  const hostDirsBySource = new Map<string, string[]>();
+  for (const root of hostRoots) {
+    const list = hostDirsBySource.get(root.source);
+    if (list) list.push(root.dir);
+    else hostDirsBySource.set(root.source, [root.dir]);
+  }
+  const hostTargets = (source: ResourceSource): ScanTarget[] =>
+    (hostDirsBySource.get(source) ?? []).map((dir) => ({ dir, source, enabled: true }));
 
   const targets: ScanTarget[] = [];
   // 1. user .pi/agent/{kind}/（宿主注入，pi 壳 source "user-pi"）
-  const userPiDir = hostDirBySource.get("user-pi");
-  if (userPiDir !== undefined) {
-    targets.push({ dir: userPiDir, source: "user-pi", enabled: true });
-  }
-  // 2. user .agents/{kind}/（core 自建：homedir 推导，非宿主依赖）
+  targets.push(...hostTargets("user-pi"));
+  // 2. user .agents/{kind}/（硬编码根 = homedir 推导 + 宿主可选注入合并，硬编码
+  //    本体根后置 → 注入的展开目标在前、本体在后，last-writer-wins 本体胜）
+  targets.push(...hostTargets("user-agents"));
   targets.push({ dir: join(home, ".agents", kind), source: "user-agents", enabled: true });
   // 3. npm global: <agentDir>/npm/node_modules/*/<pkg>/（宿主注入，pi 壳 source "npm"）
-  const npmDir = hostDirBySource.get("npm");
-  if (npmDir !== undefined) {
-    targets.push({ dir: npmDir, source: "npm", enabled: true });
-  }
+  targets.push(...hostTargets("npm"));
   // 4. npm dev symlink: <agentDir>/extensions/*/<pkg>/（宿主注入，pi 壳 source "npm-dev"）
-  const npmDevDir = hostDirBySource.get("npm-dev");
-  if (npmDevDir !== undefined) {
-    targets.push({ dir: npmDevDir, source: "npm-dev", enabled: true });
-  }
+  targets.push(...hostTargets("npm-dev"));
   // user extension paths (XYZ_EXTENSION_PATHS, dev-link): each path is a package dir,
   // 走 processPackage 读 pi.{kind} manifest 或扫 {kind}/ 目录。优先级高于 npm/npm-dev
   // （dev-link 是开发版 override），低于 project（项目正式资源优先）。
@@ -568,7 +593,13 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
     });
   }
 
-  // 7. project .agents/{kind}/
+  // 6.5 project host 根（宿主注入，W2②）：承接宿主自有项目级布局（如 zsw 的
+  //     <ws>/.zcode/agents）。序位在 project-agents 之下（.agents 是项目级最高
+  //     逃生门）；未注入该标签时槽位缺席（与 user-pi/npm/npm-dev 同语义）。
+  targets.push(...hostTargets("project-host"));
+
+  // 7. project .agents/{kind}/（硬编码根 + 宿主可选注入合并，本体根后置同槽 2）
+  targets.push(...hostTargets("project-agents"));
   targets.push({
     dir: join(workspaceRoot, ".agents", kind),
     source: "project-agents",
@@ -586,8 +617,14 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
  * 按优先级低→高扫描所有源，同名资源靠后覆盖靠前（last-writer-wins）。
  * npm/dev 包内：有 manifest 只走 manifest（路径不存在则失败），无 manifest 扫约定目录。
  *
+ * realpath 归一去重（W2①，仅 async 链）：多个不同名 symlink 指向同一物理文件时
+ * （多链同文件），stem 去重防不住——清单按物理文件归一只留一条（首遇者，位置
+ * 固定语义与 stem 合并一致）；同 stem 不同物理文件的遮蔽语义不受影响（仍按
+ * last-writer-wins 覆盖）。realpath 解析失败（扫描后竞态删除/ELOOP 深链）回退
+ * 原 path，属预期失败不抛。
+ *
  * Throws on unrecoverable scan errors——未捕获异常向上抛（Promise.all 首个 reject
- * 即整体拒绝，与串行版 discoverResourcesSync 的传播语义一致，见实现内 [perf] 注释）。
+ * 即整体拒绝，见实现内 [perf] 注释）。
  * 预期失败不抛：目录不存在/不可读返回空列表，manifest 声明路径缺失以 available=false 返回。
  *
  * @returns 去重后的资源列表（按优先级合并，高优先级覆盖低优先级同名）
@@ -597,11 +634,10 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
 
   // [perf] 源级并行（swf-perf-impl cleanup TC2/IF2）：targets.map + Promise.all，
   // Promise.all 对 map 数组保序——allBySource 顺序 = targets 优先级序（低→高），
-  // 与串行逐源 push 完全一致 → 下方合并去重逻辑零改动、输出逐字节等价。
+  // 下方合并去重按该顺序 last-writer-wins。
   // 不加新增 catch：每源预期失败路径由内部既有 catch 面承担（scanDirectory access
-  // catch / scanNpmDir readdir catch / processPackage 全链 catch），未捕获异常
-  // 传播语义与串行版等价（ES2：串行版 target k 抛错中断后续源，并行版全部源已并发
-  // 启动、以首个 reject 拒绝——两版对调用方同为 discoverResources 抛出，各源只读无副作用）。
+  // catch / scanNpmDir readdir catch / processPackage 全链 catch）；未捕获异常经
+  // Promise.all 以首个 reject 整体向上拒绝（各源只读无副作用）。
   const allBySource: Array<{ source: ResourceSource; resources: DiscoveredResource[] }> = await Promise.all(
     targets.map(async (target) => {
       if (target.source === "npm" || target.source === "npm-dev") {
@@ -624,13 +660,35 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
     }),
   );
 
+  // [W2①] realpath 归一键（仅 async 链）：与 allBySource 同构的二维数组（源序×
+  // 源内资源序）。源级并行解析（每资源一次 realpath，资源量级为个位/十位数）；
+  // 失败回退原 path——扫描与 realpath 之间竞态删除/ELOOP 属预期失败，不抛
+  // （对齐 scanDirectory 的 stat().catch 吞错面）。
+  const realpathKeys: string[][] = await Promise.all(
+    allBySource.map(async ({ resources }) =>
+      Promise.all(resources.map((r) => realpath(r.path).catch(() => r.path))),
+    ),
+  );
+
   // 按优先级合并：targets 数组顺序即优先级（低→高），高优先级后写覆盖
   // 用文件名 stem 作为去重 key（与旧逻辑一致：同名资源高优先级覆盖）
   const merged = new Map<string, DiscoveredResource>();
-
-  for (const { resources } of allBySource) {
-    for (const r of resources) {
+  // realpath → 已入清单 stem key：多链同文件（不同名 symlink 指向同一物理文件）
+  // 时后到链 skip——清单按物理文件只留一条，不计入遮蔽（同一文件无遮蔽语义）。
+  const realpathOwner = new Map<string, string>();
+
+  for (let si = 0; si < allBySource.length; si++) {
+    const { resources } = allBySource[si]!;
+    for (let ri = 0; ri < resources.length; ri++) {
+      const r = resources[ri]!;
       const key = stem(r.path);
+      const rp = realpathKeys[si]![ri]!;
+      // 同物理文件已以另一 stem 入清单 → 多链重复，跳过（不影响 stem 遮蔽语义：
+      // 同 stem 不同物理文件仍走下方 last-writer-wins）
+      const owner = realpathOwner.get(rp);
+      if (owner !== undefined && owner !== key) {
+        continue;
+      }
       const existing = merged.get(key);
       // available=false 的占位不覆盖已有的 available=true
       if (!r.available && existing) {
@@ -661,175 +719,10 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
         }
       }
       merged.set(key, r);
+      realpathOwner.set(rp, key);
     }
   }
 
   return Array.from(merged.values());
 }
 
-/**
- * 同步版：扫描单个目录下的资源文件路径（供 agent-registry 的 mtime 缓存模式使用）。
- *
- * agent .md 发现需要 mtime 缓存（hot-reload），不能走 async 全量扫描。
- * 此函数提供目录级同步扫描，npm/dev 包内发现仍需 async（agent-registry 用 builtin 兜底）。
- */
-export function scanDirectorySync(dirPath: string, kind: ResourceKind): string[] {
-  try {
-    fsSync.accessSync(dirPath);
-  } catch {
-    return [];
-  }
-
-  let entries: string[];
-  try {
-    entries = fsSync.readdirSync(dirPath);
-  } catch {
-    return [];
-  }
-
-  const files: string[] = [];
-  for (const entry of entries) {
-    if (!isTargetFile(entry, kind)) continue;
-    files.push(resolve(dirPath, entry));
-  }
-  return files;
-}
-
-/**
- * 同步版：读取 package.json 的 pi.{kind} manifest。
- * 供 agent-registry 同步路径使用。与 async 版共享 manifestCache（双读者同一 Map）。
- */
-export function readPackageManifestSync(pkgDir: string, kind: ResourceKind): string[] | undefined {
-  const pkgJsonPath = resolve(pkgDir, "package.json");
-  let mtimeMs: number;
-  try {
-    mtimeMs = fsSync.statSync(pkgJsonPath).mtimeMs;
-  } catch {
-    // stat 失败：文件不存在/不可 stat → 驱逐条目（对齐 getCachedFile 语义）
-    manifestCache.delete(pkgJsonPath);
-    return undefined;
-  }
-  const entry = manifestCache.get(pkgJsonPath);
-  if (entry && entry.mtimeMs === mtimeMs) return piToManifest(entry.pi, kind);
-  let pi: Record<string, unknown> | undefined;
-  try {
-    const content = fsSync.readFileSync(pkgJsonPath, "utf-8");
-    pi = parsePiField(content);
-  } catch {
-    // read 失败或坏 JSON → 不缓存不驱逐已有好条目，下次调用重试
-    return undefined;
-  }
-  manifestCache.set(pkgJsonPath, { mtimeMs, pi });
-  return piToManifest(pi, kind);
-}
-
-/**
- * 同步版：处理单个 npm/dev 包。
- * 供 agent-registry 同步路径使用。
- */
-export function processPackageSync(pkgDir: string, kind: ResourceKind): DiscoveredResource[] {
-  const manifestPaths = readPackageManifestSync(pkgDir, kind);
-
-  if (manifestPaths && manifestPaths.length > 0) {
-    const results: DiscoveredResource[] = [];
-
-    for (const relPath of manifestPaths) {
-      const absPath = resolve(pkgDir, relPath);
-      let fileStat: fsSync.Stats | null;
-      try {
-        fileStat = fsSync.statSync(absPath);
-      } catch {
-        fileStat = null;
-      }
-      if (!fileStat) {
-        results.push({ path: absPath, source: "npm", available: false });
-        continue;
-      }
-
-      if (fileStat.isDirectory()) {
-        const files = scanDirectorySync(absPath, kind);
-        for (const f of files) {
-          results.push({ path: f, source: "npm", available: true });
-        }
-      } else if (fileStat.isFile()) {
-        results.push({ path: absPath, source: "npm", available: true });
-      }
-    }
-
-    return results;
-  }
-
-  // 无 manifest：扫约定目录
-  const conventionDir = resolve(pkgDir, kind);
-  const files = scanDirectorySync(conventionDir, kind);
-  return files.map((f) => ({ path: f, source: "npm", available: true }));
-}
-
-/**
- * 同步版：扫描 npm node_modules 目录。
- * 供 agent-registry 同步路径使用。
- */
-export function scanNpmDirSync(nodeModulesDir: string, kind: ResourceKind): DiscoveredResource[] {
-  let entries: string[];
-  try {
-    entries = fsSync.readdirSync(nodeModulesDir);
-  } catch {
-    return [];
-  }
-
-  const results: DiscoveredResource[] = [];
-  for (const entry of entries) {
-    const entryPath = resolve(nodeModulesDir, entry);
-
-    if (entry.startsWith("@")) {
-      let scopedEntries: string[];
-      try {
-        scopedEntries = fsSync.readdirSync(entryPath);
-      } catch {
-        continue;
-      }
-      for (const scopedPkg of scopedEntries) {
-        const scopedPkgDir = resolve(entryPath, scopedPkg);
-        results.push(...processPackageSync(scopedPkgDir, kind));
-      }
-    } else {
-      results.push(...processPackageSync(entryPath, kind));
-    }
-  }
-  return results;
-}
-
-/**
- * 同步版：发现所有资源（agent-registry 专用，支持 mtime 缓存的 hot-reload）。
- *
- * 与 discoverResources 对应的同步实现，扫描相同的源。
- * 返回所有源的资源（未去重，调用方按需处理优先级）。
- */
-export function discoverResourcesSync(config: ScanConfig): DiscoveredResource[] {
-  const targets = buildScanTargets(config);
-  const all: DiscoveredResource[] = [];
-
-  for (const target of targets) {
-    if (target.source === "npm" || target.source === "npm-dev") {
-      const resources = scanNpmDirSync(target.dir, config.kind);
-      all.push(...resources.map((r) => ({ ...r, source: target.source })));
-    } else if (target.source === "user-extension-paths") {
-      // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录
-      const resources = processPackageSync(target.dir, config.kind);
-      all.push(...resources.map((r) => ({ ...r, source: target.source })));
-    } else {
-      const files = scanDirectorySync(target.dir, config.kind);
-      all.push(...files.map((f) => ({ path: f, source: target.source, available: true })));
-    }
-  }
-
-  // 按优先级合并（targets 顺序 = 优先级低→高）
-  const merged = new Map<string, DiscoveredResource>();
-  for (const r of all) {
-    const key = stem(r.path);
-    if (!r.available && merged.has(key)) continue;
-    merged.set(key, r);
-  }
-
-  return Array.from(merged.values());
-}

package/src/shared/resource-meta.ts

@@ -59,6 +59,20 @@ export interface AgentMeta extends ResourceMetaBase {
    * 与 model 字段同风格——路由字段（不进 system prompt），执行侧（P4 路由层）消费。
    */
   engine?: string;
+  /**
+   * 执行预算：turn 上限（sink 设计 D3 新增可选执行字段之一）。
+   * 消费优先级：显式参数 > 本字段 > 缺省——pi 工具参数 maxTurns 语义不变（本字段
+   * 对 pi 是清单元数据），zsw 决策链 timeoutMs > profile.maxTurns > 缺省。
+   */
+  maxTurns?: number;
+  /** tool denylist（D3 可选执行字段）：spawn 侧剔除，与 tools allowlist 正交。 */
+  disallowedTools?: string[];
+  /**
+   * agent 声明依赖的 skill 名清单（D3 可选执行字段）。注意与本文件头注
+   * 「skills 归 pi core」的 skills（资源种类）不同物：此处是 agent frontmatter 的
+   * 执行配置字段，不是 ResourceKind。
+   */
+  skills?: string[];
 }
 
 /** 判别联合（kind 判别）。 */

package/src/shared/schema-jsonify.ts

@@ -3,7 +3,7 @@
  *
  * 同一 schema 对象引用的重复 JSON.stringify 消除：resolver（compact，instruction
  * 与 schemaEnv 复用同串，formatSchemaInstruction 现居 resolver）在单次 agent call
- * 内对同一 schema 对象各 stringify 一次；error-recovery 重试路径再加一次。本
+ * 内对同一 schema 对象各 stringify 一次；worker-message-pump 重试路径再加一次。本
  * helper 用 WeakMap 按对象引用缓存两种格式，命中返回缓存串。
  *
  * 返回值与直接 JSON.stringify 逐字节一致（compact = JSON.stringify(x)、

package/src/shared/xml-injection.ts

@@ -9,12 +9,12 @@
  * XML 结构——全部字段过一遍转义防注入段破碎）。
  */
 export function escapeXml(str: string): string {
-	return str
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&apos;");
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
 }
 
 /**
@@ -29,7 +29,7 @@ export function renderXmlSection(section: {
 	guide: string;
 	items: string[];
 }): string {
-	if (section.items.length === 0) return "";
-	const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
-	return lines.join("\n");
+  if (section.items.length === 0) return "";
+  const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
+  return lines.join("\n");
 }

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）──────────────────────────────────────────────────