@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/agent-registry.ts

@@ -0,0 +1,252 @@
+// src/execution/agent-registry.ts
+//
+// agent .md 文件发现与解析。
+//
+// 发现逻辑统一走 shared/resource-discovery（ADR-031），与 workflow 共享同一套
+// 扫描源前缀 + manifest 校验。hot-reload：每次调用重扫（mtime 缓存跳过未变文件）。
+//
+// builtin agent（包内 agents/*.md）走 pi.agents manifest（与 npm 包内发现规则一致）。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  type DiscoveredResource,
+  discoverResourcesSync,
+  type ScanConfig,
+} from "../shared/resource-discovery.ts";
+import type { AgentConfig } from "./model-resolver.ts";
+
+/** 内置 agent（代码硬编码，如 default worker）。 */
+export interface BuiltinAgentRegistry {
+  get(name: string): AgentConfig | undefined;
+  list(): string[];
+}
+
+/**
+ * 包内自带 agents（与 src/ 同级的 agents/ 目录）。
+ *
+ * 走 pi.agents manifest（package.json 的 pi.agents 字段），与 npm 包内发现规则一致。
+ * manifest 缺失时 fallback 扫约定目录 agents/。
+ *
+ * [HISTORICAL] 此前 discoverAll 从未被调用，agentRegistry 永远为空——包内
+ * agents/*.md（worker/reviewer/scout 等）pi install 后开箱不可用。修复：构造时扫描
+ * 包内 agents/ 作为 builtin（优先级最低，被用户同名文件覆盖）。
+ */
+export function createPackageBuiltinRegistry(): BuiltinAgentRegistry {
+  const packageRoot = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+  );
+  const cache = new Map<string, AgentConfig>();
+  try {
+    const config = discoverPackageAgentsSync(packageRoot);
+    for (const resource of config) {
+      if (!resource.available) continue;
+      try {
+        const raw = fs.readFileSync(resource.path, "utf-8");
+        const agentConfig = parseAgentFrontmatter(resource.path, raw);
+        if (agentConfig) cache.set(agentConfig.name, agentConfig);
+      } catch (err) {
+        // 单个 builtin agent 文件损坏不影响其他——降级跳过该文件。
+        void err;
+        console.warn(`[subagents] skip malformed builtin agent: ${resource.path}`, err);
+      }
+    }
+  } catch (err) {
+    // agents/ 目录不存在（打包遗漏）→ 空 builtin，不崩。
+    void err;
+    console.warn("[subagents] builtin agents/ directory unreadable, falling back to empty set:", err);
+  }
+  return {
+    get: (name) => cache.get(name),
+    list: () => [...cache.keys()],
+  };
+}
+
+/** mtime 缓存条目（跨 discoverAll 保留，靠 mtime 判失效）。 */
+interface FileCacheEntry {
+  mtimeMs: number;
+  config: AgentConfig;
+}
+
+// ============================================================
+// frontmatter 解析
+// ============================================================
+
+/** frontmatter 分隔符。 */
+const FM_DELIM = "---";
+
+/**
+ * 解析 .md frontmatter（name/tools/model/thinkingLevel/defaultBackground）+ body（systemPrompt）。
+ * 兼容简单 YAML（key: value 单行格式）。body 作为 systemPrompt。
+ */
+export function parseAgentFrontmatter(filePath: string, content: string): AgentConfig {
+  const name = path.basename(filePath, ".md");
+
+  // 无 frontmatter → 整个内容作为 systemPrompt
+  if (!content.startsWith(FM_DELIM)) {
+    return { name, systemPrompt: content.trim() };
+  }
+
+  const closeIdx = content.indexOf(FM_DELIM, FM_DELIM.length);
+  if (closeIdx === -1) {
+    // 未闭合 frontmatter：提取 name，其余作为 systemPrompt
+    const yamlBlock = content.slice(FM_DELIM.length);
+    return {
+      name: extractYamlField(yamlBlock, "name") ?? name,
+      systemPrompt: content.trim(),
+    };
+  }
+
+  const yamlBlock = content.slice(FM_DELIM.length, closeIdx);
+  const body = content.slice(closeIdx + FM_DELIM.length).trim();
+
+  const toolsRaw = extractYamlField(yamlBlock, "tools");
+  const tools = toolsRaw
+    ? toolsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+
+  const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
+
+  return {
+    name: extractYamlField(yamlBlock, "name") ?? name,
+    systemPrompt: body,
+    model: extractYamlField(yamlBlock, "model") ?? undefined,
+    thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
+    tools: tools && tools.length > 0 ? tools : undefined,
+    defaultBackground: defaultBackgroundRaw === "true" ? true : undefined,
+  };
+}
+
+/** 提取简单 `key: value` 字段，剥离引号。 */
+function extractYamlField(yaml: string, key: string): string | undefined {
+  const regex = new RegExp(`^${key}:\\s*(.+)$`, "m");
+  const match = yaml.match(regex);
+  if (!match) return undefined;
+  let value = match[1].trim();
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  }
+  return value || undefined;
+}
+
+// ============================================================
+// AgentRegistry
+// ============================================================
+
+/**
+ * 发现配置：用于统一资源发现的扫描参数。
+ */
+export interface AgentDiscoveryConfig {
+  /** 项目根目录（findWorkspaceRoot 推导结果） */
+  workspaceRoot: string;
+  /** agent 配置目录（getAgentDir() 结果） */
+  agentDir: string;
+}
+
+/**
+ * agent 注册表。通过统一资源发现（shared/resource-discovery）扫描所有源。
+ * hot-reload：每次 discoverAll 重扫，mtime 未变的文件跳过 read+parse。
+ *
+ * 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev →
+ * project .pi → project .agents。builtin（包内）优先级最低。
+ * 详见 ADR-031。
+ */
+export class AgentRegistry {
+  private readonly cache = new Map<string, AgentConfig>();
+  /** 文件级 mtime 缓存（key=绝对路径，跨 discoverAll 保留）。 */
+  private readonly fileCache = new Map<string, FileCacheEntry>();
+  /** 本轮扫描到的路径集（清理已删除文件的缓存）。 */
+  private currentScanPaths = new Set<string>();
+
+  constructor(private readonly discoveryConfig: AgentDiscoveryConfig) {}
+
+  /** 扫描所有源 + 合并 builtin（hot-reload，每次重扫）。 */
+  discoverAll(builtin: BuiltinAgentRegistry): void {
+    this.cache.clear();
+    this.currentScanPaths = new Set();
+
+    const scanConfig: ScanConfig = {
+      kind: "agents",
+      workspaceRoot: this.discoveryConfig.workspaceRoot,
+      agentDir: this.discoveryConfig.agentDir,
+    };
+    const resources = discoverResourcesSync(scanConfig);
+
+    for (const resource of resources) {
+      if (!resource.available) continue;
+      this.currentScanPaths.add(resource.path);
+      try {
+        const config = this.loadWithMtimeCache(resource.path);
+        if (config) this.cache.set(config.name, config);
+      } catch (_err) {
+        // 有意吞掉：文件不可读/解析失败 → 跳过（不阻断其他 agent 发现）
+        void _err;
+      }
+    }
+
+    // builtin 优先级最低（先写入，被文件 agent 覆盖）
+    for (const agentName of builtin.list()) {
+      if (!this.cache.has(agentName)) {
+        const config = builtin.get(agentName);
+        if (config) this.cache.set(agentName, config);
+      }
+    }
+
+    // 清理本轮未扫描到的文件缓存条目（文件被删除/移走）
+    for (const cachedPath of this.fileCache.keys()) {
+      if (!this.currentScanPaths.has(cachedPath)) {
+        this.fileCache.delete(cachedPath);
+      }
+    }
+  }
+
+  /** 按 name 查找。require=false 时找不到返回 undefined；true 时抛错。 */
+  get(name: string, require?: boolean): AgentConfig | undefined {
+    const config = this.cache.get(name);
+    if (!config && require) {
+      throw new Error(
+        `Agent "${name}" not found. Discovered: ${[...this.cache.keys()].join(", ") || "(none)"}`,
+      );
+    }
+    return config;
+  }
+
+  /** 列出所有已发现 agent 名（诊断/wizard 用）。 */
+  list(): string[] {
+    return [...this.cache.keys()];
+  }
+
+  // ── 内部 ──────────────────────────────────────────────────
+
+  /** 带 mtime 缓存的单文件加载。mtime 未变复用缓存，否则 read+parse。 */
+  private loadWithMtimeCache(filePath: string): AgentConfig | undefined {
+    const stat = fs.statSync(filePath);
+    const mtimeMs = stat.mtimeMs;
+    const cached = this.fileCache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+      return cached.config;
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    const config = parseAgentFrontmatter(filePath, content);
+    this.fileCache.set(filePath, { mtimeMs, config });
+    return config;
+  }
+}
+
+// ============================================================
+// 包内 agent 发现（builtin 用，走 pi.agents manifest）
+// ============================================================
+
+import { processPackageSync } from "../shared/resource-discovery.ts";
+
+/**
+ * 发现包内 agent 文件（走 pi.agents manifest 或约定目录 agents/）。
+ * builtin 专用——不参与优先级合并，优先级最低。
+ */
+function discoverPackageAgentsSync(packageRoot: string): DiscoveredResource[] {
+  return processPackageSync(packageRoot, "agents");
+}

package/src/execution/agent-result-mapper.ts

@@ -0,0 +1,84 @@
+// src/execution/agent-result-mapper.ts
+//
+// D-A10: subagents AgentResult → workflow AgentResult 映射。
+// 纯 DTO 映射函数——executeAndAwait 出口调，SAR 不感知形状差异。
+//
+// 接线层级：[模块内直调] —— SubagentService.executeAndAwait 出口调。
+
+import type { AgentResult as WorkflowAgentResult, AgentUsage as WorkflowAgentUsage, ToolCallEntry } from "../orchestration/models/types.ts";
+import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } from "./types.ts";
+
+/**
+ * D-A10: subagents AgentResult → workflow AgentResult 映射。
+ *
+ * 字段映射表：
+ *   subagents                         → workflow
+ *   ─────────────────────────────────────────────
+ *   text                              → content
+ *   parsedOutput                      → parsedOutput（structured-output 契约，BC-8）
+ *   !success && error                 → error（失败时填，成功时 undefined）
+ *   durationMs                        → durationMs
+ *   sessionId                         → sessionId
+ *   usage (AgentUsageTotal)           → usage (AgentUsage: input/output/cacheRead/cacheWrite/cost/contextTokens/turns)
+ *   toolCalls (ToolCall[])            → toolCalls (ToolCallEntry[]: name/input)
+ *
+ * @param r subagents 管道产出的 AgentResult（runSpawn/collectResult 出口形状）
+ * @returns workflow 编排层消费的 AgentResult（executeAgentCall/finalizeCall 入参形状）
+ */
+export function mapToWorkflowAgentResult(
+  r: SubagentsAgentResult,
+): WorkflowAgentResult {
+  return {
+    content: r.text,
+    parsedOutput: r.parsedOutput,
+    error: r.success ? undefined : r.error,
+    durationMs: r.durationMs,
+    sessionId: r.sessionId,
+    usage: r.usage ? mapUsage(r.usage, r.turns) : undefined,
+    toolCalls: r.toolCalls ? mapToolCalls(r.toolCalls) : undefined,
+  };
+}
+
+/**
+ * AgentUsageTotal（subagents）→ AgentUsage（workflow）映射。
+ *
+ * subagents AgentUsageTotal: { input, output, cacheRead, cacheWrite, total, cost }
+ * workflow AgentUsage:       { input, output, cacheRead, cacheWrite, cost, contextTokens, turns }
+ *
+ * contextTokens ≈ total（subagents 的四项之和，近似上下文 token 量）。
+ * turns 来自 AgentResult.turns（非 usage 内字段）。
+ */
+function mapUsage(u: AgentUsageTotal, turns: number): WorkflowAgentUsage {
+  return {
+    input: u.input,
+    output: u.output,
+    cacheRead: u.cacheRead,
+    cacheWrite: u.cacheWrite,
+    cost: u.cost,
+    contextTokens: u.total,
+    turns,
+  };
+}
+
+/**
+ * ToolCall（subagents）→ ToolCallEntry（workflow）映射。
+ *
+ * subagents ToolCall:     { toolName, args?, result?, isError? }
+ * workflow ToolCallEntry: { name, input }
+ */
+function mapToolCalls(calls: ToolCall[]): ToolCallEntry[] {
+  return calls.map((c) => ({
+    name: c.toolName,
+    input: c.args === undefined ? "" : safeStringify(c.args),
+  }));
+}
+
+/** 安全序列化（args 可能含循环引用或大对象，截断防 OOM）。 */
+function safeStringify(value: unknown): string {
+  try {
+    const s = JSON.stringify(value);
+    return s.length > 500 ? `${s.slice(0, 500)}...` : s;
+  } catch {
+    return String(value);
+  }
+}

package/src/execution/alive-store.ts

@@ -0,0 +1,92 @@
+// src/runtime/execution/alive-store.ts
+//
+// .alive sidecar 生产者 + pid 探活。
+//
+// 子进程启动时写 .alive（pid+id+startedAt），心跳检测时读它 + isProcessAlive
+// 判活。finalize/cancel 收尾时 remove。与 .cancelled/.finalized 构成三件套。
+//
+// 设计对齐 tombstone-store：单文件 sidecar、best-effort I/O、无全局 index。
+
+import * as fs from "node:fs";
+
+import type { AliveMarker } from "./types.ts";
+
+// ============================================================
+// 公开函数
+// ============================================================
+
+/**
+ * 在 sessionFile 旁写 .alive sidecar（单行 JSON）。
+ * 覆盖写——同一 sessionFile 只有最后一个 alive marker 有意义。
+ */
+export function writeAliveMarker(sessionFile: string, marker: AliveMarker): void {
+  const alivePath = `${sessionFile}.alive`;
+  fs.writeFileSync(alivePath, `${JSON.stringify(marker)}\n`, "utf-8");
+}
+
+/**
+ * 读 sessionFile 旁的 .alive sidecar。
+ * 返回 undefined：不存在 / 损坏 / 解析失败。
+ */
+export function readAliveMarker(sessionFile: string): AliveMarker | undefined {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(`${sessionFile}.alive`, "utf-8");
+  } catch {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<AliveMarker>;
+    if (
+      typeof parsed.pid === "number" &&
+      typeof parsed.id === "string" &&
+      typeof parsed.startedAt === "number"
+    ) {
+      return parsed as AliveMarker;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 删除 sessionFile 旁的 .alive sidecar。
+ * best-effort：不存在不抛（finalize/cancel 收尾调，sidecar 可能已被清理）。
+ */
+export function removeAliveMarker(sessionFile: string): void {
+  try {
+    fs.unlinkSync(`${sessionFile}.alive`);
+  } catch {
+    void 0; // best-effort
+  }
+}
+
+/**
+ * 检测 pid 是否存活。
+ *
+ * process.kill(pid, 0) 语义：不发信号，仅检查进程是否存在。
+ *   - 无异常 → 存活
+ *   - ESRCH（No such process）→ 死
+ *   - EPERM（Process exists but no permission）→ 存活（保守）
+ *   - 其他异常 → 保守判死 false，避免误删活进程
+ */
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    if (isErrnoException(err) && err.code === "EPERM") {
+      return true; // 存在但无权限发信号 → 判活
+    }
+    return false; // ESRCH 或其他异常 → 保守判死
+  }
+}
+
+// ============================================================
+// 内部工具
+// ============================================================
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && "code" in err;
+}

package/src/execution/best-effort.ts

@@ -0,0 +1,30 @@
+// src/utils/best-effort.ts
+//
+// best-effort IO 清理的错误吞咽 helper。
+//
+// 用途：sidecar 写入 / worktree remove / alive marker 删除等次要 IO，失败不影响
+// 主流程（session 已完成或正在收尾）。这类 catch 故意吞错——但 taste/no-silent-catch
+// 规则禁止空 catch 或仅 console 的 catch。本 helper 提供一条「实质调用语句」让
+// catch 合规，同时把错误记录到 debug/error 便于排查。
+//
+// 规则绕过原理：taste/no-silent-catch 仅检查 CatchClause 直接 body 是否为空或仅
+// console 调用。本 helper 是普通函数调用（ExpressionStatement），既非空也非仅
+// console，故合规。helper 函数体内部的 console 不被该规则检查。
+
+/** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
+export type BestEffortLevel = "debug" | "error";
+
+/**
+ * 吞咽 best-effort IO 的错误，按 level 记录到 console。
+ *
+ *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
+ *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
+ *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
+ *
+ * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样打印。
+ */
+export function bestEffort(err: unknown, context: string, level: BestEffortLevel = "debug"): void {
+  const detail = err instanceof Error ? err.message : err;
+  const fn = level === "error" ? console.error : console.debug;
+  fn(`[subagents] best-effort ${context} failed:`, detail);
+}

package/src/execution/concurrency-pool.ts

@@ -0,0 +1,84 @@
+// src/core/concurrency-pool.ts
+//
+// 并发控制 + 优先级排队。background=1000（单一优先级，保留 priority 机制供未来扩展）。
+
+/** 队列条目：优先级 + resolver + 入队序号（同优先级 FIFO）。 */
+interface QueueEntry {
+  priority: number;
+  resolve: () => void;
+  seq: number;
+}
+
+/** 并发池接口（可注入，便于测试 mock）。 */
+export interface ConcurrencyPool {
+  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。 */
+  acquire(priority: number, effectiveMaxConcurrent?: number): Promise<void>;
+  /** 归还槽位。必须无条件执行（finally）。 */
+  release(): void;
+  /** 当前已占用槽位数（诊断/widget 用）。 */
+  readonly active: number;
+  /** 实例级最大并发配额。调用方可据此计算分层配额（max(1, maxConcurrent - depth)）。 */
+  readonly maxConcurrent: number;
+}
+
+/**
+ * 默认实现：maxConcurrent 槽位 + 优先级队列。
+ *
+ *   acquire(priority, effectiveMaxConcurrent?):
+ *     effective = effectiveMaxConcurrent ?? maxConcurrent
+ *     active < effective → active++, resolve
+ *     否则 → 入队 { priority, resolve, seq }, 队列按 priority 升序 + seq FIFO
+ *
+ *   release():
+ *     queue 非空 → 出队最高优先级 resolve（active 不变）
+ *     queue 空 → active--（防下溢）
+ */
+export class DefaultConcurrencyPool implements ConcurrencyPool {
+  private _active = 0;
+  private readonly queue: QueueEntry[] = [];
+  private seqCounter = 0;
+
+  /** 下限 1——maxConcurrent=0 会让 acquire 永久排队死锁（C3 修复）。 */
+  readonly maxConcurrent: number;
+
+  constructor(maxConcurrent: number) {
+    this.maxConcurrent = Math.max(1, maxConcurrent);
+  }
+
+  acquire(priority: number, effectiveMaxConcurrent?: number): Promise<void> {
+    // effectiveMaxConcurrent 覆盖实例级默认配额（分层配额：调用方传 max(1, maxConcurrent - depth)）。
+    // 不修改实例级 maxConcurrent——实例配额是全局共享上限，分层配额是本次 acquire 的局部上限。
+    const effective = effectiveMaxConcurrent ?? this.maxConcurrent;
+    if (this._active < effective) {
+      this._active += 1;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this.queue.push({ priority, resolve, seq: this.seqCounter++ });
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      // 取优先级最高（priority 最小）的；同优先级 FIFO（seq 最小）
+      let bestIdx = 0;
+      for (let i = 1; i < this.queue.length; i++) {
+        const cur = this.queue[i];
+        const best = this.queue[bestIdx];
+        if (cur.priority < best.priority || (cur.priority === best.priority && cur.seq < best.seq)) {
+          bestIdx = i;
+        }
+      }
+      const next = this.queue.splice(bestIdx, 1)[0];
+      next.resolve();
+      // active 不变（一个离开队列立即进入活跃）
+    } else if (this._active > 0) {
+      // 防御性下界：release 调用次数多于 acquire 时不让 active 为负
+      this._active -= 1;
+    }
+  }
+
+  get active(): number {
+    return this._active;
+  }
+}

package/src/execution/config.ts

@@ -0,0 +1,73 @@
+// src/runtime/config/config.ts
+//
+// 全局配置（~/.pi/agent/subagents/config.json）。
+// 仅保留 maxConcurrent（pool 大小）。模型解析已退化为「主 agent model 优先」，
+// 不再有 category/fallback/session 级覆盖——相关字段读取时忽略。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { SubagentsGlobalConfig } from "./types.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/**
+ * 开箱默认配置（单一真相源，内联在代码里）。
+ *
+ * 历史教训 [HISTORICAL]：曾用包内 config.json（与 src/ 同级）作为默认值源，
+ * 但 config.json 被 .gitignore 排除且不应随 npm 包分发用户私有配置——导致
+ * npm pack 后读不到文件，catch 兜底用空字段，pi install 后首次执行抛错。
+ * 修复：默认值内联在代码里，不依赖任何包内文件。
+ */
+const DEFAULT_CONFIG: SubagentsGlobalConfig = {
+  version: 1,
+  maxConcurrent: 6,
+};
+
+/** 默认 maxConcurrent（DEFAULT_CONFIG 的镜像，sanitize 用）。 */
+const DEFAULT_MAX_CONCURRENT = 6;
+
+// ============================================================
+// 路径
+// ============================================================
+
+/**
+ * 配置文件路径（<agentDir>/subagents/config.json）。
+ * agentDir 由 Pi 核心 getAgentDir() 决定（读 PI_CODING_AGENT_DIR，默认 ~/.pi/agent），
+ * 与 Pi 主进程的目录约定完全一致——支持宿主经环境变量整体重定向。
+ */
+export function getGlobalConfigPath(agentDir: string): string {
+  return path.join(agentDir, "subagents", "config.json");
+}
+
+// ============================================================
+// 全局配置加载
+// ============================================================
+
+/**
+ * 加载全局配置。文件不存在 / JSON 解析失败 / 字段缺失时返回默认配置。
+ * 旧 config.json 中的 categories/fallback/yoloByDefault 等字段读取时忽略
+ * （模型解析已退化为「主 agent model 优先」）。
+ */
+export function loadGlobalConfig(agentDir: string): SubagentsGlobalConfig {
+  const configPath = getGlobalConfigPath(agentDir);
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<SubagentsGlobalConfig>;
+    return {
+      version: parsed.version ?? DEFAULT_CONFIG.version,
+      maxConcurrent: sanitizeMaxConcurrent(parsed.maxConcurrent),
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+/** maxConcurrent 校验：正整数，否则默认。 */
+function sanitizeMaxConcurrent(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_CONCURRENT;
+}