# kh hermes agent

**Repository Path**: longwenbin/kh-hermes-agent

## Basic Information

- **Project Name**: kh hermes agent
- **Description**: 这是一个基于 Hermes（Observe-Think-Act-Reflect）模式的多智能体工程，默认接入智谱大模型（GLM）。


- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-26
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Multi-Agent (Zhipu)

这是一个基于 Hermes（Observe-Think-Act-Reflect）模式的多智能体工程，默认接入智谱大模型（GLM）。

## 系统架构

### 架构总览图

```mermaid
graph LR
    U[用户终端] --> CLI[main.py 命令行入口]
    CLI --> RT[MultiAgentRuntime 运行时编排]

    RT --> MA[主智能体 HermesAgent]
    RT --> SA[子智能体池 HermesAgent]
    RT --> SI[SkillInstaller 技能安装器]
    RT --> ASF[Auto Skill Factory 自动建技]

    MA --> LLM[ZhipuClient 智谱接口]
    SA --> LLM

    MA --> TRM[主工具注册中心 ToolRegistry]
    SA --> TRS[子工具注册中心 ToolRegistry]

    TRM --> OC[OpenClaw 工具集]
    TRS --> OC

    OC --> PLAN[PlanManager 计划管理]
    OC --> VFS[VirtualFileSystem 虚拟文件系统]
    OC --> MEM[LongTermMemoryStore 长期记忆]
    OC --> NET[联网工具 weather_query / web_search]

    RT --> CFG[配置文件 config/agents.yaml]
    RT --> CFG2[配置回退 config/agents.json]
    RT --> SUBCFG[子智能体模板 config/sub_agents.yaml]

    SI --> SKILLS[skills/<skill名>/skill.md]
    ASF --> SKILLS
    VFS --> VFSROOT[vfs/]
    MEM --> MEMFILE[memory/long_term_memory.jsonl]
```

### 请求执行时序图

```mermaid
sequenceDiagram
    participant User as 用户
    participant CLI as main.py
    participant RT as MultiAgentRuntime
    participant MA as 主智能体
    participant TR as ToolRegistry
    participant TOOL as OpenClaw工具
    participant LLM as 智谱模型

    User->>CLI: 输入任务
    CLI->>RT: runtime.run(user_input)
    RT->>MA: 主智能体执行
    MA->>LLM: 发送上下文与工具描述
    LLM-->>MA: 返回JSON决策
    alt 需要调用工具
        MA->>TR: execute(action)
        TR->>TOOL: 执行具体工具
        TOOL-->>MA: 返回观察结果
        MA->>LLM: 继续推理
        LLM-->>MA: 最终回答
    else 可直接回答
        LLM-->>MA: final_answer
    end
    alt 首轮回答显示能力不足
        RT->>RT: 自动创建/启用对应技能
        RT->>MA: 触发二次重试（强制优先调用新工具）
        MA-->>RT: 重试回答
    end
    MA-->>RT: 回复文本
    RT-->>CLI: 输出给用户
```

## 组件职责说明

| 组件 | 作用 | 关键文件 |
| --- | --- | --- |
| CLI 入口 | 初始化配置、启动运行时、处理命令循环 | `main.py` |
| 运行时编排 | 主/子智能体创建、任务委托、并行调用、技能安装、能力缺口自动建技重试 | `hermes/multi_agent.py` |
| 智能体执行器 | Observe-Think-Act-Reflect 循环，解析模型决策并调工具 | `hermes/agent.py` |
| 模型客户端 | 调用智谱 Chat Completions 接口 | `hermes/llm/zhipu_client.py` |
| 工具注册中心 | 工具注册、执行、工具描述渲染 | `hermes/tools/registry.py` |
| OpenClaw 工具集 | 计划/VFS/子智能体/长期记忆/技能安装/天气/网络搜索 | `hermes/tools/openclaw.py` |
| 运行时状态层 | 计划管理、虚拟文件系统、长期记忆存储 | `hermes/runtime_state.py` |
| 技能安装器 | 从本地或 Git 安装技能到 `skills/` | `hermes/skills/installer.py` |

## 关键能力

- 强制多智能体：主智能体启动时必建，子智能体至少保留一个。
- 子智能体支持预置加载与运行时动态创建，并在创建时自动读取 `config/sub_agents.yaml` 的 `defaults/agents` 模板。
- 自动技能安装：基于 `skill_sources` 自动装载技能目录。
- 实时信息补全：天气查询失败时自动安装对应技能并重试。
- 通用能力补齐：当回答显示“当前无能力处理”时，运行时会自动创建 `skills/<skill名>/skill.md`，启用后重试请求。
- 降雨时段分析：`weather_query` 可给出“预计何时下雨、何时停雨”的结构化结论。
- 子智能体联网：子智能体默认可用 `web_search` 做网络搜索。
- 过程实时可见：CLI 会实时输出推理步骤与工具调用进度，不再仅等待最终结果。
- 工具/技能可见：过程日志会明确展示当前调用的工具名，以及加载/启用的技能名和绑定工具。
- 技能名误调纠正：若模型误把技能名当工具名，会自动映射到绑定工具继续执行（例如 `web_research_assistant -> web_search`）。
- 无工具直答收敛：若模型误调用不存在工具，会自动切换为无工具直答模式并强制收敛，避免无限重试。
- 通用容错机制：Agent 会按工具 schema 自动补齐缺失参数，并在同类工具错误重复出现时自动熔断，避免死循环重试。
- 结果统计可见：每次最终回答后会输出本次 Token 用量、模型/工具调用次数与总耗时。
- 收敛保底机制：当同一工具调用过多或接近步数上限时，会强制进入“只收敛不调工具”阶段，降低超步数失败率。
- 会话记忆落盘：每个智能体会将会话记忆写入 `memory/sessions/<agent名>.md`。
- 记忆按需读取：仅当用户请求“结合历史/继续上次”等场景时，才全量读取对应记忆文件。

## 配置文件说明

- `config/agents.yaml`：主运行时配置（主智能体、预置子智能体、技能来源）。
- `config/agents.json`：当解释器缺少 PyYAML 时的 JSON 回退配置。
- `config/sub_agents.yaml`：子智能体模板定义文件（用于动态创建模板管理与后续扩展）。

## 存储目录说明

- `skills/`：技能安装目录，结构为 `skills/<skill名>/skill.md`。
- `vfs/`：虚拟文件系统根目录。
- `memory/long_term_memory.jsonl`：长期记忆持久化文件。
- `memory/sessions/*.md`：各智能体会话记忆 Markdown 文件。
- `memory/change_log.md`：变更动作记录。

## 架构维护规范（每次变更必看）

每次代码变更后，都要执行一次“架构影响检查”：

1. 变更是否新增/删除核心模块或工具。
2. 变更是否改变主流程调用链（入口、运行时、工具、存储）。
3. 变更是否新增配置文件、环境变量、外部依赖或数据目录。
4. 若任一项为“是”，必须同步更新本 README 的以下内容：
   - 架构总览图
   - 请求时序图
   - 组件职责说明
   - 配置与存储说明
5. 在 `memory/change_log.md` 记录“是否影响架构、是否已更新 README 架构说明”。

## 快速开始

1. 安装依赖

```bash
pip install -r requirements.txt
```

2. 配置环境

```bash
cp .env.example .env
# 填写 ZHIPU_API_KEY
```

3. 启动项目

```bash
python3 main.py
```

## CLI 命令

- `/agents`：查看当前子智能体
- `/spawn <name> [role_or_template]`：动态创建子智能体（可选传模板名）