8.5 KiB
8.5 KiB
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 (可选的覆盖配置)
数据模型变更
-
internal/types/tenant.go- ✅ 添加了
AgentConfig字段
- ✅ 添加了
-
internal/types/knowledgebase.go- ✅ 移除了
AgentConfig字段
- ✅ 移除了
-
internal/application/service/session.go- ✅ 添加了
tenantService依赖 - ✅ 更新了
NewSessionService构造函数 - ✅ 修改了配置优先级逻辑(Session > Tenant)
- ✅ 添加了
-
internal/handler/initialization.go- ✅ 移除了在知识库初始化时更新租户配置的不当逻辑
- ✅ 更新了
GetCurrentConfigByKB从租户读取Agent配置
新增API接口
在 internal/handler/tenant.go 中添加了专门的租户Agent配置管理接口:
-
GET /api/v1/tenants/:id/agent-config- 获取租户的全局Agent配置
- 如果未配置则返回默认值
-
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)
数据库迁移
创建了两个迁移脚本:
- MySQL:
migrations/mysql/007_move_agent_config_to_tenant.sql - 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实现特点
- 事件驱动: 使用回调函数处理各种Agent事件
- SSE流式处理: 实时接收和处理服务器推送事件
- 类型安全: 完整的类型定义和错误处理
- 灵活性: 支持自定义事件处理和错误处理
- 易用性: 提供简单的封装和丰富的示例
终端调试工具特点
- 交互式: 命令行式交互,支持多种命令
- 可视化: 彩色输出,清晰展示各种事件
- 完整性: 显示思考、工具调用、引用、答案、反思等所有信息
- 统计信息: 显示耗时、工具调用次数、引用数量等
- 会话管理: 支持创建、切换、列表会话
架构重构优势
- 简化管理: 租户级别的全局配置,一次设置全局生效
- 一致性: 所有会话默认使用相同的Agent配置
- 灵活性: 会话级别仍可覆盖配置
- 正确的关注点分离:
- 租户配置 → 全局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
测试建议
- 单元测试: 测试Agent配置的读取逻辑
- 集成测试: 测试会话创建和Agent QA流程
- API测试: 测试新的租户Agent配置接口
- 迁移测试: 在测试环境验证数据库迁移
- 终端工具测试: 使用终端工具进行端到端测试
注意事项
⚠️ Breaking Change: 这是一个破坏性变更
- 现有的知识库级别的Agent配置将失效
- 需要运行数据库迁移脚本
- 需要更新使用Agent功能的代码
- 建议在测试环境充分测试后再部署到生产环境
相关文档
贡献者
- 架构设计和实现
- 完整的文档编写
- 测试工具开发
创建时间: 2025-11-03
最后更新: 2025-11-03