 zhuyongxin
|
8890cd2806
|
feat(observability): 增强 Agent 和工具调用的可观测日志
## 改动内容
### 1. ChatService - Agent 执行日志
在 `executeChat` 方法中添加：
```
========================================
========== Agent 执行开始 ==========
========================================
📝 用户问题: 支付为什么会失败？
----------------------------------------
🚀 执行 ReactAgent.call() - 自动处理工具调用
========================================
========== Agent 执行完成 ==========
========================================
⏱️ 执行耗时: 1523 ms
📏 最终输出长度: 456 字符
----------------------------------------
📤 最终输出内容:
根据知识库的记录，支付失败的主要原因是...
========================================
```
**关键信息**：
- 用户问题
- 执行耗时
- 最终输出长度和内容
---
### 2. LookupKnowledgeTool - 工具调用详细日志
```
========================================
>>> [工具调用] lookup_knowledge
>>> 参数: query = "支付为什么会失败？"
>>> RequestId: a3b4c5d6
----------------------------------------
[L0 精确匹配] 完成: matches=0, time=3ms
[置信度判断] highConfidence=false, reason=多个或零个匹配
[L1 语义检索] L0非唯一匹配，触发L1语义检索...
[L1 语义检索] 完成: matches=1, time=245ms
[L1 语义检索] 找到文档:
- [1] 文档ID: doc-123, 相似度得分: 0.82
----------------------------------------
<<< [工具返回] lookup_knowledge
<<< 结果: found=true, matchType=semantic_L1, confidence=medium
<<< 总耗时: 248ms (L0=3ms, L1=245ms)
<<< 返回内容长度: 1234 字符
<<< 内容预览: ## 支付网关错误码定义...
========================================
```
**关键信息**：
- 工具名称和参数
- L0/L1 执行时间和结果
- 匹配文档列表
- 返回结果摘要
---
## 日志格式说明
### 符号约定
- `>>>` - 工具调用（入参）
- `<<<` - 工具返回（出参）
- `***` - Agent 思考过程（暂未实现）
- `📝` - 用户输入
- `📤` - Agent 输出
- `⏱️` - 性能指标
### 日志级别
- `INFO` - 关键节点和结果
- `DEBUG` - 详细的中间状态（已设置但默认不显示）
---
## 使用场景
### 1. 调试工具调用
```bash
# 查看工具调用详情
grep "工具调用\|工具返回" logs/application.log
# 输出示例
>>> [工具调用] lookup_knowledge
>>> 参数: query = "ERR_TIMEOUT"
<<< [工具返回] lookup_knowledge
<<< 结果: found=true, matchType=exact_L0, confidence=high
```
### 2. 性能分析
```bash
# 查看执行耗时
grep "执行耗时\|总耗时" logs/application.log
# 输出示例
⏱️ 执行耗时: 1523 ms
<<< 总耗时: 248ms (L0=3ms, L1=245ms)
```
### 3. L0/L1 验证
```bash
# 查看检索路径
grep "L0精确匹配\|L1语义检索" logs/application.log
# 示例 - L0 命中
[L0 精确匹配] 完成: matches=1, time=3ms
[L0 精确匹配] 找到文档:
- [1] 标题: 支付网关错误码定义, 路径: api/payment-errors.md
[L1 语义检索] L0唯一匹配，跳过L1检索
# 示例 - L1 命中
[L0 精确匹配] 完成: matches=0, time=2ms
[L1 语义检索] L0非唯一匹配，触发L1语义检索...
[L1 语义检索] 完成: matches=1, time=245ms
```
---
## 后续优化
### 可能的增强（未实现）
由于阿里云 ReactAgent 不支持内置监听器，以下功能暂时无法实现：
- ❌ Agent 思考过程实时监听（`onStateUpdate`）
- ❌ 工具调用前拦截（`onToolCall`）
- ❌ 工具返回后拦截（`onToolResponse`）
如需这些功能，需要：
1. 包装每个工具，统一添加日志
2. 或使用支持监听器的 Agent 框架
当前实现已满足基本可观测需求。
---
## 验证
```bash
# 1. 启动应用
mvn spring-boot:run
# 2. 发起对话
curl -X POST http://localhost:9900/api/chat \
-H "Content-Type: application/json" \
-d '{"id":"test","question":"支付为什么会失败？"}'
# 3. 查看日志
tail -f logs/application.log | grep -E "Agent|工具|输出"
```
|
2026-06-25 16:16:46 +08:00 |
|
|
zhuyongxin
|
f002571629
|
refactor(ai-ops): 增强 lookup_knowledge 工具描述并调整工具优先级
## 主要改动
1. 增强 lookup_knowledge 工具描述
- 参考 queryLogs 的详细描述格式
- 添加 IMPORTANT 关键词强调优先使用场景
- 详细列举 4 种查询场景及示例：
* 错误码定义（ERR_TIMEOUT）
* 接口文档（payment-gateway）
* 排障步骤（支付超时排查）
* 配置说明（HikariCP）
- 保留性能优势说明（L0 < 10ms, L1 200-500ms）
2. 调整工具数组顺序
- 将 lookupKnowledgeTool 提前到第 2 位（仅次于 dateTimeTools）
- Mock 模式顺序：dateTimeTools → lookupKnowledgeTool → queryMetricsTools → queryLogsTools
- 真实模式顺序：dateTimeTools → lookupKnowledgeTool → queryMetricsTools → internalDocsTools
- 弃用工具（internalDocsTools）放在最后
## 设计目标
解决 Executor 优先选择 queryLogsTools 的问题：
- 工具描述对等：lookup_knowledge 与 queryLogs 同等详细
- 位置优先：知识库查询排在日志查询之前
- 明确引导：IMPORTANT 关键词强调使用时机
## 预期效果
Executor 在遇到错误码、配置项、排障问题时，应优先调用 lookup_knowledge，
而不是直接查询日志。
|
2026-06-25 09:55:02 +08:00 |
|
|
zhuyongxin
|
d6229f3385
|
feat(knowledge): 完成 L0+L1 混合检索集成
核心功能：
- 新增 FrontmatterParser 解析 YAML frontmatter
- 新增 KnowledgeIndexService L0 内存索引
- 新增 LookupKnowledgeTool 混合检索工具
- 增强 DocumentManagementService 文件保存和索引同步
技术实现：
- 数据库迁移 V004: api_document.metadata (TEXT)
- 依赖新增: snakeyaml 2.0
- 配置新增: knowledge.base-path
- 可观测性: requestId 追踪 + 性能日志
质量保证：
- 单元测试: 31/31 通过
- 测试覆盖: FrontmatterParser(11), KnowledgeIndexService(13), LookupKnowledgeTool(7)
- 启动验证: L0 索引正常加载
归档文档：
- OpenSpec: openspec/changes/lookup-knowledge-integration/
- devflow 档案: devflow/projects/2026-06-24-lookup-knowledge-integration/
- handoff: handoff/2026-06-24-lookup-knowledge-integration.md
|
2026-06-24 16:07:10 +08:00 |
|