@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/src/shared/resource-discovery.ts

@@ -1,811 +0,0 @@
-// src/shared/resource-discovery.ts
-//
-// 统一资源发现模块——agent .md 与 workflow .js/.mjs 共享同一套扫描逻辑。
-//
-// 设计原则（ADR-031 统一资源发现）：
-// 1. 扫描源前缀统一：user/project 级目录用相同前缀，末级目录名（agents/workflows）参数化
-// 2. 路径动态获取：user 级用 getAgentDir()（尊重 PI_CODING_AGENT_DIR），project 级用 findWorkspaceRoot(cwd)
-// 3. npm/dev 包内发现：有 manifest（pi.agents/pi.workflows）只走 manifest，无 manifest 扫约定目录
-// 4. manifest 路径存在性校验：声明的路径不存在 → 该包发现失败，不 fallback
-// 5. 废弃 discovery.json：扫描路径完全由代码内推导，无外部依赖
-//
-// 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev → project .pi → project .pi/.tmp(仅workflow) → project .agents
-
-import * as fsSync from "node:fs";
-import { access, readdir, readFile, stat } from "node:fs/promises";
-import { homedir } from "node:os";
-import { delimiter, join, resolve } from "node:path";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-// 模块级 logger（setPiHandle 注入后自动走 appendEntry，未注入时 console 兜底）
-const logger = getLogger("subagents");
-
-// [D8d] warn 路径进程内去重集合：key=(kind, stem, shadowedPath, keptPath)，
-// cap 1024 超限先清空再 add（对齐 ui-request-observability 的 MAX_WARNED_SESSIONS 范式）。
-// debug 路径不去重（默认 no-op，无成本）。
-const shadowWarnDedup = new Set<string>();
-const MAX_SHADOW_WARN_DEDUP = 1024;
-
-/** @internal 测试辅助：重置 warn 去重集合（cap 测试用，生产代码不调用）。 */
-export function __testResetShadowDedup(): void {
-  shadowWarnDedup.clear();
-}
-
-/** @internal 测试辅助：向 warn 去重集合注入 key（cap 测试用）。 */
-export function __testInjectShadowDedupKey(key: string): void {
-  shadowWarnDedup.add(key);
-}
-
-// ── 类型 ─────────────────────────────────────────────────────
-
-/** 资源种类：agent 或 workflow */
-export type ResourceKind = "agents" | "workflows";
-
-/** 发现到的单个资源文件（原始数据，由调用方解析 frontmatter/meta） */
-export interface DiscoveredResource {
-  /** 绝对路径 */
-  path: string;
-  /** 来源层级 */
-  source: ResourceSource;
-  /** 是否可用（manifest 校验失败的包整体标 false） */
-  available: boolean;
-}
-
-/** 资源来源层级 */
-export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "user-extension-paths" | "project-pi" | "project-pi-tmp" | "project-agents";
-
-/** 扫描配置 */
-export interface ScanConfig {
-  /** 资源种类 */
-  kind: ResourceKind;
-  /** 项目根目录（findWorkspaceRoot 推导结果） */
-  workspaceRoot: string;
-  /** agent 配置目录（getAgentDir() 结果） */
-  agentDir: string;
-  /** 是否包含 tmp 源（仅 workflow 用 .pi/workflows/.tmp/） */
-  includeTmp?: boolean;
-}
-
-// ── 常量 ─────────────────────────────────────────────────────
-
-/** 机器源集合：包管理/工程配置产物，其同名重复是安装拓扑常态（非用户配置错误）。
- *  用户个人源（user-pi / user-agents）不在此列——双个人源同名重复保留 warn。 */
-const MACHINE_SOURCES: ReadonlySet<ResourceSource> = new Set<ResourceSource>([
-  "npm",
-  "npm-dev",
-  "user-extension-paths",
-  "project-pi",
-  "project-pi-tmp",
-  "project-agents",
-]);
-
-/** 判断 source 是否属于机器源（安装拓扑常态，同名重复降 debug）。
- *  导出仅为测试穷举断言用（封闭 8 值枚举 × 分级边界）。 */
-export function isMachineSource(source: ResourceSource): boolean {
-  return MACHINE_SOURCES.has(source);
-}
-
-/** workspace root 向上查找的最大深度 */
-const WORKSPACE_ROOT_MAX_DEPTH = 20;
-
-// ── workspace root 推导（从 config-loader 提取，agent/workflow 共用） ──
-
-/**
- * 判断 dir 是否是 workspaceRoot 的直接子目录（一层深度）。
- * 用于 bare+worktree 结构里识别 worktree 根。
- */
-function isDirectChildOfWorkspaceRoot(dir: string, workspaceRoot: string): boolean {
-  return resolve(dir, "..") === workspaceRoot;
-}
-
-/**
- * 从 cwd 向上查找 workspace root。
- *
- * bare+worktree 优先找 .bare；普通 repo 找最顶层 .git；fallback 找 .pi。
- * 与 config-loader 原有逻辑一致（合并后提取为共享函数）。
- */
-// ── 统一 mtime 缓存层（m5 IF10）────────────────────────────────────
-//
-// 模块级 Map<path, { mtimeMs, content }>：mtime 判变缓存文件内容。
-// - sync 实现（statSync/readFileSync）：agent-registry discoverAll 是同步路径，
-//   async 缓存无法被 await（m5 design-review A1 探针实证约束）
-// - stat 失败/ENOENT → 驱逐条目（mtime 缓存下文件删除不自愈——A3 修复）
-// - 已知局限（C3 记录）：内容变 mtime 未变（cp -p/rsync -t 保留源 mtime、
-//   2s 粒度文件系统）→ 漏判，invalidateCache/clearFileCache 兜底；
-//   APFS mtimeMs 微秒级浮点 === 判变可靠（探针 P-mtime-精度）
-
-interface MtimeCacheEntry {
-  mtimeMs: number;
-  content: string;
-}
-
-const mtimeCache = new Map<string, MtimeCacheEntry>();
-
-// [perf] findWorkspaceRoot 结果按 cwd memo——每次调用最多 3 phase × 20 层 existsSync
-//（30-60 次 stat），调用点（session_start、discoverWorkflows、getWorkflow）在 spawn/
-// tool 热路径上重复付。cwd 不变则祖先目录结构（.bare/.git/.pi）不变；变化场景由
-// clearFileCache 兜底（invalidateCache 语义，测试隔离也走这里）。
-const workspaceRootCache = new Map<string, string>();
-
-// [perf] npm/dev 包 package.json manifest 缓存（swf-perf-impl cleanup TC1/IF1）。
-// key = package.json 绝对路径；缓存 parse 后的整个 pi 对象（agents/workflows 两 kind
-// 共享一次 parse，不按 kind 分裂条目）。失效 = mtimeMs 严格相等判定（与 mtimeCache 同构，
-// 『内容变 mtime 未变』漏判局限共享 C3 声明，clearFileCache 兜底）。
-// 失败语义（消歧，三方 TC1/DM1/IF1 同一口径）：
-// - stat 失败（文件不存在/不可 stat）→ 驱逐该 path 条目 + undefined（对齐 getCachedFile：
-//   文件已删条目无意义）
-// - read 失败（stat 与 read 间竞态删除/EACCES）或 JSON.parse 失败（坏 JSON）→
-//   不缓存（不写新条目、不驱逐已有好条目）+ undefined，下次调用重试——毒条目永不入缓存，
-//   坏文件被修复且 mtime 变化后正常覆写。
-// pi === undefined 条目仅在『read+parse 成功且 manifest 无 pi 字段』时写入（合法解析结果）。
-interface ManifestCacheEntry {
-  mtimeMs: number;
-  pi: Record<string, unknown> | undefined;
-}
-
-const manifestCache = new Map<string, ManifestCacheEntry>();
-
-/** 从缓存的 pi 对象派生 kind manifest（廉价操作，每次调用新数组——语义与旧直读版一致）。 */
-function piToManifest(pi: Record<string, unknown> | undefined, kind: ResourceKind): string[] | undefined {
-  if (!pi) return undefined;
-  const entries = pi[kind];
-  if (!Array.isArray(entries)) return undefined;
-  // 过滤非字符串元素
-  return entries.filter((p): p is string => typeof p === "string");
-}
-
-/**
- * package.json 文本 → pi 字段对象（pi.agents / pi.workflows 的容器）。
- * [review 修复] 结构守卫：JSON.parse 对 "42" / '"str"' / "null" 等合法 JSON 产出
- * 非对象值，旧 `as Record<string, unknown>` 盲断言下 .pi 访问是「碰巧不抛」
- * （primitive 装箱返 undefined / null 抛 TypeError 落入 catch）——显式判非对象，
- * 按「无 manifest」（undefined）处理，后果与原先一致但语义不再依赖巧合。
- * pi 字段本身非对象（如 {"pi":42}）或为数组（如 {"pi":[]}——数组不是合法 pi 容器，
- * typeof "object" 守卫会放行，Record 断言对数组是谎言）同样显式归 undefined。
- * JSON SyntaxError 向上抛，由调用方 catch 承担「坏 JSON 不缓存、下次重试」语义。
- */
-function parsePiField(content: string): Record<string, unknown> | undefined {
-  const parsed: unknown = JSON.parse(content);
-  if (typeof parsed !== "object" || parsed === null) return undefined;
-  const pi: unknown = (parsed as Record<string, unknown>).pi;
-  return typeof pi === "object" && pi !== null && !Array.isArray(pi)
-    ? (pi as Record<string, unknown>)
-    : undefined;
-}
-
-/**
- * stat + content 统一缓存。文件不存在/不可读 → null（并驱逐条目）。
- * mtime 未变 → 返回缓存 content（不重 read）；变 → readFileSync + 缓存。
- */
-export function getCachedFile(filePath: string): { mtimeMs: number; content: string } | null {
-  let mtimeMs: number;
-  try {
-    mtimeMs = fsSync.statSync(filePath).mtimeMs;
-  } catch {
-    mtimeCache.delete(filePath);
-    return null;
-  }
-  const entry = mtimeCache.get(filePath);
-  if (entry && entry.mtimeMs === mtimeMs) return entry;
-  let content: string;
-  try {
-    content = fsSync.readFileSync(filePath, "utf-8");
-  } catch {
-    // stat 与 read 之间的删除/EACCES 竞态 → 驱逐并返回 null（exec-review major-2：
-    // docstring 承诺「不可读 → null」——readFileSync 也必须入守卫）
-    mtimeCache.delete(filePath);
-    return null;
-  }
-  const cached = { mtimeMs, content };
-  mtimeCache.set(filePath, cached);
-  return cached;
-}
-
-/** 便捷封装：只取 content（不存在 → null）。 */
-export function getCachedFileContent(filePath: string): string | null {
-  return getCachedFile(filePath)?.content ?? null;
-}
-
-// [perf] 解析结果缓存（KV-cache 稳定性改造）：外层 key = parse 函数身份，内层 key =
-// path，value = { mtimeMs, parsed }。key 含 parse 身份是正确性要求——同一 path 可能被
-// 不同 parse（agent frontmatter vs workflow meta）解析，单层 path key 会跨 parse 类型
-// 互相污染缓存（先 parse 的结果被 as T 断言返回）。用普通 Map 而非 WeakMap：
-// clearFileCache 需全量清空（测试隔离），WeakMap 不可遍历；parse 函数均为模块级
-// 常量，强引用无泄漏。复用 getCachedFile 的 mtime 判变——mtime 未变时跳过 parse
-// （frontmatter YAML 解析是重建发现时最大的可省 CPU 项）。parse 的确定性结果（含
-// null，如 frontmatter 非法）均可缓存：同一 content 必然解析出同一结果。失效与
-// mtimeCache 同步（clearFileCache）。
-const parsedCache = new Map<
-  (content: string) => unknown,
-  Map<string, { mtimeMs: number; parsed: unknown }>
->();
-
-/**
- * mtime 级解析结果缓存：mtime 未变返回缓存 parsed，变则经 getCachedFile 取 content
- * 重新 parse 并缓存。文件不存在/不可读 → null（并驱逐条目）。缓存按 parse 函数隔离
- * ——同一 path 的不同 parse 互不污染。
- */
-export function getCachedParsed<T>(filePath: string, parse: (content: string) => T): T | null {
-  const file = getCachedFile(filePath);
-  let perParse = parsedCache.get(parse);
-  if (!file) {
-    perParse?.delete(filePath);
-    return null;
-  }
-  if (!perParse) {
-    perParse = new Map();
-    parsedCache.set(parse, perParse);
-  }
-  const entry = perParse.get(filePath);
-  if (entry && entry.mtimeMs === file.mtimeMs) return entry.parsed as T;
-  const parsed = parse(file.content);
-  perParse.set(filePath, { mtimeMs: file.mtimeMs, parsed });
-  return parsed;
-}
-
-/** 清空（invalidateCache 语义——测试隔离 + mtime 漏判场景手动刷新兜底）。 */
-export function clearFileCache(): void {
-  mtimeCache.clear();
-  workspaceRootCache.clear();
-  manifestCache.clear();
-  for (const perParse of parsedCache.values()) perParse.clear();
-}
-
-export function findWorkspaceRoot(cwd?: string): string {
-  const dir = cwd ?? process.cwd();
-  const memo = workspaceRootCache.get(dir);
-  if (memo !== undefined) return memo;
-  const root = computeWorkspaceRoot(dir);
-  workspaceRootCache.set(dir, root);
-  return root;
-}
-
-function computeWorkspaceRoot(dir: string): string {
-  const root = resolve("/");
-
-  // Phase 1: bare repo 优先——先全路径扫一遍找 .bare
-  let probe = dir;
-  for (let i = 0; i < WORKSPACE_ROOT_MAX_DEPTH; i++) {
-    if (fsSync.existsSync(resolve(probe, ".bare"))) {
-      // worktree 是 workspace 根的直接子目录。若 cwd 自身有 .pi/，优先用 cwd
-      if (probe !== dir && isDirectChildOfWorkspaceRoot(dir, probe) && fsSync.existsSync(resolve(dir, ".pi"))) {
-        return dir;
-      }
-      return probe;
-    }
-    if (probe === root) break;
-    probe = resolve(probe, "..");
-  }
-
-  // Phase 2: 无 .bare 时，找最顶层的 .git
-  let topLevel = dir;
-  probe = dir;
-  for (let i = 0; i < WORKSPACE_ROOT_MAX_DEPTH; i++) {
-    if (fsSync.existsSync(resolve(probe, ".git"))) {
-      topLevel = probe;
-    }
-    if (probe === root) break;
-    probe = resolve(probe, "..");
-  }
-  if (topLevel !== dir) {
-    return topLevel;
-  }
-
-  // Phase 3: fallback——用第一个遇到的 .pi
-  probe = dir;
-  for (let i = 0; i < WORKSPACE_ROOT_MAX_DEPTH; i++) {
-    if (fsSync.existsSync(resolve(probe, ".pi"))) {
-      return probe;
-    }
-    if (probe === root) break;
-    probe = resolve(probe, "..");
-  }
-
-  return dir;
-}
-
-// ── 文件扩展名判定 ───────────────────────────────────────────
-
-/** 根据资源种类判定脚本文件扩展名 */
-function isTargetFile(name: string, kind: ResourceKind): boolean {
-  // _ 前缀 = draft/示例，不参与发现（与原 agent-registry/workflow 约定一致）
-  if (name.startsWith("_")) return false;
-  if (kind === "agents") {
-    return name.endsWith(".md") && !name.endsWith(".chain.md");
-  }
-  // workflows
-  return name.endsWith(".js") || name.endsWith(".mjs");
-}
-
-/** 提取文件名 stem（去目录去扩展名） */
-function stem(filePath: string): string {
-  const base = filePath.split("/").pop() ?? filePath;
-  const dot = base.lastIndexOf(".");
-  return dot > 0 ? base.slice(0, dot) : base;
-}
-
-// ── 目录扫描 ─────────────────────────────────────────────────
-
-/**
- * 扫描单个目录下的资源文件。
- * 返回文件绝对路径列表。目录不存在时返回空数组。
- */
-async function scanDirectory(dirPath: string, kind: ResourceKind): Promise<string[]> {
-  try {
-    await access(dirPath);
-  } catch {
-    return [];
-  }
-
-  const entries = await readdir(dirPath, { withFileTypes: true });
-  const files: string[] = [];
-  for (const e of entries) {
-    if (!isTargetFile(e.name, kind)) continue;
-    const absPath = resolve(dirPath, e.name);
-    // symlink 单独处理：Dirent.isFile() 对 symlink 返回 false
-    if (e.isFile()) {
-      files.push(absPath);
-    } else if (e.isSymbolicLink()) {
-      const targetStat = await stat(absPath).catch(() => null);
-      if (targetStat?.isFile()) files.push(absPath);
-    }
-  }
-  return files;
-}
-
-// ── npm/dev 包内 manifest 发现 ───────────────────────────────
-
-/**
- * 读取 package.json 的 pi.{kind} manifest（pi.agents / pi.workflows）。
- * 返回 undefined 表示无 manifest 声明（无 pi / pi[kind] 非数组 / 解析失败）。
- * 内部走 manifestCache（与 readPackageManifestSync 共享同一 Map，失败语义见声明处）。
- */
-async function readPackageManifest(pkgDir: string, kind: ResourceKind): Promise<string[] | undefined> {
-  const pkgJsonPath = resolve(pkgDir, "package.json");
-  let mtimeMs: number;
-  try {
-    mtimeMs = (await stat(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 = await readFile(pkgJsonPath, "utf-8");
-    pi = parsePiField(content);
-  } catch {
-    // read 失败或坏 JSON → 不缓存不驱逐已有好条目，下次调用重试
-    return undefined;
-  }
-  manifestCache.set(pkgJsonPath, { mtimeMs, pi });
-  return piToManifest(pi, kind);
-}
-
-/**
- * 处理单个 npm/dev 包：按 manifest 或约定目录发现资源。
- *
- * 规则：
- * - 有 manifest → 只按 manifest 声明路径加载。路径不存在 → 整包失败（返回 available=false 占位）
- * - 无 manifest → 扫约定目录 {kind}/（agents/ 或 workflows/）
- */
-async function processPackage(
-  pkgDir: string,
-  kind: ResourceKind,
-): Promise<DiscoveredResource[]> {
-  const manifestPaths = await readPackageManifest(pkgDir, kind);
-
-  // manifest 模式：只按声明路径加载，路径不存在则整包失败
-  if (manifestPaths && manifestPaths.length > 0) {
-    const results: DiscoveredResource[] = [];
-    let allFailed = true;
-
-    for (const relPath of manifestPaths) {
-      const absPath = resolve(pkgDir, relPath);
-      const fileStat = await stat(absPath).catch(() => null);
-      if (!fileStat) {
-        // manifest 声明的路径不存在 → 记录失败占位（路径存在性校验）
-        results.push({ path: absPath, source: "npm", available: false });
-        continue;
-      }
-
-      if (fileStat.isDirectory()) {
-        const files = await scanDirectory(absPath, kind);
-        for (const f of files) {
-          results.push({ path: f, source: "npm", available: true });
-          allFailed = false;
-        }
-      } else if (fileStat.isFile()) {
-        results.push({ path: absPath, source: "npm", available: true });
-        allFailed = false;
-      }
-    }
-
-    // manifest 全失败：返回 available=false 占位，不 fallback 到约定目录
-    if (allFailed) {
-      return results;
-    }
-    return results;
-  }
-
-  // 无 manifest：扫约定目录 {kind}/
-  const conventionDir = resolve(pkgDir, kind);
-  const files = await scanDirectory(conventionDir, kind);
-  return files.map((f) => ({ path: f, source: "npm", available: true }));
-}
-
-/**
- * 扫描 npm node_modules 目录下所有包的资源。
- * 支持 scoped（@scope/pkg）和 unscoped（pkg）包。
- */
-async function scanNpmDir(
-  nodeModulesDir: string,
-  kind: ResourceKind,
-): Promise<DiscoveredResource[]> {
-  let entries: string[];
-  try {
-    entries = await readdir(nodeModulesDir);
-  } catch {
-    return [];
-  }
-
-  // [perf] 包级并行（swf-perf-impl cleanup TC2/IF2）：entries.map + Promise.all，
-  // perEntry.flat() 按原 readdir 序 concat——输出序与串行逐包 push 等价。
-  // 不加新增 catch：每包失败面由 processPackage 内部既有 catch 承担，未捕获异常
-  // 传播语义与串行版一致（Promise.all 整体 reject ↔ 串行版向上抛）。
-  const perEntry = await Promise.all(
-    entries.map(async (entry): Promise<DiscoveredResource[]> => {
-      const entryPath = resolve(nodeModulesDir, entry);
-
-      if (entry.startsWith("@")) {
-        // scoped 包——迭代子包（子包级同样并行，flat 保序）
-        let scopedEntries: string[];
-        try {
-          scopedEntries = await readdir(entryPath);
-        } catch {
-          return [];
-        }
-        const perScoped = await Promise.all(
-          scopedEntries.map((scopedPkg) => processPackage(resolve(entryPath, scopedPkg), kind)),
-        );
-        return perScoped.flat();
-      }
-      // unscoped 包
-      return processPackage(entryPath, kind);
-    }),
-  );
-
-  return perEntry.flat();
-}
-
-// ── 扫描源构建 ───────────────────────────────────────────────
-
-/** 扫描源定义：路径 + source 标签 */
-interface ScanTarget {
-  dir: string;
-  source: ResourceSource;
-  /** 该源是否参与本次扫描（如 tmp 仅 workflow 启用） */
-  enabled: boolean;
-}
-
-/**
- * 读取 XYZ_EXTENSION_PATHS 环境变量（dev-link 写入的扩展源码路径）。
- *
- * delimiter 分隔（POSIX ':' / Windows ';'），trim + 过滤空 + ~ 展开。
- * 每个路径是一个 extension 包目录（dev-link 指向源码），走 processPackage 发现其
- * agents/workflows。解析逻辑与 extension-service.getUserExtensionPaths() 一致。
- */
-function readExtensionPaths(): string[] {
-  const raw = process.env.XYZ_EXTENSION_PATHS;
-  if (!raw) return [];
-  const paths = raw
-    .split(delimiter)
-    .map((p) => p.trim())
-    .filter((p) => p.length > 0)
-    .map((p) => (p.startsWith("~") ? join(homedir(), p.slice(1)) : p));
-  return [...new Set(paths)];
-}
-
-/**
- * 构建所有扫描源（按优先级低→高排列）。
- *
- * agent 和 workflow 共享相同的前缀体系，末级目录名由 kind 决定。
- */
-function buildScanTargets(config: ScanConfig): ScanTarget[] {
-  const { kind, workspaceRoot, agentDir, includeTmp } = config;
-  const home = homedir();
-
-  const targets: ScanTarget[] = [
-    // 1. user .pi/agent/{kind}/
-    { dir: join(agentDir, kind), source: "user-pi", enabled: true },
-    // 2. user .agents/{kind}/
-    { dir: join(home, ".agents", kind), source: "user-agents", enabled: true },
-    // 3. npm global: agentDir/npm/node_modules/*/<pkg>/
-    { dir: join(agentDir, "npm", "node_modules"), source: "npm", enabled: true },
-    // 4. npm dev symlink: agentDir/extensions/*/<pkg>/
-    { dir: join(agentDir, "extensions"), source: "npm-dev", enabled: true },
-    // 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（项目正式资源优先）。
-    ...readExtensionPaths().map((dir) => ({ dir, source: "user-extension-paths" as const, enabled: true })),
-    // 5. project .pi/{kind}/
-    { dir: join(workspaceRoot, ".pi", kind), source: "project-pi", enabled: true },
-  ];
-
-  // 6. project .pi/{kind}/.tmp/（仅 workflow）
-  if (includeTmp) {
-    targets.push({
-      dir: join(workspaceRoot, ".pi", kind, ".tmp"),
-      source: "project-pi-tmp",
-      enabled: true,
-    });
-  }
-
-  // 7. project .agents/{kind}/
-  targets.push({
-    dir: join(workspaceRoot, ".agents", kind),
-    source: "project-agents",
-    enabled: true,
-  });
-
-  return targets.filter((t) => t.enabled);
-}
-
-// ── 公共 API ─────────────────────────────────────────────────
-
-/**
- * 发现所有资源文件（agent .md 或 workflow .js/.mjs）。
- *
- * 按优先级低→高扫描所有源，同名资源靠后覆盖靠前（last-writer-wins）。
- * npm/dev 包内：有 manifest 只走 manifest（路径不存在则失败），无 manifest 扫约定目录。
- *
- * Throws on unrecoverable scan errors——未捕获异常向上抛（Promise.all 首个 reject
- * 即整体拒绝，与串行版 discoverResourcesSync 的传播语义一致，见实现内 [perf] 注释）。
- * 预期失败不抛：目录不存在/不可读返回空列表，manifest 声明路径缺失以 available=false 返回。
- *
- * @returns 去重后的资源列表（按优先级合并，高优先级覆盖低优先级同名）
- */
-export async function discoverResources(config: ScanConfig): Promise<DiscoveredResource[]> {
-  const targets = buildScanTargets(config);
-
-  // [perf] 源级并行（swf-perf-impl cleanup TC2/IF2）：targets.map + Promise.all，
-  // Promise.all 对 map 数组保序——allBySource 顺序 = targets 优先级序（低→高），
-  // 与串行逐源 push 完全一致 → 下方合并去重逻辑零改动、输出逐字节等价。
-  // 不加新增 catch：每源预期失败路径由内部既有 catch 面承担（scanDirectory access
-  // catch / scanNpmDir readdir catch / processPackage 全链 catch），未捕获异常
-  // 传播语义与串行版等价（ES2：串行版 target k 抛错中断后续源，并行版全部源已并发
-  // 启动、以首个 reject 拒绝——两版对调用方同为 discoverResources 抛出，各源只读无副作用）。
-  const allBySource: Array<{ source: ResourceSource; resources: DiscoveredResource[] }> = await Promise.all(
-    targets.map(async (target) => {
-      if (target.source === "npm" || target.source === "npm-dev") {
-        // npm/dev 目录：迭代包，走 manifest 或约定目录
-        const resources = await scanNpmDir(target.dir, config.kind);
-        // 覆盖 source 标签（scanNpmDir 内部统一标 "npm"，这里修正为实际源）
-        const tagged = resources.map((r) => ({ ...r, source: target.source }));
-        return { source: target.source, resources: tagged };
-      }
-      if (target.source === "user-extension-paths") {
-        // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录，走 processPackage
-        const resources = await processPackage(target.dir, config.kind);
-        const tagged = resources.map((r) => ({ ...r, source: target.source }));
-        return { source: target.source, resources: tagged };
-      }
-      // 普通目录：直接扫
-      const files = await scanDirectory(target.dir, config.kind);
-      const resources = files.map((f) => ({ path: f, source: target.source, available: true }));
-      return { source: target.source, resources };
-    }),
-  );
-
-  // 按优先级合并：targets 数组顺序即优先级（低→高），高优先级后写覆盖
-  // 用文件名 stem 作为去重 key（与旧逻辑一致：同名资源高优先级覆盖）
-  const merged = new Map<string, DiscoveredResource>();
-
-  for (const { resources } of allBySource) {
-    for (const r of resources) {
-      const key = stem(r.path);
-      const existing = merged.get(key);
-      // available=false 的占位不覆盖已有的 available=true
-      if (!r.available && existing) {
-        continue;
-      }
-      // [D8d] 同名遮蔽可观测：高优先级源覆盖低优先级同名资源时分级报告——
-      // 机器源重复是安装拓扑常态（npm 包与用户目录结构性同名），降 debug 默认静默
-      // （XYZ_AGENT_DEBUG=1 文件日志可查）；双用户源重复是配置错误，保留 warn 首报。
-      // warn 路径进程内去重（Set cap 1024，对齐 ui-request-observability 范式）：
-      // 每 session 独立进程（process-manager.ts L142-143），进程级去重 ≈ session 级首报。
-      if (existing && existing.path !== r.path) {
-        const msg =
-          `[resource-discovery] duplicate ${config.kind} "${key}" from ${r.source} shadows ${existing.source}`;
-        const data = { shadowed: existing.path, kept: r.path };
-        if (isMachineSource(existing.source) || isMachineSource(r.source)) {
-          // 任一侧为机器源 → 降级 debug（安装拓扑常态，排查走 XYZ_AGENT_DEBUG=1）
-          logger.debug(msg, data);
-        } else {
-          // 双侧均为用户源 → 保持 warn，进程内去重（同 key 只报首次）
-          const dedupKey = `${config.kind}|${key}|${existing.path}|${r.path}`;
-          if (!shadowWarnDedup.has(dedupKey)) {
-            if (shadowWarnDedup.size >= MAX_SHADOW_WARN_DEDUP) {
-              shadowWarnDedup.clear();
-            }
-            shadowWarnDedup.add(dedupKey);
-            logger.warn(msg, data);
-          }
-        }
-      }
-      merged.set(key, r);
-    }
-  }
-
-  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());
-}