cognitive-modules-cli 2.2.14 → 2.2.16

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this package are documented in this file.
 
+## 2.2.16 - 2026-03-09
+
+- Fix: preserve module-local `$defs` / `definitions` when loading `schema.json`, so runtime validation can resolve internal references inside `data`, `meta`, and `error` sub-schemas.
+- Hardening: restore the official `pr-risk-gate` smoke path; schema validation now succeeds for contracts that include local schema references such as `extensions`.
+
+## 2.2.15 - 2026-03-09
+
+- Runtime: add schema-guided output canonicalization so enum labels and unordered arrays can be normalized before validation/repair.
+- Benchmarks: tighten gate/extraction contracts around canonical labels and publish `Benchmark Evidence` showing Gemini + MiniMax contract stability.
+- Use case: add the official `pr-risk-gate` module plus a copy-paste GitHub Actions template for blocking risky PRs in CI.
+
 ## 2.2.14 - 2026-03-08
 
 - Release: add docs build to `release:check`, so docs regressions fail before npm publish.

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/cognitive-modules-cli.svg)](https://www.npmjs.com/package/cognitive-modules-cli)
 
-Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 `npx cogn@2.2.14 ...`，避免 PATH/命令冲突。
+Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 `npx cogn@2.2.16 ...`，避免 PATH/命令冲突。
 
 > 这是 [cognitive-modules](../../README.md) monorepo 的一部分。
 
@@ -10,11 +10,11 @@ Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入
 
 ```bash
 # 零安装（推荐）
-npx cogn@2.2.14 --help
+npx cogn@2.2.16 --help
 
 # 全局安装（可选）
-npm install -g cogn@2.2.14
-# 或：npm install -g cognitive-modules-cli@2.2.14
+npm install -g cogn@2.2.16
+# 或：npm install -g cognitive-modules-cli@2.2.16
 ```
 
 ## 快速开始
@@ -24,16 +24,16 @@ npm install -g cogn@2.2.14
 export OPENAI_API_KEY=sk-xxx
 
 # 查看 providers 能力矩阵（结构化输出/流式）
-npx cogn@2.2.14 providers --pretty
+npx cogn@2.2.16 providers --pretty
 
 # 运行模块
-npx cogn@2.2.14 run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
+npx cogn@2.2.16 run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
 
 # 列出模块
-npx cogn@2.2.14 list
+npx cogn@2.2.16 list
 
 # 管道模式
-echo "review this code" | npx cogn@2.2.14 pipe --module code-reviewer
+echo "review this code" | npx cogn@2.2.16 pipe --module code-reviewer
 ```
 
 ## 支持的 Provider
@@ -59,21 +59,21 @@ echo "review this code" | npx cogn@2.2.14 pipe --module code-reviewer
 查看全部 provider（含实验/社区）：
 
 ```bash
-npx cogn@2.2.14 providers --pretty --all
+npx cogn@2.2.16 providers --pretty --all
 ```
 
 ## 命令
 
 ```bash
 # Core（单文件极简路径）
-npx cogn@2.2.14 core new                       # 生成 demo.md
-npx cogn@2.2.14 core run demo.md --args "..."  # 运行单文件模块
-npx cogn@2.2.14 core promote demo.md           # 升级为 v2 模块目录
+npx cogn@2.2.16 core new                       # 生成 demo.md
+npx cogn@2.2.16 core run demo.md --args "..."  # 运行单文件模块
+npx cogn@2.2.16 core promote demo.md           # 升级为 v2 模块目录
 
 # 渐进复杂度（Profiles）
-npx cogn@2.2.14 run code-reviewer --args "..." --profile core       # 极简：跳过校验
-npx cogn@2.2.14 run code-reviewer --args "..." --profile standard   # 推荐：日常默认
-npx cogn@2.2.14 run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
+npx cogn@2.2.16 run code-reviewer --args "..." --profile core       # 极简：跳过校验
+npx cogn@2.2.16 run code-reviewer --args "..." --profile standard   # 推荐：日常默认
+npx cogn@2.2.16 run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
 # 兼容别名（不推荐写进新文档）：
 # - default -> standard
 # - strict  -> standard（deprecated preset）
@@ -83,41 +83,41 @@ npx cogn@2.2.14 run code-reviewer --args "..." --profile certified  # 最严格
 # - --audit（写入 ~/.cognitive/audit/）
 
 # 模块操作
-npx cogn@2.2.14 list                      # 列出模块
-npx cogn@2.2.14 run <module> --args "..." # 运行模块
-npx cogn@2.2.14 add <url> -m <module>     # 从 GitHub 添加模块
-npx cogn@2.2.14 update <module>           # 更新模块
-npx cogn@2.2.14 remove <module>           # 删除模块
-npx cogn@2.2.14 versions <url>            # 查看可用版本
-npx cogn@2.2.14 init <name>               # 创建新模块
-npx cogn@2.2.14 pipe --module <name>      # 管道模式
+npx cogn@2.2.16 list                      # 列出模块
+npx cogn@2.2.16 run <module> --args "..." # 运行模块
+npx cogn@2.2.16 add <url> -m <module>     # 从 GitHub 添加模块
+npx cogn@2.2.16 update <module>           # 更新模块
+npx cogn@2.2.16 remove <module>           # 删除模块
+npx cogn@2.2.16 versions <url>            # 查看可用版本
+npx cogn@2.2.16 init <name>               # 创建新模块
+npx cogn@2.2.16 pipe --module <name>      # 管道模式
 
 # 组合执行
-npx cogn@2.2.14 compose <module> --args "..."
-npx cogn@2.2.14 compose-info <module>
+npx cogn@2.2.16 compose <module> --args "..."
+npx cogn@2.2.16 compose-info <module>
 
 # 校验与迁移
-npx cogn@2.2.14 validate <module> --v22
-npx cogn@2.2.14 validate --all
-npx cogn@2.2.14 migrate <module> --dry-run
-npx cogn@2.2.14 migrate --all --no-backup
+npx cogn@2.2.16 validate <module> --v22
+npx cogn@2.2.16 validate --all
+npx cogn@2.2.16 migrate <module> --dry-run
+npx cogn@2.2.16 migrate --all --no-backup
 
 # 服务器
-npx cogn@2.2.14 serve --port 8000         # 启动 HTTP API 服务
-npx cogn@2.2.14 mcp                       # 启动 MCP 服务（Claude Code / Cursor）
+npx cogn@2.2.16 serve --port 8000         # 启动 HTTP API 服务
+npx cogn@2.2.16 mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 
 # 环境检查
-npx cogn@2.2.14 doctor
+npx cogn@2.2.16 doctor
 
 # Registry（索引与分发）
 # 默认 registry index（latest）：
 #   https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
 # 可通过环境变量或全局参数覆盖：
-COGNITIVE_REGISTRY_URL=... npx cogn@2.2.14 search
-COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx cogn@2.2.14 search
-npx cogn@2.2.14 search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
-npx cogn@2.2.14 registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
-npx cogn@2.2.14 registry verify --remote --concurrency 2
+COGNITIVE_REGISTRY_URL=... npx cogn@2.2.16 search
+COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx cogn@2.2.16 search
+npx cogn@2.2.16 search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
+npx cogn@2.2.16 registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+npx cogn@2.2.16 registry verify --remote --concurrency 2
 ```
 
 ## 开发
@@ -140,6 +140,27 @@ npm run dev -- run code-reviewer --args "..."
 npm run release:check
 ```
 
+## Cognitive 对照基准
+
+如果你要验证“使用 Cognitive”和“直接 prompt/skill 风格 JSON 提示”之间的差异，可以运行内置对照基准：
+
+```bash
+# 先确保 dist 已构建
+npm run build
+
+# 只看计划，不实际调用模型
+npm run bench:cognitive-vs-raw -- --provider gemini --plan
+
+# 实际运行（示例）
+npm run bench:cognitive-vs-raw -- --provider gemini --model gemini-3-pro-preview --runs 3
+```
+
+相关文件：
+
+- `benchmarks/cognitive-vs-raw/README.md`
+- `benchmarks/cognitive-vs-raw/suite.example.json`
+- `benchmarks/cognitive-vs-raw/report-template.md`
+
 ## License
 
 MIT

package/dist/modules/loader.js

@@ -47,6 +47,23 @@ function detectV2Version(manifest) {
     }
     return 'v2.0';
 }
+function withLocalSchemaDefinitions(subSchema, rootSchema) {
+    if (!subSchema || typeof subSchema !== 'object')
+        return subSchema;
+    const defs = rootSchema.$defs;
+    const definitions = rootSchema.definitions;
+    if (defs === undefined && definitions === undefined) {
+        return subSchema;
+    }
+    const normalized = { ...subSchema };
+    if (normalized.$defs === undefined && defs !== undefined) {
+        normalized.$defs = defs;
+    }
+    if (normalized.definitions === undefined && definitions !== undefined) {
+        normalized.definitions = definitions;
+    }
+    return normalized;
+}
 /**
  * Load v2 format module (module.yaml + prompt.md)
  */
@@ -77,12 +94,12 @@ async function loadModuleV2(modulePath) {
     try {
         const schemaContent = await fs.readFile(schemaFile, 'utf-8');
         const schema = JSON.parse(schemaContent);
-        inputSchema = schema.input;
+        inputSchema = withLocalSchemaDefinitions(schema.input, schema);
         // Support both "data" (v2.2) and "output" (v2.1) aliases
-        dataSchema = schema.data || schema.output;
+        dataSchema = withLocalSchemaDefinitions((schema.data || schema.output), schema);
         outputSchema = dataSchema; // Backward compat
-        metaSchema = schema.meta;
-        errorSchema = schema.error;
+        metaSchema = withLocalSchemaDefinitions(schema.meta, schema);
+        errorSchema = withLocalSchemaDefinitions(schema.error, schema);
     }
     catch {
         // Schema file is optional but recommended

package/dist/modules/runner.js

@@ -21,6 +21,74 @@ function safeSnippet(s, max = 500) {
         return raw;
     return raw.slice(0, max) + `…(+${raw.length - max} chars)`;
 }
+function stableCanonicalKey(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableCanonicalKey(item)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableCanonicalKey(obj[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function normalizeStringValue(value, hint) {
+    let normalized = value.trim().replace(/\s+/g, ' ');
+    switch (hint) {
+        case 'lowercase':
+            normalized = normalized.toLowerCase();
+            break;
+        case 'lower_snake_case':
+            normalized = normalized
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, '_')
+                .replace(/^_+|_+$/g, '');
+            break;
+        default:
+            break;
+    }
+    return normalized;
+}
+function canonicalizeDataBySchema(value, schema) {
+    if (!schema || typeof schema !== 'object' || schema === null) {
+        return typeof value === 'string' ? normalizeStringValue(value) : value;
+    }
+    const schemaObj = schema;
+    const type = schemaObj.type;
+    if (typeof value === 'string') {
+        const hint = typeof schemaObj['x-cognitive-string-normalize'] === 'string'
+            ? String(schemaObj['x-cognitive-string-normalize'])
+            : undefined;
+        const normalized = normalizeStringValue(value, hint);
+        if (Array.isArray(schemaObj.enum)) {
+            const enumMatch = schemaObj.enum.find((candidate) => {
+                if (typeof candidate !== 'string')
+                    return false;
+                return normalizeStringValue(candidate, hint).toLowerCase() === normalized.toLowerCase();
+            });
+            return enumMatch ?? normalized;
+        }
+        return normalized;
+    }
+    if (Array.isArray(value)) {
+        const itemSchema = schemaObj.items;
+        const normalizedItems = value.map((item) => canonicalizeDataBySchema(item, itemSchema));
+        if (schemaObj['x-cognitive-unordered'] === true) {
+            normalizedItems.sort((a, b) => stableCanonicalKey(a).localeCompare(stableCanonicalKey(b)));
+        }
+        return normalizedItems;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value) && type === 'object') {
+        const properties = (schemaObj.properties && typeof schemaObj.properties === 'object')
+            ? schemaObj.properties
+            : {};
+        const normalized = {};
+        for (const [key, child] of Object.entries(value)) {
+            normalized[key] = canonicalizeDataBySchema(child, properties[key]);
+        }
+        return normalized;
+    }
+    return value;
+}
 function parseJsonWithCandidates(raw) {
     const candidates = extractJsonCandidates(raw);
     const attempts = [];
@@ -936,6 +1004,12 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
     if (meta.explain.length > maxExplainLength) {
         meta.explain = meta.explain.slice(0, maxExplainLength - 3) + '...';
     }
+    // data.rationale is commonly required by module contracts and is safely
+    // synthesizable from meta.explain when the model omitted the longer field.
+    if (typeof data.rationale !== 'string' || data.rationale.trim().length === 0) {
+        data.rationale = meta.explain;
+        repaired.data = data;
+    }
     // Build proper v2.2 response with version
     const builtMeta = {
         confidence: meta.confidence,
@@ -947,8 +1021,9 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
         version: ENVELOPE_VERSION,
         meta: builtMeta,
         // E4000 is an internal/runtime error fallback (should rarely happen after repair).
-        error: repaired.error ?? { code: 'E4000', message: 'Unknown error' },
-        partial_data: repaired.partial_data
+        error: repaired.error ??
+            { code: 'E4000', message: typeof meta.explain === 'string' && meta.explain.trim() ? meta.explain : 'Unknown error' },
+        partial_data: repaired.partial_data ?? repaired.data
     } : {
         ok: true,
         version: ENVELOPE_VERSION,
@@ -990,10 +1065,38 @@ function repairErrorEnvelope(data, maxExplainLength = 280) {
             explain: meta.explain,
         },
         // E4000 is an internal/runtime error fallback (should rarely happen after repair).
-        error: repaired.error ?? { code: 'E4000', message: 'Unknown error' },
-        partial_data: repaired.partial_data,
+        error: repaired.error ??
+            { code: 'E4000', message: typeof meta.explain === 'string' && meta.explain.trim() ? meta.explain : 'Unknown error' },
+        partial_data: repaired.partial_data ?? repaired.data,
     };
 }
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeEnvelopeLikeObject(parsed) {
+    if (!isPlainRecord(parsed) || !isPlainRecord(parsed.meta) || typeof parsed.ok !== 'boolean') {
+        return parsed;
+    }
+    const normalized = deepClone(parsed);
+    const reserved = new Set(['ok', 'version', 'meta', 'data', 'error', 'partial_data']);
+    const payloadEntries = Object.entries(normalized).filter(([key]) => !reserved.has(key));
+    if (normalized.ok === true) {
+        if (!isPlainRecord(normalized.data) && payloadEntries.length > 0) {
+            normalized.data = Object.fromEntries(payloadEntries);
+            for (const [key] of payloadEntries)
+                delete normalized[key];
+        }
+        return normalized;
+    }
+    const hasError = isPlainRecord(normalized.error) && typeof normalized.error.code === 'string';
+    if (!hasError && payloadEntries.length > 0) {
+        normalized.data = Object.fromEntries(payloadEntries);
+        for (const [key] of payloadEntries)
+            delete normalized[key];
+        normalized.ok = true;
+    }
+    return normalized;
+}
 /**
  * Wrap v2.1 response to v2.2 format
  */
@@ -1671,14 +1774,15 @@ export async function runModule(module, provider, options = {}) {
         }
         // Convert to v2.2 envelope
         let response;
-        if (isV22Envelope(parsed)) {
-            response = parsed;
+        const normalizedParsed = normalizeEnvelopeLikeObject(parsed);
+        if (isV22Envelope(normalizedParsed)) {
+            response = normalizedParsed;
         }
-        else if (isEnvelopeResponse(parsed)) {
-            response = wrapV21ToV22(parsed, riskRule);
+        else if (isEnvelopeResponse(normalizedParsed)) {
+            response = wrapV21ToV22(normalizedParsed, riskRule);
         }
         else {
-            response = convertLegacyToEnvelope(parsed);
+            response = convertLegacyToEnvelope(normalizedParsed);
         }
         // Add version and meta fields
         response.version = ENVELOPE_VERSION;
@@ -1727,6 +1831,9 @@ export async function runModule(module, provider, options = {}) {
             // Get data schema (support both "data" and "output" aliases)
             const dataSchema = module.dataSchema || module.outputSchema;
             const metaSchema = module.metaSchema;
+            if (dataSchema) {
+                response.data = canonicalizeDataBySchema(response.data ?? {}, dataSchema);
+            }
             const dataToValidate = response.data ?? {};
             if (dataSchema && Object.keys(dataSchema).length > 0) {
                 let dataErrors = validateData(dataToValidate, dataSchema, 'Data');
@@ -1735,7 +1842,8 @@ export async function runModule(module, provider, options = {}) {
                     response = repairEnvelope(response, riskRule);
                     response.version = ENVELOPE_VERSION;
                     // Re-validate after repair
-                    const repairedData = response.data ?? {};
+                    const repairedData = canonicalizeDataBySchema(response.data ?? {}, dataSchema);
+                    response.data = repairedData;
                     dataErrors = validateData(repairedData, dataSchema, 'Data');
                 }
                 if (dataErrors.length > 0) {
@@ -2115,14 +2223,15 @@ export async function* runModuleStream(module, provider, options = {}) {
         }
         // Convert to v2.2 envelope
         let response;
-        if (isV22Envelope(parsed)) {
-            response = parsed;
+        const normalizedParsed = normalizeEnvelopeLikeObject(parsed);
+        if (isV22Envelope(normalizedParsed)) {
+            response = normalizedParsed;
         }
-        else if (isEnvelopeResponse(parsed)) {
-            response = wrapV21ToV22(parsed, riskRule);
+        else if (isEnvelopeResponse(normalizedParsed)) {
+            response = wrapV21ToV22(normalizedParsed, riskRule);
         }
         else {
-            response = convertLegacyToEnvelope(parsed);
+            response = convertLegacyToEnvelope(normalizedParsed);
         }
         // Add version and meta
         response.version = ENVELOPE_VERSION;
@@ -2172,12 +2281,15 @@ export async function* runModuleStream(module, provider, options = {}) {
             const metaSchema = module.metaSchema;
             if (dataSchema && Object.keys(dataSchema).length > 0) {
                 let dataToValidate = response.data ?? {};
+                dataToValidate = canonicalizeDataBySchema(dataToValidate, dataSchema);
+                response.data = dataToValidate;
                 let dataErrors = validateData(dataToValidate, dataSchema, 'Data');
                 if (dataErrors.length > 0 && enableRepair) {
                     response = repairEnvelope(response, riskRule);
                     response.version = ENVELOPE_VERSION;
                     // Re-validate after repair
-                    const repairedData = response.data ?? {};
+                    const repairedData = canonicalizeDataBySchema(response.data ?? {}, dataSchema);
+                    response.data = repairedData;
                     dataToValidate = repairedData;
                     dataErrors = validateData(repairedData, dataSchema, 'Data');
                 }

package/dist/providers/minimax.js

@@ -2,15 +2,17 @@
  * MiniMax Provider - MiniMax API
  */
 import { BaseProvider } from './base.js';
+const DEFAULT_MINIMAX_BASE_URL = 'https://api.minimax.io/v1';
 export class MiniMaxProvider extends BaseProvider {
     name = 'minimax';
     apiKey;
     model;
-    baseUrl = 'https://api.minimax.chat/v1';
+    baseUrl;
     constructor(apiKey, model = 'MiniMax-M2.1') {
         super();
         this.apiKey = apiKey || process.env.MINIMAX_API_KEY || '';
         this.model = model;
+        this.baseUrl = (process.env.MINIMAX_BASE_URL || DEFAULT_MINIMAX_BASE_URL).replace(/\/+$/, '');
     }
     isConfigured() {
         return !!this.apiKey;

package/dist/types.js

@@ -7,7 +7,17 @@
 // =============================================================================
 /** Check if response is v2.2 format */
 export function isV22Envelope(response) {
-    return 'meta' in response;
+    if (typeof response !== 'object' || response === null)
+        return false;
+    const envelope = response;
+    if (typeof envelope.ok !== 'boolean')
+        return false;
+    if (typeof envelope.meta !== 'object' || envelope.meta === null || Array.isArray(envelope.meta))
+        return false;
+    if (envelope.ok === true) {
+        return 'data' in envelope;
+    }
+    return typeof envelope.error === 'object' && envelope.error !== null && !Array.isArray(envelope.error);
 }
 /** Check if response is successful */
 export function isEnvelopeSuccess(response) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "2.2.14",
+  "version": "2.2.16",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "bench:cognitive-vs-raw": "node benchmarks/cognitive-vs-raw/run.mjs",
     "pack:check": "npm pack --dry-run --json --cache ../../.npm-cache",
     "release:check": "node ../../scripts/release/check-docs-build.js && npm run build && npm test && npm run pack:check",
     "prepublishOnly": "npm run release:check"