# 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端点: ```go 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 ```go 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 }) ``` ### 使用终端调试工具 ```bash cd client/cmd/agent_test ./run.sh -k kb_12345 # 或使用make make build ./agent_test -url http://localhost:8080 -kb kb_12345 ``` ### 管理租户Agent配置 ```bash # 获取配置 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"] }' ``` ## 数据库迁移 在生产环境部署前,需要执行数据库迁移: ```bash # 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功能的代码 - 建议在测试环境充分测试后再部署到生产环境 ## 相关文档 - [Agent配置重构文档](AGENT_CONFIG_TENANT_REFACTORING.md) - [Client Agent使用文档](client/README.md) - [终端工具快速入门](client/cmd/agent_test/QUICKSTART.md) - [终端工具完整文档](client/cmd/agent_test/README.md) - [Agent示例代码](client/agent_example.go) ## 贡献者 - 架构设计和实现 - 完整的文档编写 - 测试工具开发 --- **创建时间**: 2025-11-03 **最后更新**: 2025-11-03