SonnetDB Copilot AI 架构解析：Agent Orchestrator + Knowledge Base + Skills + MCP Tools

SonnetDB Copilot 是一个深度集成在时序数据库中的 AI 智能体系统。它并非简单的"套壳 ChatGPT"，而是一套完整的 RAG（检索增强生成）+ ReAct（推理行动）架构，包含四大核心组件：

Agent Orchestrator（编排器）

CopilotAgent 是整个 Copilot 的大脑。它接收用户问题后，依次执行：

  1. 对话裁剪：将历史消息按 1200 token 预算裁剪，保留最近的相关上下文
  2. 双路检索：同时从知识库（文档）和技能库（Skills）做向量召回
  3. ReAct 循环：最多 6 轮推理-行动循环，每轮 Planner 决定调什么工具
  4. 最终回答：汇总所有工具结果，生成带引用的自然语言回答
public async IAsyncEnumerable<CopilotChatEvent> RunAsync(
    CopilotAgentContext context,
    IReadOnlyList<AiMessage> messages,
    int? docsK = null,
    int? skillsK = null,
    CancellationToken cancellationToken = default)
{
    // Step 1: 准备对话
    var conversation = PrepareConversation(messages);
    // Step 2: 双路检索
    var docs = await _docsSearchService.SearchAsync(...);
    var skillHits = await _skillSearchService.SearchAsync(...);
    // Step 3: ReAct 循环，每轮执行一个工具
    for (var round = 0; round < MaxReActRounds; round++)
    {
        var plan = await PlanToolsAsync(...);
        if (plan.Count == 0) break;
        var result = await ExecuteToolAsync(...);
    }
    // Step 4: 生成最终回答
    var answer = await GenerateAnswerAsync(...);
}

Knowledge Base（知识库）

知识库存放在 __copilot__.docs 表中，包含文档分块后的段落及其 384 维向量。服务启动时后台自动增量摄入 ./docs、./web/help 等目录中的 Markdown/HTML 文件。

Skills（技能库）

24 个预置技能以 Markdown + YAML frontmatter 格式存放在 copilot/skills/ 目录。每个技能声明自己的名称、描述、触发关键词和所需工具。例如 query-aggregation 技能声明：

---
name: query-aggregation
description: 编写时间窗口聚合查询的最佳实践
triggers:
  - aggregation
  - group by
  - 聚合
requires_tools:
  - query_sql
  - describe_measurement
---

MCP Tools（工具层）

Copilot 定义了 8 个 MCP 工具供 Agent 调用：

工具 用途 读写
list_databases 列出可见数据库 只读
list_measurements 列出 measurement 只读
describe_measurement 查看表结构 只读
sample_rows 采样数据行 只读
query_sql 执行只读 SQL 只读
explain_sql 估算执行计划 只读
draft_sql 草拟 SQL 但不执行 工具本身只读
execute_sql 执行任意 SQL 可写

架构亮点