@dommaker/harness 0.6.0 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # @dommaker/harness
 
-> 通用工程约束框架 - 铁律系统、检查点验证、测试门控
+> 通用工程约束框架 - 铁律系统、检查点验证、测试门控、拦截器
 
 ## 简介
 
@@ -10,13 +10,14 @@
 
 | 功能 | 说明 |
 |------|------|
-| **铁律系统** | 13 条内置铁律，违规则阻止操作 |
+| **铁律系统** | 16 条内置约束（4 Iron Laws + 10 Guidelines + 2 Tips） |
 | **检查点验证** | 验证工作流步骤的结果是否符合预期 |
 | **测试门控** | 禁止自评通过，必须通过真实测试 |
+| **拦截器** | 抽象拦截框架，自动执行 enforcement（v0.7+） |
 | **Session 管理** | 启动检查点 + 结束状态管理 |
 | **预设系统** | 提供 strict/standard/relaxed 三种预设 |
-| **Execution Trace** | 轻量记录约束检查，异常检测，诊断系统（v0.3+） |
-| **项目级自定义约束** | 扩展/覆盖内置约束，无需 fork（v0.4+） |
+| **Execution Trace** | 轻量记录约束检查，异常检测，诊断系统 |
+| **项目级自定义约束** | 扩展/覆盖内置约束，无需 fork |
 | **CLI 工具** | 命令行工具执行检查 |
 
 ## 安装
@@ -46,12 +47,27 @@ npx harness init --preset standard
 # 初始化项目配置
 harness init --preset standard
 
+# 输出配置代码片段（不创建文件）
+harness init --print-snippets
+
 # 检查铁律
 harness check
 
 # 列出所有铁律
 harness check --list
 
+# 查看状态（统计、异常、建议）
+harness status
+
+# 查看详细状态
+harness status --detail
+
+# 只显示异常
+harness status --anomalies
+
+# 一键执行诊断+提案流程
+harness flow
+
 # 验证检查点
 harness validate
 
@@ -61,12 +77,10 @@ harness passes-gate
 # 生成报告
 harness report
 
-# Trace 分析（Execution Traces）
-harness traces stats              # 查看 trace 文件统计
-harness traces summary            # 查看约束汇总
-harness traces anomalies          # 检测异常模式
-harness traces report             # 生成完整报告
-harness traces clean              # 清理旧 trace 文件
+# [已弃用] 请使用 harness status
+harness traces stats
+harness traces summary
+harness traces anomalies
 ```
 
 ### 3. 在 CI 中使用
@@ -83,7 +97,48 @@ jobs:
       - run: npx harness passes-gate
 ```
 
-### 4. 在代码中使用
+### 5. Spec 验证
+
+验证架构文档、模块定义、API 定义等 Spec 文件：
+
+```bash
+# 验证所有 Spec 文件
+harness spec
+
+# 验证暂存文件（pre-commit）
+harness spec --staged
+
+# 验证指定文件
+harness spec --file ARCHITECTURE.md
+
+# 使用自定义 Schema
+harness spec --schema ./my-specs/schemas
+
+# 列出支持的 Spec 类型
+harness spec list
+```
+
+**项目自定义 Schema**：
+
+项目可以定义自己的 Spec Schema，在 `src/specs/schemas/index.ts` 中导出 `validate` 函数：
+
+```typescript
+// src/specs/schemas/index.ts
+import { z } from 'zod';
+
+export const ArchitectureSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  modules: z.array(z.string()),
+});
+
+export async function validate(content: string, filePath: string) {
+  // 解析并验证内容
+  // 返回 SpecValidationResult
+}
+```
+
+### 6. 在代码中使用
 
 ```typescript
 import { 
@@ -115,23 +170,102 @@ const cleaner = new CleanStateManager();
 const cleanResult = await cleaner.onSessionEnd(workDir, sessionInfo);
 ```
 
-## 内置铁律（13 条）
-
-| ID | 规则 | 严重性 |
-|---|------|:------:|
-| `no_simplification_without_approval` | 不能擅自简化逻辑 | 🔴 error |
-| `no_fix_without_root_cause` | 修复前必须找到根因 | 🔴 error |
-| `no_completion_without_verification` | 完成必须有验证证据 | 🔴 error |
-| `no_skill_without_test` | 创建技能前必须有测试 | 🟡 warning |
-| `no_code_without_test` | 写代码前必须有测试 | 🔴 error |
-| `no_creation_without_reuse_check` | 创建前必须检查可复用 | 🟡 warning |
-| `capability_sync` | 代码变更必须更新 CAPABILITIES.md | 🟡 warning |
-| `no_any_type` | 禁止使用 any 类型 | 🟡 warning |
-| `no_bypass_checkpoint` | 禁止跳过检查点 | 🔴 error |
-| `test_coverage_required` | 测试覆盖率必须达标 | 🟡 warning |
-| `no_self_approval` | 禁止自评通过 | 🔴 error |
-| `doc_required_for_public_api` | 公共 API 必须有文档 | 🟡 warning |
-| `readme_required` | 新模块必须有 README | 🔵 info |
+### 5. 使用拦截器（v0.7+）
+
+拦截器自动执行 enforcement，无需手动调用检查 API：
+
+```typescript
+import { 
+  interceptor, 
+  registerExecutor,
+  interceptOperation,
+  claimOperation,
+  type EnforcementExecutor,
+  type ConstraintContext,
+} from '@dommaker/harness';
+
+// 1. 注册执行器（使用者实现具体逻辑）
+registerExecutor('verify-completion', {
+  description: '验证完成声明：运行测试命令',
+  supportedParams: ['command', 'timeout'],
+  async execute(context) {
+    // 使用者自定义验证逻辑
+    const result = await exec('npm test', { cwd: context.projectPath });
+    return {
+      passed: result.success,
+      evidence: result.stdout,
+    };
+  },
+});
+
+// 2. 在关键操作前拦截
+try {
+  // 拦截 task_completion_claim 操作
+  // 自动查找适用的约束并执行对应的 enforcement
+  await claimOperation('task_completion_claim', {
+    operation: 'task_completion_claim',
+    projectPath: '/path/to/project',
+    sessionId: 'session-123',
+  });
+  
+  // 拦截通过，可以宣布完成
+  await announceCompletion();
+} catch (e) {
+  // 拦截失败，铁律违规
+  console.error('必须先验证才能完成');
+}
+
+// 3. 查询拦截结果（不抛异常）
+const result = await interceptOperation('task_completion_claim', context);
+if (result.passed) {
+  console.log('✅ 通过拦截');
+} else {
+  console.log('❌ 约束违规:', result.violations);
+}
+```
+
+**拦截器 vs 手动检查**：
+
+| 方式 | 特点 |
+|------|------|
+| 手动检查 | `checkConstraints()` 需要手动调用 API |
+| 拦截器 | 自动执行 enforcement，抽象框架，使用者实现逻辑 |
+
+**内置 enforcement IDs**：
+
+| enforcement | 说明 |
+|-------------|------|
+| verify-completion | 验证完成声明：运行测试 |
+| verify-e2e | 验证端到端测试 |
+| debug-systematic | 系统性调试检查 |
+| reuse-first | 复用优先检查 |
+| update-capabilities | CAPABILITIES.md 同步检查 |
+| tdd-cycle | TDD 循环检查 |
+| passes-gate | 测试门控 |
+| checkpoint-required | 检查点必须通过 |
+| check-coverage | 覆盖率检查 |
+| require-discussion | 设计决策讨论检查 |
+
+## 内置约束（16 条）
+
+| ID | 规则 | 层级 | 严重性 |
+|---|------|------|:------:|
+| `no_bypass_checkpoint` | 禁止跳过检查点 | iron_law | 🔴 error |
+| `no_self_approval` | 禁止自评通过 | iron_law | 🔴 error |
+| `no_completion_without_verification` | 完成必须有验证证据 | iron_law | 🔴 error |
+| `no_test_simplification` | 禁止擅自简化测试 | iron_law | 🔴 error |
+| `no_fix_without_root_cause` | 修复前必须找到根因 | guideline | 🔴 error |
+| `no_code_without_test` | 写代码前必须有测试 | guideline | 🔴 error |
+| `no_any_type` | 禁止使用 any 类型 | guideline | 🟡 warning |
+| `simplest_solution_first` | 优先选择最简方案 | guideline | 🟡 warning |
+| `no_creation_without_reuse_check` | 创建前必须检查可复用 | guideline | 🟡 warning |
+| `capability_sync` | 代码变更必须更新 CAPABILITIES.md | guideline | 🟡 warning |
+| `no_simplification_without_approval` | 不能擅自简化逻辑 | guideline | 🟡 warning |
+| `no_skill_without_test` | 创建技能前必须有测试 | guideline | 🟡 warning |
+| `test_coverage_required` | 测试覆盖率必须达标 | guideline | 🟡 warning |
+| `design_decision_requires_discussion` | 设计决策必须先讨论 | guideline | 🟡 warning |
+| `readme_required` | 新模块必须有 README | tip | 🔵 info |
+| `doc_required_for_public_api` | 公共 API 必须有文档 | tip | 🔵 info |
 
 ## 预设系统
 
@@ -141,6 +275,56 @@ const cleanResult = await cleaner.onSessionEnd(workDir, sessionInfo);
 | `standard` | 标准模式，推荐使用 |
 | `relaxed` | 宽松模式，警告不阻止 |
 
+## 自定义约束（v0.4+）
+
+### 扩展例外（v0.6+）
+
+使用 `extend_exceptions` 追加例外，保留内置例外：
+
+```yaml
+# .harness/custom-constraints.yml
+custom_constraints:
+  no_fix_without_root_cause:
+    extend_exceptions:
+      - my_special_case_1
+      - my_special_case_2
+```
+
+结果：内置例外 + 新增例外
+
+### 完全覆盖
+
+使用 `exceptions` 完全覆盖内置例外：
+
+```yaml
+# .harness/custom-constraints.yml
+custom_constraints:
+  no_fix_without_root_cause:
+    level: guideline
+    rule: Do not fix without root cause
+    message: 禁止没有根因分析就修复
+    trigger: bug_fix
+    exceptions:
+      - my_only_exception
+```
+
+结果：只使用自定义例外
+
+### 混合模式
+
+同时使用 `exceptions` 和 `extend_exceptions`：
+
+```yaml
+custom_constraints:
+  no_fix_without_root_cause:
+    exceptions:
+      - my_new_exception
+    extend_exceptions:
+      - another_exception
+```
+
+结果：内置例外 + my_new_exception + another_exception
+
 ## 项目模板
 
 提供多种项目模板：

package/bin/harness.js

@@ -18,7 +18,9 @@ const {
   diagnoseCommand,
   proposeCommand,
   status,
-  flow
+  flow,
+  specValidate,
+  listSpecTypes
 } = require('../dist/cli/commands/index');
 
 const program = new Command();
@@ -26,7 +28,7 @@ const program = new Command();
 program
   .name('harness')
   .description('通用工程约束框架 - 铁律系统、检查点验证、测试门控、执行追踪')
-  .version('0.3.0');
+  .version('0.7.0');
 
 // ========================================
 // harness check
@@ -114,16 +116,21 @@ program
   });
 
 // ========================================
-// harness traces
+// harness traces [DEPRECATED]
 // ========================================
 program
   .command('traces [subcommand]')
-  .description('Execution Trace 分析')
+  .description('[已弃用] 请使用 harness status')
   .option('--hours <n>', '分析最近 N 小时', '1')
   .option('--constraint <id>', '过滤约束 ID')
   .option('--format <format>', '输出格式 (json/text)', 'text')
   .option('--max-age-days <n>', '清理超过 N 天的文件', '30')
   .action(async (subcommand, options, command) => {
+    console.log('⚠️  harness traces 已弃用，请使用 harness status');
+    console.log('   harness status          # 查看统计');
+    console.log('   harness status --detail # 查看详情');
+    console.log('   harness status --anomalies # 查看异常');
+    console.log();
     const sub = subcommand || 'stats';
     await tracesCommand(sub, {
       hours: parseInt(options.hours, 10),
@@ -134,17 +141,20 @@ program
   });
 
 // ========================================
-// harness diagnose
+// harness diagnose [DEPRECATED]
 // ========================================
 program
   .command('diagnose [subcommand]')
-  .description('约束诊断')
+  .description('[已弃用] 请使用 harness flow')
   .option('--hours <n>', '分析最近 N 小时', '24')
   .option('--constraint <id>', '过滤约束 ID')
   .option('--anomaly <id>', '特定异常 ID')
   .option('--format <format>', '输出格式 (json/text)', 'text')
   .option('--save', '保存诊断结果', false)
   .action(async (subcommand, options, command) => {
+    console.log('⚠️  harness diagnose 已弃用，请使用 harness flow');
+    console.log('   harness flow  # 一键执行诊断 + 提案流程');
+    console.log();
     const sub = subcommand || 'list';
     await diagnoseCommand(sub, {
       hours: parseInt(options.hours, 10),
@@ -156,11 +166,11 @@ program
   });
 
 // ========================================
-// harness propose
+// harness propose [DEPRECATED]
 // ========================================
 program
   .command('propose [subcommand]')
-  .description('约束提案')
+  .description('[已弃用] 请使用 harness flow')
   .option('--diagnosis <id>', '诊断 ID')
   .option('--status <status>', '过滤状态')
   .option('--format <format>', '输出格式 (json/text)', 'text')
@@ -169,6 +179,9 @@ program
   .option('--reject', '拒绝提案', false)
   .option('--comment <text>', '审核意见')
   .action(async (subcommand, options, command) => {
+    console.log('⚠️  harness propose 已弃用，请使用 harness flow');
+    console.log('   harness flow  # 一键执行诊断 + 提案流程');
+    console.log();
     const sub = subcommand || 'list';
     await proposeCommand(sub, {
       diagnosisId: options.diagnosis,
@@ -219,5 +232,31 @@ program
     });
   });
 
+// ========================================
+// harness spec
+// ========================================
+program
+  .command('spec [subcommand]')
+  .description('Spec 验证命令')
+  .option('-s, --schema <path>', 'Schema 路径（项目定义）')
+  .option('--staged', '只验证暂存文件', false)
+  .option('-f, --file <path>', '验证指定文件')
+  .option('-p, --project-path <path>', '项目路径')
+  .option('-v, --verbose', '详细输出', false)
+  .action(async (subcommand, options, command) => {
+    if (subcommand === 'list') {
+      listSpecTypes();
+    } else {
+      // 默认执行 validate
+      await specValidate({
+        schema: options.schema,
+        staged: options.staged,
+        file: options.file || (subcommand && !subcommand.startsWith('-') ? subcommand : undefined),
+        projectPath: options.projectPath,
+        verbose: options.verbose,
+      });
+    }
+  });
+
 // 解析命令行参数
 program.parse();

package/dist/cli/commands/index.d.ts

@@ -11,4 +11,5 @@ export { diagnoseCommand } from './diagnose';
 export { proposeCommand } from './propose';
 export { status, type StatusOptions } from './status';
 export { flow, type FlowOptions } from './flow';
+export { specValidate, listSpecTypes, type SpecValidateOptions } from './spec';
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/cli/commands/index.js

@@ -3,7 +3,7 @@
  * CLI 命令导出
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.flow = exports.status = exports.proposeCommand = exports.diagnoseCommand = exports.tracesCommand = exports.report = exports.init = exports.checkCoverage = exports.runPassesGate = exports.createExampleCheckpoint = exports.validate = exports.listLaws = exports.check = void 0;
+exports.listSpecTypes = exports.specValidate = exports.flow = exports.status = exports.proposeCommand = exports.diagnoseCommand = exports.tracesCommand = exports.report = exports.init = exports.checkCoverage = exports.runPassesGate = exports.createExampleCheckpoint = exports.validate = exports.listLaws = exports.check = void 0;
 var check_1 = require("./check");
 Object.defineProperty(exports, "check", { enumerable: true, get: function () { return check_1.check; } });
 Object.defineProperty(exports, "listLaws", { enumerable: true, get: function () { return check_1.listLaws; } });
@@ -27,4 +27,7 @@ var status_1 = require("./status");
 Object.defineProperty(exports, "status", { enumerable: true, get: function () { return status_1.status; } });
 var flow_1 = require("./flow");
 Object.defineProperty(exports, "flow", { enumerable: true, get: function () { return flow_1.flow; } });
+var spec_1 = require("./spec");
+Object.defineProperty(exports, "specValidate", { enumerable: true, get: function () { return spec_1.specValidate; } });
+Object.defineProperty(exports, "listSpecTypes", { enumerable: true, get: function () { return spec_1.listSpecTypes; } });
 //# sourceMappingURL=index.js.map

package/dist/cli/commands/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iCAA6D;AAApD,8FAAA,KAAK,OAAA;AAAE,iGAAA,QAAQ,OAAA;AACxB,uCAAqF;AAA5E,oGAAA,QAAQ,OAAA;AAAE,mHAAA,uBAAuB,OAAA;AAC1C,6CAAqF;AAA5E,4GAAA,aAAa,OAAA;AAAE,4GAAA,aAAa,OAAA;AACrC,+BAAgD;AAAvC,4FAAA,IAAI,OAAA;AACb,mCAAsD;AAA7C,gGAAA,MAAM,OAAA;AACf,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AACtB,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AACxB,qCAA2C;AAAlC,yGAAA,cAAc,OAAA;AACvB,mCAAsD;AAA7C,gGAAA,MAAM,OAAA;AACf,+BAAgD;AAAvC,4FAAA,IAAI,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iCAA6D;AAApD,8FAAA,KAAK,OAAA;AAAE,iGAAA,QAAQ,OAAA;AACxB,uCAAqF;AAA5E,oGAAA,QAAQ,OAAA;AAAE,mHAAA,uBAAuB,OAAA;AAC1C,6CAAqF;AAA5E,4GAAA,aAAa,OAAA;AAAE,4GAAA,aAAa,OAAA;AACrC,+BAAgD;AAAvC,4FAAA,IAAI,OAAA;AACb,mCAAsD;AAA7C,gGAAA,MAAM,OAAA;AACf,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AACtB,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AACxB,qCAA2C;AAAlC,yGAAA,cAAc,OAAA;AACvB,mCAAsD;AAA7C,gGAAA,MAAM,OAAA;AACf,+BAAgD;AAAvC,4FAAA,IAAI,OAAA;AACb,+BAA+E;AAAtE,oGAAA,YAAY,OAAA;AAAE,qGAAA,aAAa,OAAA"}

package/dist/cli/commands/spec.d.ts

@@ -0,0 +1,31 @@
+/**
+ * harness spec validate 命令
+ *
+ * 验证 Spec 文件格式
+ *
+ * 设计原则：
+ * - 框架不包含具体 Schema 定义
+ * - 项目需要定义自己的 Spec Schema
+ * - 支持动态加载项目的 Schema
+ */
+export interface SpecValidateOptions {
+    /** Schema 路径（项目定义） */
+    schema?: string;
+    /** 只验证暂存文件 */
+    staged?: boolean;
+    /** 验证指定文件 */
+    file?: string;
+    /** 项目路径 */
+    projectPath?: string;
+    /** 详细输出 */
+    verbose?: boolean;
+}
+/**
+ * 执行 Spec 验证
+ */
+export declare function specValidate(options: SpecValidateOptions): Promise<void>;
+/**
+ * 列出支持的 Spec 类型
+ */
+export declare function listSpecTypes(): void;
+//# sourceMappingURL=spec.d.ts.map

package/dist/cli/commands/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC9E;AA2ED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CASpC"}

package/dist/cli/commands/spec.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * harness spec validate 命令
+ *
+ * 验证 Spec 文件格式
+ *
+ * 设计原则：
+ * - 框架不包含具体 Schema 定义
+ * - 项目需要定义自己的 Spec Schema
+ * - 支持动态加载项目的 Schema
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specValidate = specValidate;
+exports.listSpecTypes = listSpecTypes;
+const chalk_1 = __importDefault(require("chalk"));
+const path = __importStar(require("path"));
+const validator_1 = require("../../core/spec/validator");
+/**
+ * 执行 Spec 验证
+ */
+async function specValidate(options) {
+    console.log(chalk_1.default.blue('📋 验证 Spec 文件...'));
+    const projectPath = options.projectPath || process.cwd();
+    const validator = validator_1.SpecValidator.getInstance();
+    // 设置 Schema 路径
+    if (options.schema) {
+        const absoluteSchemaPath = path.resolve(projectPath, options.schema);
+        validator.setConfig({ schemaPath: absoluteSchemaPath });
+        console.log(chalk_1.default.gray(`Schema 路径: ${absoluteSchemaPath}`));
+    }
+    let result;
+    // 单文件验证
+    if (options.file) {
+        const absoluteFilePath = path.resolve(projectPath, options.file);
+        console.log(chalk_1.default.gray(`验证文件: ${absoluteFilePath}`));
+        result = await validator.validateFile(absoluteFilePath);
+        printSingleResult(result, options.verbose);
+        return;
+    }
+    // 批量验证
+    console.log(chalk_1.default.gray(`项目路径: ${projectPath}`));
+    console.log(chalk_1.default.gray(`仅暂存: ${options.staged ? '是' : '否'}`));
+    console.log();
+    result = await (0, validator_1.validateAllSpecs)(projectPath, options.staged);
+    // 打印结果
+    printBatchResult(result, options.verbose);
+    // 根据失败级别决定退出码
+    if (!options.staged && result.failed > 0) {
+        process.exitCode = 1;
+    }
+}
+/**
+ * 打印单个文件验证结果
+ */
+function printSingleResult(result, verbose) {
+    if (result.valid) {
+        console.log(chalk_1.default.green(`✅ ${result.file} 验证通过`));
+    }
+    else {
+        console.log(chalk_1.default.red(`❌ ${result.file} 验证失败`));
+    }
+    if (result.errors.length > 0) {
+        console.log();
+        console.log(chalk_1.default.red('错误:'));
+        for (const error of result.errors) {
+            console.log(chalk_1.default.red(`  - ${error.path ? error.path + ': ' : ''}${error.message}`));
+        }
+    }
+    if (result.warnings.length > 0) {
+        console.log();
+        console.log(chalk_1.default.yellow('警告:'));
+        for (const warning of result.warnings) {
+            console.log(chalk_1.default.yellow(`  - ${warning.path ? warning.path + ': ' : ''}${warning.message}`));
+        }
+    }
+    if (verbose && result.metrics) {
+        console.log();
+        console.log(chalk_1.default.gray('指标:'));
+        for (const [key, value] of Object.entries(result.metrics)) {
+            console.log(chalk_1.default.gray(`  - ${key}: ${value}`));
+        }
+    }
+}
+/**
+ * 打印批量验证结果
+ */
+function printBatchResult(result, verbose) {
+    // 汇总
+    console.log(chalk_1.default.bold('验证结果:'));
+    console.log(chalk_1.default.gray(`  总文件数: ${result.total}`));
+    console.log(chalk_1.default.green(`  通过: ${result.passed}`));
+    console.log(chalk_1.default.red(`  失败: ${result.failed}`));
+    console.log(chalk_1.default.yellow(`  警告: ${result.warnings}`));
+    console.log();
+    // 详细结果
+    if (verbose || result.failed > 0) {
+        for (const r of result.results) {
+            if (!r.valid || verbose) {
+                printSingleResult(r, verbose);
+                console.log();
+            }
+        }
+    }
+    // 成功提示
+    if (result.failed === 0 && result.total > 0) {
+        console.log(chalk_1.default.green('✅ 所有 Spec 文件验证通过'));
+    }
+    else if (result.total === 0) {
+        console.log(chalk_1.default.gray('没有找到 Spec 文件，跳过验证'));
+        console.log();
+        console.log(chalk_1.default.gray('提示: Spec 文件包括:'));
+        console.log(chalk_1.default.gray('  - ARCHITECTURE.md'));
+        console.log(chalk_1.default.gray('  - specs/ 目录下的 .yml/.yaml 文件'));
+        console.log();
+        console.log(chalk_1.default.gray('要定义自己的 Schema，请在项目中创建:'));
+        console.log(chalk_1.default.gray('  src/specs/schemas/index.ts'));
+        console.log(chalk_1.default.gray('  导出 validate 函数'));
+    }
+}
+/**
+ * 列出支持的 Spec 类型
+ */
+function listSpecTypes() {
+    console.log(chalk_1.default.blue('📋 支持的 Spec 类型:'));
+    console.log();
+    console.log('  architecture  - ARCHITECTURE.md 架构文档');
+    console.log('  module        - 模块定义（specs/modules/*.yml）');
+    console.log('  api           - API 定义（specs/apis/*.yml）');
+    console.log('  custom        - 自定义 Spec');
+    console.log();
+    console.log(chalk_1.default.gray('提示: 项目可以定义自己的 Schema 进行验证'));
+}
+//# sourceMappingURL=spec.js.map

package/dist/cli/commands/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../../src/cli/commands/spec.ts"],"names":[],"mappings":"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"}