libagentcore - 一个基于c++的AI多agent系统升级到2.0版本

1. 系统功能与作用

libagentcore是一个基于大语言模型的多Agent协作系统核心库，旨在提供灵活、高效的智能体协作框架。该系统通过多个专门化的Agent协同工作，能够处理复杂的任务，如代码生成、问题求解、数据分析等。

核心功能

多Agent协作：支持多个专门化Agent（Planner、Worker等）协同完成任务
任务规划与执行：自动分解复杂任务，制定执行计划，并协调各Agent执行
JSON任务描述符：通过JSON格式提交任务，支持目标、优先级、Agent配置和元数据
分级任务控制：基于优先级的任务控制（终止/暂停/恢复/回溯），高优先级任务可控制低优先级任务
线程间通信：任务间消息传递与广播，支持消息过滤
影响控制流：新任务提交时同步暂停低优先级任务，新任务执行完成后异步分析影响并决策终止/恢复/重启
SQLite操作日志与回溯：每个任务的操作全程记录到SQLite，支持按日志ID/时间戳/最近成功状态/初始状态回溯
工具调用：支持工具扩展，应用层可通过ChaiScript脚本动态加载和执行外部工具
记忆管理：基于向量数据库的长期记忆存储，支持语义检索
模型推理：集成llama.cpp推理引擎，支持多种量化模型；同时支持OpenAI兼容HTTP API（如智谱GLM、OpenAI GPT等）
多Token预测(MTP)：支持Multi-Token Prediction加速推理
运行时模型切换 ：通过 SystemConfig::use_http_model 在本地模型和网络模型之间切换，无需重新编译
知识库注入：支持为WorkerAgent配置Markdown知识库文件，在思考时作为背景知识注入system上下文
任务自愈循环：任务失败时自动回溯到本轮起点（ROUND_START快照），保留跨轮进度与failure_history学习信号，重新规划换策略重试；优先UndoRegistry撤销，不可逆则快照恢复

应用场景

自动化代码生成与重构
复杂问题求解与决策支持
数据分析与报告生成
智能对话与问答系统
自动化测试用例生成

2. 系统架构

2.1 整体架构

复制代码

┌─────────────────────────────────────────────────────────┐
│                    Application Layer                     │
│                  (GUI / CLI / API)                       │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                   TaskManager                            │
│    (任务调度、状态管理、分级控制、线程间通信、结果收集)     │
└──────────┬──────────────────────┬───────────────────────┘
           │                      │
┌──────────▼──────────┐  ┌───────▼────────────────────────┐
│   AgentManager       │  │   MemoryManager                │
│  (Agent生命周期管理)  │  │  (向量存储、语义检索)           │
└──────────┬──────────┘  └────────────────────────────────┘
           │
    ┌──────┴──────┬──────────────┐
    │             │              │
┌───▼────┐  ┌────▼─────┐  ┌────▼─────┐
│Planner │  │  Worker  │  │  Tool    │
│ Agent  │  │  Agent   │  │ Manager  │
└────────┘  └──────────┘  └──────────┘
    │             │              │
    └─────────────┴──────────────┘
                  │
         ┌────────▼────────┐
         │  ModelManager   │
         │ (llama.cpp推理) │
         └─────────────────┘

┌─────────────────────────────────────────────────────────┐
│                   辅助子系统                              │
├─────────────┬──────────────┬────────────────────────────┤
│ImpactControl│OperationLogger│ InterThreadMessageBus      │
│   Flow      │  (SQLite)    │   (消息总线)                │
├─────────────┼──────────────┼────────────────────────────┤
│Disposition  │  Rollback    │   TaskControl              │
│ Executor    │  Support     │   Command                  │
└─────────────┴──────────────┴────────────────────────────┘

2.2 核心模块

Agent模块 (`includes/agent/`)

AgentManager : 管理所有Agent的生命周期，负责Agent的创建、配置加载和销毁
- get_agent_names() --- 获取所有已加载Agent名称
- get_capabilities() --- 获取Agent能力描述
BaseAgent: Agent基类，定义Agent的基本接口和行为
PlannerAgent: 规划Agent，负责任务分解和执行计划制定
WorkerAgent: 工作Agent，负责具体任务的执行和工具调用
DefaultAgentInterface: Agent统一接口，封装模型调用、影响分析等功能

Task模块 (`includes/task/`)

TaskManager : 任务管理器，负责任务提交、调度、状态跟踪、分级控制和结果收集
- submit_task(descriptor) --- 提交新任务（JSON描述符）
- cancel_task(task_id) --- 取消指定任务
- get_active_task_ids() --- 查询活跃任务ID列表
- get_task_state(task_id) --- 查询任务状态
- get_task_result(task_id) --- 查询任务结果
- get_task_priority_level(task_id) --- 查询任务优先级
- control_task(source, target, cmd) --- 分级控制（终止/暂停/恢复/回溯）
- control_batch(source, max_level, cmd) --- 批量分级控制
- send_message(source, target, type, content) --- 任务间消息发送
- broadcast_message(source, type, content) --- 消息广播
- rollback_task(source, target, point) --- 任务回溯
- get_operation_logs(task_id, type_filter, limit) --- 查询操作日志
- get_metrics() --- 获取任务度量
- get_impact_control_metrics() --- 获取影响控制度量
- create_task_descriptor(goal, priority, agent_config, metadata) --- 创建任务描述符（静态方法）
TaskThread : 任务线程，封装任务执行全生命周期
- 状态流转：PENDING_PLAN → PLANNING → PENDING_VALIDATE → EXECUTING → VALIDATING_RESULT → COMPLETED/FAILED/CANCELLED
- 支持暂停/恢复（pause/resume）
- 支持控制命令队列和消息队列
- 支持任务自愈循环（详见 2.5 节）：失败时回溯到本轮起点（ROUND_START 快照），保留跨轮进度与 failure_history 学习信号，重新规划换策略重试
- rollback_to_round_start(round_id) --- 回溯到指定轮次的起点快照
TaskContext: 任务上下文，封装 user_input、memory_snapshot、子任务结果集合等任务级状态，供各阶段共享与快照恢复
TaskIdGenerator: 任务ID生成器，提供全局唯一任务ID

TaskDescriptor : 任务描述符，JSON格式定义任务

复制代码

{
  "goal": "任务目标描述",
  "priority_level": 0,
  "agent_config": "agent名称",
  "metadata": {}
}

ImpactControlFlow : 影响控制流，两阶段异步化设计
- 阶段一（同步）：新任务提交时暂停所有低优先级任务
- 阶段二（异步）：新任务执行完成后触发影响分析Agent，决策处置方式（终止/恢复/重启）
- 新任务零等待启动，影响分析不阻塞新任务执行
- 支持超时回退和保守策略
DispositionExecutor: 处置执行器，执行影响分析产生的处置决策
OperationLogger : 操作日志器，基于SQLite记录任务全生命周期操作
- 支持按操作类型、日志ID、时间戳查询
- 支持状态快照保存与加载（用于回溯恢复）
- 支持按轮次查询日志（query_round_logs）、轮次起止标记（begin_round/end_round）
- 支持三类快照：ROUND_START（本轮起点）、STEP（步级）、ROLLBACK_TARGET（回溯目标）
- load_round_start_snapshot(round_id) --- 加载指定轮次起点快照，用于自愈回溯
UndoRegistry: 回溯撤销注册表（单例），登记各操作是否可逆及其撤销处理器；回溯时优先调用 undo handler 清理本轮资源，无 handler 或不可逆时回退到快照恢复
InterThreadMessageBus: 线程间消息总线，支持消息ID生成和溢出策略

Model模块 (`includes/model/`)

ModelManager: 模型管理器，负责模型加载、推理接口封装
支持llama.cpp推理引擎，兼容GGUF格式模型
支持OpenAI兼容HTTP API（通过libcurl），可在运行时切换
支持多种量化方案（Q4_K_M、Q4_K_XL等）
支持GPU加速（CUDA）和CPU推理
支持多种工具调用格式：Qwen3.5（peg-native）、Gemma4（peg-gemma4）、MiniCPM5等

Tool模块 (`includes/tool/`)

ToolManager: 工具管理器，负责工具加载、注册和调用
脚本执行器通过回调函数注入，应用层负责集成ChaiScript脚本引擎

Memory模块 (`includes/memory/`)

MemoryManager: 记忆管理器，基于SQLite向量扩展实现
EmbeddingModel: 嵌入模型，用于文本向量化
支持语义检索，根据查询向量返回相关记忆

Core模块 (`includes/core/`)

Config: 系统配置，包括模型路径、Agent配置、工具目录、影响控制参数、自愈回溯参数等
Types: 核心类型定义（TaskState、ControlType、RollbackKind、Disposition、SnapshotKind、FailureKind、RollbackStrategy、FailureHistoryEntry 等）
Error: 错误类型定义

日志系统通过 commons/signal.hpp 的 g_log_signal 信号槽实现，支持多级别日志输出和信号订阅，不在 core 模块内。

Commons模块 (`includes/commons/`)

ThreadPool: 线程池，支持并发任务执行
Signal: 信号槽机制，实现模块间松耦合通信
SQLite-Vector: SQLite向量扩展，支持向量存储和检索
nlohmann::json: JSON处理库

2.3 数据流

复制代码

用户输入 (JSON描述符)
   │
   ▼
TaskManager.submit_task(descriptor)
   │
   ├─► 解析验证TaskDescriptor
   │
   ├─► 存储用户输入记忆(MemoryManager)
   │
   ├─► 创建TaskThread、OperationLogger、AgentInterface
   │
    ├─► 影响控制流-同步段(ImpactControlFlow.run_pause_phase)
    │     └─► 暂停低优先级任务
    │
    ├─► 提交到线程池（零等待启动）
    │
    ▼
    新任务执行完成
    │
    ├─► 影响控制流-异步段(ImpactControlFlow.run_analysis_phase)
    │     ├─► 调用影响分析Agent（含新任务结果摘要）
    │     ├─► 执行处置决策(终止/恢复/重启)
    │     └─► 记录影响控制度量
   │
   ▼
PlannerAgent.plan()
   │
   ├─► 分析任务 → 制定计划(含子任务依赖关系)
   │
   ▼
WorkerAgent.execute() (每个子任务)
   │
   ├─► 调用模型(ModelManager)
   ├─► 调用工具(ToolManager)
   ├─► 存储记忆(MemoryManager)
   ├─► 记录操作日志(OperationLogger)
   ├─► 处理控制命令(暂停/终止/回溯)
   ├─► 处理线程间消息
   │
   ▼
TaskResult
   │
   ▼
返回给用户

2.4 任务状态流转

复制代码

PENDING_PLAN → PLANNING → PENDING_VALIDATE → EXECUTING → VALIDATING_RESULT → COMPLETED
                    ↑           |                  |                |        → FAILED
                    |           |                  |                |
                    └───────────┴──────────────────┴────────────────┘
                                    重规划/重执行
                                               |
                                               ↓
                                       失败 & enable_auto_rollback
                                               |
                                               ↓
                            回溯到本轮起点(ROUND_START 快照)
                                               |
                                               ↓
                            重新规划(携带 failure_history 换策略)
                                               |
                                               ↓
                            达 max_retry_rounds 仍失败 → FAILED
                                               |
                                               ↓
                                           CANCELLED (外部终止)

状态说明：

状态	说明
`PENDING_PLAN`	等待规划
`PLANNING`	正在规划
`PENDING_VALIDATE`	等待计划验证
`EXECUTING`	正在执行子任务
`VALIDATING_RESULT`	正在验证结果
`COMPLETED`	任务完成
`FAILED`	任务失败（自愈重试耗尽或禁用自愈）
`CANCELLED`	任务被取消

2.5 任务自愈循环

任务在执行过程中可能因规划失败、执行异常、结果验证不通过等原因失败。当 enable_auto_rollback = true 时，系统会启动自愈循环：回溯到本轮起点并重新规划，而不是直接判定任务失败。

设计原则

回溯粒度------回到本轮起点：只回退当前轮次（plan→execute→validate 为一轮）的状态，保留跨轮已完成的进度，避免全量重做。
保留学习信号 ：每次失败生成 FailureHistoryEntry（含失败轮次、失败类型、失败步、操作日志摘要、plan 哈希），累积到 failure_history_ 传给 PlannerAgent，使其在重新规划时换用不同策略，避免重复撞墙。
可逆优先，快照兜底 ：回溯时优先调用 UndoRegistry 登记的撤销处理器清理本轮资源（RollbackStrategy::UNDO_PREFER_SNAPSHOT）；当操作不可逆或无 handler 时，回退到 ROUND_START 快照恢复（restore_from_snapshot）。

关键组件

组件	作用
`OperationLogger`	每轮起点保存 `SnapshotKind::ROUND_START` 快照；`load_round_start_snapshot(round_id)` 加载回溯
`UndoRegistry`	单例，登记操作可逆性与撤销处理器；`apply_undo(op_name, payload)` 执行撤销
`TaskThread::rollback_to_round_start`	回溯到指定轮次起点，清理本轮资源并恢复状态
`TaskThread::failure_history_`	跨轮累积的失败历史，传入 PlannerAgent 换策略
`FailureKind`	失败分类（EXCEPTION/PLAN_FAILED/EXECUTION_FAILED/PLAN_STAGNATION/ROLLBACK_CORRUPTED 等），驱动策略选择

自愈流程

复制代码

本轮执行失败
    │
    ├─► build_failure_entry() 生成 FailureHistoryEntry
    │
    ├─► 分类失败(FailureKind)，记录到 failure_history_
    │
    ├─► current_round < max_retry_rounds ?
    │     ├─ 是 → rollback_to_round_start(current_round)
    │     │       ├─► 优先 UndoRegistry.apply_undo() 清理本轮资源
    │     │       └─► 不可逆则 restore_from_snapshot(ROUND_START)
    │     │       → 重新规划(携带 failure_history_ 换策略)
    │     └─ 否 → 判定 FAILED
    │
    └─► plan 停滞(相同 plan_hash 重复) → FailureKind::PLAN_STAGNATION → FAILED

参数	默认值	说明
`enable_auto_rollback`	`true`	启用自愈回溯
`max_retry_rounds`	`3`	最大自愈重试轮数
`rollback_strategy`	`UNDO_PREFER_SNAPSHOT`	回溯策略（优先撤销，快照兜底）
`failure_feedback_step_limit`	`20`	失败反馈操作日志摘要条数上限
`force_snapshot_per_step`	`false`	是否每步强制保存快照（更细粒度但开销更大）

3. 编译说明

3.1 依赖项

必需依赖

CMake >= 3.16
C++17 编译器（MSVC 2019+ / GCC 9+ / Clang 10+）
llama.cpp：大语言模型推理引擎
ONNX Runtime：嵌入模型推理
libcurl：HTTP模型API支持（OpenAI兼容接口）

可选依赖

CUDA >= 11.8：GPU加速支持
wxWidgets >= 3.2：GUI支持（测试程序）
ChaiScript：脚本工具执行（测试程序使用，已内置在third_party中）

3.2 编译步骤

Windows (MSVC)

复制代码

# 1. 配置CMake
cmake -B build -G "Visual Studio 17 2022" -A x64

# 2. 编译静态库
cmake --build build --config Release --target agentcore

# 3. 编译测试程序（可选）
cmake --build build --config Release --target calculator_test

Linux (GCC/Clang)

复制代码

# 1. 配置CMake
cmake -B build -DCMAKE_BUILD_TYPE=Release

# 2. 编译静态库
cmake --build build --target agentcore

# 3. 编译测试程序（可选）
cmake --build build --target calculator_test

3.3 输出产物

编译完成后，将在以下目录生成产物：

静态库 ：libagentcore2/libs/agentcore.lib (Windows) 或 libagentcore2/libs/libagentcore.a (Linux)
calculator测试程序 ：bin/calculator_test.exe (Windows) - wxWidgets GUI + ChaiScript脚本工具 + 任务系统测试

3.4 集成到项目

CMake集成

复制代码

# 添加libagentcore2子目录
add_subdirectory(libagentcore2)

# 链接静态库
target_link_libraries(your_target PRIVATE agentcore)

# 添加包含路径
target_include_directories(your_target PRIVATE
    ${CMAKE_SOURCE_DIR}/libagentcore2/includes
)

直接链接静态库

复制代码

# 添加包含路径
target_include_directories(your_target PRIVATE
    path/to/libagentcore2/includes
)

# 链接静态库
target_link_libraries(your_target PRIVATE
    path/to/libagentcore2/libs/agentcore.lib
    # 其他依赖库...
)

4. 使用示例

4.1 基本使用（本地模型）

复制代码

#include "task/task_manager.h"
#include "core/config.h"
#include <iostream>
#include <chrono>
#include <thread>

using namespace agent;

int main() {
    // 1. 配置系统（默认使用本地模型）
    SystemConfig config;
    config.model_path = "models/Spark-X2.6-4B.Q5_K_M.gguf";
    config.agents_dir = "agents";
    config.tools_dir = "tools";
    config.memory_db_path = "db/memory.db";
    config.thread_count = 4;

    // 2. 初始化TaskManager
    if (!TaskManager::instance().initialize(config)) {
        std::cerr << "初始化失败" << std::endl;
        return -1;
    }

    // 3. 创建任务描述符并提交
    auto descriptor = TaskManager::create_task_descriptor(
        "请帮我写一个Python函数，计算斐波那契数列的第n项", 0);
    std::string task_id = TaskManager::instance().submit_task(descriptor);

    if (task_id.empty()) {
        std::cerr << "任务提交失败" << std::endl;
        return -1;
    }

    std::cout << "任务已提交，ID: " << task_id << std::endl;

    // 4. 等待任务完成
    while (true) {
        auto state = TaskManager::instance().get_task_state(task_id);
        if (state == TaskState::COMPLETED || state == TaskState::FAILED ||
            state == TaskState::CANCELLED) {
            auto result = TaskManager::instance().get_task_result(task_id);
            if (result && result->success) {
                std::cout << "任务完成！结果: " << result->output << std::endl;
            } else {
                std::cout << "任务失败" << std::endl;
            }
            break;
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }

    // 5. 关闭系统
    TaskManager::instance().shutdown();
    return 0;
}

4.2 使用HTTP网络模型

复制代码

#include "task/task_manager.h"
#include "core/config.h"

using namespace agent;

int main() {
    SystemConfig config;
    // 切换为HTTP网络模型（OpenAI兼容API）
    config.use_http_model = true;
    config.api_url   = "https://open.bigmodel.cn/api/paas/v4/chat/completions";
    config.api_key   = "your-api-key";
    config.api_model = "glm-5";

    // 也可使用环境变量：AGENT_API_URL / AGENT_API_KEY / AGENT_API_MODEL

    if (!TaskManager::instance().initialize(config)) {
        return -1;
    }

    auto descriptor = TaskManager::create_task_descriptor("你好", 0);
    std::string task_id = TaskManager::instance().submit_task(descriptor);
    // ...
    TaskManager::instance().shutdown();
    return 0;
}

4.3 使用日志订阅

复制代码

#include "task/task_manager.h"
#include "core/config.h"
#include "commons/signal.hpp"

using namespace agent;

class MyLogHandler : public sigslot::has_slots<> {
public:
    void on_log(const std::string& msg) {
        std::cout << "[LOG] " << msg << std::endl;
    }
};

int main() {
    MyLogHandler handler;
    g_log_signal.connect(&handler, &MyLogHandler::on_log);

    SystemConfig config;
    TaskManager::instance().initialize(config);

    auto descriptor = TaskManager::create_task_descriptor("你的任务", 0);
    std::string task_id = TaskManager::instance().submit_task(descriptor);

    // 日志会自动通过信号槽机制输出

    TaskManager::instance().shutdown();
    g_log_signal.disconnect(&handler);
    return 0;
}

4.4 查询Agent能力

复制代码

#include "agent/agent_manager.h"
#include "task/task_manager.h"

using namespace agent;

int main() {
    SystemConfig config;
    TaskManager::instance().initialize(config);

    // 获取所有Agent名称
    auto agent_names = AgentManager::instance().get_agent_names();
    std::cout << "可用Agent: ";
    for (const auto& name : agent_names) {
        std::cout << name << " ";
    }
    std::cout << std::endl;

    // 获取Agent能力描述
    auto capabilities = AgentManager::instance().get_capabilities();
    for (const auto& [name, desc] : capabilities) {
        std::cout << name << ": " << desc << std::endl;
    }

    TaskManager::instance().shutdown();
    return 0;
}

4.5 分级任务控制

基于优先级的任务控制：高优先级任务可以控制低优先级任务。

复制代码

#include "task/task_manager.h"
#include "core/config.h"

using namespace agent;

int main() {
    SystemConfig config;
    TaskManager::instance().initialize(config);

    // 提交高优先级任务 (level=10)
    auto desc_high = TaskManager::create_task_descriptor("高优先级任务", 10);
    std::string high_id = TaskManager::instance().submit_task(desc_high);

    // 提交低优先级任务 (level=1)
    auto desc_low = TaskManager::create_task_descriptor("低优先级任务", 1);
    std::string low_id = TaskManager::instance().submit_task(desc_low);

    // 高优先级任务暂停低优先级任务
    TaskControlCommand cmd;
    cmd.type = ControlType::PAUSE;
    auto result = TaskManager::instance().control_task(high_id, low_id, cmd);

    // 批量控制：暂停所有优先级 < 5 的任务
    TaskControlCommand batch_cmd;
    batch_cmd.type = ControlType::PAUSE;
    auto affected = TaskManager::instance().control_batch(high_id, 5, batch_cmd);
    std::cout << "受影响任务数: " << affected.size() << std::endl;

    // 终止低优先级任务
    cmd.type = ControlType::TERMINATE;
    TaskManager::instance().control_task(high_id, low_id, cmd);

    TaskManager::instance().shutdown();
    return 0;
}

4.6 任务回溯

通过操作日志支持任务状态回溯恢复：

复制代码

// 回溯到最近一次成功状态
RollbackPoint rp;
rp.kind = RollbackKind::LAST_SUCCESS;
TaskManager::instance().rollback_task(source_id, target_id, rp);

// 回溯到指定日志ID
rp.kind = RollbackKind::BY_LOG_ID;
rp.log_id = 42;
TaskManager::instance().rollback_task(source_id, target_id, rp);

// 回溯到指定时间戳
rp.kind = RollbackKind::BY_TIMESTAMP;
rp.timestamp = std::chrono::system_clock::now() - std::chrono::hours(1);
TaskManager::instance().rollback_task(source_id, target_id, rp);

// 回溯到初始状态
rp.kind = RollbackKind::INITIAL_STATE;
TaskManager::instance().rollback_task(source_id, target_id, rp);

自愈回溯（回到本轮起点）

除上述用户主动回溯外，系统支持自愈回溯 ：任务执行失败时自动回溯到本轮起点（ROUND_START 快照）并重新规划。该机制由 enable_auto_rollback 开关控制（默认开启），通过 TaskThread::rollback_to_round_start(round_id) 内部触发，不走 RollbackKind 枚举。

复制代码

SystemConfig config;
config.enable_auto_rollback = true;          // 启用自愈回溯（默认 true）
config.max_retry_rounds = 3;                 // 最大自愈重试轮数
config.rollback_strategy = RollbackStrategy::UNDO_PREFER_SNAPSHOT; // 优先撤销，快照兜底
config.failure_feedback_step_limit = 20;     // 失败反馈日志摘要条数

// 任务失败时系统自动：
// 1. 生成 FailureHistoryEntry 记录失败信息
// 2. 回溯到本轮 ROUND_START 快照（优先 UndoRegistry 撤销，不可逆则快照恢复）
// 3. 携带 failure_history_ 重新规划（PlannerAgent 换策略）
// 4. 达 max_retry_rounds 仍失败或 plan 停滞 → 判定 FAILED

4.7 线程间消息通信

复制代码

// 发送消息到指定任务
TaskManager::instance().send_message(
    source_task_id, target_task_id, "info", "消息内容");

// 广播消息到所有活跃任务
int count = TaskManager::instance().broadcast_message(
    source_task_id, "notification", "系统通知");

4.8 影响控制

启用影响控制后，新任务提交时同步暂停低优先级任务，新任务执行完成后异步分析影响并执行处置决策：

复制代码

SystemConfig config;
config.enable_impact_control = true;
config.impact_analysis_agent_name = "impact_analyzer";
config.impact_analysis_timeout_ms = 30000;
config.impact_control_total_timeout_ms = 60000;
config.impact_conservative_policy = Disposition::RESTART;

TaskManager::instance().initialize(config);

// 提交高优先级任务时，系统自动：
// 1. 同步暂停所有低优先级任务（零等待）
// 2. 新任务立即进入线程池执行
// 3. 新任务完成后异步触发影响分析Agent
// 4. 异步执行处置决策（终止/恢复/重启）
// 5. 异步记录影响控制度量

// 查询影响控制度量
auto metrics = TaskManager::instance().get_impact_control_metrics();
std::cout << "分析调用次数: " << metrics.impact_analysis_call_count << std::endl;
std::cout << "分析成功次数: " << metrics.impact_analysis_success_count << std::endl;
std::cout << "自动暂停次数: " << metrics.auto_pause_count << std::endl;

4.9 操作日志查询

复制代码

// 查询任务的操作日志
auto logs = TaskManager::instance().get_operation_logs(
    task_id, std::nullopt, 20);  // 最近20条

for (const auto& entry : logs) {
    std::cout << "[" << entry.log_id << "] "
              << operation_type_to_string(entry.operation_type)
              << ": " << entry.params_summary << std::endl;
}

// 按操作类型过滤
auto plan_logs = TaskManager::instance().get_operation_logs(
    task_id, OperationType::AGENT_CALLED, 10);

4.10 GUI应用示例

测试程序提供了一个完整的wxWidgets GUI示例，位于libagentcore2/test/calculator/目录：

复制代码

#include <wx/wx.h>
#include "task/task_manager.h"
#include "commons/signal.hpp"

class MainFrame : public wxFrame, public sigslot::has_slots<> {
public:
    MainFrame() : wxFrame(nullptr, wxID_ANY, "Multi-Agent System") {
        // 创建UI控件...
        // 绑定事件...
        // 订阅日志信号
        g_log_signal.connect(this, &MainFrame::on_log_message);

        // 初始化系统（使用joinable线程，在on_close中join）
        init_thread_ = std::thread([this]() {
            SystemConfig config;
            TaskManager::instance().initialize(config);
        });
    }

    void on_close(wxCloseEvent& event) {
        g_log_signal.disconnect(this);
        if (init_thread_.joinable()) init_thread_.join();
        TaskManager::instance().shutdown();
        Destroy();
    }

private:
    void on_submit(wxCommandEvent& event) {
        wxString text = input_ctrl_->GetValue();
        // 安全的UTF-8转换：先保存wxCharBuffer再取data()
        wxCharBuffer buf = text.ToUTF8();
        std::string input(buf.data());

        auto descriptor = TaskManager::create_task_descriptor(input, 0);
        TaskManager::instance().submit_task(descriptor);
    }

    void on_log_message(const std::string& msg) {
        CallAfter([this, msg]() {
            if (log_ctrl_ && !log_ctrl_->IsBeingDeleted()) {
                log_ctrl_->AppendText(wxString::FromUTF8(msg + "\n"));
            }
        });
    }

    wxTextCtrl* log_ctrl_;
    wxTextCtrl* input_ctrl_;
    std::thread init_thread_;
};

wxIMPLEMENT_APP(MyApp);

5. 配置说明

5.1 系统配置参数

参数	类型	默认值	说明
`model_path`	string	"models/Spark-X2.6-4B.Q5_K_M.gguf"	本地模型文件路径
`agents_dir`	string	"agents"	Agent配置目录
`tools_dir`	string	"tools"	工具脚本目录
`memory_db_path`	string	"db/memory.db"	记忆数据库路径
`embedding_model_dir`	string	"models/bge"	嵌入模型目录
`thread_count`	int	-1	线程数（-1为自动检测）
`max_plan_rounds`	int	5	最大规划轮数
`max_result_rounds`	int	3	最大结果生成轮数
`script_timeout_ms`	int	120000	脚本超时时间（毫秒）
`enable_mtp`	bool	true	启用多Token预测加速
`use_http_model`	bool	false	是否使用HTTP网络模型
`api_url`	string	""	HTTP API地址（空则读环境变量AGENT_API_URL）
`api_key`	string	""	HTTP API密钥
`api_model`	string	""	HTTP API模型名称（空则读环境变量AGENT_API_MODEL）
`n_ctx`	int	4096	模型上下文大小
`http_timeout_seconds`	int	300	HTTP模型超时（秒）
`clear_memory_on_startup`	bool	true	启动时清空记忆
`task_log_db_dir`	string	"db/task_logs"	任务操作日志数据库目录
`max_task_queue_size`	int	100	最大任务队列大小
`max_message_queue_size`	int	1024	最大消息队列大小
`message_queue_overflow_policy`	OverflowPolicy	DROP_OLDEST	消息队列溢出策略
`agent_call_timeout_ms`	uint64_t	0	Agent调用超时（毫秒，0=不超时）
`enable_auto_rollback`	bool	true	启用自愈回溯（失败时回到本轮起点重新规划）
`max_retry_rounds`	int	3	最大自愈重试轮数
`rollback_strategy`	RollbackStrategy	UNDO_PREFER_SNAPSHOT	回溯策略（优先撤销，快照兜底）
`failure_feedback_step_limit`	int	20	失败反馈操作日志摘要条数上限
`force_snapshot_per_step`	bool	false	是否每步强制保存快照
`enable_impact_control`	bool	false	启用影响控制
`impact_analysis_agent_name`	string	""	影响分析Agent名称
`impact_analysis_timeout_ms`	uint32_t	30000	影响分析超时（毫秒）
`impact_control_total_timeout_ms`	uint32_t	60000	影响控制总超时（毫秒）
`impact_log_summary_limit`	int	50	影响日志摘要条数限制
`impact_conservative_policy`	Disposition	RESTART	保守策略处置方式

5.2 Agent配置

Agent配置文件位于agents/目录，每个Agent一个JSON文件：

复制代码

{
  "name": "code_generator",
  "type": "worker",
  "description": "代码生成Agent",
  "system_prompt": "你是一个专业的代码生成助手...",
  "tools": ["python_runner", "code_formatter"],
  "max_tokens": 2048,
  "temperature": 0.7,
  "knowledge_base": ["example.md"]
}

knowledge_base 字段

属性	说明
字段名	`knowledge_base`
类型	字符串数组
可选	是（默认空数组）
含义	引用的知识库 .md 文件名列表（相对于 `knowledge/` 目录）

知识库文件存放于与Agent配置目录平级的 knowledge/ 目录中，例如：

复制代码

resources/
├── agents/
│   └── code_generator.agent
├── knowledge/
│   ├── example.md
│   └── glossary.md

5.3 知识库使用说明

目录规则

知识库目录位于与 agents/ 目录平级的 knowledge/ 目录中
知识库文件必须为 .md 扩展名，UTF-8 编码

配置方法

在 .agent JSON 文件中添加 knowledge_base 数组，列出需要引用的 .md 文件名：

复制代码

{
  "name": "my_agent",
  "instructions": "...",
  "knowledge_base": ["domain_rules.md", "glossary.md"]
}

.md 文件编写建议

使用 Markdown 结构化格式（标题、列表、表格等）
单文件建议不超过 512KB
文件名建议使用小写字母与下划线
UTF-8 编码

路径安全约束

禁止使用绝对路径（如 /etc/passwd 或 C:\file.md）
禁止路径逃逸（如 ../../secret.md）
仅允许 .md 扩展名文件

注入时机

Agent 创建时一次性加载知识库内容
知识库内容注入到 system 消息中，位于 instructions 之后
当知识库内容超过上下文长度（n_ctx）的 80% 时，使用 UTF-8 安全截断（不切断多字节字符边界）并记录告警日志

5.4 工具配置

工具脚本位于tools/目录，calculator测试使用ChaiScript脚本引擎（内置在third_party/chaiscript/中）：

复制代码

// tools/math_helper.chai
fn calculate(x) {
    return x * 2 + 1;
}

fn factorial(n) {
    if (n <= 1) { return 1; }
    return n * factorial(n - 1);
}

内置函数：

log_info(msg) / log_warn(msg) / log_error(msg) / log_debug(msg) / log_fatal(msg) --- 日志输出
json_decode(json_str) --- JSON字符串解码为ChaiScript对象
json_encode(obj) --- ChaiScript对象编码为JSON字符串
is_number(value) --- 判断值是否为数字

6. 性能优化

6.1 GPU加速

确保安装CUDA并正确配置环境变量：

复制代码

export CUDA_HOME=/usr/local/cuda
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

6.2 多Token预测(MTP)

启用MTP可以显著提升推理速度：

复制代码

SystemConfig config;
config.enable_mtp = true;  // 启用MTP加速

6.3 线程池优化

根据CPU核心数调整线程数：

复制代码

config.thread_count = std::thread::hardware_concurrency();

6.4 任务队列清理

任务队列达到或超过 max_task_queue_size 时自动清理已完成/失败/取消的任务，防止内存泄漏。也可手动调用 cleanup_finished_tasks() 清理。

7. 常见问题

Q1: 编译时找不到llama.cpp库

确保llama.cpp已正确编译，并检查路径配置：

复制代码

set(LLAMA_BUILD_DIR "${CMAKE_SOURCE_DIR}/llama.cpp/build_cuda")

Q2: 运行时找不到模型文件

检查模型路径是否正确，模型文件是否存在：

复制代码

config.model_path = "models/Spark-X2.6-4B.Q5_K_M.gguf";

Q3: 内存不足

尝试使用更小的量化模型或减少上下文长度：

复制代码

// 使用Q4_K_M量化模型
config.model_path = "models/Spark-X2.6-4B.Q5_K_M.gguf";
// 减少上下文长度
config.n_ctx = 2048;

Q4: HTTP模型API调用失败

确保API地址、密钥和模型名称配置正确：

复制代码

config.use_http_model = true;
config.api_url   = "https://open.bigmodel.cn/api/paas/v4/chat/completions";
config.api_key   = "your-api-key";
config.api_model = "glm-5";

也可通过环境变量配置：AGENT_API_URL、AGENT_API_KEY、AGENT_API_MODEL

Q5: 如何在本地模型和网络模型之间切换

通过 SystemConfig::use_http_model 在运行时切换，无需重新编译：

复制代码

// 使用本地模型
config.use_http_model = false;
config.model_path = "models/Spark-X2.6-4B.Q5_K_M.gguf";

// 使用网络模型
config.use_http_model = true;
config.api_url = "https://api.openai.com/v1/chat/completions";
config.api_key = "sk-...";
config.api_model = "gpt-4o-mini";

Q6: 影响控制分析超时怎么办

影响分析Agent调用超时时，系统自动回退到保守策略（默认RESTART）：

复制代码

config.impact_analysis_timeout_ms = 30000;     // 分析超时30秒
config.impact_control_total_timeout_ms = 60000; // 总超时60秒
config.impact_conservative_policy = Disposition::RESTART; // 保守策略

8. 许可证

本项目采用MIT许可证，详见LICENSE文件。

9. 贡献指南

欢迎提交Issue和Pull Request。在提交PR前，请确保：

代码风格一致
通过所有测试
添加必要的文档和注释

项目主页

libagentcore: libagentcore是一个基于大语言模型的多Agent协作系统核心库，旨在提供灵活、高效的智能体协作框架。该系统通过多个专门化的Agent协同工作，能够处理复杂的任务，如代码生成、问题求解、数据分析等。

产品案例

阿福老年陪护机器人

libagentcore - 一个基于c++的AI多agent系统升级到2.0版本

1. 系统功能与作用

核心功能

应用场景

2. 系统架构

2.1 整体架构

2.2 核心模块

Agent模块 (includes/agent/)

Task模块 (includes/task/)

Model模块 (includes/model/)

Tool模块 (includes/tool/)

Memory模块 (includes/memory/)

Core模块 (includes/core/)

Commons模块 (includes/commons/)

2.3 数据流

2.4 任务状态流转

2.5 任务自愈循环

设计原则

关键组件

自愈流程

相关配置

3. 编译说明

3.1 依赖项

必需依赖

可选依赖

3.2 编译步骤

Windows (MSVC)

Linux (GCC/Clang)

3.3 输出产物

3.4 集成到项目

CMake集成

直接链接静态库

4. 使用示例

4.1 基本使用（本地模型）

4.2 使用HTTP网络模型

4.3 使用日志订阅

4.4 查询Agent能力

4.5 分级任务控制

4.6 任务回溯

自愈回溯（回到本轮起点）

4.7 线程间消息通信

4.8 影响控制

4.9 操作日志查询

4.10 GUI应用示例

5. 配置说明

5.1 系统配置参数

5.2 Agent配置

knowledge_base 字段

5.3 知识库使用说明

目录规则

配置方法

.md 文件编写建议

路径安全约束

注入时机

5.4 工具配置

6. 性能优化

6.1 GPU加速

6.2 多Token预测(MTP)

6.3 线程池优化

6.4 任务队列清理

7. 常见问题

Q1: 编译时找不到llama.cpp库

Q2: 运行时找不到模型文件

Q3: 内存不足

Q4: HTTP模型API调用失败

Q5: 如何在本地模型和网络模型之间切换

Q6: 影响控制分析超时怎么办

8. 许可证

9. 贡献指南

项目主页

产品案例

Agent模块 (`includes/agent/`)

Task模块 (`includes/task/`)

Model模块 (`includes/model/`)

Tool模块 (`includes/tool/`)

Memory模块 (`includes/memory/`)

Core模块 (`includes/core/`)

Commons模块 (`includes/commons/`)