# openai

**Repository Path**: wx_e4de35b4a7/openai

## Basic Information

- **Project Name**: openai
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Agent Core — 架构逻辑代码框架

基于 [Nous Research Hermes Agent](https://github.com/NousResearch/hermes-agent) 官方文档核心能力提取，构建的一套可实践、可扩展的 **AI 智能体架构代码框架**。

---

## 一、架构概览

```
┌──────────────────────────────────────────────────────┐
│ 用户接入层 (Gateway)                                  │
│ CLI / Telegram / Discord / 微信 / 飞书 ...           │
└──────────┬───────────────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────────────┐
│ 推理核心层 (AIAgent)                                   │
│ Perception → Decision → Execution → Reflection         │
│ 工具编排 | 上下文压缩 | 迭代预算 | 模型路由               │
└──────────┬───────────────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────────────┐
│ 多级记忆层 (Memory) — 5层架构                           │
│ L1 会话记忆 → L2 持久记忆 → L3 技能记忆 → L4 偏好 → L5 元记忆│
│ SQLite + FTS5 | 向量检索 | 压缩快照                       │
└──────────┬───────────────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────────────┐
│ 技能引擎层 (Skill Engine)                              │
│ 内置技能 | 自动生成 | 社区 Skill Hub | 版本管理             │
└──────────┬───────────────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────────────┐
│ 进化闭环层 (Self-Improving Loop)                        │
│ Nudge Engine → 行为记录 → 模式提炼 → 技能生成 → 验证归档    │
└──────────┬───────────────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────────────┐
│ 执行后端层 (Environments)                               │
│ Local / Docker / SSH / Daytona / Modal / Singularity   │
└──────────────────────────────────────────────────────┘
```

---

## 二、核心模块说明

### 1. `config/manager.py` — 配置管理
- 深度合并默认配置与用户自定义 `config.yaml`
- 支持点号路径读写（如 `model.default_model`）
- 自动创建必要目录结构

### 2. `memory/manager.py` — 5层记忆系统
- **L1 会话记忆**: 内存缓存，TTL 过期（默认 30 分钟）
- **L2 持久记忆**: SQLite + FTS5 全文检索，支持跨会话召回
- **L3 技能记忆**: YAML 格式，可复用操作流程
- **L4 偏好记忆**: 用户画像表（沟通风格、工作习惯）
- **L5 元记忆**: 学习策略、反思记录
- **三阶段启动流程**: 用户画像重建 → 上下文预加载 → 技能热启动

### 3. `tools/registry.py` — 工具注册与执行
- **ToolRegistry**: 装饰器注册，导入即注册，支持 Toolset 分组
- **ToolExecutor**: 异步分发，危险命令审批
- **ExecutionBackend**: 抽象后端（Local / Docker / SSH / Modal）
- 内置工具覆盖：terminal、file、web、memory、skill 等

### 4. `skills/manager.py` — 技能系统
- **SKILL.md 格式**: YAML frontmatter + Markdown 正文
- **自动生成流程**: 触发 → 分析器 → 生成器 → 验证器（4层）
- **Slash 命令**: 每个技能自动注册为 `/skillname`
- **使用追踪**: 记录使用次数，热技能优先加载

### 5. `learning/loop.py` — 自进化学习闭环
- **Nudge Engine**: 每 N 次任务触发反思（默认 15 次）
- **TaskTrajectory**: 记录完整任务执行轨迹
- **学习四阶段**: 观察 → 反思 → 提炼 → 巩固
- **自动技能生成**: 从成功轨迹提取模式，生成 SKILL.md

### 6. `core/agent.py` — AIAgent 协调器
- **Session 管理**: 状态机、迭代预算、上下文压缩
- **三阶段记忆启动**: 新会话自动加载相关记忆和技能
- **流式处理**: 支持流式 LLM 输出
- **工具调用循环**: 自动处理多轮工具调用

### 7. `gateway/manager.py` — 消息网关
- **统一消息格式**: GatewayMessage / GatewayResponse
- **平台适配器**: CLI、Webhook（Telegram/Discord 等）
- **会话隔离**: 按 chat_id 隔离会话，支持群聊/线程
- **插件化扩展**: 新增平台只需实现 PlatformAdapter

---

## 三、快速开始

### 环境要求
- Python 3.11+
- `pip install pyyaml`（其他依赖按需安装）

### 运行
```bash
cd hermes-agent-core
python main.py
```

### 配置
编辑 `~/.hermes/config.yaml`：
```yaml
model:
  default_model: "gpt-4-turbo"
  context_window: 65536

memory:
  db_path: "~/.hermes/data/memory.db"

skills:
  auto_create: true

learning:
  nudge_interval_tasks: 15

tools:
  enabled_toolsets: ["terminal", "file", "web", "memory", "skill"]
```

---

## 四、扩展指南

### 添加自定义工具
```python
from hermes_agent_core.tools.registry import ToolRegistry, ToolCategory

registry = ToolRegistry()

@registry.register(
    name="my_tool",
    description="我的自定义工具",
    category=ToolCategory.INFORMATION,
    parameters={"type": "object", "properties": {"input": {"type": "string"}}},
    toolset="custom"
)
async def my_tool(input: str):
    return {"result": f"Processed: {input}"}
```

### 添加新平台适配器
```python
from hermes_agent_core.gateway.manager import PlatformAdapter, Platform

class MyPlatformAdapter(PlatformAdapter):
    def __init__(self, config):
        super().__init__(Platform.WEB, config)

    async def start(self):
        # 启动 WebSocket / HTTP 服务器
        pass

    async def send(self, response):
        # 调用平台 API 发送消息
        pass
```

### 接入真实 LLM
替换 `MockLLMClient` 为 OpenAI / Anthropic 客户端：
```python
import openai

class OpenAIClient:
    async def chat(self, messages, tools=None, stream=False):
        client = openai.AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))
        response = await client.chat.completions.create(
            model="gpt-4-turbo",
            messages=messages,
            tools=tools,
            stream=stream
        )
        return response
```

---

## 五、与官方 Hermes Agent 的对比

| 维度 | 本框架 (Core) | 官方 Hermes Agent |
|------|--------------|-------------------|
| 目的 | 学习架构、二次开发 | 生产级部署 |
| 代码量 | ~2,000 行（精简框架） | 数万行（完整系统） |
| 平台支持 | CLI + 框架接口 | 15+ 平台完整适配 |
| 工具数量 | 5 个示例 | 40+ 内置工具 |
| LLM 支持 | Mock（需自行接入） | 200+ 模型原生支持 |
| 安全 | 基础审批 | 完整沙箱 + 容器隔离 |
| 记忆 | 5层 + SQLite | 5层 + Honcho + LanceDB |

---

## 六、目录结构

```
hermes-agent-core/
├── __init__.py
├── main.py                     # 主入口：组装所有组件
├── config/
│   ├── __init__.py
│   └── manager.py              # 配置管理
├── memory/
│   ├── __init__.py
│   └── manager.py              # 5层记忆系统
├── tools/
│   ├── __init__.py
│   └── registry.py             # 工具注册 + 执行后端
├── skills/
│   ├── __init__.py
│   └── manager.py              # 技能管理 + 自动生成
├── learning/
│   ├── __init__.py
│   └── loop.py                 # 学习闭环 + Nudge Engine
├── core/
│   ├── __init__.py
│   └── agent.py                # AIAgent 协调器
├── gateway/
│   ├── __init__.py
│   └── manager.py              # 消息网关 + 平台适配器
├── env/
│   └── __init__.py             # 执行后端（扩展点）
└── utils/
    └── __init__.py             # 通用工具
```

---

## 七、设计理念

> **"不是工具集成平台，而是会自我进化的 AI 成长伙伴。"**

本框架继承了 Hermes Agent 的核心设计哲学：
1. **闭环学习**: 任务 → 记录 → 反思 → 技能，越用越强
2. **记忆分层**: 从瞬时缓存到长期沉淀，5层记忆各司其职
3. **技能自生长**: 不是手写而是"长出来"，从实践中自动提炼
4. **模型无关**: 标准化接入层，支持任意 OpenAI-compatible API
5. **随处运行**: 从 $5 VPS 到 serverless，轻量可部署

---

**GitHub**: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)  
**文档**: https://hermes-agent.nousresearch.com/docs