 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
|
f4f0c63325
|
fix(knowledge): 修复 readDocument 文件路径拼接问题
## 问题
L1 语义检索返回文档后，尝试读取文档内容时报错：
```
读取文档失败: api/payment-errors.md
java.nio.file.NoSuchFileException: api\payment-errors.md
```
**原因**：
- `KnowledgeEntry.filePath` 存储的是相对路径（如 `api/payment-errors.md`）
- `readDocument()` 方法直接使用相对路径读取，未拼接 `knowledge_base` 前缀
- 导致找不到文件
## 修复内容
### 1. 添加 knowledge.base-path 配置
```java
@Value("${knowledge.base-path:knowledge_base}")
private String knowledgeBasePath;
```
**默认值**：`knowledge_base`（当前工作目录下）
### 2. 修复 readDocument 方法
```java
public String readDocument(String filePath, int maxChars) {
// 拼接完整路径：knowledge_base + 相对路径
Path fullPath = Paths.get(knowledgeBasePath, filePath);
String content = Files.readString(fullPath);
// ...
}
```
**修复前**：
```
读取: api/payment-errors.md
实际路径: <当前目录>/api/payment-errors.md ❌
```
**修复后**：
```
读取: api/payment-errors.md
实际路径: knowledge_base/api/payment-errors.md ✅
```
## 数据流
```
L1 语义检索
↓
返回 KnowledgeEntry
filePath = "api/payment-errors.md"
↓
readDocument("api/payment-errors.md", 2000)
↓
拼接路径: Paths.get("knowledge_base", "api/payment-errors.md")
↓
完整路径: "knowledge_base/api/payment-errors.md"
↓
Files.readString(fullPath)
↓
返回文档内容 ✅
```
## 配置
在 `application.yml` 中可以自定义路径：
```yaml
knowledge:
base-path: ./knowledge_base # 默认值
```
或者绝对路径：
```yaml
knowledge:
base-path: /data/knowledge_base
```
## 验证
```bash
# 1. 启动应用
mvn spring-boot:run
# 2. 提问触发 L1
你：支付为什么会失败？
# 3. Agent 应该：
# - lookup_knowledge("支付为什么会失败")
# - L0 失败 → L1 语义检索
# - 找到 api/payment-errors.md
# - 读取文件内容成功 ✅
# - 返回文档内容给用户
```
## 相关代码路径
- `KnowledgeIndexService.readDocument()` - 文件读取
- `KnowledgeEntry.filePath` - 存储相对路径
- `LookupKnowledgeTool` - 调用 readDocument
|
2026-06-25 15:56:49 +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 |
|