Cognitive Modules CLI (Node.js)

Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 npx [email protected] ...，避免 PATH/命令冲突。

这是 cognitive-modules monorepo 的一部分。

安装

# 零安装（推荐）
npx [email protected] --help

# 全局安装（可选）
npm install -g [email protected]
# 或：npm install -g [email protected]

快速开始

# 配置 LLM
export OPENAI_API_KEY=sk-xxx

# 查看 providers 能力矩阵（结构化输出/流式）
npx [email protected] providers --pretty

# 运行模块
npx [email protected] run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty

# 列出模块
npx [email protected] list

# 管道模式
echo "review this code" | npx [email protected] pipe --module code-reviewer

支持的 Provider

对外“稳定支持面”收敛为 6 个 provider（减少认知负担与维护成本）：

| Provider（Stable） | 环境变量 | 说明 | |----------|----------|------| | OpenAI (ChatGPT) | OPENAI_API_KEY | OpenAI API | | Anthropic (Claude) | ANTHROPIC_API_KEY | Claude | | Gemini | GEMINI_API_KEY | Google Gemini | | MiniMax | MINIMAX_API_KEY | MiniMax | | DeepSeek | DEEPSEEK_API_KEY | DeepSeek API | | Qwen (DashScope) | DASHSCOPE_API_KEY / QWEN_API_KEY | 通义千问 |

实验/社区 provider 仍保留实现，但默认不在文档/能力矩阵中承诺稳定性（需要显式指定 --provider）：

| Provider（Experimental/Community） | 环境变量 | 说明 | |----------|----------|------| | Moonshot (Kimi) | MOONSHOT_API_KEY | experimental | | Ollama (local) | OLLAMA_HOST | community |

查看全部 provider（含实验/社区）：

npx [email protected] providers --pretty --all

命令

# Core（单文件极简路径）
npx [email protected] core new                       # 生成 demo.md
npx [email protected] core run demo.md --args "..."  # 运行单文件模块
npx [email protected] core promote demo.md           # 升级为 v2 模块目录

# 渐进复杂度（Profiles）
npx [email protected] run code-reviewer --args "..." --profile core       # 极简：跳过校验
npx [email protected] run code-reviewer --args "..." --profile standard   # 推荐：日常默认
npx [email protected] run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
# 兼容别名（不推荐写进新文档）：
# - default -> standard
# - strict  -> standard（deprecated preset）
# 覆盖开关：
# - --validate auto|on|off
# - --structured auto|off|prompt|native（provider 层结构化输出策略）
# - --audit（写入 ~/.cognitive/audit/）

# 模块操作
npx [email protected] list                      # 列出模块
npx [email protected] run <module> --args "..." # 运行模块
npx [email protected] add <url> -m <module>     # 从 GitHub 添加模块
npx [email protected] update <module>           # 更新模块
npx [email protected] remove <module>           # 删除模块
npx [email protected] versions <url>            # 查看可用版本
npx [email protected] init <name>               # 创建新模块
npx [email protected] pipe --module <name>      # 管道模式

# 组合执行
npx [email protected] compose <module> --args "..."
npx [email protected] compose-info <module>

# 校验与迁移
npx [email protected] validate <module> --v22
npx [email protected] validate --all
npx [email protected] migrate <module> --dry-run
npx [email protected] migrate --all --no-backup

# 服务器
npx [email protected] serve --port 8000         # 启动 HTTP API 服务
npx [email protected] mcp                       # 启动 MCP 服务（Claude Code / Cursor）

# 环境检查
npx [email protected] doctor

# Registry（索引与分发）
# 默认 registry index（latest）：
#   https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
# 可通过环境变量或全局参数覆盖：
COGNITIVE_REGISTRY_URL=... npx [email protected] search
COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx [email protected] search
npx [email protected] search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
npx [email protected] registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
npx [email protected] registry verify --remote --concurrency 2

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式运行
npm run dev -- run code-reviewer --args "..."

发布前检查

# 完整发布检查（构建 + 测试 + npm 打包清单）
npm run release:check

Cognitive 对照基准

如果你要验证“使用 Cognitive”和“直接 prompt/skill 风格 JSON 提示”之间的差异，可以运行内置对照基准：

# 先确保 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