Files
Enterprise-Knowledge-Base/SUMMARY.md
T

307 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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