@dommaker/harness 1.2.3 → 1.4.0

package/src/__tests__/passes-gate.test.ts

@@ -3,7 +3,8 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
-import { PassesGate, createPassesGate } from '../core/validators/passes-gate';
+import { PassesGate, createPassesGate, detectTestCommand } from '../core/validators/passes-gate';
+import type { TaskTestResult } from '../types/passes-gate';
 import { mkdirSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
@@ -60,13 +61,13 @@ describe('PassesGate', () => {
   });
 
   describe('runTests', () => {
-    // 跳过：会调用真实测试套件，需要 mock 重构
-    it.skip('应该返回测试结果', async () => {
-      const result = await gate.runTests();
-      
-      expect(result).toBeDefined();
-      expect(result.passed).toBeDefined();
-      expect(result.duration).toBeGreaterThan(0);
+    // 执行根由调用方传入（#95）：tempDir 的 package.json 测试命令是 echo，不再跑真实套件
+    it('应该返回测试结果', async () => {
+      const result = await gate.runTests(tempDir);
+
+      expect(result.passed).toBe(true);
+      expect(result.passedTests).toBe(1);
+      expect(result.duration).toBeGreaterThanOrEqual(0);
     });
   });
 
@@ -79,6 +80,93 @@ describe('PassesGate', () => {
     });
   });
 
+  // 探测正本行为钉住（架构评审 A2：CLI/core 双版收口后的统一语义，
+  // 此前 e2e 优先级、echo 排除、兜底均无测试钉住）
+  describe('detectTestCommand 正本（统一探测顺序）', () => {
+    const detectDir = join(process.cwd(), 'temp-test-detect-command');
+
+    const writePkg = (dir: string, scripts: Record<string, string>) => {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'detect-case', scripts }));
+    };
+
+    afterAll(() => {
+      try {
+        rmSync(detectDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    });
+
+    it('test:ci 与 test 同存时优先 test:ci', async () => {
+      const dir = join(detectDir, 'ci-over-test');
+      writePkg(dir, { test: 'jest', 'test:ci': 'jest --ci' });
+
+      expect(await detectTestCommand(dir)).toBe('npm run test:ci');
+    });
+
+    it('echo 占位脚本不算 test，同存 e2e 时落到 e2e', async () => {
+      const dir = join(detectDir, 'echo-placeholder');
+      writePkg(dir, { test: 'echo "Error: no test specified"', 'test:e2e': 'playwright test' });
+
+      expect(await detectTestCommand(dir)).toBe('npm run test:e2e');
+    });
+
+    it('仅有 echo 占位且无其他标记时返回 undefined', async () => {
+      const dir = join(detectDir, 'echo-only');
+      writePkg(dir, { test: 'echo "Error: no test specified"' });
+
+      expect(await detectTestCommand(dir)).toBeUndefined();
+    });
+
+    it('无 test/test:ci 时 test:e2e 命中，无 e2e 时 test:coverage 命中', async () => {
+      const e2eDir = join(detectDir, 'e2e-only');
+      writePkg(e2eDir, { 'test:e2e': 'vitest e2e', 'test:coverage': 'vitest --coverage' });
+      expect(await detectTestCommand(e2eDir)).toBe('npm run test:e2e');
+
+      const covDir = join(detectDir, 'coverage-only');
+      writePkg(covDir, { 'test:coverage': 'vitest --coverage' });
+      expect(await detectTestCommand(covDir)).toBe('npm run test:coverage');
+    });
+
+    it('Python 标记 pyproject.toml 或 pytest.ini 任一命中', async () => {
+      const pyprojectDir = join(detectDir, 'py-pyproject');
+      mkdirSync(pyprojectDir, { recursive: true });
+      writeFileSync(join(pyprojectDir, 'pyproject.toml'), '[project]\nname = "x"\n');
+      expect(await detectTestCommand(pyprojectDir)).toBe('pytest');
+
+      const pytestIniDir = join(detectDir, 'py-pytest-ini');
+      mkdirSync(pytestIniDir, { recursive: true });
+      writeFileSync(join(pytestIniDir, 'pytest.ini'), '[pytest]\n');
+      expect(await detectTestCommand(pytestIniDir)).toBe('pytest');
+    });
+
+    it('go.mod 命中 go test，无任何标记返回 undefined', async () => {
+      const goDir = join(detectDir, 'go-mod');
+      mkdirSync(goDir, { recursive: true });
+      writeFileSync(join(goDir, 'go.mod'), 'module example.com/x\n');
+      expect(await detectTestCommand(goDir)).toBe('go test ./...');
+
+      const emptyDir = join(detectDir, 'empty');
+      mkdirSync(emptyDir, { recursive: true });
+      expect(await detectTestCommand(emptyDir)).toBeUndefined();
+    });
+
+    it('探测失败时 runTests 与 setPasses 双路径 fail-closed', async () => {
+      const emptyDir = join(detectDir, 'fail-closed');
+      mkdirSync(emptyDir, { recursive: true });
+
+      const runResult = await gate.runTests(emptyDir);
+      expect(runResult.passed).toBe(false);
+      expect(runResult.message).toBe('未检测到测试命令');
+
+      const setResult = await gate.setPasses('task-nocmd', true, emptyDir);
+      expect(setResult.allowed).toBe(false);
+      expect(setResult.testResult?.passed).toBe(false);
+      expect(setResult.testResult?.output).toBe('未检测到测试命令');
+    });
+  });
+
   describe('checkTestFileChanges', () => {
     it('应该检测测试文件变更', async () => {
       // 无 git 变更时返回空数组
@@ -88,104 +176,6 @@ describe('PassesGate', () => {
     });
   });
 
-  describe('扩展点支持', () => {
-    it('应该能注册扩展', () => {
-      gate.registerExtension('custom', {
-        name: 'custom',
-        run: async () => ({
-          passed: true,
-          command: 'custom-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const names = gate.getExtensionNames();
-      expect(names).toContain('custom');
-    });
-
-    it('应该能注销扩展', () => {
-      gate.registerExtension('temp', {
-        name: 'temp',
-        run: async () => ({
-          passed: true,
-          command: 'temp-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const removed = gate.unregisterExtension('temp');
-      expect(removed).toBe(true);
-      
-      const names = gate.getExtensionNames();
-      expect(names).not.toContain('temp');
-    });
-
-    it('runAllTests 应该运行所有测试包括扩展', async () => {
-      gate.registerExtension('puppeteer', {
-        name: 'puppeteer',
-        run: async () => ({
-          passed: true,
-          command: 'puppeteer-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const results = await gate.runAllTests(tempDir);
-      
-      expect(results.length).toBeGreaterThan(1);  // 单元测试 + puppeteer
-      expect(results.some(r => r.type === 'puppeteer')).toBe(true);
-    });
-
-    it('checkAllPasses 应该返回综合结果', async () => {
-      gate.registerExtension('passing-ext', {
-        name: 'passing-ext',
-        run: async () => ({
-          passed: true,
-          command: 'passing-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const result = await gate.checkAllPasses(tempDir);
-      
-      expect(result.passed).toBeDefined();
-      expect(result.results).toBeDefined();
-      expect(Array.isArray(result.failedTypes)).toBe(true);
-    });
-
-    it('checkAllPasses 应该返回失败类型', async () => {
-      const failingGate = createPassesGate({ enabled: true });
-      failingGate.registerExtension('failing-ext', {
-        name: 'failing-ext',
-        run: async () => ({
-          passed: false,
-          command: 'failing-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const result = await failingGate.checkAllPasses(tempDir);
-      
-      expect(result.failedTypes).toContain('failing-ext');
-    });
-
-    it('扩展抛错应返回失败结果', async () => {
-      const errorGate = createPassesGate({ enabled: true });
-      errorGate.registerExtension('error-ext', {
-        name: 'error-ext',
-        run: async () => {
-          throw new Error('Extension error');
-        },
-      });
-      
-      const results = await errorGate.runAllTests(tempDir);
-      
-      const errorResult = results.find(r => r.type === 'error-ext');
-      expect(errorResult?.passed).toBe(false);
-      expect(errorResult?.error).toContain('Extension error');
-    });
-  });
-
   describe('getTestResult', () => {
     it('应该返回已存储的测试结果', async () => {
       const result = await gate.setPasses('stored-task', true, tempDir);
@@ -228,4 +218,50 @@ describe('PassesGate', () => {
       rmSync(retryDir, { recursive: true, force: true });
     });
   });
+
+  /**
+   * #94 裁决 B：harness 核心判定不管覆盖率 —— 从 stdout 抠覆盖率的 regex 路
+   * （extractCoverage → TaskTestResult.coverage）整体删除，结果面不再有 coverage 字段。
+   */
+  describe('覆盖率取数路删除（harness#94）', () => {
+    const covDir = join(process.cwd(), 'temp-test-no-coverage-field');
+
+    beforeAll(() => {
+      mkdirSync(covDir, { recursive: true });
+
+      // 输出里放一份 jest 覆盖率表：删除前 extractCoverage 会从中抠出 80.5 填进结果字段
+      writeFileSync(join(covDir, 'package.json'), JSON.stringify({
+        name: 'coverage-project',
+        scripts: { test: 'echo "All files | 80.50 | 70.21 | 83.33 | 79.59 |"' },
+      }));
+    });
+
+    afterAll(() => {
+      try {
+        rmSync(covDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    });
+
+    it('setPasses 结果不带 coverage 字段', async () => {
+      const covGate = createPassesGate({ enabled: true, requireEvidence: false });
+
+      const result = await covGate.setPasses('cov-task', true, covDir);
+
+      expect(result.testResult?.passed).toBe(true);
+      expect(result.testResult).not.toHaveProperty('coverage');
+    });
+
+    it('TaskTestResult 公开类型面不再接受 coverage 字段', () => {
+      const testResult: TaskTestResult = {
+        passed: true,
+        command: 'npm test',
+        // @ts-expect-error coverage 随 harness#94 删除，类型面不接受该字段
+        coverage: 85,
+      };
+
+      expect(testResult.passed).toBe(true);
+    });
+  });
 });

package/src/__tests__/public-exports.test.ts

@@ -29,6 +29,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'DEFAULT_COMMAND_BLACKLIST',
   'DEFAULT_COMPACTION_CONFIG',
   'DEFAULT_DECAY_CONFIG',
+  'DEFAULT_FAILURE_LOG_FILE',
   'DEFAULT_LEVEL_MAPPING',
   'DEFAULT_NONCODE_GLOBS',
   'DEFAULT_TEST_GLOBS',
@@ -103,6 +104,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'getCommandGate',
   'getCommandRiskLevel',
   'getConstraint',
+  'getCriticalArtifacts',
   'getEffectiveConstraints',
   'getEffectiveGates',
   'getFailureLevel',
@@ -127,6 +129,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'validateSpec',
   'verifyContractPresence',
   'verifyPhaseFormat',
+  'verifyReleaseArtifacts',
   'verifyTddChain',
 ];
 

package/src/__tests__/skip-semantics.test.ts

@@ -9,7 +9,7 @@
  * - trace 记录 result: 'skip'；TraceAnalyzer 的 pass/fail 率分母不计 skip
  */
 
-import { describe, it, expect, beforeAll, afterAll, afterEach } from '@jest/globals';
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
 import { ConstraintChecker } from '../core/constraints/checker';
 import { detectTrigger, buildConstraintContext } from '../core/constraints/context-builder';
 import { IRON_LAWS } from '../core/constraints/definitions';
@@ -20,7 +20,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 
-const checker = ConstraintChecker.getInstance();
+/** 套件共用 checker：显式 no-op 记录器（trace 断言的用例自带记录器实例） */
+const checker = new ConstraintChecker({ record: () => undefined });
 
 function makeConstraint(
   id: string,
@@ -51,11 +52,6 @@ describe('skip 三态语义（ADR-0001）', () => {
     }
   });
 
-  afterEach(() => {
-    // 复位 trace recorder，避免泄漏到其他用例
-    checker.setTraceRecorder({ record: () => undefined });
-  });
-
   describe('capability_sync 存在性探测', () => {
     it('无 CAPABILITIES.md（未采用约定）→ skip，不计 fail', async () => {
       const dir = path.join(tempDir, 'cap-skip');
@@ -289,9 +285,9 @@ describe('skip 三态语义（ADR-0001）', () => {
   describe('trace 的 skip 形态', () => {
     it('recordTrace：skip 记录为 result: skip', async () => {
       const records: ExecutionTrace[] = [];
-      checker.setTraceRecorder({ record: (t) => records.push(t) });
+      const recording = new ConstraintChecker({ record: (t) => records.push(t) });
 
-      await checker.checkConstraints({
+      await recording.checkConstraints({
         operation: 'code_implementation',
         projectPath: path.join(tempDir, 'empty'),
       });

package/src/cli/__tests__/command-contract.test.ts

@@ -0,0 +1,170 @@
+/**
+ * 命令契约测试（架构评审候选7）
+ *
+ * Seam：src/cli/command-contract.ts —— 命令实现的返回形状 + 输出注入面。
+ * 关键不变量：注入缺省 io（process 流）时，log/logError 的输出字节与
+ * console.log/console.error 逐字一致（CLI 语法冻结护栏：输出文案不得漂移）。
+ */
+
+import { Writable } from 'stream';
+import {
+  captureIO,
+  lastJsonOutput,
+  log,
+  logError,
+  processIO,
+  type CommandIO,
+  type CommandResult,
+} from '../command-contract';
+
+/** 同步收集写入 chunk 的最小可写流（console.Console 与 CommandIO 共用同一 sink） */
+class Sink extends Writable {
+  private chunks: string[] = [];
+  _write(chunk: any, _enc: string, cb: () => void): void {
+    this.chunks.push(String(chunk));
+    cb();
+  }
+  reset(): void {
+    this.chunks = [];
+  }
+  get text(): string {
+    return this.chunks.join('');
+  }
+}
+
+/**
+ * 同一参数分别经 Node 的 console（标准实现）与 log/logError（命令侧写入面）
+ * 写入同一 sink，返回两者渲染文本。
+ */
+function renderBoth(method: 'log' | 'error', args: unknown[]): { viaConsole: string; viaContract: string } {
+  const out = new Sink();
+  const err = new Sink();
+  const io: CommandIO = { stdout: out, stderr: err };
+
+  const nodeConsole = new console.Console(out, err);
+  (nodeConsole[method] as (...a: unknown[]) => void)(...args);
+  const viaConsole = method === 'log' ? out.text : err.text;
+
+  out.reset();
+  err.reset();
+  if (method === 'log') log(io, ...args);
+  else logError(io, ...args);
+  const viaContract = method === 'log' ? out.text : err.text;
+
+  return { viaConsole, viaContract };
+}
+
+describe('log/logError 与 console 输出等价', () => {
+  const cases: unknown[][] = [
+    [],
+    ['plain'],
+    ['%s and %d and %j', 'x', 3, { a: 1 }],
+    [{ nested: { deep: [1, 2, 3] } }],
+    [null, undefined, 0, false],
+    ['多字节 ✓ emoji 🎉'],
+    [''],
+  ];
+
+  it.each(cases.map((c, i) => [i, c] as [number, unknown[]]))(
+    'case %i：log(io) 与 console.log 逐字节一致',
+    (_i, args) => {
+      const { viaConsole, viaContract } = renderBoth('log', args as unknown[]);
+      expect(viaContract).toBe(viaConsole);
+    },
+  );
+
+  it.each(cases.map((c, i) => [i, c] as [number, unknown[]]))(
+    'case %i：logError(io) 与 console.error 逐字节一致',
+    (_i, args) => {
+      const { viaConsole, viaContract } = renderBoth('error', args as unknown[]);
+      expect(viaContract).toBe(viaConsole);
+    },
+  );
+
+  it('缺省 io 指向 process 标准流', () => {
+    expect(processIO.stdout).toBe(process.stdout);
+    expect(processIO.stderr).toBe(process.stderr);
+  });
+});
+
+describe('captureIO（测试注入面）', () => {
+  it('stdout/stderr 分别累积，按行可取', () => {
+    const io = captureIO();
+    log(io, 'one');
+    log(io, 'two %s', 'x');
+    logError(io, 'boom');
+    expect(io.outLines()).toEqual(['one', 'two x']);
+    expect(io.errLines()).toEqual(['boom']);
+    expect(io.outText()).toBe('one\ntwo x\n');
+    expect(io.errText()).toBe('boom\n');
+  });
+
+  it('无参 log 产生空行（console.log() 语义）', () => {
+    const io = captureIO();
+    log(io);
+    expect(io.outText()).toBe('\n');
+    expect(io.outLines()).toEqual(['']);
+  });
+
+  it('outRecords/errRecords 保留每次写入原文（多行 JSON 等同一次打印的整体）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ a: 1 }, null, 2));
+    logError(io, 'e1');
+    logError(io, 'e2');
+
+    expect(io.outRecords()).toHaveLength(1);
+    expect(JSON.parse(io.outRecords()[0])).toEqual({ a: 1 });
+    expect(io.errRecords()).toEqual(['e1\n', 'e2\n']);
+  });
+
+  it('同一命令内 stdout 与 stderr 互不串台', () => {
+    const io = captureIO();
+    log(io, 'a');
+    logError(io, 'b');
+    log(io, 'c');
+    expect(io.outLines()).toEqual(['a', 'c']);
+    expect(io.errLines()).toEqual(['b']);
+  });
+});
+
+describe('lastJsonOutput（--json 命令输出解析正本，harness#108）', () => {
+  it('解析 captureIO 累计的 stdout 为 JSON（缺省 Record 形状）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ sessions: 3, corrections: 3 }));
+    expect(lastJsonOutput(io)).toEqual({ sessions: 3, corrections: 3 });
+  });
+
+  it('多行 pretty JSON 整体解析（一次 log 写入）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ a: 1, nested: { b: [2] } }, null, 2));
+    expect(lastJsonOutput(io)).toEqual({ a: 1, nested: { b: [2] } });
+  });
+
+  it('泛型参数解锁消费方已知形状（任意字段穿透）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ flywheel: { refCoverage: 0.5 } }));
+    expect(lastJsonOutput<any>(io).flywheel.refCoverage).toBe(0.5);
+  });
+
+  it('stdout 非 JSON 时抛错（解析失败不静默吞掉）', () => {
+    const io = captureIO();
+    log(io, 'not json');
+    expect(() => lastJsonOutput(io)).toThrow();
+  });
+});
+
+describe('CommandResult 判别联合', () => {
+  it('四种 kind 均可构造，fail/usage-error 必带 reason（类型层护栏）', () => {
+    const results: CommandResult[] = [
+      { kind: 'ok' },
+      { kind: 'skip', reason: '约定未采纳' },
+      { kind: 'skip' },
+      { kind: 'fail', reason: 'gate:branch 非 master' },
+      { kind: 'usage-error', reason: '缺少 planPath' },
+    ];
+    const kinds = results.map(r => r.kind);
+    expect(kinds).toEqual(['ok', 'skip', 'skip', 'fail', 'usage-error']);
+    expect(results.filter(r => r.kind !== 'ok').map(r => ('reason' in r ? r.reason : undefined)))
+      .toEqual(['约定未采纳', undefined, 'gate:branch 非 master', '缺少 planPath']);
+  });
+});

package/src/cli/command-contract.ts

@@ -0,0 +1,108 @@
+/**
+ * CLI 命令契约（架构评审候选7）
+ *
+ * 命令实现的 interface 由两部分组成，都在本模块定义：
+ * - **返回值 `CommandResult`**：判定结果（哪个 kind、为什么）。退出码不再由命令
+ *   自己 `process.exit`，而是由 bin 依 kind 唯一映射（`process.exit` 因此只出现在
+ *   bin/harness.js 一处）。
+ * - **写入面 `CommandIO`**：流式输出去向。命令一律经注入的 io 打印，缺省 process
+ *   标准流——长命令（如 release）边跑边输出，不憋到结束由 bin 统一打印。
+ *
+ * 对外行为护栏：`processIO` 下 log/logError 的输出字节与 console.log/console.error
+ * 逐字一致（见 __tests__/command-contract.test.ts），CLI 语法与文案冻结。
+ */
+
+import { format } from 'util';
+
+/**
+ * 命令判定类别。
+ * 对外退出码只有 0/1（历史面），语义放进 kind，码值映射收敛在 bin。
+ */
+export type CommandKind = 'ok' | 'skip' | 'fail' | 'usage-error';
+
+/**
+ * 命令实现返回值（判别联合）。
+ * `fail` / `usage-error` 必附 `reason`，且 reason 要能唯一定位失败点
+ * （多闸门命令须含闸门标识）；`skip` 可选附原因。
+ */
+export type CommandResult =
+  | { kind: 'ok' }
+  | { kind: 'skip'; reason?: string }
+  | { kind: 'fail'; reason: string }
+  | { kind: 'usage-error'; reason: string };
+
+/**
+ * 命令输出流注入面（最小可写接口，`process.stdout` / `process.stderr` 结构化满足）
+ */
+export interface CommandIO {
+  stdout: { write(chunk: string): boolean };
+  stderr: { write(chunk: string): boolean };
+}
+
+/** 缺省 io：process 标准流（bin 不注入时的现状行为） */
+export const processIO: CommandIO = {
+  stdout: process.stdout,
+  stderr: process.stderr,
+};
+
+/**
+ * 与 console.log 同语义（util.format + 换行）写入 io.stdout
+ */
+export function log(io: CommandIO, ...args: unknown[]): void {
+  io.stdout.write(format(...args) + '\n');
+}
+
+/**
+ * 与 console.error 同语义（util.format + 换行）写入 io.stderr
+ */
+export function logError(io: CommandIO, ...args: unknown[]): void {
+  io.stderr.write(format(...args) + '\n');
+}
+
+/**
+ * 捕获型 io：测试注入面，替代 `spyOn(process, 'exit')` 时代的彩色字符串断言。
+ */
+export interface CapturingIO extends CommandIO {
+  /** 已写入 stdout 的全部文本 */
+  outText(): string;
+  /** 已写入 stderr 的全部文本 */
+  errText(): string;
+  /** stdout 按行切分（末尾换行不产生空尾行） */
+  outLines(): string[];
+  /** stderr 按行切分（末尾换行不产生空尾行） */
+  errLines(): string[];
+  /** stdout 每次写入的原始文本（一次 log 调用 = 一条记录，等价旧的 console.log 调用参数视图） */
+  outRecords(): string[];
+  /** stderr 每次写入的原始文本 */
+  errRecords(): string[];
+}
+
+export function captureIO(): CapturingIO {
+  let out = '';
+  let err = '';
+  const outChunks: string[] = [];
+  const errChunks: string[] = [];
+  const split = (text: string): string[] =>
+    text.endsWith('\n') ? text.slice(0, -1).split('\n') : (text === '' ? [] : text.split('\n'));
+  return {
+    stdout: { write: (chunk: string) => { out += chunk; outChunks.push(chunk); return true; } },
+    stderr: { write: (chunk: string) => { err += chunk; errChunks.push(chunk); return true; } },
+    outText: () => out,
+    errText: () => err,
+    outLines: () => split(out),
+    errLines: () => split(err),
+    outRecords: () => [...outChunks],
+    errRecords: () => [...errChunks],
+  };
+}
+
+/**
+ * 解析 --json 命令的捕获输出（测试断言面，harness#108）
+ *
+ * 与 captureIO 同住一处：它是 captureIO 的消费端正本，此前散在各命令测试里
+ * 逐字复制（JSON.parse(outText())）。缺省返回 Record 形状；消费方已知字段
+ * 形状时传泛型（如 lastJsonOutput<any>(io) 做任意字段穿透）。
+ */
+export function lastJsonOutput<T = Record<string, unknown>>(capture: CapturingIO): T {
+  return JSON.parse(capture.outText());
+}