Files
Enterprise-Knowledge-Base/SUMMARY.md
T

8.5 KiB
Raw Blame History

Summary of Changes

完成的工作

本次提交完成了两个主要任务:

1. Client包中添加AgentQA支持

为WeKnora的Go client包添加了完整的Agent QA功能支持,包括:

新增文件

  • client/agent.go - Agent QA的核心实现

    • AgentQAStream() - 执行Agent问答并处理SSE流
    • AgentSession - Agent会话封装
    • 支持所有Agent事件类型(thinking, tool_call, tool_result, references, answer, reflection, error)
  • client/agent_example.go - 完整的使用示例

    • 基础Agent问答
    • 工具调用跟踪
    • 知识引用捕获
    • 完整事件跟踪
    • 自定义错误处理
    • 流取消控制
    • 多会话管理

终端调试工具

创建了功能完善的交互式终端调试工具:

  • client/cmd/agent_test/main.go - 主程序(371行)

    • 交互式命令行界面
    • 彩色输出
    • 实时显示所有Agent事件
    • 会话管理(创建、切换、列表)
    • 性能统计
  • 辅助文件:

    • Makefile - 构建和运行脚本
    • run.sh - 快速启动脚本(支持环境变量配置)
    • test_scenarios.sh - 测试场景脚本
    • .env.example - 环境变量示例
    • README.md - 详细使用文档(370行)
    • QUICKSTART.md - 5分钟快速入门指南(294行)

文档更新

  • 更新了 client/README.md,添加了Agent问答的完整文档
    • API使用说明
    • 事件类型表格
    • 代码示例
    • 终端工具说明

2. Agent配置架构重构(租户级别)

将Agent配置从知识库级别重构为租户级别的全局配置。

架构变更

之前的问题:

  • Agent配置在每个知识库中独立配置
  • 配置分散,难以管理
  • 缺乏全局控制

新的架构:

Tenant (全局默认配置)
  ↓
Session (可选的覆盖配置)

数据模型变更

  1. internal/types/tenant.go

    • ✅ 添加了 AgentConfig 字段
  2. internal/types/knowledgebase.go

    • ✅ 移除了 AgentConfig 字段
  3. internal/application/service/session.go

    • ✅ 添加了 tenantService 依赖
    • ✅ 更新了 NewSessionService 构造函数
    • ✅ 修改了配置优先级逻辑(Session > Tenant)
  4. internal/handler/initialization.go

    • ✅ 移除了在知识库初始化时更新租户配置的不当逻辑
    • ✅ 更新了 GetCurrentConfigByKB 从租户读取Agent配置

新增API接口

在 internal/handler/tenant.go 中添加了专门的租户Agent配置管理接口:

  1. GET /api/v1/tenants/:id/agent-config

    • 获取租户的全局Agent配置
    • 如果未配置则返回默认值
  2. PUT /api/v1/tenants/:id/agent-config

    • 更新租户的全局Agent配置
    • 包含完整的参数验证
    • Validation规则:
      • max_iterations: 1-20之间
      • temperature: 0-2之间
      • thinking_model_id: Agent启用时必填
      • allowed_tools: 至少一个工具

路由更新

在 internal/router/router.go 中注册了新的API端点:

tenantRoutes.GET("/:id/agent-config", handler.GetTenantAgentConfig)
tenantRoutes.PUT("/:id/agent-config", handler.UpdateTenantAgentConfig)

数据库迁移

创建了两个迁移脚本:

  1. MySQL: migrations/mysql/007_move_agent_config_to_tenant.sql
  2. ParadeDB: migrations/paradedb/008_move_agent_config_to_tenant.sql

迁移步骤:

  • 在 tenants 表添加 agent_config 列
  • 将现有的 agent_config 从 knowledge_bases 迁移到 tenants
  • 从 knowledge_bases 表删除 agent_config 列

文档

创建了完整的重构文档:

AGENT_CONFIG_TENANT_REFACTORING.md (430行)

  • 问题陈述
  • 解决方案
  • 所有变更的详细说明
  • 数据库迁移指南
  • API变更文档
  • 使用场景示例
  • 测试指南
  • 向后兼容性说明

技术细节

Agent QA Client实现特点

  1. 事件驱动: 使用回调函数处理各种Agent事件
  2. SSE流式处理: 实时接收和处理服务器推送事件
  3. 类型安全: 完整的类型定义和错误处理
  4. 灵活性: 支持自定义事件处理和错误处理
  5. 易用性: 提供简单的封装和丰富的示例

终端调试工具特点

  1. 交互式: 命令行式交互,支持多种命令
  2. 可视化: 彩色输出,清晰展示各种事件
  3. 完整性: 显示思考、工具调用、引用、答案、反思等所有信息
  4. 统计信息: 显示耗时、工具调用次数、引用数量等
  5. 会话管理: 支持创建、切换、列表会话

架构重构优势

  1. 简化管理: 租户级别的全局配置,一次设置全局生效
  2. 一致性: 所有会话默认使用相同的Agent配置
  3. 灵活性: 会话级别仍可覆盖配置
  4. 正确的关注点分离:
    • 租户配置 → 全局Agent策略
    • 会话配置 → 特定场景的覆盖
    • 知识库配置 → 不再包含Agent配置

文件清单

新增文件

client/
├── agent.go                           (139行)
├── agent_example.go                   (293行)
└── cmd/
    └── agent_test/
        ├── main.go                    (371行)
        ├── go.mod                     (7行)
        ├── Makefile                   (76行)
        ├── run.sh                     (173行)
        ├── test_scenarios.sh          (160行)
        ├── .env.example               (17行)
        ├── README.md                  (370行)
        └── QUICKSTART.md              (294行)

migrations/
├── mysql/
│   └── 007_move_agent_config_to_tenant.sql      (32行)
└── paradedb/
    └── 008_move_agent_config_to_tenant.sql      (34行)

# 文档
AGENT_CONFIG_TENANT_REFACTORING.md    (430行)
SUMMARY.md                             (本文件)

修改的文件

client/README.md                       (增加了~100行Agent文档)
internal/types/tenant.go               (添加AgentConfig字段)
internal/types/knowledgebase.go        (移除AgentConfig字段)
internal/application/service/session.go (添加租户服务依赖,更新配置逻辑)
internal/handler/initialization.go     (移除不当逻辑,更新读取逻辑)
internal/handler/tenant.go             (添加2个新的API接口,~150行)
internal/router/router.go              (注册新的API路由)

如何使用

使用Agent QA Client

import "github.com/Tencent/WeKnora/client"

// 创建client
client := client.NewClient("http://localhost:8080")

// 创建Agent会话
agentSession := client.NewAgentSession("session_id")

// 执行问答
err := agentSession.Ask(ctx, "你的问题", func(resp *client.AgentStreamResponse) error {
    switch resp.ResponseType {
    case client.AgentResponseTypeAnswer:
        fmt.Print(resp.Content)
    }
    return nil
})

使用终端调试工具

cd client/cmd/agent_test
./run.sh -k kb_12345

# 或使用make
make build
./agent_test -url http://localhost:8080 -kb kb_12345

管理租户Agent配置

# 获取配置
curl http://localhost:8080/api/v1/tenants/1/agent-config

# 更新配置
curl -X PUT http://localhost:8080/api/v1/tenants/1/agent-config \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "max_iterations": 5,
    "temperature": 0.7,
    "thinking_model_id": "model-123",
    "allowed_tools": ["knowledge_search"]
  }'

数据库迁移

在生产环境部署前,需要执行数据库迁移:

# For MySQL
mysql -u username -p database_name < migrations/mysql/007_move_agent_config_to_tenant.sql

# For PostgreSQL/ParadeDB
psql -U username -d database_name -f migrations/paradedb/008_move_agent_config_to_tenant.sql

测试建议

  1. 单元测试: 测试Agent配置的读取逻辑
  2. 集成测试: 测试会话创建和Agent QA流程
  3. API测试: 测试新的租户Agent配置接口
  4. 迁移测试: 在测试环境验证数据库迁移
  5. 终端工具测试: 使用终端工具进行端到端测试

注意事项

⚠️ Breaking Change: 这是一个破坏性变更

  • 现有的知识库级别的Agent配置将失效
  • 需要运行数据库迁移脚本
  • 需要更新使用Agent功能的代码
  • 建议在测试环境充分测试后再部署到生产环境

相关文档

贡献者

  • 架构设计和实现
  • 完整的文档编写
  • 测试工具开发

创建时间: 2025-11-03
最后更新: 2025-11-03