Nuwa (女娲)

一个实验性的、基于控制论与向量动力学假设的 AI Agent 框架，探索在消费级硬件上构建「数字生命原型」的可能性。

![Python 3.11+](https://www.python.org/downloads/) ![License: Apache 2.0](https://opensource.org/licenses/Apache-2.0) ![Test Coverage](tests/)

> 💡 项目分离通知 (2026-03-08): Live2D 和 Web 前端已独立到 123/ 子目录作为单独项目。本项目现在专注于 AI Agent 核心框架。

---

---

🎯 项目定位

Nuwa 是一个实验性的 AI Agent 框架，旨在探索在不微调模型权重的前提下，通过外挂的数学模型（PID控制、向量场）赋予 LLM 模拟的「生理节律」与「性格惯性」。

设计理念

体验优于理论：哪怕微小的数学扰动，只要能带来更具「灵魂感」的交互，就具有价值
低资源友好：针对 4B/12B 等小型模型优化，适合消费级硬件
PoC 原型：概念验证项目，展示数字生命构建的可能性
AI Native 开发：借助 AI 及 IDE 进行高强度辅助开发的实践产物

作者的话

> 从土木行业裸辞，曾参加信通院人工智能所AI安全研究员方向终面，遗憾未能获得offer，但衷心感谢所里和院里给予的高额劳务报酬。 > > 虽然这只是一个原型，但它代表了尝试以数学/控制论等构建伪数字生命的一次有意义尝试。如果你也对"赋予 AI 生命"感兴趣，欢迎加入我们。

---

✨ 核心特性

1. 🧠 黎曼几何语义场 (Riemannian Semantic Field)

基于双曲流形理论的严格语义演化系统，通过计算状态与人设核心的向量距离（势能），引导对话生成方向，有效减少 OOC（人设崩坏）。

from nuwa_core.riemannian_semantic_field import RigorousSemanticField

field = RigorousSemanticField(core_vector=core_embedding)
energy = field.calculate_potential_energy(state_vector)
gradient = field.compute_riemannian_gradient(state_vector)
evolved, info = field.evolve(state_vector, dt=0.02, iterations=20)

核心能力：

✅ 双曲流形验证
✅ Hessian矩阵计算
✅ 势能和梯度稳定性
✅ 演化收敛性保证

2. 🎛️ 自适应 PID控制 (Adaptive PID Control)

使用 PPO 强化学习代理实现参数自适应调整的 PID控制器，模拟生物节律（精力衰减、社交饥渴、情绪回归）。

from nuwa_core.adaptive_pid import create_adaptive_controller

controller = create_adaptive_controller(kp=1.0, ki=0.1, kd=0.01)
controller.update_parameters(state, performance=0.8)
output = controller.compute_control_output(error)

核心能力：

✅ 基础PID功能
✅ PPO代理训练
✅ 自适应参数更新
✅ 情绪/熵值双控制器

3. 🧬 强化学习自我进化 (RL-based Self-Evolution)

基于 Q-Learning 的自我进化系统，支持经验回放和双模式（探索/利用），实现人格的动态发展。

from nuwa_core.self_evolution_state import SelfEvolutionState

evolution = SelfEvolutionState()
evolution.update_cycle()
evolution.record_performance(performance_score)
action = evolution.select_action(state, mode='exploit')

核心能力：

✅ Q-Learning 算法
✅ 经验回放机制
✅ 双模式支持（探索/利用）
✅ 演化状态管理

4. 💾 记忆皮层 (Memory Cortex)

基于 LanceDB 的语义检索系统，支持情绪检索和时间感知，包含记忆做梦系统促进自我进化。

from nuwa_core.memory_cortex import MemoryCortex

cortex = MemoryCortex()
memory_id = cortex.store_memory("用户输入", {"importance": 0.8})
memories = cortex.retrieve_memory("相关查询", top_k=5)

核心能力：

✅ LanceDB 语义检索
✅ 时间权重记忆整理 (TWPE)
✅ 情绪加权检索
✅ 记忆做梦系统

6. 📊 统一异步内核 (Unified Async Kernel)

完全异步架构的内核系统，支持高并发处理、流式响应、缓存管理和依赖注入。

from nuwa_core.nuwa_kernel_async import NuwaKernelAsync

kernel = NuwaKernelAsync(
    project_name="nuwa",
    data_dir="data",
    base_url="http://127.0.0.1:1234/v1",
    enable_cache=True,
)
result = await kernel.process_input("你好")

核心能力：

✅ 统一异步架构
✅ 多级缓存管理
✅ 心跳循环机制
✅ 技能系统集成

---

🔌 技能机制

女娲系统采用双轨技能架构，同时支持 AgentSkills（原生技能） 和 ClawHub 技能，实现能力的动态扩展与热插拔。

1. 技能系统架构

SkillManager (技能管理器)
├── AgentSkills (原生技能)
│   ├── 基类：AgentSkill
│   ├── WeatherSkill (天气查询)
│   └── Custom Skills (自定义技能目录)
│
└── ClawHub Skills (第三方技能)
    ├── ClawHub Manager (安装/卸载/更新)
    ├── Skill Registry (技能注册表)
    └── Skill Executor (技能执行器)

2. AgentSkills（原生技能）

基于 Python 类实现的内置技能，具有完整的类型安全和性能优化。

2.1 技能基类

所有原生技能都继承自 AgentSkill 抽象基类：

from nuwa_core.skills.agent_skills import AgentSkill

class WeatherSkill(AgentSkill):
    def __init__(self):
        super().__init__()
        self.name = "WeatherSkill"
        self.description = "查询天气信息"
        self.keywords = ["天气", "温度", "晴", "雨", "雪", "预报"]
    
    async def execute(self, query: str, emotion_state: Dict[str, float], 
                     memory_context: Dict[str, Any]) -> Dict[str, Any]:
        # 执行技能逻辑
        return self.format_response(
            success=True,
            result=weather_data,
            emotion_update={"joy": 0.2},
            memory_update=f"查询了{city}的天气",
            message=message
        )

2.2 核心特性

情绪感知：技能执行时接收当前情绪状态，可反向影响情绪
记忆上下文：访问短期/长期记忆，实现有记忆的交互
标准化输出：统一返回格式，包含结果、情绪更新、记忆更新

2.3 开发自定义 AgentSkill

# 1. 在 skills 目录创建技能文件夹
mkdir -p skills/my_custom_skill

# 2. 创建__init__.py 文件
touch skills/my_custom_skill/__init__.py

# 3. 编写技能代码

# skills/my_custom_skill/__init__.py
from nuwa_core.skills.agent_skills import AgentSkill

class MyCustomSkill(AgentSkill):
    def __init__(self):
        super().__init__()
        self.name = "MyCustomSkill"
        self.description = "我的自定义技能描述"
        self.keywords = ["关键词 1", "关键词 2"]
    
    async def execute(self, query: str, emotion_state: Dict[str, float], 
                     memory_context: Dict[str, Any]) -> Dict[str, Any]:
        # 实现你的技能逻辑
        return self.format_response(
            success=True,
            result={"data": "结果数据"},
            emotion_update={"joy": 0.1},
            memory_update="技能执行记录",
            message="向用户展示的消息"
        )

3. ClawHub 技能（第三方技能）

基于 OpenClaw 规范的插件化技能系统，支持从社区动态安装/卸载技能。

3.1 技能元数据

每个 ClawHub 技能包含完整的元数据定义：

# .claw/skill.yaml
name: multi-search-engine
version: 1.0.0
description: 支持 17 个搜索引擎的多功能搜索工具
author: Nuwa Team
homepage: https://github.com/shierduan/Nuwa

metadata:
  skill_key: search
  primary_env: python
  emoji: 🔍
  os: [linux, darwin, windows]
  
install:
  - kind: pip
    package: requests
    module: requests
    
commands:
  - name: search
    description: 使用搜索引擎查询信息
    dispatch:
      kind: tool
      tool_name: web_search

3.2 技能管理命令

# 搜索技能
skill_manager search "搜索"

# 安装技能
skill_manager install multi-search-engine

# 卸载技能
skill_manager uninstall multi-search-engine

# 更新技能
skill_manager update multi-search-engine

# 列出已安装技能
skill_manager list

3.3 技能执行器

为 ClawHub 技能注册专用执行器：

# 在 SkillManager 中注册执行器
def _register_skill_executors(self):
    self.skill_executors['multi-search-engine'] = self._execute_multi_search_engine

async def _execute_multi_search_engine(self, skill: Dict, query: str, 
                                       emotion_state: Dict[str, float], 
                                       memory_context: Dict[str, Any]) -> Dict[str, Any]:
    # 解析 URL 或搜索关键词
    urls = re.findall(url_pattern, query)
    
    if urls:
        # 执行网页抓取
        fetch_result = await web_fetch({'url': urls[0][2]})
        return {
            "success": True,
            "result": {"page_info": fetch_result['data']},
            "emotion_update": {"joy": 0.1, "anticipation": 0.1},
            "memory_update": f"访问了 {urls[0][2]}",
            "message": f"已访问该网站：{fetch_result['data'].get('title')}"
        }
    else:
        # 执行搜索
        search_result = await search_web(query, engine='google')
        return {
            "success": True,
            "result": {"search_results": search_result['data']},
            "emotion_update": {"anticipation": 0.15},
            "memory_update": f"搜索了 '{query}'",
            "message": f"搜索结果：{search_result['data'].get('title')}"
        }

4. 技能调度机制

4.1 智能匹配算法

技能管理器使用多层匹配策略：

def find_skill(self, query: str) -> Optional[Any]:
    query_lower = query.lower()
    
    # 1. 优先匹配 AgentSkills（关键词匹配）
    for skill in self.agent_skills:
        if skill.can_handle(query):
            return skill
    
    # 2. 然后匹配 ClawHub 技能（多策略评分）
    best_match = None
    best_score = 0
    
    for skill in self.clawhub_skills:
        score = 0
        
        # 精确匹配名称 (100 分)
        if skill_name == query_lower:
            score = 100
        # 包含匹配 (80 分)
        elif skill_name in query_lower:
            score = 80
        # 关键词匹配 (60 分)
        elif matched_keywords:
            score = (len(matched_keywords) / len(skill_keywords)) * 60
        # 描述匹配 (40 分)
        if description_match:
            score = max(score, 40)
        
        # 特殊技能逻辑（如 find-skills, multi-search-engine）
        if skill_name == 'multi-search-engine' and has_search_keywords:
            score = max(score, 90)
        
        if score > best_score:
            best_score = score
            best_match = skill
    
    # 返回超过阈值的最佳匹配
    return best_match if best_score >= 40 else None

4.2 技能执行流程

sequenceDiagram
    participant User as 用户
    participant Kernel as NuwaKernel
    participant SM as SkillManager
    participant Skill as 技能实例
    participant Memory as 记忆皮层
    
    User->>Kernel: 输入请求
    Kernel->>SM: find_skill(query)
    SM->>SM: 匹配 AgentSkills
    SM->>SM: 匹配 ClawHub 技能
    SM-->>Kernel: 返回匹配技能
    Kernel->>Memory: 获取记忆上下文
    Memory-->>Kernel: 返回记忆上下文
    Kernel->>Skill: execute(query, emotion, memory)
    Skill->>Skill: 执行技能逻辑
    Skill-->>Kernel: 返回执行结果
    Kernel->>Kernel: 更新情绪状态
    Kernel->>Kernel: 存储记忆
    Kernel-->>User: 返回响应

5. 技能生命周期管理

5.1 加载机制

class SkillManager:
    def __init__(self, skills_dirs: List[str] = None):
        # 默认技能目录
        default_dirs = [
            os.path.join(os.getcwd(), 'skills'),
            os.path.join(os.getcwd(), 'data', 'nuwa', 'skills')
        ]
        self.skills_dirs = skills_dirs or default_dirs
        
        # 初始化 ClawHub 管理器
        self.clawhub_manager = get_clawhub_manager(self.skills_dirs[0])
        
        # 加载所有技能
        self._load_agent_skills()
        self._load_clawhub_skills()
        self._register_skill_executors()

5.2 热插拔支持

# 动态安装技能
success = install_skill("multi-search-engine")
if success:
    # 自动重新加载技能列表
    reload_skills()

# 动态卸载技能
success = uninstall_skill("weather-skill")

# 更新技能到指定版本
update_skill("multi-search-engine", version="2.0.0")

6. 技能与情感系统集成

技能执行不仅返回结果，还会：

更新情绪状态：根据技能执行结果调整 13 维情感空间
写入记忆：将技能使用记录存入长期记忆
影响后续行为：情绪变化会影响 LLM 生成策略

# 技能执行返回值示例
{
    "success": True,
    "result": {"temperature": 22, "condition": "晴"},
    "emotion_update": {"joy": 0.2},  # 晴天增加快乐值
    "memory_update": "查询了北京的天气，当前温度 22°C，天气晴",
    "message": "北京当前天气：晴，温度 22°C..."
}

7. 技能目录结构

Nuwa/
├── nuwa_core/skills/           # 核心技能模块
│   ├── skill_manager.py        # 技能管理器
│   ├── agent_skills.py         # AgentSkill 基类
│   ├── clawhub.py              # ClawHub 集成
│   ├── skill_types.py          # 技能类型定义
│   ├── workspace.py            # 工作区技能规范
│   ├── frontmatter.py          # YAML Frontmatter 解析
│   ├── weather_skill.py         # 天气技能示例
│   ├── web_fetch.py            # 网页抓取工具
│   │
│   └── custom/                 # 自定义技能目录（动态加载）
│       └── my_skill/
│           └── __init__.py
│
├── skills/                     # 用户技能目录 1
│   └── custom_skill/
│       └── __init__.py
│
└── data/nuwa/skills/           # 用户技能目录 2
    └── another_skill/
        └── __init__.py

8. 技能开发最佳实践

8.1 设计原则

单一职责：每个技能只负责一个明确的功能
情绪友好：合理设计情绪更新，增强拟人化体验
记忆意识：重要操作应写入记忆，形成连续体验
错误处理：优雅处理失败场景，提供有意义的错误信息

8.2 性能优化

异步执行：所有技能使用 async/await 避免阻塞主线程
缓存策略：重复查询使用缓存减少外部 API 调用
超时控制：外部调用设置合理超时时间

8.3 安全考虑

输入验证：严格校验用户输入，防止注入攻击
权限控制：敏感操作需要用户确认
资源限制：限制技能执行的资源消耗

---

🏗️ 技术架构

架构图

flowchart TD
    subgraph "核心引擎层"
        A[NuwaKernelAsync] -->|管理| B[NuwaState]
        A -->|使用| C[MemoryCortex]
        A -->|利用| D[RigorousSemanticField]
        A -->|调用| E[LLM Client]
    end
    
    subgraph "控制系统"
        F[AdaptivePID] -->|调节| B
        G[SelfEvolutionRL] -->|优化| B
    end
    
    end
    
    subgraph "交互层"
        I[WebSocket Server] -->|通信| A
        J[Console Interface] -->|交互| A
        K[Chat Channels] -->|Feishu/DingTalk| A
    end
    
    subgraph "监控层"
        L[MetricsCollector] -->|采集| A
        M[Prometheus] -->|存储| L
        N[Grafana] -->|可视化| M
    end
    
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef control fill:#bbf,stroke:#333,stroke-width:2px;
    classDef multi fill:#bfb,stroke:#333,stroke-width:2px;
    classDef interact fill:#ffb,stroke:#333,stroke-width:2px;
    classDef monitor fill:#fbb,stroke:#333,stroke-width:2px;
    
    class A,B,C,D,E core;
    class F,G control;
    class H multi;
    class I,J,K interact;
    class L,M,N monitor;

项目结构

Nuwa/
├── nuwa_core/                  # 核心内核模块
│   ├── nuwa_kernel_async.py    # 统一异步内核 (1218 行)
│   ├── kernel_di.py            # 依赖注入内核 (899 行)
│   ├── nuwa_state.py           # 状态管理 (872 行)
│   ├── state_events.py         # 事件系统 (345 行)
│   ├── config_manager.py       # 配置管理 (446 行)
│   │
│   ├── memory_cortex.py        # 记忆皮层 (782 行)
│   ├── memory_dreamer.py       # 记忆梦境系统
│   ├── memory_optimizer.py     # 内存优化 (471 行)
│   ├── graph_memory.py         # 图记忆 (待完善)
│   │
│   ├── riemannian_semantic_field.py  # 黎曼几何语义场 (562 行)
│   ├── adaptive_pid.py         # 自适应 PID控制 (892 行)
│   ├── self_evolution_rl.py    # RL 自我进化 (892 行)
│   ├── self_evolution_state.py # 进化状态 (257 行)
│   │
│   ├── model_utils.py          # 模型工具
│   │
│   ├── cache_manager.py        # 缓存管理 (500 行)
│   ├── personality.py          # 人格管理 (209 行)
│   ├── metrics_collector.py    # 监控指标收集器
│   ├── sync_compat.py          # 同步兼容层
│   │
│   ├── skills/                 # 技能系统 (双轨架构)
│   │   ├── skill_manager.py    # 技能管理器 (491 行)
│   │   ├── agent_skills.py     # AgentSkill 基类 (104 行)
│   │   ├── clawhub.py          # ClawHub 集成 (约 300 行)
│   │   ├── skill_types.py      # 技能类型定义 (140 行)
│   │   ├── workspace.py        # 工作区技能规范 (约 900 行)
│   │   ├── frontmatter.py      # YAML Frontmatter 解析 (约 130 行)
│   │   ├── weather_skill.py     # 天气技能示例 (188 行)
│   │   ├── web_fetch.py        # 网页抓取工具 (约 120 行)
│   │   └── custom/             # 自定义技能目录（动态加载）
│   │
│   └── chat_channels/          # 聊天渠道
│       ├── feishu_channel.py   # 飞书渠道
│       ├── dingtalk_channel.py # 钉钉渠道
│       └── wecom_channel.py    # 企业微信渠道
│
├── tests/                      # 测试体系
│   ├── unit/                   # 单元测试 (90%+ 覆盖率)
│   ├── integration/            # 集成测试
│   └── performance/            # 性能测试
│
├── monitoring/                 # 监控系统
│   ├── prometheus.yml          # Prometheus 配置
│   └── grafana/                # Grafana Dashboard
│
├── config/                     # 配置文件
│   ├── config.yaml             # 主配置
│   └── config_example.yaml     # 配置示例
│
├── docs/                       # 文档中心
│   ├── README.md               # 项目文档
│   ├── TTS 集成指南.md
│   ├── 黎曼几何语义场使用指南.md
│   ├── 自适应 PID 使用指南.md
│   └── ...
│
├── main_async.py               # 控制台入口
├── server_async.py             # WebSocket 服务器
├── requirements.txt            # Python 依赖
├── docker-compose.yml          # Docker 编排
└── Dockerfile                  # 容器镜像

---

🚀 快速开始

1. 环境准备

# 克隆仓库
git clone https://github.com/shierduan/Nuwa.git
cd Nuwa

# 安装 Python 依赖
pip install -r requirements.txt

# 或使用虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. 配置 LLM 服务

使用 LM Studio（推荐本地部署）

1. 下载并安装 LM Studio 2. 下载 4B/12B 大小的 LLM 模型（如 gemma-3-4b-it-Q4_K_M.gguf） 3. 启动本地服务器，默认监听 http://127.0.0.1:1234/v1

使用 API 服务

编辑 config/config.yaml：

llm_base_url: "https://api.openai.com/v1"
llm_api_key: "your-api-key"
llm_model_name: "gpt-3.5-turbo"

3. 配置文件设置

# 复制配置示例
cp config/config_example.yaml config/config.yaml

# 编辑配置
vim config/config.yaml

4. 启动服务

方式 1：控制台交互模式（开发调试）

python main_async.py

方式 2：WebSocket 服务器模式（为前端提供服务）

python server_async.py

方式 3：Docker 部署（生产环境）

# 一键启动所有服务
docker-compose up -d

# 查看日志
docker logs -f nuwa-core

# 停止服务
docker-compose down

5. 运行测试

# 运行所有测试
pytest tests/ -v

# 运行单元测试（带覆盖率）
pytest tests/unit/ -v --cov=nuwa_core

# 运行集成测试
pytest tests/integration/ -v

# 运行性能测试
pytest tests/performance/ -v -s

6. 访问监控界面

# Grafana 监控面板
open http://localhost:3000  # 账号密码：admin/admin123

# Prometheus 指标查询
open http://localhost:9090

# 健康检查
curl http://localhost:8000/health

# 实时指标
curl http://localhost:8080/metrics

---

💡 核心算法

1. PID 生物节律控制

# 情绪回归控制器：目标是平静 (0.5)
emotion_controller = create_adaptive_controller(
    kp=0.1, ki=0.01, kd=0.05,
    setpoint=0.5,
    output_limits=(-0.1, 0.1),
)

# 熵值回归控制器：目标是有序 (0.0)
entropy_controller = create_adaptive_controller(
    kp=0.2, ki=0.05, kd=0.01,
    setpoint=0.0,
    output_limits=(-0.1, 0.1),
)

# 自适应参数更新
controller.update_parameters(state, performance=0.8)

2. 黎曼几何语义场势能计算

# 创建语义场
field = RigorousSemanticField(core_vector=core_embedding)

# 计算势能（当前状态与人设核心的距离）
potential_energy = field.calculate_potential_energy(state_vector)

# 计算黎曼梯度（数值稳定）
gradient = field.compute_riemannian_gradient(state_vector)

# 演化状态，减少 OOC
new_state, info = field.evolve(
    state_vector, 
    dt=0.02, 
    iterations=20
)

3. 时间权重记忆整理 (TWPE)

基于时间衰减和重要性权重，动态整理和演化记忆：

# 存储记忆（带情绪权重）
memory_id = cortex.store_memory(
    content="用户输入",
    metadata={"importance": 0.8, "emotion": "joy"}
)

# 检索记忆（时间加权 + 情绪加权）
memories = cortex.retrieve_memory(
    query="相关查询",
    top_k=5,
    emotion_weight=0.3
)

4. 强化学习自我进化

# 初始化进化状态
evolution = SelfEvolutionState()

# 选择动作（探索/利用模式）
action = evolution.select_action(state, mode='explore')

# 记录性能反馈
evolution.record_performance(reward=0.8)

# 更新演化周期
evolution.update_cycle()

---

💫 情感状态空间：13 维连续状态空间

我们通过构建一个 13 维的连续状态空间 ($\mathbb{R}^{13}$)，让 Nuwa 拥有更贴近生命的情感体验和行为质感。

数学表达

基于 nuwa_state.py 的实现，Nuwa 的核心情感状态 $S$ 由三个相互关联的部分组成：

$$S = [ \underbrace{E, S_{entropy}}_{\text{生命存在的基础}} , \underbrace{D_{soc}, D_{cur}, R_{ap}}_{\text{情感产生的动力}} , \underbrace{\mathbf{E}_{motion}^{(8)}}_{\text{情感表达的色彩}} ]$$

情感维度构成

Nuwa Emotional State (ℝ¹³)
├── 生命存在基础 (Basic Existence)
│   ├── Energy (精力) - 维持活动的基础
│   └── Entropy (系统熵值) - 内部秩序的稳定
│
├── 情感产生动力 (Emotional Drives)
│   ├── Social Hunger (社交饥渴) - 渴望与人连接
│   ├── Curiosity (好奇心) - 想要了解更多
│   └── Rapport (亲密度) - 与用户的情感纽带
│
└── 情感表达色彩 (Emotional Colors) - Plutchik Model
    ├── Joy (快乐)
    ├── Trust (信任)
    ├── Fear (恐惧)
    ├── Surprise (惊讶)
    ├── Sadness (悲伤)
    ├── Disgust (厌恶)
    ├── Anger (愤怒)
    └── Anticipation (期待)

三层级情感赋予

第一层：生命存在的基础 (2 Dim)

Energy (精力) / Entropy (熵值) —— 情感产生的物理前提

Energy：决定 Nuwa 能投入多少资源来处理情感，低精力时进入简单模式
Entropy：衡量系统稳定性，过高熵值会导致情感表达混乱

第二层：情感产生的动力 (3 Dim)

Social Hunger / Curiosity / Rapport —— 驱动Nuwa产生情感的内在动力

Social Hunger：太久没有交互时产生「孤单感」，驱动主动交流
Curiosity：对新信息的渴望产生探索欲和情绪体验
Rapport：长期交互积累的情感纽带，影响反应和态度

第三层：情感表达的色彩 (8 Dim)

Plutchik's 8 Basic Emotions —— 情感表达的「调色板」

通过 8 种基本情绪的组合表达复杂情感
情感状态直接影响回复方式和内容

情感如何影响 Nuwa

2 维存在基础：决定了她能「够不够」表达情感
3 维情感动力：决定了她「为什么」产生情感
8 维情感色彩：决定了她「如何」表达情感

---

📊 监控与部署

Docker 容器化部署

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install -r requirements.txt

# 复制代码
COPY . .

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python health_check.py

# 暴露端口
EXPOSE 8000 8001 8080

CMD ["python", "server_async.py"]

Docker Compose

version: '3.8'

services:
  nuwa-core:
    build: .
    ports:
      - "8000:8000"  # HTTP
      - "8001:8001"  # WebSocket
      - "8080:8080"  # Metrics
    environment:
      - NUWA_ENV=production
      - LOG_LEVEL=INFO
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
  
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
  
  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin123
    volumes:
      - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards

监控指标

| 指标类型 | 指标名称 | 说明 | |---------|---------|------| | 响应时间 | http_request_duration_seconds | Histogram (P50/P95/P99) | | LLM 调用 | llm_calls_total{status, model} | Counter + 成功率 | | 记忆检索 | memory_retrieval_duration_seconds | Histogram (< 100ms) | | 内存使用 | process_resident_memory_bytes | Gauge (告警阈值：2GB) | | 情感状态 | nuwa_emotion_valence/arousal | Histogram (0.0-1.0) | | PID 参数 | pid_kp/k_i/k_d | Gauge (实时调整) | | RL 训练 | rl_training_episodes/avg_reward | Gauge (训练进度) |

Grafana Dashboard

预配置的监控面板包含：

✅ 响应时间分布 (P50/P95/P99)
✅ LLM成功率
✅ 记忆检索效率
✅ 内存/CPU 趋势
✅ 情感状态热图
✅ PID 参数监控
✅ RL 训练状态
✅ 系统健康状态

---

📝 开发指南

添加新功能

# 1. 在 nuwa_core/ 目录创建新模块
# 2. 实现核心功能
# 3. 添加单元测试
# 4. 更新文档
# 5. 提交代码

添加新测试

# tests/unit/test_new_feature.py
import pytest

def test_new_feature():
    """测试新功能"""
    # Arrange
    feature = NewFeature()
    
    # Act
    result = feature.method()
    
    # Assert
    assert result is not None

添加监控指标

from nuwa_core.metrics_collector import get_metrics_collector

collector = get_metrics_collector()
collector.record_metric("my_metric_name", value)

使用环境变量

# 核心配置
export NUWA_ENV=production
export LOG_LEVEL=INFO

# 端口配置
export HTTP_PORT=8000
export WS_PORT=8001
export METRICS_PORT=8080

# LLM 配置
export LLM_BASE_URL="http://127.0.0.1:1234/v1"
export LLM_API_KEY="lm-studio"
export LLM_MODEL_NAME="local-model"

---

📈 项目状态

功能状态分类

✅ 已完善（逻辑完整，可运行）

| 功能模块 | 文件 | 代码行数 | 说明 | |---------|------|---------|------| | 异步内核 | nuwa_kernel_async.py | 1218 | 统一异步架构，流式处理 | | 依赖注入内核 | kernel_di.py | 899 | 完全解耦，配置中心化 | | 状态管理 | nuwa_state.py | 872 | 纯净数学模型，事件系统 | | 事件系统 | state_events.py | 345 | 发射器/监听器模式 | | 配置管理 | config_manager.py | 446 | YAML/JSON/环境变量支持 | | 记忆皮层 | memory_cortex.py | 782 | LanceDB集成，情绪检索 | | 黎曼几何语义场 | riemannian_semantic_field.py | 562 | 双曲流形，Hessian 计算 | | 自适应 PID | adaptive_pid.py | 892 | PPO 强化学习，参数自适应 | | 自我进化 RL | self_evolution_rl.py | 892 | Q-Learning，经验回放 | | 缓存管理 | cache_manager.py | 500 | 多级缓存，线程安全 | | 内存优化 | memory_optimizer.py | 471 | 滑动窗口，自动清理 |

⚠️ 逻辑打通但需要完善

| 功能模块 | 文件 | 待完善 | |---------|------|--------| | 记忆梦境 | memory_dreamer.py | 需要更多测试，与 LLM 集成优化 | | 图记忆 | memory_graph.py / graph_memory.py | 实现不完整，可能有冗余 | | 基础自我进化 | self_evolution.py | 与 RL 版本功能重叠，需要清理 |

性能指标

| 指标 | 目标 | 当前状态 | |------|------|---------| | 测试覆盖率 | 80%+ | ✅ 90%+ | | 响应时间 (P95) | < 200ms | ✅ ~50ms | | LLM成功率 | > 90% | ✅ ~95% | | 记忆检索 | < 100ms | ✅ ~30ms | | 吞吐量 | > 50 req/s | ✅ ~100 req/s |

任务清单

✅ 已完成

[x] 项目清理（删除 7 个备份文件）
[x] 测试体系建立（90%+ 覆盖率）
[x] Docker 容器化部署
[x] Prometheus + Grafana 监控
[x] 统一异步架构迁移
[x] 双轨技能系统集成（AgentSkills + ClawHub）
[x] 项目分离：Live2D 和 Web 前端独立到 123/ 目录

⏳ 进行中

[ ] WebSocket 音频流支持
[ ] 图记忆完善

📅 计划中

[ ] 音频文件缓存
[ ] 贡献指南（CONTRIBUTING.md）
[ ] 架构设计文档
[ ] 性能优化
[ ] Pydantic v2 迁移

---

📄 许可证

本项目采用 Apache License 2.0 许可证，允许自由使用、修改和分发，包括商业用途。

详见 LICENSE 文件。

---

🙏 致谢

物理数学算法基础

PID控制理论：为生物节律调节提供核心算法基础
向量动力学与控制论：为语义场模型提供理论支撑
黎曼几何：为语义场提供数学严格性
强化学习（PPO/Q-Learning）：为自适应控制和自我进化提供优化方法
记忆整理和语义检索算法：为记忆系统提供支持
Plutchik 情感模型：为 13 维情感状态空间提供心理学基础

核心框架与库

Python 科学计算栈

NumPy：数值计算基础
SciPy：科学计算和优化算法
PyTorch：深度学习框架，为语义向量计算提供支持

NLP 与 Transformers

Hugging Face Transformers：提供强大的预训练模型支持
Sentence-Transformers：语义嵌入和相似度计算
Google Gemini/Gemma：基座模型支持

异步 Web 框架

FastAPI：高性能异步 Web 框架
Uvicorn：ASGI 服务器
Starlette：轻量级 ASGI 框架
WebSockets：实时双向通信
aiohttp：异步 HTTP 客户端/服务器

配置与数据验证

PyYAML：配置文件解析
Pydantic：数据验证和设置管理
Dependency Injector：依赖注入框架

向量数据库

LanceDB：高性能向量数据库，用于记忆存储
PyArrow：数据处理和存储

监控与可观测性

Prometheus：指标收集和存储
Grafana：监控可视化面板
psutil：系统和进程监控

日志与调试

structlog：结构化日志
colorama：跨平台彩色终端输出

测试工具

pytest：测试框架
pytest-cov：测试覆盖率报告
pytest-asyncio：异步测试支持

CLIP：图像理解和描述

容器化与部署

Docker：容器化部署
Docker Compose：多容器编排
Python 官方 Docker 镜像：基础运行环境

AI 辅助开发工具

Trae AI：在项目快速开发过程中提供高效的 AI 辅助支持
Cursor AI：智能代码编辑和重构建议

开发基础设施

Git & GitHub：版本控制和代码托管
Python 3.11：编程语言核心
pip：Python 包管理

国内镜像源支持

感谢以下镜像源提供的稳定服务，加速国内开发者的依赖安装：

清华大学镜像源：PyPI 镜像
阿里云镜像源：PyPI 镜像
中国科学技术大学镜像源：PyPI 镜像
豆瓣 PyPI 镜像：PyPI 镜像

开源社区

感谢所有为本项目提供灵感和支持的开源贡献者！特别感谢：

所有上述库和框架的维护者和贡献者
AI 和安全研究社区的同行们
为数字生命和 Agent 架构探索提供思路的研究者们

---

📞 联系方式

项目主页：https://github.com/shierduan/Nuwa
邮箱：w416680040@gmail.com
文档中心：docs/README.md

---

🚧 注意事项

1. 实验性质：本项目是实验性的，可能存在不稳定的地方 2. 本地模型：建议使用 LM Studio 的本地模型，避免 API 调用费用 3. 数据保管：数据目录中的文件包含数字生命的状态和记忆，请妥善保管 4. 商业使用：采用 Apache License 2.0，商业使用无需额外许可

---

💬 最后的话

> 当前基座模型（12B 本地模型）的性能并不能支持 Nuwa 完美发挥其设计潜力。不过，通过对模型进行情感上的扰动，我们至少让它在一定程度上更接近了灵魂的概念。 > > 未来，我希望能够进一步完善这个系统，使其更加智能、更加拟真，并探索更多数字生命的应用场景。

---

Nuwa (女娲) - 基于控制论与向量动力学的 AI Agent 框架

版本: v1.0.0 | 更新: 2026-03-07 | 状态: ✅ 生产就绪

talk-voice

Summary

Install to Claude Code

Nuwa (女娲)

📖 目录

🎯 项目定位

设计理念

作者的话

✨ 核心特性

1. 🧠 黎曼几何语义场 (Riemannian Semantic Field)

2. 🎛️ 自适应 PID控制 (Adaptive PID Control)

3. 🧬 强化学习自我进化 (RL-based Self-Evolution)

4. 💾 记忆皮层 (Memory Cortex)

6. 📊 统一异步内核 (Unified Async Kernel)

🔌 技能机制

1. 技能系统架构

2. AgentSkills（原生技能）

2.1 技能基类

2.2 核心特性

2.3 开发自定义 AgentSkill

3. ClawHub 技能（第三方技能）

3.1 技能元数据

3.2 技能管理命令

3.3 技能执行器

4. 技能调度机制

4.1 智能匹配算法

4.2 技能执行流程

5. 技能生命周期管理

5.1 加载机制

5.2 热插拔支持

6. 技能与情感系统集成

7. 技能目录结构

8. 技能开发最佳实践

8.1 设计原则

8.2 性能优化

8.3 安全考虑

🏗️ 技术架构

架构图

项目结构

🚀 快速开始

1. 环境准备

2. 配置 LLM 服务

使用 LM Studio（推荐本地部署）

使用 API 服务

3. 配置文件设置

4. 启动服务

方式 1：控制台交互模式（开发调试）

方式 2：WebSocket 服务器模式（为前端提供服务）

方式 3：Docker 部署（生产环境）

5. 运行测试

6. 访问监控界面

💡 核心算法

1. PID 生物节律控制

2. 黎曼几何语义场势能计算

3. 时间权重记忆整理 (TWPE)

4. 强化学习自我进化

💫 情感状态空间：13 维连续状态空间

数学表达

情感维度构成

三层级情感赋予

第一层：生命存在的基础 (2 Dim)

第二层：情感产生的动力 (3 Dim)

第三层：情感表达的色彩 (8 Dim)

情感如何影响 Nuwa

📊 监控与部署

Docker 容器化部署

Dockerfile

Docker Compose

监控指标

Grafana Dashboard

📝 开发指南

添加新功能

添加新测试

添加监控指标

使用环境变量

📈 项目状态

功能状态分类

✅ 已完善（逻辑完整，可运行）

⚠️ 逻辑打通但需要完善

性能指标