# libagentcore2

**Repository Path**: akinggw/libagentcore2

## Basic Information

- **Project Name**: libagentcore2
- **Description**: libagentcore2是一个基于大语言模型的多Agent协作系统核心库，旨在提供灵活、高效的智能体协作框架。该系统通过多个专门化的Agent协同工作，能够处理复杂的任务，如代码生成、问题求解、数据分析等。
- **Primary Language**: C++
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# libagentcore2 - 多Agent系统核心库

## 1. 系统功能与作用

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

### 核心功能

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

### 应用场景

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

## 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）
  - 支持控制命令队列和消息队列
- **TaskDescriptor**: 任务描述符，JSON格式定义任务
  ```json
  {
    "goal": "任务目标描述",
    "priority_level": 0,
    "agent_config": "agent名称",
    "metadata": {}
  }
  ```
- **ImpactControlFlow**: 影响控制流，两阶段异步化设计
  - 阶段一（同步）：新任务提交时暂停所有低优先级任务
  - 阶段二（异步）：新任务执行完成后触发影响分析Agent，决策处置方式（终止/恢复/重启）
  - 新任务零等待启动，影响分析不阻塞新任务执行
  - 支持超时回退和保守策略
- **DispositionExecutor**: 处置执行器，执行影响分析产生的处置决策
- **OperationLogger**: 操作日志器，基于SQLite记录任务全生命周期操作
  - 支持按操作类型、日志ID、时间戳查询
  - 支持状态快照保存与加载（用于回溯恢复）
- **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等）
- **Log**: 日志系统，支持多级别日志输出和信号订阅

#### 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
                    |           |                  |                |
                    └───────────┴──────────────────┴────────────────┘
                                    重规划/重执行
                                              |
                                              ↓
                                          CANCELLED (外部终止)
```

**状态说明：**

| 状态 | 说明 |
|------|------|
| `PENDING_PLAN` | 等待规划 |
| `PLANNING` | 正在规划 |
| `PENDING_VALIDATE` | 等待计划验证 |
| `EXECUTING` | 正在执行子任务 |
| `VALIDATING_RESULT` | 正在验证结果 |
| `COMPLETED` | 任务完成 |
| `FAILED` | 任务失败 |
| `CANCELLED` | 任务被取消 |

## 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)

```powershell
# 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)

```bash
# 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集成

```cmake
# 添加libagentcore2子目录
add_subdirectory(libagentcore2)

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

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

#### 直接链接静态库

```cmake
# 添加包含路径
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 基本使用（本地模型）

```cpp
#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/Qwen3.5-4B-UD-Q4_K_XL.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网络模型

```cpp
#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 使用日志订阅

```cpp
#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能力

```cpp
#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 分级任务控制

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

```cpp
#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 任务回溯

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

```cpp
// 回溯到最近一次成功状态
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);
```

### 4.7 线程间消息通信

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

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

### 4.8 影响控制

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

```cpp
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 操作日志查询

```cpp
// 查询任务的操作日志
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/`目录：

```cpp
#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/Qwen3.5-4B-UD-Q4_K_XL.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 | 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文件：

```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 文件名：
```json
{
  "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/`中）：

```javascript
// 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并正确配置环境变量：

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

### 6.2 多Token预测(MTP)

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

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

### 6.3 线程池优化

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

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

### 6.4 任务队列清理

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

## 7. 常见问题

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

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

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

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

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

```cpp
config.model_path = "models/Qwen3.5-4B-UD-Q4_K_XL.gguf";
```

### Q3: 内存不足

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

```cpp
// 使用Q4_K_M量化模型
config.model_path = "models/Qwen3.5-4B-Q4_K_M.gguf";
// 减少上下文长度
config.n_ctx = 2048;
```

### Q4: HTTP模型API调用失败

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

```cpp
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` 在运行时切换，无需重新编译：

```cpp
// 使用本地模型
config.use_http_model = false;
config.model_path = "models/Qwen3.5-4B-UD-Q4_K_XL.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）：

```cpp
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前，请确保：

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