osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
120 Commits 15 Branches 0 Tags
050cbc8feef6135a44bafc2248c10e37571ba351
Commit Graph
70 Commits
Author SHA1 Message Date
aruo 050cbc8fee feat(agent): add executor evidence v2 contract 2026-07-08 01:37:15 +08:00
zhuyongxin 0ee27eb523 feat(trace): improve session workbench review 2026-07-07 19:06:18 +08:00
zhuyongxin 04eb50e2b4 feat(agent): add executor evidence output contract 2026-07-07 19:02:02 +08:00
aruo b3315ead52 fix(agent): harden live diagnosis skill observability 2026-07-07 00:20:34 +08:00
zhuyongxin ed7efc58b7 feat(rag): close eval pipeline with live snapshots 2026-07-06 21:39:27 +08:00
zhuyongxin cf3333d607 feat(rag): modularize knowledge retrieval pipeline 2026-07-06 17:06:05 +08:00
zhuyongxin a375daead7 fix: clean up aiops mojibake text 2026-07-06 11:38:01 +08:00
aruo 6ccfd33ec5 Add diagnosis playbook skills 2026-07-06 08:35:54 +08:00
aruo ed267d753d feat: add aiops lightweight verifier 2026-07-05 13:44:30 +08:00
aruo 72a3dbf8c5 feat: add aiops payload query augmentation 2026-07-05 12:56:20 +08:00
aruo c7e2fc2ee2 feat: include breadcrumb in embedding text 2026-07-05 12:15:27 +08:00
aruo f2bae0382c fix: align vectorstore live retrieval 2026-07-05 10:53:45 +08:00
aruo 5c71f5fc79 feat: integrate spring ai vectorstore fallback 2026-07-05 10:20:29 +08:00
aruo b9ec07de57 feat: add spring ai retrieval sidecar 2026-07-05 03:22:03 +08:00
aruo 5197712719 feat: add rag evidence postprocess blocks 2026-07-05 03:03:18 +08:00
aruo 4a94c14feb feat: treat l0 retrieval as domain hint 2026-07-05 02:18:40 +08:00
aruo 79feed3314 Merge branch 'emdash/shy-items-fry-f4zze' into refactor/mvp1.0 
# Conflicts:
#	mvp/issues/README.md
 2026-07-05 01:42:42 +08:00
aruo 69deb15330 Add diagnosis eval baseline diff 2026-07-05 00:59:53 +08:00
aruo ca5c61fabf Add diagnosis eval harness 2026-07-04 23:51:43 +08:00
aruo 23ee05c7c3 feat: add traceable scoped AIOps diagnosis 2026-07-04 22:57:28 +08:00
aruo dc6cd32a67 Harden evidence trace semantics 2026-07-04 22:36:30 +08:00
zhuyongxin f01866c1a2 refactor: use sequential agent for chat workflow 2026-07-03 18:03:06 +08:00
zhuyongxin 6919092b83 feat: archive mvp demo trace acceptance 2026-07-03 16:25:00 +08:00
zhuyongxin 5b827fe90e fix: avoid low-confidence supervisor retry by default 2026-07-03 15:32:09 +08:00
zhuyongxin b0f288ae36 use supervisor agent for complex chat 2026-07-03 14:10:55 +08:00
zhuyongxin 1ff7f09d25 fix chat session traces and document paths 2026-07-03 13:53:16 +08:00
zhuyongxin 9050487307 feat: add chat verifier agent 2026-07-03 10:54:33 +08:00
zhuyongxin e438df4355 feat(knowledge): Executor 行动记忆 + 归一化质量等级解决 ISS-002 重复检索 
- RetrievedDocTracker 升级为域级+文档级双层记录（Map<sessionId, Map<domain, Set<filePath>>>）
- LookupKnowledgeTool 新增 Min-Max 归一化层（BGE-M3 L2 距离→[0,1] similarity）
- 三等级 relevanceLevel：PRECISE / HIGHLY_RELEVANT / REFERENCE + completenessHint 兜底信号
- LookupResult 新增 relevanceLevel、completenessHint、retrievedDomainsThisSession
- Executor prompt 重写：4 条检索约束 + 合法出口不查全不追责，重复检索才惩罚
- 入库可观测性：V010 迁移 + retrieval_details JSON 扩展
- 归档 executor-action-memory-relevance change
 2026-07-01 18:24:41 +08:00
zhuyongxin e4f37cb9e6 fix(knowledge): 修复循环依赖 + 归档 session-dedup-knowledge-map + 记录 ISS-002 
- KnowledgeIndexService: 域级生成从 @PostConstruct 移到 @EventListener(ApplicationReadyEvent)，解决 KnowledgeIndexService ↔ KnowledgeDomainService 循环依赖
- devflow 归档: evidence.md + acceptance.md（含运行验证结果）
- devflow/index.md: session-dedup-knowledge-map 状态改为 archived
- openspec .archive-ready 标记
- mvp/issues/ISS-002: Executor 无约束重复调用 lookup_knowledge
 2026-07-01 14:26:59 +08:00
zhuyongxin 354ffc1947 feat(feedback): 补提交 feedback 相关源码（漏提交的新建文件） 2026-07-01 10:57:49 +08:00
zhuyongxin bb44140901 feat(knowledge): 会话级去重 + 知识域地图注入 Planner 解决 ISS-001 重复检索 
- RetrievedDocTracker: sessionId → Set<filePath> 会话级去重，LookupKnowledgeTool Step 5 过滤已检索文档
- KnowledgeDomainService: 域级聚合，LLM 生成 when_to_retrieve，构建 knowledge map YAML
- DocumentFieldEnricher: 上传时 LLM 补全 covers + whenToRetrieve（含同域文档排除上下文）
- KnowledgeDomain entity + V009 迁移: 域级元数据持久化，避免重启重复 LLM 调用
- ChatService: 注入 knowledge map 到 Planner prompt，会话结束时清理去重状态
- KnowledgeIndexService: 手写 JSON 解析替换为 Jackson ObjectMapper，启动时补建缺失域记录
- chat-planner-prompt: 新增知识库检索规则（按域 when_to_retrieve 判断，每域最多一次检索）
- doc-field-enricher-prompt / domain-summary-prompt: 外部化 LLM 提示词
 2026-07-01 10:47:46 +08:00
zhuyongxin 2a796da490 feat(feedback): 置信度评分与用户反馈机制 & 归档 confidence-feedback change 2026-06-30 18:01:06 +08:00
zhuyongxin a3abe3f7a2 refactor(session): 清理代码 & RunnableConfig 传 sessionId 
- AgentLoggingHook 改为从 config.metadata 读取 sessionId（线程安全）
- 移除 AgentLoggingHook 调试用的 metadata 日志
- TokenTrackingChatModel 日志降为 debug
- SessionContextHolder 移除未使用的 setAgentName/getAgentName
- ChatService 清理无用 import
- 修复 stream 路径下 ThreadLocal NPE
 2026-06-26 17:28:30 +08:00
zhuyongxin 0d9cce75f9 feat(session): 会话存储体系实现 & Chat多Agent路由 
- 新增诊断会话(diagnosis_session/agent_step/tool_invocation)三表
- AgentLoggingHook 持久化 agent_step，记录决策链和耗时
- LookupKnowledgeTool 写入 tool_invocation，记录L0/L1检索质量
- TokenTrackingChatModel 捕获真实token用量
- Chat接口支持意图路由：简单问题单Agent，复杂问题多Agent(Planner+Executor)
- Prompt外置到 src/main/resources/prompts/
- 删除旧 diagnosis_record 表及相关文件
- 新增SessionContextHolder(ThreadLocal传递sessionId)
- QuestionComplexity 复杂度判断工具
- 测试覆盖三张新表的Repository
 2026-06-26 16:22:05 +08:00
zhuyongxin a74ccea5be feat(knowledge): breadcrumb分块上下文 & LookupKnowledgeTool日志优化 
- DocumentChunk新增breadcrumb字段，分块时构建完整标题层级路径
- DocumentChunkService splitByHeadings维护标题层级栈算法
- VectorIndexService 将breadcrumb写入Milvus metadata
- LookupKnowledgeTool日志替换为结构化摘要，替代原始MD预览
- L0返回策略：唯一匹配用正文摘要，多匹配+L1有结果仅元数据（不读文件）
- 新增buildCompactSummary / buildMetadataOnlySummary方法
- 安装frontend-design skill
- 创建mvp/文档目录（架构设计+会话存储方案）
- 更新测试适配新逻辑
 2026-06-26 13:56:10 +08:00
zhuyongxin a1876286fd fix(observability): 增强模型文本提取，支持多种方式并输出调试信息 
## 改动内容

### 增强 extractTextContent() 方法

支持 6 种提取方式，依次尝试：

```java
// 方法 1: 反射获取 text 字段
Field textField = message.getClass().getDeclaredField("text");

// 方法 2: 反射获取 content 字段
Field contentField = message.getClass().getDeclaredField("content");

// 方法 3: 调用 getText() 方法
Method getTextMethod = message.getClass().getMethod("getText");

// 方法 4: 调用 getContent() 方法
Method getContentMethod = message.getClass().getMethod("getContent");

// 方法 5: 打印类结构信息（帮助调试）
log.warn("字段列表: ...");
log.warn("方法列表: ...");

// 方法 6: toString() 兜底
return message.toString();
```

---

## 调试信息输出

### 当提取失败时

```
[WARN] 无法提取 AssistantMessage 文本内容，打印类信息:
[WARN] 类名: org.springframework.ai.chat.messages.AssistantMessage
[WARN] 字段列表:
[WARN]   - text: String
[WARN]   - toolCalls: List
[WARN]   - metadata: Map
[WARN] 方法列表:
[WARN]   - getText(): String
[WARN]   - getToolCalls(): List
[WARN]   - getMetadata(): Map
```

**用途**：
- 帮助快速定位正确的字段/方法名
- 不同 Spring AI 版本可能有不同实现
- 一次调试，永久修复

---

### 当提取成功时

```
[DEBUG] 通过 text 字段提取成功
[INFO] *** [Agent 思考] 模型返回文本: 我需要查询知识库...
```

---

## 适配不同 Spring AI 版本

| 版本 | 字段/方法 | 提取方式 |
|------|----------|---------|
| **Spring AI 0.x** | `text` 字段 | 方法 1 ✅ |
| **Spring AI 1.x** | `content` 字段 | 方法 2 ✅ |
| **阿里云版本** | `getText()` 方法 | 方法 3 ✅ |
| **自定义实现** | `getContent()` 方法 | 方法 4 ✅ |
| **未知版本** | 打印类信息 | 方法 5 → 手动适配 |

---

## 错误处理

### 提取失败但不中断

```java
catch (Exception e) {
    log.error("提取 AssistantMessage 文本内容时出错", e);
    return null;
}

// 调用处
String textContent = extractTextContent(lastAssistant);
if (textContent != null && !textContent.isEmpty()) {
    log.info("*** [Agent 思考] 模型返回文本: {}", textContent);
} else {
    // 跳过，不打印
}
```

**不会中断流程**：
- 提取失败 → 返回 null
- null 检查 → 跳过日志输出
- 继续执行后续逻辑

---

## 使用场景

### 场景 1：首次运行，不确定字段名

```bash
# 启动应用
mvn spring-boot:run

# 发起请求
curl -X POST http://localhost:9900/api/chat \
  -d '{"id":"test","question":"测试"}'

# 查看日志
tail -f logs/application.log | grep "模型返回文本\|字段列表\|方法列表"
```

**如果看到**：
```
[WARN] 无法提取 AssistantMessage 文本内容，打印类信息:
[WARN] 方法列表:
[WARN]   - getTextContent(): String  ← 找到了！
```

**修复**：在 `extractTextContent()` 中添加方法 7：
```java
// 方法 7: 尝试 getTextContent()
Method method = message.getClass().getMethod("getTextContent");
Object value = method.invoke(message);
```

---

### 场景 2：提取成功

```
[DEBUG] 通过 text 字段提取成功
[INFO] *** [Agent 思考] 模型返回文本: 我需要查询知识库来了解支付失败的具体原因
```

正常使用，无需调整。

---

## 性能考虑

### 反射开销

- 反射调用比直接调用慢 ~10-100 倍
- 但只在日志输出时使用，不在热路径
- Agent 调用频率低（秒级），性能影响可忽略

### 优化建议（可选）

缓存反射结果：

```java
private static Field cachedTextField = null;

private String extractTextContent(AssistantMessage message) {
    if (cachedTextField == null) {
        cachedTextField = message.getClass().getDeclaredField("text");
        cachedTextField.setAccessible(true);
    }
    return (String) cachedTextField.get(message);
}
```

**当前未实现**，因为：
- 日志场景无性能瓶颈
- 简单实现更易维护
- 如需优化再添加

---

## 提交历史

```
当前 fix(observability): 增强模型文本提取，支持多种方式并输出调试信息
934d8ee feat(observability): 在 Hook 中输出模型返回的文本内容
7c8758d refactor(observability): 简化 ChatService 日志，避免与 Hook 重复
```
 2026-06-25 17:41:37 +08:00
zhuyongxin 934d8eee29 feat(observability): 在 Hook 中输出模型返回的文本内容 
## 改动内容

### 增强 AgentLoggingHook.afterModel()

在模型调用完成后，提取并输出模型返回的文本内容：

```java
@Override
public AgentCommand afterModel(List<Message> messages, RunnableConfig config) {
    // 查找最后一条 AssistantMessage
    AssistantMessage lastAssistant = ...;

    // 提取文本内容
    String textContent = extractTextContent(lastAssistant);
    log.info("*** [Agent 思考] 模型返回文本: {}", textContent);

    // 检查工具调用
    if (hasToolCalls) {
        log.info("*** [Agent 思考] 模型决定调用 N 个工具");
    } else {
        log.info("*** [Agent 思考] 这是最终答案");
    }
}
```

---

### extractTextContent() 实现

通过反射提取 AssistantMessage 的文本内容：

```java
private String extractTextContent(AssistantMessage message) {
    try {
        // 尝试获取 text 或 content 字段
        Field textField = message.getClass().getDeclaredField("text");
        textField.setAccessible(true);
        Object value = textField.get(message);
        return value != null ? value.toString() : null;
    } catch (NoSuchFieldException e) {
        // 尝试 content 字段
        try {
            Field contentField = message.getClass().getDeclaredField("content");
            // ...
        } catch (NoSuchFieldException ex) {
            // 字段不存在，返回 null
        }
    }
}
```

**为什么用反射？**
- Spring AI 的 `AssistantMessage` 没有公开的 `getText()` 或 `getContent()` 方法
- 不同版本可能使用 `text` 或 `content` 字段
- 反射可以兼容不同实现

---

## 日志输出示例

### 第 1 轮：模型决定调用工具

```
========================================
*** [Agent 思考] 第 1 轮思考完成
*** [Agent 思考] 模型返回文本: 我需要查询知识库来了解支付失败的原因
*** [Agent 思考] 模型决定调用 1 个工具:
  - 工具: lookup_knowledge, 参数: {"query":"支付失败原因"}
*** [Agent 思考] 等待工具执行结果...
========================================
```

---

### 第 2 轮：模型返回最终答案

```
========================================
*** [Agent 思考] 第 2 轮思考完成
*** [Agent 思考] 模型返回文本: 根据知识库的记录，支付失败的主要原因包括：
1. ERR_TIMEOUT - 支付网关响应超时，通常是网络问题或第三方服务不稳定
2. ERR_INVALID_SIGNATURE - 签名验证失败，检查密钥配置
3. ERR_INSUFFICIENT_BALANCE - 账户余额不足
... (已截断，总长度: 1234)
*** [Agent 思考] 模型决定不调用工具
*** [Agent 思考] 这是最终答案，准备返回给用户
========================================
```

---

## 关键观测点

| 轮次 | 模型输出内容 | 决策 |
|------|-------------|------|
| **第 1 轮** | 模型的推理过程（通常很短） | 决定调用工具 |
| **第 2 轮** | 模型的最终答案（完整回复） | 不调用工具 |

---

## 内容截断策略

- 长度 ≤ 500：完整输出
- 长度 > 500：截断前 500 字符，显示总长度

```
模型返回文本: 根据知识库的记录，支付失败的主要原因包括...
（前 500 字符）
... (已截断，总长度: 1234)
```

---

## 异常处理

如果反射失败（字段不存在或访问被拒绝）：

```java
catch (Exception e) {
    log.debug("无法提取 AssistantMessage 文本内容: {}", e.getMessage());
    return null;
}
```

日志输出：
```
*** [Agent 思考] 模型返回文本: (无法提取)
```

不会中断程序，只是跳过文本输出。

---

## 完整的思考流程日志

```
📝 用户问题: 支付为什么会失败？

*** [Agent 思考] 第 1 轮思考开始
*** [Agent 思考] 准备调用模型...
*** [Agent 思考] 第 1 轮思考完成
*** [Agent 思考] 模型返回文本: 我需要查询知识库
*** [Agent 思考] 模型决定调用 1 个工具:
  - 工具: lookup_knowledge, 参数: {"query":"支付失败"}

>>> [工具调用] lookup_knowledge
<<< [工具返回] lookup_knowledge
<<< 结果: found=true

*** [Agent 思考] 第 2 轮思考开始
*** [Agent 思考] 准备调用模型...
*** [Agent 思考] 第 2 轮思考完成
*** [Agent 思考] 模型返回文本: 根据知识库的记录，支付失败...
*** [Agent 思考] 模型决定不调用工具
*** [Agent 思考] 这是最终答案，准备返回给用户

⏱️  总耗时: 1523 ms
📏 输出长度: 456 字符
```

---

## 提交历史

```
当前 feat(observability): 在 Hook 中输出模型返回的文本内容
7c8758d refactor(observability): 简化 ChatService 日志，避免与 Hook 重复
b3ea6e2 feat(observability): 添加 Agent 思考过程日志 Hook
```
 2026-06-25 17:27:48 +08:00
zhuyongxin 7c8758d7fa refactor(observability): 简化 ChatService 日志，避免与 Hook 重复 
## 改动内容

### 修改前：重复的日志

```java
// ChatService.executeChat()
logger.info("========== Agent 执行开始 ==========");
logger.info("📝 用户问题: {}", question);
logger.info("🚀 执行 ReactAgent.call() - 自动处理工具调用");

// ... Agent 执行 ...

logger.info("========== Agent 执行完成 ==========");
logger.info("⏱️  执行耗时: {} ms", duration);
logger.info("📤 最终输出内容:");
// 打印完整答案
```

**问题**：
- 与 `AgentLoggingHook` 的日志重复
- 日志过于冗长
- Hook 已经覆盖了 Agent 的思考过程

---

### 修改后：精简的日志

```java
// ChatService.executeChat() - 只保留最外层框架
logger.info("========================================");
logger.info("📝 用户问题: {}", question);

// ... Agent 执行（Hook 负责内部日志）...

logger.info("⏱️  总耗时: {} ms", duration);
logger.info("📏 输出长度: {} 字符", answer.length());
logger.info("========================================");
```

**优势**：
- 职责清晰：ChatService 只记录最外层信息
- 避免重复：思考过程由 Hook 负责
- 更简洁：减少噪音日志

---

## 日志分层

| 层级 | 负责类 | 职责 |
|------|--------|------|
| **外层框架** | `ChatService` | 用户问题、总耗时、输出长度 |
| **思考过程** | `AgentLoggingHook` | 每轮思考、模型决策、消息流转 |
| **工具执行** | `LookupKnowledgeTool` | L0/L1 检索、工具参数/返回 |

---

## 日志输出对比

### 修改前（重复冗长）

```
========================================
========== Agent 执行开始 ==========      ← ChatService
========================================
📝 用户问题: 支付为什么会失败？          ← ChatService
----------------------------------------
🚀 执行 ReactAgent.call()               ← ChatService

*** [Agent 思考] 第 1 轮思考开始         ← Hook
...
*** [Agent 思考] 第 1 轮思考完成         ← Hook

>>> [工具调用] lookup_knowledge         ← Tool
...
<<< [工具返回] lookup_knowledge         ← Tool

*** [Agent 思考] 第 2 轮思考开始         ← Hook
...
*** [Agent 思考] 第 2 轮思考完成         ← Hook

========================================
========== Agent 执行完成 ==========      ← ChatService (重复)
========================================
⏱️  执行耗时: 1523 ms                   ← ChatService
📤 最终输出内容:                         ← ChatService
根据知识库的记录...（完整答案）          ← ChatService (太长)
========================================
```

---

### 修改后（清晰简洁）

```
========================================
📝 用户问题: 支付为什么会失败？          ← ChatService (简洁)

*** [Agent 思考] 第 1 轮思考开始         ← Hook
...
*** [Agent 思考] 第 1 轮思考完成         ← Hook

>>> [工具调用] lookup_knowledge         ← Tool
...
<<< [工具返回] lookup_knowledge         ← Tool

*** [Agent 思考] 第 2 轮思考开始         ← Hook
...
*** [Agent 思考] 第 2 轮思考完成         ← Hook
*** [Agent 思考] 这是最终答案            ← Hook (已说明)

⏱️  总耗时: 1523 ms                     ← ChatService (简洁)
📏 输出长度: 456 字符                    ← ChatService (摘要)
========================================
```

**改进**：
- ✅ 去掉重复的"开始/完成"标记
- ✅ 不再打印完整答案（通过 HTTP 响应已返回）
- ✅ Hook 已说明"这是最终答案"
- ✅ 日志更紧凑，信噪比更高

---

## 设计原则

### 1. 单一职责

- **ChatService**：顶层编排，只记录执行框架
- **Hook**：Agent 内部状态，记录思考过程
- **Tool**：工具执行细节，记录检索过程

### 2. 避免重复

- 不在多处打印相同信息
- Hook 已说明"最终答案"，ChatService 不再重复

### 3. 信息密度

- 关键信息：保留（用户问题、耗时、长度）
- 冗余信息：删除（重复标题、完整答案）

---

## 查看日志

```bash
# 完整日志
tail -f logs/application.log

# 只看框架
tail -f logs/application.log | grep "📝\|⏱️\|📏"

# 只看思考过程
tail -f logs/application.log | grep "Agent 思考"

# 只看工具调用
tail -f logs/application.log | grep "工具调用\|工具返回"
```

---

## 提交历史

```
当前 refactor(observability): 简化 ChatService 日志，避免与 Hook 重复
b3ea6e2 feat(observability): 添加 Agent 思考过程日志 Hook
8890cd2 feat(observability): 增强 Agent 和工具调用的可观测日志
```
 2026-06-25 17:24:59 +08:00
zhuyongxin b3ea6e202d feat(observability): 添加 Agent 思考过程日志 Hook 
## 改动内容

### 1. 创建 AgentLoggingHook

基于 Spring AI Alibaba 的 `MessagesModelHook` 实现：

```java
@HookPositions({HookPosition.BEFORE_MODEL, HookPosition.AFTER_MODEL})
public class AgentLoggingHook extends MessagesModelHook {

    // 在模型调用前
    public AgentCommand beforeModel(List<Message> messages, RunnableConfig config)

    // 在模型调用后
    public AgentCommand afterModel(List<Message> messages, RunnableConfig config)
}
```

---

### 2. 集成到 ReactAgent

在 `ChatService.createReactAgent()` 中添加 Hook：

```java
ReactAgent.builder()
    .name("intelligent_assistant")
    .model(chatModel)
    .hooks(new AgentLoggingHook())  // ✅ 添加日志 Hook
    .build();
```

---

## 日志输出示例

### 完整的 Agent 思考流程

```
========================================
========== Agent 执行开始 ==========
========================================
📝 用户问题: 支付为什么会失败？
----------------------------------------
🚀 执行 ReactAgent.call() - 自动处理工具调用

========================================
*** [Agent 思考] 第 1 轮思考开始
*** [Agent 思考] 当前消息数量: 2
*** [Agent 思考] 最近 2 条消息:
  [1] 角色: User（用户）, 类型: UserMessage
  [2] 角色: User（用户）, 类型: UserMessage
*** [Agent 思考] 准备调用模型...
========================================

========================================
*** [Agent 思考] 第 1 轮思考完成
*** [Agent 思考] 模型输出: <AssistantMessage>
*** [Agent 思考] 模型决定调用 1 个工具:
  - 工具: lookup_knowledge, 参数: {"query":"支付失败原因"}
*** [Agent 思考] 等待工具执行结果...
========================================

========================================
>>> [工具调用] lookup_knowledge
>>> 参数: query = "支付失败原因"
>>> RequestId: a3b4c5d6
----------------------------------------
[L0 精确匹配] 完成: matches=0, time=2ms
[L1 语义检索] L0非唯一匹配，触发L1语义检索...
[L1 语义检索] 完成: matches=1, time=245ms
<<< [工具返回] lookup_knowledge
<<< 结果: found=true, matchType=semantic_L1, confidence=medium
========================================

========================================
*** [Agent 思考] 第 2 轮思考开始
*** [Agent 思考] 当前消息数量: 4
*** [Agent 思考] 最近 3 条消息:
  [1] 角色: User（用户）, 类型: UserMessage
  [2] 角色: Assistant（模型）, 类型: AssistantMessage
  [3] 角色: Tool（工具返回）, 类型: ToolResponseMessage
*** [Agent 思考] 准备调用模型...
========================================

========================================
*** [Agent 思考] 第 2 轮思考完成
*** [Agent 思考] 模型输出: <AssistantMessage>
*** [Agent 思考] 模型决定不调用工具
*** [Agent 思考] 这是最终答案，准备返回给用户
========================================

========================================
========== Agent 执行完成 ==========
========================================
⏱️  执行耗时: 1523 ms
📏 最终输出长度: 456 字符
📤 最终输出内容:
根据知识库的记录，支付失败的主要原因包括...
========================================
```

---

## 核心观测点

| 阶段 | 日志标识 | 信息 |
|------|---------|------|
| **Agent 开始** | `Agent 执行开始` | 用户问题 |
| **思考开始** | `第 N 轮思考开始` | 消息数量、最近消息 |
| **思考完成** | `第 N 轮思考完成` | 模型决策（调用工具 or 返回答案） |
| **工具调用** | `工具调用 lookup_knowledge` | 工具名称、参数 |
| **工具返回** | `工具返回 lookup_knowledge` | 结果摘要、耗时 |
| **Agent 完成** | `Agent 执行完成` | 总耗时、最终输出 |

---

## Hook 机制说明

### MessagesModelHook

- **触发时机**：
  - `BEFORE_MODEL`：模型调用前
  - `AFTER_MODEL`：模型调用后

- **消息流转**：
  ```
  用户问题
      ↓
  [第1轮] beforeModel → 模型决定调用工具 → afterModel
      ↓
  工具执行（lookup_knowledge）
      ↓
  [第2轮] beforeModel → 模型生成最终答案 → afterModel
      ↓
  返回给用户
  ```

- **轮次统计**：
  - 每次调用模型计为一轮
  - 通常需要 2 轮：第 1 轮调用工具，第 2 轮生成答案

---

## 技术细节

### 1. 为什么不用 ModelHook？

`ModelHook` 需要处理 `OverAllState`，更复杂。`MessagesModelHook` 直接操作消息列表，更简单。

### 2. 为什么跳过消息内容？

Spring AI 的 `Message` 接口没有统一的 `getContent()` 方法，不同实现类有不同的访问方式。工具调用的详细内容已在工具层日志体现。

### 3. 消息类型识别

```java
UserMessage          → "User（用户）"
AssistantMessage     → "Assistant（模型）"
ToolResponseMessage  → "Tool（工具返回）"
```

---

## 验证方法

```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

# 4. 过滤关键日志
tail -f logs/application.log | grep -E "Agent|思考|工具|输出"
```

---

## 提交历史

```
当前 feat(observability): 添加 Agent 思考过程日志 Hook
8890cd2 feat(observability): 增强 Agent 和工具调用的可观测日志
f4f0c63 fix(knowledge): 修复 readDocument 文件路径拼接问题
```
 2026-06-25 17:02:13 +08:00
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 f02a1389c8 refactor(knowledge): KnowledgeIndexService 从数据库加载索引 
## 改动内容

### 修改前：从文件系统扫描

```java
@Value("${knowledge.base-path}")
private String knowledgeBasePath;

@Autowired
private FrontmatterParser frontmatterParser;

@PostConstruct
public void loadIndex() {
    // 1. 扫描 knowledge_base 目录
    // 2. 读取每个 .md 文件
    // 3. 解析 frontmatter
    // 4. 构建内存索引
}
```

**问题**：
- 依赖文件系统，无法利用数据库已有数据
- 启动时需要重新扫描和解析所有文件
- 文件和数据库可能不一致

---

### 修改后：从数据库加载

```java
@Autowired
private ApiDocumentRepository apiDocumentRepository;

@PostConstruct
public void loadIndex() {
    // 1. 从数据库读取所有文档
    List<ApiDocument> documents = apiDocumentRepository.findAll();

    // 2. 解析 metadata JSON
    // 3. 构建内存索引
}
```

**优势**：
- ✅ 数据源统一：数据库是唯一真实数据源
- ✅ 启动更快：无需重新扫描文件和解析 frontmatter
- ✅ 数据一致：L0 索引与数据库完全同步
- ✅ 支持动态更新：初始化接口更新数据库后，L0 索引也会更新

---

## 核心方法

### 1. parseDocumentToEntry

从 `ApiDocument` 转换为 `KnowledgeEntry`：

```java
private KnowledgeEntry parseDocumentToEntry(ApiDocument doc) {
    String metadata = doc.getMetadata();

    String title = extractJsonValue(metadata, "title");
    String summary = extractJsonValue(metadata, "summary");
    String category = extractJsonValue(metadata, "category");
    List<String> keywords = extractJsonArray(metadata, "keywords");

    return KnowledgeEntry.builder()
        .filePath(doc.getFilePath())
        .title(title)
        .keywords(keywords)
        .summary(summary)
        .category(category)
        .build();
}
```

### 2. 简单的 JSON 解析

```java
private String extractJsonValue(String json, String key) {
    // 提取 "key":"value" 格式
}

private List<String> extractJsonArray(String json, String key) {
    // 提取 "key":["v1","v2"] 格式
}
```

**注意**：使用简单的字符串解析，避免引入 JSON 库依赖

---

## 数据流

```
应用启动
    ↓
KnowledgeIndexService.loadIndex()
    ↓
apiDocumentRepository.findAll()
    ↓
读取所有 api_document 记录
    ↓
解析每条记录的 metadata JSON
    ↓
构建 KnowledgeEntry
    ↓
加入内存索引（CopyOnWriteArrayList）
    ↓
L0 索引就绪
```

---

## 启动日志

```
[INFO] 开始从数据库加载知识库索引
[INFO] 知识库索引加载完成，共 6 个文档
```

---

## 与初始化接口的配合

### 流程 1：首次启动（数据库为空）

```
1. 应用启动
2. KnowledgeIndexService.loadIndex() → 0 个文档
3. 调用 POST /api/knowledge/init
4. 写入数据库 + 调用 knowledgeIndexService.addToIndex()
5. L0 索引更新为 6 个文档
```

### 流程 2：重启应用（数据库有数据）

```
1. 应用启动
2. KnowledgeIndexService.loadIndex() → 从数据库加载 6 个文档
3. L0 索引已就绪，无需再调用初始化接口
```

---

## 兼容性

### metadata JSON 示例

```json
{
  "title": "支付网关错误码定义",
  "summary": "记录了支付网关所有核心错误码的含义及排查方向",
  "category": "api",
  "keywords": ["ERR_TIMEOUT","超时","支付网关"]
}
```

### 字段映射

| metadata | KnowledgeEntry | 说明 |
|----------|---------------|------|
| title | title | 文档标题 |
| summary | summary | 文档摘要 |
| category | category | 文档分类 |
| keywords | keywords | 关键词列表 |

---

## 删除的代码

- ❌ `@Value("${knowledge.base-path}")`：不再需要文件路径配置
- ❌ `FrontmatterParser` 依赖：不再扫描文件
- ❌ `indexFile()` 方法：不再读取文件
- ❌ `extractCategoryFromPath()` 方法：从 metadata 获取

---

## 验证

```bash
# 1. 清空数据库
# DELETE FROM api_document;

# 2. 启动应用
mvn spring-boot:run

# 3. 查看日志
# [INFO] 知识库索引加载完成，共 0 个文档

# 4. 初始化
curl -X POST http://localhost:9900/api/knowledge/init

# 5. 重启应用
# [INFO] 知识库索引加载完成，共 6 个文档
```
 2026-06-25 15:05:29 +08:00
zhuyongxin 91931363d4 refactor(knowledge): 重构 FaultCategory 枚举为文档分类 
## 改动内容

### 1. 重构 FaultCategory 枚举

**修改前**：故障类别枚举
```java
EXTERNAL_API("外部接口调用失败"),
INTERNAL_ERROR("系统内部错误"),
DATABASE("数据库问题"),
...
```

**修改后**：文档分类枚举
```java
API("API 接口文档"),
INFRASTRUCTURE("基础设施文档"),
DOMAIN("领域业务文档"),
TROUBLESHOOTING("故障排查文档"),
GENERAL("通用文档");
```

### 2. 新增 fromString 映射方法

```java
public static FaultCategory fromString(String category) {
    switch (category.toLowerCase()) {
        case "api": return API;
        case "infrastructure": return INFRASTRUCTURE;
        case "domain": return DOMAIN;
        case "troubleshooting": return TROUBLESHOOTING;
        default: return GENERAL;
    }
}
```

### 3. 更新所有引用

- `ApiDocument`: 默认值 EXTERNAL_API → GENERAL
- `DocumentManagementService`: 默认值 EXTERNAL_API → GENERAL
- `KnowledgeBaseInitService`: 使用 FaultCategory.fromString() 映射

### 4. 字段映射关系

| Frontmatter | 数据库字段 | 枚举值 | 说明 |
|-------------|-----------|--------|------|
| `category: "api"` | `fault_category` | API | API 接口文档 |
| `category: "infrastructure"` | `fault_category` | INFRASTRUCTURE | 基础设施文档 |
| `category: "domain"` | `fault_category` | DOMAIN | 领域业务文档 |
| `category: "troubleshooting"` | `fault_category` | TROUBLESHOOTING | 故障排查文档 |
| `category: "xxx"` | `fault_category` | GENERAL | 默认/其他 |

## 数据库影响

**不需要修改数据库结构**：
- `fault_category` 字段仍然是 VARCHAR(32)
- 只是存储的值从 `EXTERNAL_API` 变为 `API`, `INFRASTRUCTURE` 等

**已存在的数据**：
- 旧数据中的 `EXTERNAL_API` 仍可以正常读取（枚举向后兼容）
- 新导入的文档会使用新的枚举值

## 验证

```bash
# 1. 重新初始化
curl -X POST http://localhost:9900/api/knowledge/init?force=true

# 2. 查询统计
curl http://localhost:9900/api/knowledge/stats

# 3. 响应
{
  "categories": {
    "API": 1,
    "INFRASTRUCTURE": 3,
    "DOMAIN": 1,
    "TROUBLESHOOTING": 1
  }
}
```

## 数据库查询

```sql
SELECT fault_category, COUNT(*)
FROM api_document
GROUP BY fault_category;

-- 结果
API             | 1
INFRASTRUCTURE  | 3
DOMAIN          | 1
TROUBLESHOOTING | 1
```
 2026-06-25 14:23:57 +08:00
zhuyongxin 4e3502a51b fix(knowledge): 将 category 存储到 fault_source 字段 
## 问题

数据库表 api_document 没有独立的 category 字段，导致 frontmatter 的 category 信息无法正确存储。

### 表结构分析

```sql
CREATE TABLE api_document (
    fault_category VARCHAR(32) DEFAULT 'EXTERNAL_API',  -- 固定枚举，不合适存储自定义分类
    fault_source VARCHAR(128),                           -- 可以存储自定义分类
    ...
)
```

## 解决方案

使用 `fault_source` 字段存储 frontmatter 的 category：

```java
// 保存时
document.setFaultSource(category);  // api, infrastructure, domain, troubleshooting

// 统计时
Map<String, Long> categoryCount = apiDocumentRepository.findAll().stream()
    .collect(Collectors.groupingBy(
        doc -> doc.getFaultSource() != null ? doc.getFaultSource() : "general",
        Collectors.counting()
    ));
```

## 字段映射关系

| Frontmatter | 数据库字段 | 示例值 |
|-------------|-----------|--------|
| `title` | `api_name` | "支付网关错误码定义" |
| `category` | `fault_source` | "api" / "infrastructure" |
| `keywords` | `metadata` (JSON) | ["ERR_TIMEOUT","超时"] |
| `summary` | `metadata` (JSON) | "记录了..." |

## 优势

1. **充分利用现有字段**：fault_source (VARCHAR 128) 足够存储分类
2. **避免枚举限制**：不受 FaultCategory 枚举约束
3. **查询方便**：直接通过 fault_source 字段查询和统计
4. **向后兼容**：metadata 中仍保留完整的 frontmatter 信息

## 验证

```bash
# 初始化
curl -X POST http://localhost:9900/api/knowledge/init

# 查询统计
curl http://localhost:9900/api/knowledge/stats

# 响应
{
  "categories": {
    "api": 1,
    "infrastructure": 3,
    "domain": 1,
    "troubleshooting": 1
  }
}
```

## 数据库查询

```sql
-- 按分类统计
SELECT fault_source, COUNT(*)
FROM api_document
GROUP BY fault_source;

-- 结果
api             | 1
infrastructure  | 3
domain          | 1
troubleshooting | 1
```
 2026-06-25 14:08:50 +08:00
zhuyongxin b01f133efb fix(knowledge): 修复状态字段和 indexed_at 时间戳设置 
## 问题

1. **状态字段不正确**：
   - 保存到数据库时直接设置 status="INDEXED"
   - 实际上此时还未索引到 Milvus
   - 应该先设置为 "PENDING"，索引成功后更新为 "INDEXED"

2. **indexed_at 时间戳过早**：
   - 在保存数据库时就设置了 indexed_at
   - 应该在 Milvus 索引成功后才设置

3. **fault_category 字段说明**：
   - fault_category 是枚举类型（EXTERNAL_API, DATABASE, CACHE 等）
   - frontmatter 的 category 是自定义分类（api, infrastructure, domain 等）
   - 两者不匹配，保持 fault_category 默认值
   - 真实的分类信息保存在 metadata JSON 中

## 修复内容

### 1. 状态流转正确

```java
// 保存到数据库时
document.setStatus("PENDING");  // 初始状态

// Milvus 索引成功后
document.setStatus("INDEXED");
document.setChunkCount(chunks.size());
document.setIndexedAt(LocalDateTime.now());  // 此时才设置时间戳

// Milvus 索引失败后
document.setStatus("FAILED");
document.setErrorMessage(e.getMessage());
```

### 2. metadata 结构说明

```json
{
  "title": "支付网关错误码定义",
  "summary": "记录了支付网关所有核心错误码的含义及排查方向",
  "category": "api",  // 自定义分类，不是 fault_category
  "keywords": ["ERR_TIMEOUT","超时","支付网关"]
}
```

### 3. 数据库字段含义

- `fault_category`：固定枚举（EXTERNAL_API, DATABASE 等），保持默认值
- `metadata.category`：frontmatter 自定义分类（api, infrastructure, domain 等）
- `status`：索引状态（PENDING → INDEXED / FAILED）
- `indexed_at`：索引完成时间（索引成功后设置）

## 验证

```bash
# 1. 启动应用（Milvus 可以不启动）
mvn spring-boot:run

# 2. 初始化
curl -X POST http://localhost:9900/api/knowledge/init

# 3. 检查数据库
# - Milvus 未启动：status = "FAILED", indexed_at = NULL
# - Milvus 已启动：status = "INDEXED", indexed_at = 实际时间
# - fault_category：始终为 "EXTERNAL_API"（默认值）
# - metadata：包含真实的 category 信息
```
 2026-06-25 14:04:10 +08:00
zhuyongxin 3ed48e38cd feat(knowledge): 完整实现知识库初始化 - 包含 Milvus 向量索引 
## 核心改动

在上一版本基础上，补充完整的 Milvus (L1) 向量索引功能。

### 新增依赖注入

```java
@Autowired
private DocumentChunkService documentChunkService;

@Autowired
private VectorIndexService vectorIndexService;

@Autowired
private VectorEmbeddingService vectorEmbeddingService;
```

### 完整的数据流

```
knowledge_base/*.md
    ↓ 1. 扫描 & 解析 frontmatter
    ↓ 2. 保存到 MySQL (api_document)
    ↓ 3. 提取正文 & 文档分块
    ↓ 4. 生成向量并索引到 Milvus
    ↓ 5. 加入 L0 内存索引
完成 (L0 + L1 双层索引)
```

### 关键代码

```java
// 1. 提取正文（去除 frontmatter）
String body = extractBody(content);

// 2. 文档分块
List<DocumentChunk> chunks = documentChunkService.chunkDocument(body, relativePath);

// 3. 上传到 Milvus
vectorIndexService.indexDocumentChunks(document.getDocId(), chunks, category);

// 4. 更新状态
document.setStatus("INDEXED");
document.setChunkCount(chunks.size());
```

### 错误处理

- Milvus 索引失败时：
  - 更新文档状态为 FAILED
  - 记录错误信息到 error_message 字段
  - 继续处理下一个文档（不中断整个流程）

### 响应示例

```json
{
  "success": true,
  "scanned": 6,
  "inserted": 6,
  "failed": 0,
  "details": {
    "api/payment-errors.md": "导入成功（L0+L1）"
  }
}
```

### 数据库字段

新增：
- `chunk_count`：分块数量
- `error_message`：错误信息（失败时）

## 验证步骤

```bash
# 1. 启动应用（确保 Milvus 已运行）
mvn spring-boot:run

# 2. 初始化知识库
curl -X POST http://localhost:9900/api/knowledge/init

# 3. 验证结果
# - MySQL: 检查 api_document 表
# - Milvus: 检查 knowledge_base_collection
# - L0: 日志显示"知识库索引加载完成，共 6 个文档"

# 4. 测试 L1 语义检索
# lookup_knowledge("支付为什么会失败")
# 应该返回 semantic_L1 结果
```

## 文档更新

- 更新使用文档，删除"暂未实现 L1"的说明
- 添加 Milvus 数据结构说明
- 添加 Milvus 相关错误处理
 2026-06-25 11:00:10 +08:00
zhuyongxin dec587959c feat(knowledge): 添加知识库批量初始化接口 
## 新增功能

1. **KnowledgeBaseController**
   - POST /api/knowledge/init - 批量初始化知识库
   - GET /api/knowledge/stats - 查询统计信息

2. **KnowledgeBaseInitService**
   - 递归扫描 knowledge_base 目录所有 .md 文件
   - 解析 frontmatter 提取元数据
   - 自动去重（基于文件路径）
   - 数据入库到 api_document 表
   - 自动加入 L0 内存索引

## 核心特性

### 去重机制
- 基于文件相对路径去重
- 支持 force=true 强制重新导入
- 跳过已存在文档，避免重复插入

### 数据存储
- 数据库：保存文档元数据（title、keywords、summary 等）
- L0 索引：加入 KnowledgeIndexService 内存索引
- L1 索引：暂未实现（TODO）

### 错误处理
- 格式无效：frontmatter 解析失败
- 缺少标题：必填字段验证
- 详细的错误信息反馈

## API 示例

```bash
# 首次导入
curl -X POST http://localhost:9900/api/knowledge/init

# 强制重新导入
curl -X POST http://localhost:9900/api/knowledge/init?force=true

# 查询统计
curl http://localhost:9900/api/knowledge/stats
```

## 响应示例

```json
{
  "success": true,
  "scanned": 6,
  "skipped": 0,
  "inserted": 6,
  "failed": 0,
  "details": {
    "api/payment-errors.md": "导入成功（L0）"
  }
}
```

## 后续扩展

- [ ] L1 向量索引（Milvus）集成
- [ ] 文档更新检测（基于文件哈希）
- [ ] 批量删除接口
- [ ] 进度回调支持

## 文档

- 使用文档：.docs/2026-06-25-knowledge-base-init-api.md
 2026-06-25 10:49:30 +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 c88b287f83 refactor(ai-ops): 优化 lookup_knowledge 工具描述和 Executor Prompt 
## 主要改动

1. 优化工具描述（中等版）
   - 保留 L0/L1 两阶段检索机制说明
   - 增加适用场景列举（错误码、接口文档、排障步骤等）
   - 简化为核心信息，减少 token 消耗

2. Executor Prompt 新增详细使用说明
   - 添加 lookup_knowledge 返回结果字段说明
   - 提供 confidence 和 match_type 的使用建议
   - 明确 found=false 的处理方式
   - 结构化组织：工具选择 → 结果处理 → 执行反馈

## 设计思路

- 工具描述：简洁，快速理解核心用途
- Executor Prompt：详细，指导正确使用
- 分层设计：减少重复信息，降低 token 消耗
 2026-06-24 18:48:04 +08:00
zhuyongxin 463d8b817b fix: 恢复 queryInternalDocs 的原始工具描述 
保留原始 @Tool description，仅在 Java 层面标记 @Deprecated。
这样可以保留完整的工具提示词用于后续对比分析。
 2026-06-24 18:41:02 +08:00