cognitive-modules-cli 1.0.1 → 1.2.0

package/README.md

@@ -1,162 +1,86 @@
-# Cognitive Runtime
+# Cognitive Modules CLI (Node.js)
 
-**Structured AI Task Execution**
+[![npm version](https://badge.fury.io/js/cognitive-modules-cli.svg)](https://www.npmjs.com/package/cognitive-modules-cli)
 
-Cognitive Runtime is the next-generation execution engine for Cognitive Modules. It provides a clean, provider-agnostic runtime that treats LLMs as interchangeable backends.
+Node.js/TypeScript 版本的 Cognitive Modules CLI。
 
-## Philosophy
+> 这是 [cognitive-modules](../../README.md) monorepo 的一部分。
 
-Following the **Cognitive Runtime + Provider** architecture:
-
-```
-┌─────────────────────────────────────┐
-│         Cognitive Runtime           │
-│  ┌────────────────────────────────┐ │
-│  │     Module System              │ │
-│  │  (load, parse, validate)       │ │
-│  └────────────────────────────────┘ │
-│  ┌────────────────────────────────┐ │
-│  │     Execution Engine           │ │
-│  │  (prompt, schema, contract)    │ │
-│  └────────────────────────────────┘ │
-│  ┌────────────────────────────────┐ │
-│  │     Provider Abstraction       │ │
-│  │  (gemini, openai, anthropic,   │ │
-│  │   deepseek, minimax, qwen...)  │ │
-│  └────────────────────────────────┘ │
-└─────────────────────────────────────┘
-```
-
-## Installation
+## 安装
 
 ```bash
-npm install -g cognitive-runtime
-```
+# 全局安装（推荐）
+npm install -g cogn
 
-Or run directly:
-
-```bash
-npx cognitive-runtime --help
+# 或使用 npx 零安装
+npx cogn --help
 ```
 
-## Usage
-
-### Run a Module
+## 快速开始
 
 ```bash
-cog run code-reviewer --args "def foo(): pass"
-```
+# 配置 LLM
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-xxx
 
-### List Modules
+# 运行模块
+cog run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')"
 
-```bash
+# 列出模块
 cog list
-```
 
-### Pipe Mode (stdin/stdout)
-
-```bash
+# 管道模式
 echo "review this code" | cog pipe --module code-reviewer
 ```
 
-### Check Configuration
+## 与 Python 版的区别
 
-```bash
-cog doctor
-```
+| 功能 | Python (`cogn`) | Node.js (`cog`) |
+|------|----------------|-----------------|
+| 包名 | `cognitive-modules` | `cognitive-modules-cli` |
+| 安装 | `pip install` | `npm install -g` |
+| 子代理 | ✅ `@call:module` | ❌ 暂不支持 |
+| MCP Server | ✅ | ❌ 暂不支持 |
+| HTTP Server | ✅ | ❌ 暂不支持 |
 
-## Module Formats
+两个版本共享相同的模块格式和 v2.2 规范。
 
-### v2 (Recommended)
+## 支持的 Provider
 
-```
-my-module/
-├── module.yaml      # Machine-readable manifest
-├── prompt.md        # Human-readable prompt
-├── schema.json      # IO contract
-└── tests/
-    ├── case1.input.json
-    └── case1.expected.json
-```
+| Provider | 环境变量 | 别名 |
+|----------|----------|------|
+| OpenAI | `OPENAI_API_KEY` | - |
+| Anthropic | `ANTHROPIC_API_KEY` | - |
+| Gemini | `GEMINI_API_KEY` | - |
+| DeepSeek | `DEEPSEEK_API_KEY` | - |
+| MiniMax | `MINIMAX_API_KEY` | - |
+| Moonshot | `MOONSHOT_API_KEY` | `kimi` |
+| Qwen | `DASHSCOPE_API_KEY` | `tongyi` |
+| Ollama | `OLLAMA_HOST` | `local` |
 
-**module.yaml**:
-```yaml
-name: my-module
-version: 2.0.0
-responsibility: What this module does
-constraints:
-  no_network: true
-  no_side_effects: true
-output:
-  mode: json_strict
-  require_confidence: true
-  require_rationale: true
-  require_behavior_equivalence: true
-tools:
-  allowed: []
-```
-
-### v1 (Legacy, still supported)
-
-```
-my-module/
-├── MODULE.md        # Frontmatter + prompt combined
-└── schema.json
-```
-
-## Providers
-
-| Provider   | Environment Variable   | Default Model        |
-|------------|------------------------|----------------------|
-| Gemini     | `GEMINI_API_KEY`       | `gemini-3-flash`     |
-| OpenAI     | `OPENAI_API_KEY`       | `gpt-5.2`            |
-| Anthropic  | `ANTHROPIC_API_KEY`    | `claude-sonnet-4.5`  |
-| DeepSeek   | `DEEPSEEK_API_KEY`     | `deepseek-v3.2`      |
-| MiniMax    | `MINIMAX_API_KEY`      | `MiniMax-M2.1`       |
-| Moonshot   | `MOONSHOT_API_KEY`     | `kimi-k2.5`          |
-| Qwen       | `DASHSCOPE_API_KEY`    | `qwen3-max`          |
-| Ollama     | `OLLAMA_HOST`          | `llama4` (local)     |
-
-### Provider Aliases
+## 命令
 
-- `kimi` → Moonshot
-- `tongyi` / `dashscope` → Qwen
-- `local` → Ollama
-
-## Module Search Paths
-
-Modules are searched in order:
-
-1. `./cognitive/modules/` (project-local)
-2. `./.cognitive/modules/` (project-local, hidden)
-3. `~/.cognitive/modules/` (user-global)
-
-## Programmatic API
-
-```typescript
-import { getProvider, findModule, runModule } from 'cognitive-runtime';
-
-const provider = getProvider('gemini');
-const module = await findModule('code-reviewer', ['./cognitive/modules']);
-
-if (module) {
-  const result = await runModule(module, provider, {
-    args: 'def foo(): pass',
-  });
-  console.log(result.output);
-}
+```bash
+cog list                    # 列出模块
+cog run <module> --args "..." # 运行模块
+cog add <url> -m <module>   # 从 GitHub 添加模块
+cog update <module>         # 更新模块
+cog remove <module>         # 删除模块
+cog versions <url>          # 查看可用版本
+cog init <name>             # 创建新模块
+cog pipe --module <name>    # 管道模式
 ```
 
-## Development
+## 开发
 
 ```bash
-# Install dependencies
+# 安装依赖
 npm install
 
-# Build
+# 构建
 npm run build
 
-# Run in development
+# 开发模式运行
 npm run dev -- run code-reviewer --args "..."
 ```
 

package/dist/modules/loader.js

@@ -19,6 +19,18 @@ async function detectFormat(modulePath) {
         return 'v1';
     }
 }
+/**
+ * Detect v2.x sub-version from manifest
+ */
+function detectV2Version(manifest) {
+    if (manifest.tier || manifest.overflow || manifest.enums) {
+        return 'v2.2';
+    }
+    if (manifest.policies || manifest.failure) {
+        return 'v2.1';
+    }
+    return 'v2.0';
+}
 /**
  * Load v2 format module (module.yaml + prompt.md)
  */
@@ -29,6 +41,8 @@ async function loadModuleV2(modulePath) {
     // Read module.yaml
     const manifestContent = await fs.readFile(manifestFile, 'utf-8');
     const manifest = yaml.load(manifestContent);
+    // Detect v2.x version
+    const formatVersion = detectV2Version(manifest);
     // Read prompt.md
     let prompt = '';
     try {
@@ -40,17 +54,61 @@ async function loadModuleV2(modulePath) {
     // Read schema.json
     let inputSchema;
     let outputSchema;
+    let dataSchema;
+    let metaSchema;
     let errorSchema;
     try {
         const schemaContent = await fs.readFile(schemaFile, 'utf-8');
         const schema = JSON.parse(schemaContent);
         inputSchema = schema.input;
-        outputSchema = schema.output;
+        // Support both "data" (v2.2) and "output" (v2.1) aliases
+        dataSchema = schema.data || schema.output;
+        outputSchema = dataSchema; // Backward compat
+        metaSchema = schema.meta;
         errorSchema = schema.error;
     }
     catch {
         // Schema file is optional but recommended
     }
+    // Extract v2.2 fields
+    const tier = manifest.tier;
+    const schemaStrictness = manifest.schema_strictness || 'medium';
+    // Determine default max_items based on strictness (SPEC-v2.2)
+    const strictnessMaxItems = {
+        high: 0,
+        medium: 5,
+        low: 20
+    };
+    const defaultMaxItems = strictnessMaxItems[schemaStrictness] ?? 5;
+    const defaultEnabled = schemaStrictness !== 'high';
+    // Parse overflow config with strictness-based defaults
+    const overflowRaw = manifest.overflow || {};
+    const overflow = {
+        enabled: overflowRaw.enabled ?? defaultEnabled,
+        recoverable: overflowRaw.recoverable ?? true,
+        max_items: overflowRaw.max_items ?? defaultMaxItems,
+        require_suggested_mapping: overflowRaw.require_suggested_mapping ?? true
+    };
+    // Parse enums config
+    const enumsRaw = manifest.enums || {};
+    const enums = {
+        strategy: enumsRaw.strategy ??
+            (tier === 'exec' ? 'strict' : 'extensible'),
+        unknown_tag: enumsRaw.unknown_tag ?? 'custom'
+    };
+    // Parse compat config
+    const compatRaw = manifest.compat || {};
+    const compat = {
+        accepts_v21_payload: compatRaw.accepts_v21_payload ?? true,
+        runtime_auto_wrap: compatRaw.runtime_auto_wrap ?? true,
+        schema_output_alias: compatRaw.schema_output_alias ?? 'data'
+    };
+    // Parse meta config (including risk_rule)
+    const metaRaw = manifest.meta || {};
+    const metaConfig = {
+        required: metaRaw.required,
+        risk_rule: metaRaw.risk_rule,
+    };
     return {
         name: manifest.name || path.basename(modulePath),
         version: manifest.version || '1.0.0',
@@ -62,13 +120,26 @@ async function loadModuleV2(modulePath) {
         output: manifest.output,
         failure: manifest.failure,
         runtimeRequirements: manifest.runtime_requirements,
+        // v2.2 fields
+        tier,
+        schemaStrictness,
+        overflow,
+        enums,
+        compat,
+        metaConfig,
+        // Context and prompt
         context: manifest.context,
         prompt,
+        // Schemas
         inputSchema,
         outputSchema,
+        dataSchema,
+        metaSchema,
         errorSchema,
+        // Metadata
         location: modulePath,
         format: 'v2',
+        formatVersion,
     };
 }
 /**

package/dist/modules/runner.d.ts

@@ -1,6 +1,6 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.1: Envelope format support, clean input mapping
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
 import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
 export interface RunOptions {
@@ -8,5 +8,7 @@ export interface RunOptions {
     args?: string;
     verbose?: boolean;
     useEnvelope?: boolean;
+    useV22?: boolean;
+    enableRepair?: boolean;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -1,11 +1,116 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.1: Envelope format support, clean input mapping
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
+import { aggregateRisk, isV22Envelope } from '../types.js';
+// =============================================================================
+// Repair Pass (v2.2)
+// =============================================================================
+/**
+ * Attempt to repair envelope format issues without changing semantics.
+ *
+ * Repairs (lossless only):
+ * - Missing meta fields (fill with conservative defaults)
+ * - Truncate explain if too long
+ * - Trim whitespace from string fields
+ *
+ * Does NOT repair:
+ * - Invalid enum values (treated as validation failure)
+ */
+function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLength = 280) {
+    const repaired = { ...response };
+    // Ensure meta exists
+    if (!repaired.meta || typeof repaired.meta !== 'object') {
+        repaired.meta = {};
+    }
+    const meta = repaired.meta;
+    const data = (repaired.data ?? {});
+    // Repair confidence
+    if (typeof meta.confidence !== 'number') {
+        meta.confidence = data.confidence ?? 0.5;
+    }
+    meta.confidence = Math.max(0, Math.min(1, meta.confidence));
+    // Repair risk using configurable aggregation rule
+    if (!meta.risk) {
+        meta.risk = aggregateRisk(data, riskRule);
+    }
+    // Trim whitespace only (lossless), do NOT invent new values
+    if (typeof meta.risk === 'string') {
+        meta.risk = meta.risk.trim().toLowerCase();
+    }
+    // Repair explain
+    if (typeof meta.explain !== 'string') {
+        const rationale = data.rationale;
+        meta.explain = rationale ? String(rationale).slice(0, maxExplainLength) : 'No explanation provided';
+    }
+    // Trim whitespace (lossless)
+    const explainStr = meta.explain;
+    meta.explain = explainStr.trim();
+    if (meta.explain.length > maxExplainLength) {
+        meta.explain = meta.explain.slice(0, maxExplainLength - 3) + '...';
+    }
+    // Build proper v2.2 response
+    const builtMeta = {
+        confidence: meta.confidence,
+        risk: meta.risk,
+        explain: meta.explain
+    };
+    const result = repaired.ok === false ? {
+        ok: false,
+        meta: builtMeta,
+        error: repaired.error ?? { code: 'UNKNOWN', message: 'Unknown error' },
+        partial_data: repaired.partial_data
+    } : {
+        ok: true,
+        meta: builtMeta,
+        data: repaired.data
+    };
+    return result;
+}
+/**
+ * Wrap v2.1 response to v2.2 format
+ */
+function wrapV21ToV22(response, riskRule = 'max_changes_risk') {
+    if (isV22Envelope(response)) {
+        return response;
+    }
+    if (response.ok) {
+        const data = (response.data ?? {});
+        const confidence = data.confidence ?? 0.5;
+        const rationale = data.rationale ?? '';
+        return {
+            ok: true,
+            meta: {
+                confidence,
+                risk: aggregateRisk(data, riskRule),
+                explain: rationale.slice(0, 280) || 'No explanation provided'
+            },
+            data: data
+        };
+    }
+    else {
+        const errorMsg = response.error?.message ?? 'Unknown error';
+        return {
+            ok: false,
+            meta: {
+                confidence: 0,
+                risk: 'high',
+                explain: errorMsg.slice(0, 280)
+            },
+            error: response.error ?? { code: 'UNKNOWN', message: errorMsg },
+            partial_data: response.partial_data
+        };
+    }
+}
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false, useEnvelope } = options;
+    const { args, input, verbose = false, useEnvelope, useV22, enableRepair = true } = options;
     // Determine if we should use envelope format
     const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
+    // Determine if we should use v2.2 format
+    const isV22Module = module.tier !== undefined || module.formatVersion === 'v2.2';
+    const shouldUseV22 = useV22 ?? (isV22Module || module.compat?.runtime_auto_wrap === true);
+    // Get risk_rule from module config
+    const riskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
     // Build clean input data (v2 style: no $ARGUMENTS pollution)
     const inputData = input || {};
     // Map legacy --args to clean input
@@ -61,11 +166,21 @@ export async function runModule(module, provider, options = {}) {
     }
     // Add envelope format instructions
     if (shouldUseEnvelope) {
-        systemParts.push('', 'RESPONSE FORMAT (Envelope):');
-        systemParts.push('- Wrap your response in the envelope format');
-        systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
-        systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
-        systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        if (shouldUseV22) {
+            systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
+            systemParts.push('- Wrap your response in the v2.2 envelope format with separate meta and data');
+            systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
+            systemParts.push('- Error: { "ok": false, "meta": { "confidence": 0.0, "risk": "high", "explain": "error summary" }, "error": { "code": "ERROR_CODE", "message": "..." } }');
+            systemParts.push('- meta.explain must be ≤280 characters. data.rationale can be longer for detailed reasoning.');
+            systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
+        }
+        else {
+            systemParts.push('', 'RESPONSE FORMAT (Envelope):');
+            systemParts.push('- Wrap your response in the envelope format');
+            systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
+            systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
+            systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        }
         if (module.output?.require_behavior_equivalence) {
             systemParts.push('- Include "behavior_equivalence" (boolean) in data');
         }
@@ -105,10 +220,46 @@ export async function runModule(module, provider, options = {}) {
     }
     // Handle envelope format
     if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
-        return parseEnvelopeResponse(parsed, result.content);
+        let response = parseEnvelopeResponse(parsed, result.content);
+        // Upgrade to v2.2 if needed
+        if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
+            const upgraded = wrapV21ToV22(parsed, riskRule);
+            response = {
+                ok: true,
+                meta: upgraded.meta,
+                data: upgraded.data,
+                raw: result.content
+            };
+        }
+        // Apply repair pass if enabled and response needs it
+        if (enableRepair && response.ok && shouldUseV22) {
+            const repaired = repairEnvelope(response, riskRule);
+            response = {
+                ok: true,
+                meta: repaired.meta,
+                data: repaired.data,
+                raw: result.content
+            };
+        }
+        return response;
     }
     // Handle legacy format (non-envelope)
-    return parseLegacyResponse(parsed, result.content);
+    const legacyResult = parseLegacyResponse(parsed, result.content);
+    // Upgrade to v2.2 if requested
+    if (shouldUseV22 && legacyResult.ok) {
+        const data = (legacyResult.data ?? {});
+        return {
+            ok: true,
+            meta: {
+                confidence: data.confidence ?? 0.5,
+                risk: aggregateRisk(data, riskRule),
+                explain: (data.rationale ?? '').slice(0, 280) || 'No explanation provided'
+            },
+            data: legacyResult.data,
+            raw: result.content
+        };
+    }
+    return legacyResult;
 }
 /**
  * Check if response is in envelope format
@@ -120,11 +271,32 @@ function isEnvelopeResponse(obj) {
     return typeof o.ok === 'boolean';
 }
 /**
- * Parse envelope format response
+ * Parse envelope format response (supports both v2.1 and v2.2)
  */
 function parseEnvelopeResponse(response, raw) {
+    // Check if v2.2 format (has meta)
+    if (isV22Envelope(response)) {
+        if (response.ok) {
+            return {
+                ok: true,
+                meta: response.meta,
+                data: response.data,
+                raw,
+            };
+        }
+        else {
+            return {
+                ok: false,
+                meta: response.meta,
+                error: response.error,
+                partial_data: response.partial_data,
+                raw,
+            };
+        }
+    }
+    // v2.1 format
     if (response.ok) {
-        const data = response.data;
+        const data = (response.data ?? {});
         return {
             ok: true,
             data: {
@@ -169,6 +341,7 @@ function parseLegacyResponse(output, raw) {
             };
         }
     }
+    // Return as v2.1 format (data includes confidence)
     return {
         ok: true,
         data: {