soloforge 1.2.8 → 1.2.10

package/dist/engine/cognitive_anchor.d.ts

@@ -3,6 +3,7 @@
  * 备忘录要求: 每个锚点必须有 source_refs, confidence, last_verified_at。
  * 自动生成的锚点默认 advisory，核心锚点更新需人工确认。
  */
+/** 认知地图锚点 */
 export interface CognitiveMapAnchor {
     /** 锚点 ID */
     anchor_id: string;
@@ -30,6 +31,7 @@ export interface CognitiveMapAnchor {
     /** 是否过时 */
     stale_anchor?: boolean;
 }
+/** .map.json 文件结构 */
 export interface MapJsonFile {
     version: 1;
     anchors: CognitiveMapAnchor[];
@@ -37,20 +39,32 @@ export interface MapJsonFile {
 }
 /**
  * 写入 .map.json 文件。
+ * @param filePath - 目标文件路径
+ * @param anchors - 要写入的锚点列表
  */
 export declare function writeMapJson(filePath: string, anchors: CognitiveMapAnchor[]): void;
 /**
  * 读取 .map.json 文件。文件不存在时返回空锚点列表。
+ * @param filePath - 目标文件路径
+ * @returns 解析后的地图文件，文件不存在或解析失败时返回 null
  */
 export declare function readMapJson(filePath: string): MapJsonFile | null;
 /**
  * 检查锚点是否过时 — 与当前文件列表比对 source_refs。
  * 文件不存在的 source_ref 标记 stale_anchor。
+ * @param anchors - 要检查的锚点列表
+ * @param existingFiles - 当前存在的文件路径集合
+ * @returns 更新了 stale_anchor 标记的锚点列表
  */
 export declare function checkAnchorStaleness(anchors: CognitiveMapAnchor[], existingFiles: Set<string>): CognitiveMapAnchor[];
 /**
  * 按相关性筛选锚点 — 根据模块名或文件路径前缀匹配。
  * 不全量加载，避免污染上下文。
+ * @param anchors - 锚点列表
+ * @param query - 查询条件
+ * @param query.module - 按模块名精确匹配
+ * @param query.file_path - 按文件路径前缀匹配
+ * @returns 匹配的锚点列表
  */
 export declare function filterRelevantAnchors(anchors: CognitiveMapAnchor[], query: {
     module?: string;

package/dist/engine/cognitive_anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cognitive_anchor.d.ts","sourceRoot":"","sources":["../../src/engine/cognitive_anchor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,kBAAkB;IACjC,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa;IACb,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY;IACZ,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU;IACV,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW;IACX,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW;IACX,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,qCAAqC;IACrC,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB,GAAG,OAAO,CAAC;QACvE,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,UAAU;IACV,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,aAAa;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAalF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAOhE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GACzB,kBAAkB,EAAE,CAYtB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,kBAAkB,EAAE,CAWtB"}
+{"version":3,"file":"cognitive_anchor.d.ts","sourceRoot":"","sources":["../../src/engine/cognitive_anchor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,aAAa;AACb,MAAM,WAAW,kBAAkB;IACjC,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa;IACb,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY;IACZ,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU;IACV,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW;IACX,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW;IACX,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,qCAAqC;IACrC,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB,GAAG,OAAO,CAAC;QACvE,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,UAAU;IACV,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,aAAa;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,qBAAqB;AACrB,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAclF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GACzB,kBAAkB,EAAE,CAiBtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,kBAAkB,EAAE,CActB"}

package/dist/engine/cognitive_anchor.js

@@ -7,6 +7,8 @@ import fss from "node:fs";
 import path from "node:path";
 /**
  * 写入 .map.json 文件。
+ * @param filePath - 目标文件路径
+ * @param anchors - 要写入的锚点列表
  */
 export function writeMapJson(filePath, anchors) {
     const dir = path.dirname(filePath);
@@ -19,42 +21,62 @@ export function writeMapJson(filePath, anchors) {
     const tmpPath = `${filePath}.tmp`;
     fss.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
     fss.renameSync(tmpPath, filePath);
+    console.error(`[soloForge] 认知锚点: 写入完成，锚点数: ${anchors.length}，路径: ${filePath}`);
 }
 /**
  * 读取 .map.json 文件。文件不存在时返回空锚点列表。
+ * @param filePath - 目标文件路径
+ * @returns 解析后的地图文件，文件不存在或解析失败时返回 null
  */
 export function readMapJson(filePath) {
     if (!fss.existsSync(filePath))
         return null;
     try {
-        return JSON.parse(fss.readFileSync(filePath, "utf-8"));
+        const result = JSON.parse(fss.readFileSync(filePath, "utf-8"));
+        console.error(`[soloForge] 认知锚点: 读取完成，锚点数: ${result.anchors.length}，路径: ${filePath}`);
+        return result;
     }
     catch {
+        console.error(`[soloForge] 认知锚点: 读取失败，文件解析错误，路径: ${filePath}`);
         return null;
     }
 }
 /**
  * 检查锚点是否过时 — 与当前文件列表比对 source_refs。
  * 文件不存在的 source_ref 标记 stale_anchor。
+ * @param anchors - 要检查的锚点列表
+ * @param existingFiles - 当前存在的文件路径集合
+ * @returns 更新了 stale_anchor 标记的锚点列表
  */
 export function checkAnchorStaleness(anchors, existingFiles) {
+    let staleCount = 0;
     for (const anchor of anchors) {
         const hasMissing = anchor.source_refs.some((ref) => ref.type === "file" && !existingFiles.has(ref.ref));
         if (hasMissing) {
             anchor.stale_anchor = true;
+            staleCount++;
         }
         else {
             anchor.stale_anchor = false;
         }
     }
+    if (staleCount > 0) {
+        console.error(`[soloForge] 认知锚点: 检测到 ${staleCount} 个过时锚点（引用的源文件已不存在）`);
+    }
     return anchors;
 }
 /**
  * 按相关性筛选锚点 — 根据模块名或文件路径前缀匹配。
  * 不全量加载，避免污染上下文。
+ * @param anchors - 锚点列表
+ * @param query - 查询条件
+ * @param query.module - 按模块名精确匹配
+ * @param query.file_path - 按文件路径前缀匹配
+ * @returns 匹配的锚点列表
  */
 export function filterRelevantAnchors(anchors, query) {
-    return anchors.filter((anchor) => {
+    console.error(`[soloForge] 认知锚点: 按相关性筛选锚点 — 模块: ${query.module ?? '无'}, 文件路径: ${query.file_path ?? '无'}, 锚点总数: ${anchors.length}`);
+    const result = anchors.filter((anchor) => {
         if (query.module && anchor.module === query.module)
             return true;
         if (query.file_path) {
@@ -64,5 +86,7 @@ export function filterRelevantAnchors(anchors, query) {
         }
         return false;
     });
+    console.error(`[soloForge] 认知锚点: 筛选完成 — 匹配 ${result.length} 个锚点`);
+    return result;
 }
 //# sourceMappingURL=cognitive_anchor.js.map

package/dist/engine/cognitive_anchor.js.map

@@ -1 +1 @@
-{"version":3,"file":"cognitive_anchor.js","sourceRoot":"","sources":["../../src/engine/cognitive_anchor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,GAAG,MAAM,SAAS,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAoC7B;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,OAA6B;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAExC,MAAM,IAAI,GAAgB;QACxB,OAAO,EAAE,CAAC;QACV,OAAO;QACP,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACvC,CAAC;IAEF,MAAM,OAAO,GAAG,GAAG,QAAQ,MAAM,CAAC;IAClC,GAAG,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1D,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAgB,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA6B,EAC7B,aAA0B;IAE1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CACxC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAC5D,CAAC;QACF,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,YAAY,GAAG,KAAK,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA6B,EAC7B,KAA8C;IAE9C,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;QAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAChE,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CACxC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC,SAAU,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,SAAU,CAAC,CAAC,CAC/G,CAAC;YACF,IAAI,UAAU;gBAAE,OAAO,IAAI,CAAC;QAC9B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cognitive_anchor.js","sourceRoot":"","sources":["../../src/engine/cognitive_anchor.ts"],"names":[],"mappings":"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"}

package/dist/engine/command_execution_contract.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Command Execution Contract
+ *
+ * 将命令生成、dry-run 和真实执行分离，对命令来源、风险等级、
+ * cwd/env、确认要求、timeout、幂等性、长进程、输出证据、
+ * 脱敏和禁止模式统一建模。
+ *
+ * 核心原则:
+ * - 生成命令不等于执行命令
+ * - sf_verify 默认 plan_only
+ * - destructive/database/external_side_effect 必须人工确认
+ * - forbidden pattern 必须 hard block
+ */
+export type CommandMode = "plan_only" | "dry_run" | "execute";
+export type CommandRisk = "read_only" | "local_write" | "dependency_write" | "long_running" | "network" | "database" | "destructive" | "external_side_effect";
+export type CommandSource = "project_script" | "project_config" | "user_provided" | "soloforge_generated" | "knowledge_template" | "heuristic";
+export type CommandPurpose = "verify" | "build" | "test" | "lint" | "install" | "generate" | "migrate" | "dev_server" | "deploy" | "cleanup" | "diagnostic";
+export type Idempotency = "idempotent" | "non_idempotent" | "unknown";
+export type ConfirmationRequirement = "auto_allowed" | "workflow_allowed" | "require_human" | "hard_block";
+export interface CommandContract {
+    command_id: string;
+    command: string;
+    mode: CommandMode;
+    cwd: string;
+    shell?: string;
+    source: CommandSource;
+    purpose: CommandPurpose;
+    risk: CommandRisk;
+    idempotency: Idempotency;
+    requires_confirmation: ConfirmationRequirement;
+    timeout_ms: number;
+    allowed_env: string[];
+    expected_outputs: string[];
+    forbidden_patterns: string[];
+}
+export interface CommandExecutionEvidence {
+    command_id: string;
+    executed_at: string;
+    cwd: string;
+    exit_code: number | null;
+    timed_out: boolean;
+    duration_ms: number;
+    stdout_ref?: string;
+    stderr_ref?: string;
+    redaction_records: string[];
+    changed_files: string[];
+    summary: string;
+}
+export interface CommandGovernanceFinding {
+    severity: "hard_fail" | "advisory";
+    rule: string;
+    command_id?: string;
+    message: string;
+}
+/** 禁止执行的命令模式列表（hard block） */
+export declare const FORBIDDEN_COMMAND_PATTERNS: Array<{
+    pattern: RegExp;
+    reason: string;
+}>;
+/**
+ * 对命令进行风险分类。
+ * 基于命令内容匹配风险模式，返回最高优先级的风险等级。
+ * @param command - 命令字符串
+ * @returns 风险等级
+ */
+export declare function classifyCommandRisk(command: string): CommandRisk;
+/**
+ * 获取指定风险等级的默认确认要求。
+ * @param risk - 风险等级
+ * @returns 确认要求
+ */
+export declare function getDefaultConfirmation(risk: CommandRisk): ConfirmationRequirement;
+/**
+ * 获取指定用途的默认幂等性。
+ * @param purpose - 命令用途
+ * @returns 幂等性
+ */
+export declare function getDefaultIdempotency(purpose: CommandPurpose): Idempotency;
+/**
+ * 获取指定用途的默认超时时间（毫秒）。
+ * @param purpose - 命令用途
+ * @returns 超时时间（毫秒）
+ */
+export declare function getDefaultTimeout(purpose: CommandPurpose): number;
+/**
+ * 判断命令是否为禁止执行的命令。
+ * @param command - 命令字符串
+ * @returns 禁止结果及原因
+ */
+export declare function isForbiddenCommand(command: string): {
+    forbidden: boolean;
+    reason: string;
+};
+/**
+ * 创建命令执行契约。
+ * 自动分类风险等级、确认要求和幂等性。
+ * @param options.command - 命令字符串
+ * @param options.cwd - 工作目录
+ * @param options.source - 命令来源
+ * @param options.purpose - 命令用途
+ * @param options.mode - 执行模式（可选，默认 plan_only）
+ * @param options.shell - shell 类型（可选）
+ * @param options.timeout_ms - 超时时间（可选）
+ * @param options.allowed_env - 允许的环境变量（可选）
+ * @returns 命令执行契约
+ */
+/**
+ * 创建命令执行契约。
+ * @param options - 契约选项，包含命令、参数和工作目录
+ * @returns 命令执行契约实例
+ */
+export declare function createCommandContract(options: {
+    command: string;
+    cwd: string;
+    source: CommandSource;
+    purpose: CommandPurpose;
+    mode?: CommandMode;
+    shell?: string;
+    timeout_ms?: number;
+    allowed_env?: string[];
+}): CommandContract;
+/**
+ * 创建命令执行证据。
+ * 自动对敏感内容进行脱敏处理。
+ * @param options.command_id - 命令 ID
+ * @param options.cwd - 工作目录
+ * @param options.exit_code - 退出码
+ * @param options.timed_out - 是否超时
+ * @param options.duration_ms - 执行时长（毫秒）
+ * @param options.stdout_ref - stdout 文件引用（可选）
+ * @param options.stderr_ref - stderr 文件引用（可选）
+ * @param options.stdout_content - 实际 stdout 内容（可选）
+ * @param options.stderr_content - 实际 stderr 内容（可选）
+ * @param options.changed_files - 变更文件列表（可选）
+ * @param options.summary - 执行摘要
+ * @returns 命令执行证据
+ */
+/**
+ * 创建命令执行证据。
+ * @param options - 证据选项，包含命令 ID、退出码、输出和时间戳
+ * @returns 命令执行证据实例
+ */
+export declare function createExecutionEvidence(options: {
+    command_id: string;
+    cwd: string;
+    exit_code: number | null;
+    timed_out: boolean;
+    duration_ms: number;
+    /** 文件路径引用 — 非内容，非脱敏 */
+    stdout_ref?: string;
+    /** 文件路径引用 — 非内容，非脱敏 */
+    stderr_ref?: string;
+    /** 实际 stdout 内容 — 已对密钥/PII 脱敏 */
+    stdout_content?: string;
+    /** 实际 stderr 内容 — 已对密钥/PII 脱敏 */
+    stderr_content?: string;
+    changed_files?: string[];
+    summary: string;
+}): CommandExecutionEvidence;
+/**
+ * 判断命令是否可以执行。
+ * 检查禁止模式、执行模式、风险等级和确认要求。
+ * @param contract - 命令执行契约
+ * @returns 执行许可结果
+ */
+export declare function canExecute(contract: CommandContract): {
+    allowed: boolean;
+    reason: string;
+};
+/**
+ * 判断命令是否可以自动重试。
+ * 仅幂等命令失败后才允许自动重试。
+ * @param contract - 命令执行契约
+ * @param evidence - 命令执行证据
+ * @returns 重试许可结果
+ */
+export declare function canAutoRetry(contract: CommandContract, evidence: CommandExecutionEvidence): {
+    allowed: boolean;
+    reason: string;
+};
+/**
+ * 判断用途是否为长进程。
+ * @param purpose - 命令用途
+ * @returns 是否为长进程
+ */
+export declare function isLongRunningPurpose(purpose: CommandPurpose): boolean;
+/**
+ * 判断风险等级是否为长进程。
+ * @param risk - 风险等级
+ * @returns 是否为长进程
+ */
+export declare function isLongRunningRisk(risk: CommandRisk): boolean;
+/**
+ * 验证长进程命令的配置是否合理。
+ * @param contract - 命令执行契约
+ * @returns 验证结果和问题列表
+ */
+export declare function validateLongRunning(contract: CommandContract): {
+    valid: boolean;
+    issues: string[];
+};
+/**
+ * 判断工作目录是否在项目根目录范围内。
+ * @param cwd - 工作目录
+ * @param projectRoot - 项目根目录
+ * @returns 是否允许
+ */
+export declare function isCwdAllowed(cwd: string, projectRoot: string): boolean;
+/**
+ * 构建命令执行反馈信息。
+ * @param contract - 命令执行契约
+ * @returns 格式化的反馈文本
+ */
+export declare function buildCommandFeedback(contract: CommandContract): string;
+/**
+ * 验证命令执行合规性。
+ * 检查执行模式、风险确认、证据完整性等治理规则。
+ * @param options.contracts - 命令执行契约列表
+ * @param options.evidences - 命令执行证据列表
+ * @returns 治理发现列表
+ */
+export declare function validateCommandExecution(options: {
+    contracts: CommandContract[];
+    evidences: CommandExecutionEvidence[];
+}): CommandGovernanceFinding[];
+//# sourceMappingURL=command_execution_contract.d.ts.map

package/dist/engine/command_execution_contract.d.ts.map

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