智能体架构原理剖析

// 类型擦除: shared_ptr<void> 存储 + if constexpr 编译期检测 IService
using ServiceExtractor = std::function<std::shared_ptr<IService>(const std::shared_ptr<void>&)>;

template<typename Interface>
ServiceExtractor makeExtractor() {
    return [](const std::shared_ptr<void>& p) -> std::shared_ptr<IService> {
        // 编译期判断 Interface* 是否可隐式转换为 IService*
        if constexpr (std::is_convertible_v<Interface*, IService*>) {
            return std::static_pointer_cast<Interface>(p);
        }
        return nullptr;
    };
}

// 容器内部以 shared_ptr<void> 统一存储, 提取时类型擦除还原
QHash<QString, std::shared_ptr<void>> m_instances;
QReadWriteLock m_lock;  // 读写锁保证线程安全

// Agent 循环最大轮次
static constexpr int kMaxAgentIterations = 5;

void startAgentLoop(const QString& userQuery) {
    // 首轮 RAG: 召回知识库 Top3 相关条目
    auto results = KnowledgeBase::instance().search(userQuery, 3);

    // 构建系统提示: 知识上下文 + 已启用技能清单
    QString systemPrompt = buildSystemPrompt(results);

    // 保留上下文轮数
    const int maxRounds = qMax(10, AppConfig::contextRounds());

    continueAgentLoop(0);  // 进入第一轮
}

void continueAgentLoop(int iteration) {
    if (iteration >= kMaxAgentIterations) {
        emit reply("已达到最大推理轮次限制");
        return;
    }
    // 非流式调用 (stream=false), 超时 60s
    m_model->chatWithTools(m_messages, /*timeout=*/60000);
    // QNetworkReply::finished 信号回调 onToolReply
}

void onToolReply(const QJsonArray& toolCalls) {
    if (toolCalls.isEmpty()) {
        emit reply(finalText);  // 无工具调用, 结束
    } else {
        executeToolCalls(toolCalls, iteration);  // 危险操作二次确认
        continueAgentLoop(iteration + 1);  // 下一轮
    }
}

class IService {
public:
    virtual ~IService() = default;

    // 服务名称 (用于日志与诊断)
    virtual QString serviceName() const = 0;

    // 初始化: 加载资源/建立连接/注册子组件
    virtual Result<void> initialize() = 0;

    // 关闭: 释放资源/断开连接/持久化状态
    virtual Result<void> shutdown() = 0;

    // 就绪状态查询
    virtual bool isReady() const = 0;
};

// ServiceLocator.initializeAll() 按注册顺序调用 initialize()
// ServiceLocator.shutdownAll()   逆序调用 shutdown() (后注册先关闭)

template<typename TEntity, typename TKey>
class IRepository {
public:
    virtual Result<TKey> save(const TEntity& entity) = 0;
    virtual Result<TEntity> findById(const TKey& id) const = 0;
    virtual Result<QVector<TEntity>> find(const QueryOptions& opts = {}) = 0;
    virtual Result<void> remove(const TKey& id) = 0;
    virtual Result<int> count() = 0;
    virtual Result<bool> exists(const TKey& id) { /* 默认: findById */ }
};

// QueryOptions: 分页 (limit/offset) + 过滤 + 排序
struct QueryOptions {
    int limit = -1;      // -1 不限制
    int offset = 0;
    QString orderBy;
    QString filter;
};