Core Agent

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

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

目录

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

示例格式：

---
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.

单轮使用示例

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)

多轮聊天

直接运行：

python core_agent/chat_cli.py

或者：

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。

当前兼容两套变量名：

# 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