cognitive-modules 0.1.0__tar.gz

cognitive_modules-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leizii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cognitive_modules-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: cognitive-modules
+Version: 0.1.0
+Summary: Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration
+Author: leizii
+License: MIT
+Project-URL: Homepage, https://github.com/leizii/cognitive-modules
+Project-URL: Documentation, https://github.com/leizii/cognitive-modules#readme
+Project-URL: Repository, https://github.com/leizii/cognitive-modules
+Project-URL: Issues, https://github.com/leizii/cognitive-modules/issues
+Keywords: llm,cognitive,modules,ai,cli,schema,validation,prompt,agent,subagent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.17.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+Provides-Extra: ollama
+Requires-Dist: requests>=2.28.0; extra == "ollama"
+Provides-Extra: minimax
+Requires-Dist: openai>=1.0.0; extra == "minimax"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.18.0; extra == "all"
+Requires-Dist: requests>=2.28.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# Cognitive Modules
+
+> 可验证的结构化 AI 任务规范
+
+Cognitive Modules 是一种 AI 任务定义规范，专为需要**强约束、可验证、可审计**的生成任务设计。
+
+## 与 Skills 的区别
+
+| | Skills | Cognitive Modules |
+|---|--------|------------------|
+| 定位 | 轻量指令扩展 | 可验证的结构化任务 |
+| 输入校验 | 无 | JSON Schema |
+| 输出校验 | 无 | JSON Schema |
+| 置信度 | 无 | 必须 0-1 |
+| 推理过程 | 无 | 必须 rationale |
+| 适用场景 | 快捷命令 | 规范生成、设计文档 |
+
+## 快速开始
+
+```bash
+# 克隆
+git clone https://github.com/leizii/cognitive-modules.git
+cd cognitive-modules
+
+# 安装依赖
+pip install typer rich jsonschema pyyaml
+
+# 运行
+./cog --help
+```
+
+## CLI 命令
+
+```bash
+# 模块管理
+cog list                    # 列出已安装模块
+cog info <module>           # 查看模块详情
+cog validate <module>       # 验证模块结构
+
+# 创建模块
+cog init <name> -d "描述"    # 从模板创建新模块
+
+# 运行模块
+cog run <module> input.json -o output.json --pretty
+
+# 直接传参数（无需 JSON 文件）
+cog run <module> --args "你的需求描述" -o output.json
+
+# 启用子代理模式（支持 @call 调用其他模块）
+cog run <module> --args "需求" --subagent
+
+# 安装/卸载
+cog install <source>        # 从 git/本地/注册表安装
+cog uninstall <module>      # 卸载模块
+
+# 注册表
+cog registry                # 查看公共模块
+cog search <query>          # 搜索模块
+
+# 环境检查
+cog doctor                  # 检查 LLM 配置
+```
+
+## 安装来源
+
+```bash
+# 从本地安装
+cog install ./path/to/module
+
+# 从 GitHub 安装
+cog install github:leizii/cognitive-modules/cognitive/modules/ui-spec-generator
+
+# 从注册表安装
+cog install registry:ui-spec-generator
+```
+
+## 模块格式
+
+### 新格式（推荐，2 文件）
+
+```
+my-module/
+├── MODULE.md       # 元数据 + 指令
+├── schema.json     # 输入输出 Schema
+└── examples/       # 可选
+    ├── input.json
+    └── output.json
+```
+
+### 旧格式（兼容，6 文件）
+
+```
+my-module/
+├── module.md
+├── input.schema.json
+├── output.schema.json
+├── constraints.yaml
+├── prompt.txt
+└── examples/
+```
+
+## MODULE.md 格式
+
+```yaml
+---
+name: my-module
+version: 1.0.0
+responsibility: 一句话描述
+
+excludes:
+  - 不做的事情
+
+constraints:
+  no_network: true
+  no_inventing_data: true
+  require_confidence: true
+  require_rationale: true
+---
+
+# 指令内容
+
+（这里写 prompt）
+```
+
+## 在 Codex / Cursor 中使用
+
+### 方式 1：直接对话（零配置）
+
+```
+读取 ~/.cognitive/modules/ui-spec-generator/MODULE.md，
+为电商首页生成 UI 规范，保存到 ui-spec.json
+```
+
+### 方式 2：AGENTS.md（项目约定）
+
+在项目根目录创建 `AGENTS.md`：
+
+```markdown
+## UI 规范生成
+
+当需要生成 UI 规范时：
+1. 读取 `~/.cognitive/modules/ui-spec-generator/MODULE.md`
+2. 按 schema.json 格式输出
+3. 保存到 ui-spec.json
+```
+
+### 方式 3：包装成 Skill
+
+```yaml
+# ~/.claude/skills/ui-spec/SKILL.md
+---
+name: ui-spec
+description: 生成 UI 规范
+---
+执行 ~/.cognitive/modules/ui-spec-generator/MODULE.md
+```
+
+## 配置 LLM（仅 CLI 需要）
+
+```bash
+# OpenAI
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-xxx
+
+# Anthropic Claude
+export LLM_PROVIDER=anthropic
+export ANTHROPIC_API_KEY=sk-ant-xxx
+
+# Ollama（本地免费）
+export LLM_PROVIDER=ollama
+
+# 不配置则使用 stub（返回示例输出）
+```
+
+## 模块搜索路径
+
+模块按以下顺序查找：
+
+1. `./cognitive/modules/` - 项目本地
+2. `~/.cognitive/modules/` - 用户全局
+3. `$COGNITIVE_MODULES_PATH` - 自定义路径
+
+## 创建新模块
+
+```bash
+# 1. 创建骨架
+cog init my-module -d "模块职责描述"
+
+# 2. 编辑 MODULE.md 添加指令
+# 3. 编辑 schema.json 定义输入输出
+# 4. 验证
+cog validate my-module
+
+# 5. 全局安装（可选）
+cog install ./cognitive/modules/my-module
+```
+
+## 内置模块
+
+### ui-spec-generator
+
+将产品需求转换为前端可实现的 UI 规范。
+
+**输出包含**：
+- 信息架构（sections + hierarchy）
+- 组件定义（type, props, states）
+- 交互设计（events, transitions）
+- 响应式规则（breakpoints, layout）
+- 可访问性（WCAG 要求）
+- 验收标准（可测试条件）
+- 置信度 + 推理过程
+
+```bash
+cog run ui-spec-generator examples/input.json -o ui-spec.json --pretty
+```
+
+## 项目结构
+
+```
+cognitive-modules/
+├── README.md               # 本文件
+├── SPEC.md                 # 规范文档
+├── INTEGRATION.md          # Agent 集成指南
+├── AGENTS.md               # Agent 约定示例
+├── cognitive-registry.json # 公共模块注册表
+├── src/cognitive/          # CLI 源码
+│   ├── cli.py              # 命令入口
+│   ├── loader.py           # 模块加载（支持新旧格式）
+│   ├── runner.py           # 模块执行
+│   ├── validator.py        # 模块验证
+│   ├── registry.py         # 模块发现与安装
+│   ├── templates.py        # 模块模板
+│   └── providers/          # LLM 后端
+├── cognitive/modules/      # 内置模块
+│   └── ui-spec-generator/
+└── pyproject.toml
+```
+
+## 文档
+
+- [SPEC.md](SPEC.md) - 完整规范文档
+- [INTEGRATION.md](INTEGRATION.md) - Agent 工具集成指南
+- [AGENTS.md](AGENTS.md) - Agent 约定示例
+
+## License
+
+MIT

cognitive_modules-0.1.0/README.md

@@ -0,0 +1,247 @@
+# Cognitive Modules
+
+> 可验证的结构化 AI 任务规范
+
+Cognitive Modules 是一种 AI 任务定义规范，专为需要**强约束、可验证、可审计**的生成任务设计。
+
+## 与 Skills 的区别
+
+| | Skills | Cognitive Modules |
+|---|--------|------------------|
+| 定位 | 轻量指令扩展 | 可验证的结构化任务 |
+| 输入校验 | 无 | JSON Schema |
+| 输出校验 | 无 | JSON Schema |
+| 置信度 | 无 | 必须 0-1 |
+| 推理过程 | 无 | 必须 rationale |
+| 适用场景 | 快捷命令 | 规范生成、设计文档 |
+
+## 快速开始
+
+```bash
+# 克隆
+git clone https://github.com/leizii/cognitive-modules.git
+cd cognitive-modules
+
+# 安装依赖
+pip install typer rich jsonschema pyyaml
+
+# 运行
+./cog --help
+```
+
+## CLI 命令
+
+```bash
+# 模块管理
+cog list                    # 列出已安装模块
+cog info <module>           # 查看模块详情
+cog validate <module>       # 验证模块结构
+
+# 创建模块
+cog init <name> -d "描述"    # 从模板创建新模块
+
+# 运行模块
+cog run <module> input.json -o output.json --pretty
+
+# 直接传参数（无需 JSON 文件）
+cog run <module> --args "你的需求描述" -o output.json
+
+# 启用子代理模式（支持 @call 调用其他模块）
+cog run <module> --args "需求" --subagent
+
+# 安装/卸载
+cog install <source>        # 从 git/本地/注册表安装
+cog uninstall <module>      # 卸载模块
+
+# 注册表
+cog registry                # 查看公共模块
+cog search <query>          # 搜索模块
+
+# 环境检查
+cog doctor                  # 检查 LLM 配置
+```
+
+## 安装来源
+
+```bash
+# 从本地安装
+cog install ./path/to/module
+
+# 从 GitHub 安装
+cog install github:leizii/cognitive-modules/cognitive/modules/ui-spec-generator
+
+# 从注册表安装
+cog install registry:ui-spec-generator
+```
+
+## 模块格式
+
+### 新格式（推荐，2 文件）
+
+```
+my-module/
+├── MODULE.md       # 元数据 + 指令
+├── schema.json     # 输入输出 Schema
+└── examples/       # 可选
+    ├── input.json
+    └── output.json
+```
+
+### 旧格式（兼容，6 文件）
+
+```
+my-module/
+├── module.md
+├── input.schema.json
+├── output.schema.json
+├── constraints.yaml
+├── prompt.txt
+└── examples/
+```
+
+## MODULE.md 格式
+
+```yaml
+---
+name: my-module
+version: 1.0.0
+responsibility: 一句话描述
+
+excludes:
+  - 不做的事情
+
+constraints:
+  no_network: true
+  no_inventing_data: true
+  require_confidence: true
+  require_rationale: true
+---
+
+# 指令内容
+
+（这里写 prompt）
+```
+
+## 在 Codex / Cursor 中使用
+
+### 方式 1：直接对话（零配置）
+
+```
+读取 ~/.cognitive/modules/ui-spec-generator/MODULE.md，
+为电商首页生成 UI 规范，保存到 ui-spec.json
+```
+
+### 方式 2：AGENTS.md（项目约定）
+
+在项目根目录创建 `AGENTS.md`：
+
+```markdown
+## UI 规范生成
+
+当需要生成 UI 规范时：
+1. 读取 `~/.cognitive/modules/ui-spec-generator/MODULE.md`
+2. 按 schema.json 格式输出
+3. 保存到 ui-spec.json
+```
+
+### 方式 3：包装成 Skill
+
+```yaml
+# ~/.claude/skills/ui-spec/SKILL.md
+---
+name: ui-spec
+description: 生成 UI 规范
+---
+执行 ~/.cognitive/modules/ui-spec-generator/MODULE.md
+```
+
+## 配置 LLM（仅 CLI 需要）
+
+```bash
+# OpenAI
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-xxx
+
+# Anthropic Claude
+export LLM_PROVIDER=anthropic
+export ANTHROPIC_API_KEY=sk-ant-xxx
+
+# Ollama（本地免费）
+export LLM_PROVIDER=ollama
+
+# 不配置则使用 stub（返回示例输出）
+```
+
+## 模块搜索路径
+
+模块按以下顺序查找：
+
+1. `./cognitive/modules/` - 项目本地
+2. `~/.cognitive/modules/` - 用户全局
+3. `$COGNITIVE_MODULES_PATH` - 自定义路径
+
+## 创建新模块
+
+```bash
+# 1. 创建骨架
+cog init my-module -d "模块职责描述"
+
+# 2. 编辑 MODULE.md 添加指令
+# 3. 编辑 schema.json 定义输入输出
+# 4. 验证
+cog validate my-module
+
+# 5. 全局安装（可选）
+cog install ./cognitive/modules/my-module
+```
+
+## 内置模块
+
+### ui-spec-generator
+
+将产品需求转换为前端可实现的 UI 规范。
+
+**输出包含**：
+- 信息架构（sections + hierarchy）
+- 组件定义（type, props, states）
+- 交互设计（events, transitions）
+- 响应式规则（breakpoints, layout）
+- 可访问性（WCAG 要求）
+- 验收标准（可测试条件）
+- 置信度 + 推理过程
+
+```bash
+cog run ui-spec-generator examples/input.json -o ui-spec.json --pretty
+```
+
+## 项目结构
+
+```
+cognitive-modules/
+├── README.md               # 本文件
+├── SPEC.md                 # 规范文档
+├── INTEGRATION.md          # Agent 集成指南
+├── AGENTS.md               # Agent 约定示例
+├── cognitive-registry.json # 公共模块注册表
+├── src/cognitive/          # CLI 源码
+│   ├── cli.py              # 命令入口
+│   ├── loader.py           # 模块加载（支持新旧格式）
+│   ├── runner.py           # 模块执行
+│   ├── validator.py        # 模块验证
+│   ├── registry.py         # 模块发现与安装
+│   ├── templates.py        # 模块模板
+│   └── providers/          # LLM 后端
+├── cognitive/modules/      # 内置模块
+│   └── ui-spec-generator/
+└── pyproject.toml
+```
+
+## 文档
+
+- [SPEC.md](SPEC.md) - 完整规范文档
+- [INTEGRATION.md](INTEGRATION.md) - Agent 工具集成指南
+- [AGENTS.md](AGENTS.md) - Agent 约定示例
+
+## License
+
+MIT

cognitive_modules-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cognitive-modules"
+version = "0.1.0"
+description = "Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "leizii"}
+]
+keywords = [
+    "llm",
+    "cognitive",
+    "modules",
+    "ai",
+    "cli",
+    "schema",
+    "validation",
+    "prompt",
+    "agent",
+    "subagent"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "jsonschema>=4.17.0",
+    "pyyaml>=6.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.18.0"]
+ollama = ["requests>=2.28.0"]
+minimax = ["openai>=1.0.0"]
+all = [
+    "openai>=1.0.0",
+    "anthropic>=0.18.0",
+    "requests>=2.28.0"
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "build>=1.0.0",
+    "twine>=4.0.0"
+]
+
+[project.scripts]
+cog = "cognitive.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/leizii/cognitive-modules"
+Documentation = "https://github.com/leizii/cognitive-modules#readme"
+Repository = "https://github.com/leizii/cognitive-modules"
+Issues = "https://github.com/leizii/cognitive-modules/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml", "*.json", "*.md", "*.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src/cognitive"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]

cognitive_modules-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cognitive_modules-0.1.0/src/cognitive/__init__.py

@@ -0,0 +1,12 @@
+"""
+Cognitive Modules - Structured LLM task runner with schema validation.
+
+Usage:
+    cog list                     # List installed modules
+    cog run <module> <input>     # Run a module
+    cog validate <module>        # Validate module structure
+    cog install <source>         # Install module from git/local
+    cog doctor                   # Check environment setup
+"""
+
+__version__ = "0.1.0"