neuron-engine 3.0.4

类脑神经元全域智能体引擎 SDK — 基于五层神经圈层架构的通用AI Agent框架 (V2.8稳态增强版)

Neuron Engine SDK v3.0

类脑神经元全域智能体引擎 — 基于五层神经圈层架构的通用AI Agent框架

架构概览

┌─────────────────────────────────────────────────────┐
│                  决策层 (Decision)                    │
│         决策融合 · 多巴胺奖励 · RPE预测误差           │
├─────────────────────────────────────────────────────┤
│                  调度层 (Schedule)                    │
│       规则互斥 · 优先级 · 限流 · 全局调控            │
├─────────────────────────────────────────────────────┤
│                  能力层 (Skill)                       │
│       技能管理 · STDP学习 · 突触可塑性                │
├─────────────────────────────────────────────────────┤
│                  认知层 (Cognition)                   │
│       语义解析 · 情景记忆 · 程序记忆 · 知识库        │
├─────────────────────────────────────────────────────┤
│                  感知层 (Perception)                  │
│       信号采集 · 三分类协议 · 噪声过滤               │
└─────────────────────────────────────────────────────┘

核心特性

• LIF膜电位模型 — 离散近似 V(t+1) = λ·V(t) + (1-λ)·I_syn(t)
• 三分类信号协议 — 兴奋 / 抑制 / 调控（调控走旁路不触发点火）
• STDP脉冲时序可塑性 — Bi&Poo 1998 生物参数 (A+=0.08, A-=0.04)
• 四级层级记忆 — temp → short_term → long_term → permanent
• 全局调控系统 — 四维状态(觉醒/注意/学习/稳定) + 大五人格 + VAD情绪
• 三态熔断机制 — 关闭 → 打开 → 半开，60秒冷却
• 10步闭环工作流 — Bootstrap → 感知 → 认知 → 能力 → 调控 → 调度 → 执行 → 决策 → 奖励 → 演化
• 零外部依赖 — 纯Python标准库实现，可选PostgreSQL后端

快速开始

安装

cd neuron-engine
pip install -e ".[dev]"

基础使用

from neuron_engine.workflow import NeuronEngine
from neuron_engine.core.signal import Signal

# 创建引擎
engine = NeuronEngine()

# 注册神经元 + 技能
def my_skill(neuron, **kwargs):
    task_input = kwargs.get("task_input", "")
    return {"output": f"Processed: {task_input}"}

nid = engine.register_neuron(
    neuron_type="skill",
    domain_tag="demo",
    executor=my_skill,
    description="示例技能"
)

# 执行任务 (10步闭环)
result = engine.execute_task("Hello Neuron Engine")
print(result)

信号系统

from neuron_engine.core.signal import Signal, SignalType, ModulationType

# 兴奋信号
exc = Signal.create_excitation(source_id="N-01", intensity=0.8, priority=5)

# 抑制信号
inh = Signal.create_inhibition(source_id="N-02", intensity=0.6)

# 调控信号（多巴胺/NE/ACh/5-HT/组胺）
mod = Signal.create_modulation(
    source_id="G1",
    modulation_type=ModulationType.DOPAMINE,
    intensity=0.7
)

STDP学习

from neuron_engine.learning import STDPLearner, RPEEvaluator
from neuron_engine.core.synapse import Synapse

learner = STDPLearner()
synapse = Synapse(source_id="N-01", target_id="N-02", weight=0.5)

# pre-before-post: 权重增强
learner.update_single(synapse, delta_t=-100, learning_rate=1.0)
print(f"Weight: {synapse.weight:.4f}")  # > 0.5

# RPE奖励评估
evaluator = RPEEvaluator()
quality = evaluator.evaluate_quality({
    "completeness": 0.9,
    "success_rate": 0.8,
    "latency_ms": 200,
    "user_feedback": 0.7,
})
rpe = evaluator.calc_rpe(quality, expected_value=0.5)
print(f"Quality: {quality:.3f}, RPE: {rpe:+.3f}")

记忆系统

from neuron_engine.memory import MemoryManager

mgr = MemoryManager()

# 存储记忆
atom = mgr.store("重要知识点", domain_tag="AI", keywords=["深度学习"])
atom.access()  # 记录访问
atom.access()

# 搜索记忆
results = mgr.search(domain_tag="AI", keyword="深度学习")

# 记忆巩固
mgr.consolidate(atom.atom_id)

全局调控

from neuron_engine.governance import GovernanceSystem

gov = GovernanceSystem()

# 调节四维状态
gov.global_state.update(arousal=0.8, learning_mode=0.7)
gov.infer_mode()  # 自动推断运行模式

# 三维协同向量
synergy = gov.calc_synergy_vector()
print(synergy)

数据库持久化

from neuron_engine.db import NeuronDB, NeuronRow, SynapseRow, MemoryAtomRow

# SQLite (默认)
db = NeuronDB("neurons.db")

# PostgreSQL (生产)
# db = NeuronDB("postgresql://user:pass@host/db")

# 创建神经元
db.insert_neuron(NeuronRow(
    neuron_id="N-001",
    neuron_type="skill",
    domain_tag="NLP",
    description="文本分析"
))

# 创建突触
db.insert_synapse(SynapseRow(
    source_id="N-001", target_id="N-002",
    weight=0.7, signal_type="excitation"
))

# 查看统计
print(db.get_stats())

REST API

from neuron_engine.workflow import NeuronEngine
from neuron_engine.db import NeuronDB
from neuron_engine.api import NeuronAPIServer

engine = NeuronEngine(db=NeuronDB("neurons.db"))
server = NeuronAPIServer(engine, engine.db, host="0.0.0.0", port=8100)
server.start()  # 阻塞启动
# server.start(blocking=False)  # 后台启动

API端点：

方法	路径	说明
GET	/health	健康检查
GET	/neurons	列出神经元
POST	/neurons	创建神经元
GET	/neurons/{id}	获取神经元
POST	/neurons/{id}/activate	激活神经元
GET	/synapses	列出突触
POST	/synapses	创建突触
PUT	/synapses/{src}/{tgt}/weight	更新权重
GET	/memories	搜索记忆
POST	/memories	创建记忆
POST	/memories/{id}/promote	晋升记忆
POST	/tasks/execute	执行任务
GET	/governance/state	调控状态
GET	/governance/personality	人格特征
GET	/governance/emotion	情绪状态
GET	/config	获取配置
PUT	/config	更新配置
GET	/stats	引擎统计
GET	/openapi.json	OpenAPI规范

MCP Server (Claude/OpenAI 集成)

编程式调用

from neuron_engine.workflow import NeuronEngine
from neuron_engine.db import NeuronDB
from neuron_engine.mcp_server import NeuronMCPServer
import json

engine = NeuronEngine(db=NeuronDB(":memory:"))
server = NeuronMCPServer(engine)

# 列出工具
resp = server.handle_request({
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/list", "params": {}
})
for tool in resp["result"]["tools"]:
    print(f"  {tool['name']}: {tool['description']}")

# 执行任务
resp = server.handle_request({
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
        "name": "neuron_execute_task",
        "arguments": {"task_input": "分析文本情感", "priority": "5"}
    }
})
result = json.loads(resp["result"]["content"][0]["text"])
print(f"Status: {result['status']}")

自定义工具

server.register_tool_simple(
    name="my_tool",
    description="自定义工具",
    params={"query": "查询内容"},
    handler=lambda p: {"result": process(p["query"])},
)

Claude Desktop 集成

将以下配置添加到 Claude Desktop 配置文件:

{
  "mcpServers": {
    "neuron-engine": {
      "command": "python",
      "args": ["-m", "neuron_engine.mcp_server"],
      "cwd": "/path/to/neuron-engine"
    }
  }
}

运行测试

cd neuron-engine
python -m pytest tests/ -v

项目结构

neuron-engine/
├── neuron_engine/
│   ├── __init__.py          # 包入口 V3.0.0
│   ├── protocols.py         # Protocol接口定义 (ISignal/ISynapse/INeuron)
│   ├── mcp_server.py        # MCP Server (JSON-RPC 2.0 + stdio)
│   ├── logging.py           # 分层日志系统 (层级Logger + JSON格式化)
│   ├── core/                # 核心模型
│   │   ├── signal.py        # 三分类信号协议
│   │   ├── neuron.py        # LIF膜电位 + 三态熔断
│   │   └── synapse.py       # 突触 + STDP权重锁定
│   ├── config/              # 配置管理 (13+9项, 4分组)
│   ├── learning/            # STDP学习 + RPE奖励评估
│   ├── memory/              # 原子记忆 + 四级晋升 + 链式检索
│   ├── governance/          # 全局调控 + 人格 + 情绪 + 三维协同
│   ├── workflow/            # 10步闭环工作流引擎
│   ├── db/                  # 14张核心表持久化 (SQLite/PG)
│   ├── api/                 # REST API (零依赖)
│   ├── signal/              # 信号总线 + 生命周期 + 噪声过滤
│   ├── evolution/           # 自动演化引擎
│   ├── monitor/             # 指标采集 + 异常检测 + 自愈 + Dashboard
│   ├── utils/               # 工具函数
│   └── exceptions/          # 23章错误码体系 (21个异常类)
├── tests/                   # 165个单元测试 (12文件, 0.42s)
│   ├── test_core.py         # Signal/Neuron/Synapse (21)
│   ├── test_learning.py     # STDP/RPE (19)
│   ├── test_memory.py       # MemoryAtom/MemoryManager (28)
│   ├── test_governance.py   # GovernanceSystem (22)
│   ├── test_workflow.py     # NeuronEngine (5)
│   ├── test_db.py           # NeuronDB (11)
│   ├── test_protocols.py    # Protocol接口 (7)
│   ├── test_logging.py      # 日志系统 (18)
│   ├── test_mcp_server.py   # MCP Server (12)
│   ├── test_signal.py       # 信号总线/生命周期/噪声 (16)
│   ├── test_evolution.py    # 自动演化 (5)
│   └── test_monitor.py      # 监控/异常检测 (6)
├── examples/
│   ├── basic_usage.py       # 基础使用6例
│   └── mcp_server_usage.py  # MCP Server使用3例
├── docker/
│   ├── Dockerfile           # 容器化部署
│   └── docker-compose.yml   # 编排配置
├── pyproject.toml           # 打包配置 (零依赖, 可选PG)
└── README.md

白皮书映射

SDK模块	白皮书章节	核心内容
core/signal.py	第6章	三分类信号协议、工厂方法
core/neuron.py	第5/7章	LIF膜电位、三态熔断、点火放电
core/synapse.py	第6/7章	突触权重锁定[0.1,0.9]、STDP更新
learning/	第7章	Bi&Poo 1998 STDP参数、RPE奖励
memory/	第9章	原子记忆节点、四级晋升规则
governance/	第8章	四维全局状态、大五人格、VAD情绪
workflow/	第11/12章	10步闭环工作流
db/	第13章	14张核心表DDL
config/	第10章	13+9项配置、4分组、热加载
exceptions/	第23章	5级错误分级、21个异常类

License

MIT

📝 更新日志

v3.0.2 (2026-05-08)

• ✅ 【发布信息】更新维护者信息为：合肥极美景行商贸有限公司「若曦」项目组
• ✅ 【发布信息】同步更新开发者邮箱与项目归属信息
• ✅ 【发布信息】修复 PyPI 发布配置，确保版本号与描述一致性
• ✅ 【文档】完善项目简介与开发者背景说明

v3.0.1 (2026-05-07)

• ✨ 新增 MCP 协议集成接口（10个工具/4分组/协议握手/客户端配置）
• ✨ 新增命令行工具（6子命令/使用示例/退出码规范）
• ✨ 新增 HTTP REST 接口（29端点/7分组/监控端点/Router架构）
• ✨ 完善部署与分发支持（PyPI发布/安装方式/双DB/多协议/部署清单）
• ✨ 新增协议抽象与扩展接口（5接口/4后端/4枚举/扩展示例）
• ✨ 补充 V3.0 版本演进更新（里程碑10项/章节索引/全景图）
• ✨ 完成 PyPI 发布：neuron-engine 3.0.1，纯Python零外部依赖

v3.0.0 (2026-05-06)

• 🚀 发布「若曦・类脑神经元全域智能体架构」核心引擎 neuron-engine
• 🧠 实现基于五层神经圈层架构的通用AI Agent核心框架
• ⚡ 支持脉冲神经网络（SNN）、STDP突触可塑性、LIF神经元模型
• 📦 开源发布，支持 pip install neuron-engine 一键安装