191 lines
5.3 KiB
Markdown
191 lines
5.3 KiB
Markdown
|
# 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
|