# Core Agent

`core_agent/` 是一个从 `hermes-agent` 核心流程里提炼出来的独立 agent 项目，目标不是复制整套平台能力，而是把最关键的几条主线重新组织清楚：

- Agent 主循环
- 内置工具注册与调用
- 任务分发与 skill 导入
- 多轮对话状态
- 流式输出
- 持久记忆
- 长上下文压缩

## 目录

```text
core_agent/
├── agent.py                    # 主循环
├── chat_cli.py                 # 多轮聊天入口
├── compression.py              # 滚动上下文压缩
├── dispatch.py                 # 任务分发器
├── memory.py                   # 持久记忆与记忆块
├── prompts.py                  # system prompt 组装
├── session.py                  # 多轮会话与工具循环
├── skills.py                   # skill 发现与导入
├── demo.py                     # OpenAI-compatible 运行示例
├── providers/
│   ├── base.py                 # Provider 抽象
│   ├── openai_compatible.py    # OpenAI-compatible 适配器
│   └── scripted.py             # 测试/演示 provider
└── tools/
    ├── builtin.py              # 默认内置工具
    └── registry.py             # 工具注册中心
```

## 设计目标

1. 比 `run_agent.py + model_tools.py` 更容易读懂和二次开发。
2. 保留成熟 Agent 的关键能力，而不是只做一个聊天循环。
3. 所有核心能力都能单独替换。

## 对应 Hermes 的映射

- `run_agent.py` -> `core_agent/agent.py`
- `model_tools.py + tools/registry.py` -> `core_agent/tools/registry.py`
- skill 注入逻辑 -> `core_agent/skills.py + core_agent/prompts.py`
- kanban / delegation 的最小核心 -> `core_agent/dispatch.py`

## 当前内置工具

- `current_time`
- `memory_add`
- `memory_list`
- `list_skills`
- `load_skill`
- `dispatch_task`
- `list_tasks`
- `update_task`
- `read_file`
- `execute_shell`
- `run_python`
- `write_file`

## Skill 约定

默认会从以下目录扫描 `SKILL.md`：

- `<workspace>/skills`
- 可在初始化 `CoreAgent` 时传入额外 `skill_dirs`

示例格式：

```md
---
name: code-review
description: Review Python modules for core agent bugs.
---

# Code Review Skill

1. Read the target module first.
2. Check the tool registration path.
3. Verify task dispatch and skill loading are still consistent.
```

## 单轮使用示例

```python
from pathlib import Path

from core_agent.agent import CoreAgent
from core_agent.config import apply_compat_env_aliases, build_core_agent_config, load_core_agent_env
from core_agent.providers.openai_compatible import OpenAICompatibleProvider

load_core_agent_env()
apply_compat_env_aliases()
config = build_core_agent_config()

provider = OpenAICompatibleProvider(
    model=config.model,
    api_key=config.api_key,
    base_url=config.base_url,
)

agent = CoreAgent(
    provider=provider,
    workspace=Path.cwd(),
    skill_dirs=[Path.cwd() / "skills"],
)

result = agent.run("Analyze this repository and create an implementation plan.")
print(result.final_response)
```

## 多轮聊天

直接运行：

```bash
python core_agent/chat_cli.py
```

或者：

```bash
python core_agent/agent.py
```

会话层设计参考了一个更轻量的 agent 实现：

- 长期 history 只保存 `user` / `assistant`
- 当前轮次的 `tool` 消息只参与本轮推理，不写入长期 history
- 每次用户发言时，重新用 `system + 最近 N 轮 history + 当前 user` 构造消息
- provider 负责流式输出，session 负责多轮状态和工具调用闭环

## 记忆与压缩

`core_agent` 现在补了两层长期会话能力：

- 持久记忆：保存在 `<workspace>/.core_agent/memory.json`
- 滚动压缩：当历史过长时，保留最近 tail，对更早的历史做滚动摘要

设计上参考 Hermes 的成熟经验，但保持了轻量实现：

- 记忆块使用单独的 fenced system message 注入，并明确标注“这是 recalled memory，不是新的用户输入”
- 压缩摘要使用 `REFERENCE ONLY` 前缀，避免模型把旧摘要当成当前指令
- head/tail 保护：系统提示和记忆永远保留，最近几轮对话优先保留
- 工具过程仍然不进入长期 `history`

## ENV 配置

`core_agent` 会优先读取 [core_agent/.env](/D:/github_project/hermes-agent/core_agent/.env)。

当前兼容两套变量名：

```env
# Myagent 风格
API_KEY=...
BASE_URL=http://host:port/v1
MODEL_NAME=Qwen3.6-35B

# 也兼容 OpenAI 风格
OPENAI_API_KEY=...
OPENAI_BASE_URL=http://host:port/v1
CORE_AGENT_MODEL=Qwen3.6-35B
CORE_AGENT_TIMEOUT=120
```

优先级：

- `CORE_AGENT_MODEL` > `MODEL_NAME` > `OPENAI_MODEL` > `MODEL`
- `OPENAI_API_KEY` > `API_KEY`
- `OPENAI_BASE_URL` > `BASE_URL`

## 为什么这是“比较完善”的核心

它不是单纯的 `LLM + tools` 包装，而是已经把一个工程化 agent 的骨架补齐了：

- 有工具注册中心，而不是硬编码 if/else
- 有 task board，而不是只在 prompt 里“假装规划”
- 有 skill store，而不是把技能写死在 system prompt
- 有 provider 抽象，可切 OpenAI-compatible 或测试脚本 provider
- 有 workspace 约束，避免工具随意越权写文件

## 下一步可扩展点

- 加 memory store
- 加更强的 task graph 调度策略
- 加工具权限/审批层
- 加 skill 依赖文件加载
- 加多 agent worker / delegation