307 lines
8.5 KiB
Markdown
307 lines
8.5 KiB
Markdown
# 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
|
||
|