@dommaker/harness 1.2.3 → 1.4.0

package/src/cli/commands/contract.ts

@@ -8,6 +8,7 @@ import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { ContractGate } from '../../gates/contract';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ContractOptions {
   /** 项目路径 */
@@ -23,8 +24,11 @@ export interface ContractOptions {
 /**
  * 执行契约门控
  */
-export async function contract(options: ContractOptions): Promise<void> {
-  console.log(chalk.blue('📜 API 契约门控检查...'));
+export async function contract(
+  options: ContractOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('📜 API 契约门控检查...'));
 
   const projectPath = options.projectPath || process.cwd();
   const contractPath = options.contractPath || 'openapi.yaml';
@@ -34,10 +38,10 @@ export async function contract(options: ContractOptions): Promise<void> {
   try {
     await fs.access(fullPath);
   } catch {
-    console.log();
-    console.log(chalk.red('❌ 契约文件不存在'));
-    console.log(chalk.red(`   ${fullPath}`));
-    process.exit(1);
+    log(io);
+    log(io, chalk.red('❌ 契约文件不存在'));
+    log(io, chalk.red(`   ${fullPath}`));
+    return { kind: 'fail', reason: `contract file not found: ${fullPath}` };
   }
 
   // 创建契约门控实例
@@ -53,57 +57,61 @@ export async function contract(options: ContractOptions): Promise<void> {
     } as any);
 
     if (result.passed) {
-      console.log();
-      console.log(chalk.green('✅ 契约门控检查通过'));
+      log(io);
+      log(io, chalk.green('✅ 契约门控检查通过'));
 
       if (result.details) {
-        console.log(chalk.gray(`   Schema 有效: ✅`));
+        log(io, chalk.gray(`   Schema 有效: ✅`));
         if (result.details.endpoints) {
-          console.log(chalk.gray(`   端点数: ${result.details.endpoints}`));
+          log(io, chalk.gray(`   端点数: ${result.details.endpoints}`));
         }
         if (result.details.breakingChanges === false) {
-          console.log(chalk.gray(`   破坏性变更: 无`));
+          log(io, chalk.gray(`   破坏性变更: 无`));
         }
       }
     } else {
-      console.log();
-      console.log(chalk.red('❌ 契约门控检查失败'));
-      console.log(chalk.red(`   ${result.message}`));
+      log(io);
+      log(io, chalk.red('❌ 契约门控检查失败'));
+      log(io, chalk.red(`   ${result.message}`));
 
       if (result.details?.errors) {
-        console.log();
-        console.log(chalk.red('验证错误:'));
+        log(io);
+        log(io, chalk.red('验证错误:'));
         (result.details.errors as string[]).forEach((error: string) => {
-          console.log(chalk.red(`  - ${error}`));
+          log(io, chalk.red(`  - ${error}`));
         });
       }
 
       if (result.details?.breakingChanges) {
-        console.log();
-        console.log(chalk.red('破坏性变更:'));
+        log(io);
+        log(io, chalk.red('破坏性变更:'));
         (result.details.breakingChanges as any[]).forEach((change: any) => {
-          console.log(chalk.red(`  - ${change.type}: ${change.path}`));
+          log(io, chalk.red(`  - ${change.type}: ${change.path}`));
           if (change.description) {
-            console.log(chalk.gray(`    ${change.description}`));
+            log(io, chalk.gray(`    ${change.description}`));
           }
         });
       }
 
-      process.exit(1);
+      return { kind: 'fail', reason: `contract gate denied: ${result.message}` };
     }
+    return { kind: 'ok' };
   } catch (error: any) {
-    console.log();
-    console.log(chalk.red('❌ 契约门控检查出错'));
-    console.log(chalk.red(`   ${error.message}`));
-    process.exit(1);
+    log(io);
+    log(io, chalk.red('❌ 契约门控检查出错'));
+    log(io, chalk.red(`   ${error.message}`));
+    return { kind: 'fail', reason: `contract gate error: ${error.message}` };
   }
 }
 
 /**
  * 验证 OpenAPI Schema 语法
  */
-export async function validateSchema(options: ContractOptions): Promise<void> {
-  console.log(chalk.blue('📜 验证 OpenAPI Schema...\n'));
+export async function validateSchema(
+  options: ContractOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('📜 验证 OpenAPI Schema...\n'));
 
   const projectPath = options.projectPath || process.cwd();
   const contractPath = options.contractPath || 'openapi.yaml';
@@ -118,8 +126,8 @@ export async function validateSchema(options: ContractOptions): Promise<void> {
     try {
       schema = yaml.load(content);
     } catch (e: any) {
-      console.log(chalk.red(`❌ YAML 解析错误: ${e.message}`));
-      process.exit(1);
+      log(io, chalk.red(`❌ YAML 解析错误: ${e.message}`));
+      return { kind: 'fail', reason: `contract YAML parse error: ${e.message}` };
     }
 
     // 基本验证
@@ -143,26 +151,27 @@ export async function validateSchema(options: ContractOptions): Promise<void> {
     }
 
     if (errors.length > 0) {
-      console.log(chalk.red('❌ Schema 验证失败:\n'));
-      errors.forEach(err => console.log(chalk.red(`  - ${err}`)));
-      process.exit(1);
+      log(io, chalk.red('❌ Schema 验证失败:\n'));
+      errors.forEach(err => log(io, chalk.red(`  - ${err}`)));
+      return { kind: 'fail', reason: `contract schema invalid: ${errors.join('; ')}` };
     }
 
-    console.log(chalk.green('✅ Schema 验证通过'));
-    console.log();
-    console.log(chalk.gray('Schema 信息:'));
-    console.log(chalk.gray(`  版本: ${schema.openapi}`));
-    console.log(chalk.gray(`  标题: ${schema.info.title}`));
-    console.log(chalk.gray(`  API 版本: ${schema.info.version}`));
+    log(io, chalk.green('✅ Schema 验证通过'));
+    log(io);
+    log(io, chalk.gray('Schema 信息:'));
+    log(io, chalk.gray(`  版本: ${schema.openapi}`));
+    log(io, chalk.gray(`  标题: ${schema.info.title}`));
+    log(io, chalk.gray(`  API 版本: ${schema.info.version}`));
 
     if (schema.paths) {
       const endpoints = Object.keys(schema.paths).flatMap(path =>
         Object.keys(schema.paths[path]).map(method => `${method.toUpperCase()} ${path}`)
       );
-      console.log(chalk.gray(`  端点数: ${endpoints.length}`));
+      log(io, chalk.gray(`  端点数: ${endpoints.length}`));
     }
+    return { kind: 'ok' };
   } catch (error: any) {
-    console.log(chalk.red(`❌ 验证失败: ${error.message}`));
-    process.exit(1);
+    log(io, chalk.red(`❌ 验证失败: ${error.message}`));
+    return { kind: 'fail', reason: `contract schema read error: ${error.message}` };
   }
 }

package/src/cli/commands/definitions.ts

@@ -7,9 +7,10 @@
  * - 每个实现引用（CommandImplRef）标注实现文件与导出名；bin 按需
  *   per-command 懒加载（O2）：只在 action 执行时 require 对应命令模块，
  *   不再经单一 barrel 加载全部命令实现。
- * - 本模块是纯数据模块：禁止 import 任何命令实现（含运行时依赖），
- *   保证 --help/--version 懒加载不被破坏；注册表完整性断言（引用实现
- *   可解析）在 __tests__/registry.test.ts 构建/测试期校验。
+ * - 本模块是纯数据模块（候选7 后零闭包）：禁止 import 任何命令实现，
+ *   子命令别名是数据（aliases），实参编组归各命令模块的具名导出
+ *   （那才是它的 interface/测试面）；保证 --help/--version 懒加载不被破坏；
+ *   注册表完整性断言（引用实现可解析）在 __tests__/registry.test.ts 构建/测试期校验。
  */
 
 /**
@@ -35,18 +36,21 @@ export interface CommandImplRef {
 }
 
 /**
- * 子命令条目：别名 → 实现 + 实参构造
+ * 子命令条目：主名 → 实现（别名经 aliases 一名多注册，架构评审候选7）
  */
 export interface CommandSubcommand {
   /** 实现引用 */
   impl: CommandImplRef;
-  /** 实参构造：positionals = 子命令名之后的位置参数（无则 []） */
-  args?: (positionals: (string | undefined)[], options: Record<string, unknown>) => unknown[];
+  /** 别名：与主名解析到同一实现（不再整块复印 args 闭包） */
+  aliases?: string[];
+  /** true = 实现签名 (positionals, options)（需要位置参数的命令，如 knowledge search）；缺省 (options) */
+  withPositionals?: boolean;
 }
 
 /**
  * 选项条件路由（如 check --list）：选项值匹配时以路由替代默认 action；
- * 同一选项可挂多条路由（按声明顺序执行，如 passes-gate --coverage）
+ * 同一选项可挂多条路由（按序执行，如 passes-gate --coverage）。
+ * 实现一律以 (options) 调用；需编组/取值的指向命令模块内的具名包装导出。
  */
 export interface CommandOptionRoute {
   /** 触发选项键（commander options 对象键名，如 'list'） */
@@ -55,8 +59,6 @@ export interface CommandOptionRoute {
   when: unknown;
   /** 实现引用 */
   impl: CommandImplRef;
-  /** 实参构造（缺省为 [options]） */
-  args?: (positionals: (string | undefined)[], options: Record<string, unknown>) => unknown[];
 }
 
 /**
@@ -87,8 +89,6 @@ export interface CommandDefinition {
   optionRoutes?: CommandOptionRoute[];
   /** 默认 action 实参构造（缺省为 [options]） */
   mapActionArgs?: (positionals: (string | undefined)[], options: Record<string, unknown>) => unknown[];
-  /** action 完成后处理（接收返回值，如 sync-docs --check 失败 exit(1)） */
-  afterRun?: (result: unknown, options: Record<string, unknown>) => void;
 }
 
 /**
@@ -107,7 +107,7 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
     ],
     action: { module: 'check', export: 'check' },
     optionRoutes: [
-      { flag: 'list', when: true, impl: { module: 'check', export: 'listLaws' }, args: () => [] },
+      { flag: 'list', when: true, impl: { module: 'check', export: 'listLaws' } },
     ],
   },
   {
@@ -135,15 +135,7 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
     action: { module: 'passes-gate', export: 'runPassesGate' },
     optionRoutes: [
       { flag: 'coverage', when: true, impl: { module: 'passes-gate', export: 'runPassesGate' } },
-      {
-        flag: 'coverage',
-        when: true,
-        impl: { module: 'passes-gate', export: 'checkCoverage' },
-        args: (_pos, options) => [
-          options.projectPath || process.cwd(),
-          parseInt(String(options.coverageThreshold), 10),
-        ],
-      },
+      { flag: 'coverage', when: true, impl: { module: 'passes-gate', export: 'coverageCheck' } },
     ],
   },
   {
@@ -202,7 +194,7 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
     ],
     action: { module: 'spec', export: 'specValidate' },
     subcommands: {
-      list: { impl: { module: 'spec', export: 'listSpecTypes' }, args: () => [] },
+      list: { impl: { module: 'spec', export: 'listSpecTypes' } },
     },
     // 未知位置参数按文件路径落回默认 action（spec foo.yaml 合法用法）
     subcommandStrict: false,
@@ -227,12 +219,8 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--agents', description: '同步 AGENTS.md（agent 导读；PRESERVE 标记段重新生成时保留）', defaultValue: false },
       { flags: '--compact', description: '一次性迁移：将 CAPABILITIES.md 文件表格折叠为目录条目', defaultValue: false },
     ],
+    // --check 下的漂移由实现返回 fail（候选7：退出码映射只在 bin 一处），故无需 afterRun
     action: { module: 'sync-docs', export: 'syncDocs' },
-    afterRun: (ok, options) => {
-      if (!ok && options.check) {
-        process.exit(1);
-      }
-    },
   },
   {
     command: 'knowledge',
@@ -251,7 +239,7 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--title <title>', description: '知识标题（用于 upsert）' },
       { flags: '--content <content>', description: '知识内容 Markdown（用于 upsert）' },
       { flags: '--file <path>', description: '从文件读取内容（用于 upsert）' },
-      { flags: '--source <source>', description: '知识来源 (analyst/cli/design)', defaultValue: 'cli' },
+      { flags: '--source <source>', description: '知识来源 (cli/design)', defaultValue: 'cli' },
       { flags: '--fix', description: '自动修复（用于 audit）', defaultValue: false },
       { flags: '--dry-run', description: '只输出报告不修改（用于 audit）', defaultValue: false },
       { flags: '--threshold <n>', description: '短内容阈值（字符数，用于 audit）', defaultValue: '50' },
@@ -259,150 +247,24 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--json', description: 'JSON 格式输出', defaultValue: false },
     ],
     subcommands: {
-      list: {
-        impl: { module: 'knowledge', export: 'knowledgeList' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          type: options.type, maturity: options.maturity, tag: options.tag,
-        }],
-      },
-      ls: {
-        impl: { module: 'knowledge', export: 'knowledgeList' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          type: options.type, maturity: options.maturity, tag: options.tag,
-        }],
-      },
+      // 纯投影条目：commander options 与处理器参数同名，原样传入（编组归命令模块）
+      list: { impl: { module: 'knowledge', export: 'knowledgeList' }, aliases: ['ls'] },
       search: {
-        impl: { module: 'knowledge', export: 'knowledgeSearch' },
-        args: (positionals, options) => {
-          if (!positionals[0]) {
-            console.error('请提供搜索关键词');
-            process.exit(1);
-          }
-          return [positionals[0], {
-            projectPath: options.projectPath, json: options.json,
-            limit: parseInt(String(options.limit), 10),
-          }];
-        },
-      },
-      s: {
-        impl: { module: 'knowledge', export: 'knowledgeSearch' },
-        args: (positionals, options) => {
-          if (!positionals[0]) {
-            console.error('请提供搜索关键词');
-            process.exit(1);
-          }
-          return [positionals[0], {
-            projectPath: options.projectPath, json: options.json,
-            limit: parseInt(String(options.limit), 10),
-          }];
-        },
-      },
-      import: {
-        impl: { module: 'knowledge', export: 'knowledgeImport' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          sources: options.sources, reset: options.reset,
-        }],
-      },
-      i: {
-        impl: { module: 'knowledge', export: 'knowledgeImport' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          sources: options.sources, reset: options.reset,
-        }],
-      },
-      decay: {
-        impl: { module: 'knowledge', export: 'knowledgeDecay' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      d: {
-        impl: { module: 'knowledge', export: 'knowledgeDecay' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      stats: {
-        impl: { module: 'knowledge', export: 'knowledgeStats' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      st: {
-        impl: { module: 'knowledge', export: 'knowledgeStats' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      'sync-rag': {
-        impl: { module: 'knowledge', export: 'knowledgeSyncRag' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      'sync-status': {
-        impl: { module: 'knowledge', export: 'knowledgeSyncStatus' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      sync: {
-        impl: { module: 'knowledge', export: 'knowledgeSyncStatus' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      upsert: {
-        impl: { module: 'knowledge', export: 'knowledgeUpsert' },
-        args: (_pos, options) => [{
-          scope: options.scope || '',
-          title: options.title || '',
-          content: options.content || '',
-          file: options.file || '',
-          type: options.type || 'architecture',
-          source: options.source || 'cli',
-        }],
-      },
-      up: {
-        impl: { module: 'knowledge', export: 'knowledgeUpsert' },
-        args: (_pos, options) => [{
-          scope: options.scope || '',
-          title: options.title || '',
-          content: options.content || '',
-          file: options.file || '',
-          type: options.type || 'architecture',
-          source: options.source || 'cli',
-        }],
-      },
-      audit: {
-        impl: { module: 'knowledge', export: 'knowledgeAudit' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          fix: options.fix, dryRun: options.dryRun,
-          threshold: options.threshold, dir: options.dir,
-        }],
-      },
-      a: {
-        impl: { module: 'knowledge', export: 'knowledgeAudit' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          fix: options.fix, dryRun: options.dryRun,
-          threshold: options.threshold, dir: options.dir,
-        }],
-      },
-      snapshot: {
-        impl: { module: 'knowledge', export: 'knowledgeSnapshot' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
-      migrate: {
-        impl: { module: 'knowledge', export: 'knowledgeMigrate' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
-      index: {
-        impl: { module: 'knowledge', export: 'knowledgeIndex' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
-      idx: {
-        impl: { module: 'knowledge', export: 'knowledgeIndex' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
-      health: {
-        impl: { module: 'knowledge', export: 'knowledgeHealth' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
-      h: {
-        impl: { module: 'knowledge', export: 'knowledgeHealth' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
+        impl: { module: 'knowledge', export: 'knowledgeSearchCommand' },
+        aliases: ['s'],
+        withPositionals: true,
+      },
+      import: { impl: { module: 'knowledge', export: 'knowledgeImport' }, aliases: ['i'] },
+      decay: { impl: { module: 'knowledge', export: 'knowledgeDecay' }, aliases: ['d'] },
+      stats: { impl: { module: 'knowledge', export: 'knowledgeStats' }, aliases: ['st'] },
+      'sync-rag': { impl: { module: 'knowledge', export: 'knowledgeSyncRag' } },
+      'sync-status': { impl: { module: 'knowledge', export: 'knowledgeSyncStatus' }, aliases: ['sync'] },
+      upsert: { impl: { module: 'knowledge', export: 'knowledgeUpsert' }, aliases: ['up'] },
+      audit: { impl: { module: 'knowledge', export: 'knowledgeAudit' }, aliases: ['a'] },
+      snapshot: { impl: { module: 'knowledge', export: 'knowledgeSnapshot' } },
+      migrate: { impl: { module: 'knowledge', export: 'knowledgeMigrate' } },
+      index: { impl: { module: 'knowledge', export: 'knowledgeIndex' }, aliases: ['idx'] },
+      health: { impl: { module: 'knowledge', export: 'knowledgeHealth' }, aliases: ['h'] },
     },
   },
   {
@@ -415,14 +277,7 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--json', description: 'JSON 输出' },
     ],
     subcommands: {
-      index: {
-        impl: { module: 'sdd', export: 'sddIndex' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
-      idx: {
-        impl: { module: 'sdd', export: 'sddIndex' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json, dir: options.dir }],
-      },
+      index: { impl: { module: 'sdd', export: 'sddIndex' }, aliases: ['idx'] },
     },
   },
   {
@@ -437,34 +292,9 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--json', description: 'JSON 格式输出', defaultValue: false },
     ],
     subcommands: {
-      list: {
-        impl: { module: 'failure', export: 'failureList' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          limit: parseInt(String(options.limit), 10),
-          type: options.type, level: options.level,
-        }],
-      },
-      ls: {
-        impl: { module: 'failure', export: 'failureList' },
-        args: (_pos, options) => [{
-          projectPath: options.projectPath, json: options.json,
-          limit: parseInt(String(options.limit), 10),
-          type: options.type, level: options.level,
-        }],
-      },
-      stats: {
-        impl: { module: 'failure', export: 'failureStats' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      st: {
-        impl: { module: 'failure', export: 'failureStats' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
-      clear: {
-        impl: { module: 'failure', export: 'failureClear' },
-        args: (_pos, options) => [{ projectPath: options.projectPath, json: options.json }],
-      },
+      list: { impl: { module: 'failure', export: 'failureList' }, aliases: ['ls'] },
+      stats: { impl: { module: 'failure', export: 'failureStats' }, aliases: ['st'] },
+      clear: { impl: { module: 'failure', export: 'failureClear' } },
     },
   },
   {
@@ -562,22 +392,6 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       },
     ],
   },
-  {
-    command: 'doc-freshness-check',
-    argument: '<docPath>',
-    description: '检查文档声明的新鲜度：提取可验证声明，与代码对照',
-    options: [
-      { flags: '--changed-files <list>', description: '变更文件列表（逗号分隔）' },
-      { flags: '--format <format>', description: '输出格式 (table/json)', defaultValue: 'table' },
-      { flags: '-p, --project-path <path>', description: '项目路径' },
-    ],
-    action: { module: 'doc-freshness-check', export: 'docFreshnessCheck' },
-    mapActionArgs: (positionals, options) => [positionals[0], {
-      changedFiles: options.changedFiles,
-      format: options.format,
-      projectPath: options.projectPath,
-    }],
-  },
   {
     command: 'spec-baseline-check',
     argument: '<specPath>',

package/src/cli/commands/failure.ts

@@ -7,6 +7,8 @@
 import chalk from 'chalk';
 import * as path from 'path';
 import { FailureRecorder } from '../../failure/recorder';
+import { DEFAULT_FAILURE_LOG_FILE } from '../../types/failure';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface FailureOptions {
   /** 项目路径 */
@@ -21,7 +23,7 @@ export interface FailureOptions {
 function getRecorder(projectPath?: string): FailureRecorder {
   const base = projectPath || process.cwd();
   return new FailureRecorder({
-    logFile: path.join(base, '.harness', 'failures', 'failures.log'),
+    logFile: path.join(base, DEFAULT_FAILURE_LOG_FILE),
   });
 }
 
@@ -29,8 +31,9 @@ function getRecorder(projectPath?: string): FailureRecorder {
  * 失败记录列表
  */
 export async function failureList(
-  options: FailureOptions & { limit?: number; type?: string; level?: string },
-): Promise<void> {
+  options: FailureOptions & { limit?: number | string; type?: string; level?: string },
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
   const recorder = getRecorder(options.projectPath);
 
   let records = await recorder.getHistory();
@@ -41,77 +44,82 @@ export async function failureList(
   if (options.level) {
     records = records.filter(r => r.level === options.level);
   }
-  if (options.limit && options.limit > 0) {
-    records = records.slice(-options.limit);
+  // CLI 直传时 limit 为 commander 字符串值；程序内调用传 number（候选7：编组在命令函数）
+  const limit = typeof options.limit === 'string' ? parseInt(options.limit, 10) : options.limit;
+  if (limit && limit > 0) {
+    records = records.slice(-limit);
   }
 
   if (options.json) {
-    console.log(JSON.stringify({ total: records.length, records }, null, 2));
-    return;
+    log(io, JSON.stringify({ total: records.length, records }, null, 2));
+    return { kind: 'ok' };
   }
 
   if (records.length === 0) {
-    console.log(chalk.yellow('没有失败记录'));
-    return;
+    log(io, chalk.yellow('没有失败记录'));
+    return { kind: 'ok' };
   }
 
-  console.log(chalk.red(`📋 失败记录 (${records.length} 条)\n`));
+  log(io, chalk.red(`📋 失败记录 (${records.length} 条)\n`));
   for (const record of records) {
     const levelColor = record.level === 'L4' ? chalk.red
       : record.level === 'L3' ? chalk.yellow
       : record.level === 'L2' ? chalk.cyan
       : chalk.gray;
     const time = new Date(record.timestamp).toLocaleString();
-    console.log(`  ${levelColor(`[${record.level}]`)} ${chalk.bold(record.type)} ${chalk.gray(time)}`);
-    console.log(`    ${record.message}`);
+    log(io, `  ${levelColor(`[${record.level}]`)} ${chalk.bold(record.type)} ${chalk.gray(time)}`);
+    log(io, `    ${record.message}`);
   }
+  return { kind: 'ok' };
 }
 
 /**
  * 失败记录统计
  */
-export async function failureStats(options: FailureOptions): Promise<void> {
+export async function failureStats(options: FailureOptions, io: CommandIO = processIO): Promise<CommandResult> {
   const recorder = getRecorder(options.projectPath);
   const stats = await recorder.getStats();
 
   if (options.json) {
-    console.log(JSON.stringify(stats, null, 2));
-    return;
+    log(io, JSON.stringify(stats, null, 2));
+    return { kind: 'ok' };
   }
 
   if (stats.total === 0) {
-    console.log(chalk.green('✅ 没有失败记录'));
-    return;
+    log(io, chalk.green('✅ 没有失败记录'));
+    return { kind: 'ok' };
   }
 
-  console.log(chalk.red(`📊 失败统计\n`));
-  console.log(chalk.bold(`  总计: ${stats.total} 条\n`));
+  log(io, chalk.red(`📊 失败统计\n`));
+  log(io, chalk.bold(`  总计: ${stats.total} 条\n`));
 
-  console.log(chalk.bold('  按类型:'));
+  log(io, chalk.bold('  按类型:'));
   for (const [type, count] of Object.entries(stats.byType)) {
-    console.log(`    ${type}: ${count}`);
+    log(io, `    ${type}: ${count}`);
   }
 
-  console.log(chalk.bold('\n  按等级:'));
+  log(io, chalk.bold('\n  按等级:'));
   for (const [level, count] of Object.entries(stats.byLevel)) {
     const color = level === 'L4' ? chalk.red : level === 'L3' ? chalk.yellow : chalk.gray;
-    console.log(`    ${color(level)}: ${count}`);
+    log(io, `    ${color(level)}: ${count}`);
   }
+  return { kind: 'ok' };
 }
 
 /**
  * 清空失败记录
  */
-export async function failureClear(options: FailureOptions): Promise<void> {
+export async function failureClear(options: FailureOptions, io: CommandIO = processIO): Promise<CommandResult> {
   const recorder = getRecorder(options.projectPath);
   const stats = await recorder.getStats();
 
   await recorder.clear();
 
   if (options.json) {
-    console.log(JSON.stringify({ cleared: stats.total }));
-    return;
+    log(io, JSON.stringify({ cleared: stats.total }));
+    return { kind: 'ok' };
   }
 
-  console.log(chalk.green(`✅ 已清空 ${stats.total} 条失败记录`));
+  log(io, chalk.green(`✅ 已清空 ${stats.total} 条失败记录`));
+  return { kind: 'ok' };
 }