| title | Agent-Medici 架构分析方法论 - 避免文档依赖陷阱 |
|---|---|
| type | methodology |
在分析 Agent-Medici 优化方向时，我犯了一系列判断失误。本文档记录正确的架构分析方法论，避免未来重复失误。
错误表现：
- 直接采纳评估文档的 P0 建议（KnowledgeHit 抽象、查询变体生成、DeepWiki 接入）
- 没有先读取 search_knowledge.py 和 SkillIndexer 的实际代码
根本原因：
- 评估文档看起来很详细，有代码片段、优先级表格，让我误以为它已经基于代码分析
- 实际上评估文档是基于对 rag_core.py（self-grow-wiki）的熟悉度推测出来的
正确做法：
- 永远先读代码，再读文档——文档可能过时或基于错误假设
- 评估文档的"详细"不等于"准确"
错误表现：
- 修改 search_knowledge.py 时，完全没有考虑 SkillIndexer 的存在
- 以为 search_knowledge.py 就是唯一的检索入口
根本原因：
- 没有读取 orchestrator/skill_indexer.py 的代码
- 没有意识到 Phase 0 Output Gate 调用 search_knowledge.py，但 SkillIndexer 是独立的语义引擎
正确做法：
- 读代码要读全架构——不能只看一个文件
- 检索系统通常有多个层级（grep → 语义 → RRF）
错误表现：
- 把"查询变体生成"列为 P0
- 把"DeepWiki 接入"列为 P0
根本原因：
- 把 rag_core.py（RAG 助手）的优化思路错误平移到 Agent-Medici（虫群系统）
- 没有分析 Agent-Medici 的实际知识场景（FANUC、Feishu、WSL 都是私有知识）
正确做法：
- 不同场景的优化优先级不同——不能简单平移
- DeepWiki 对开源仓库有用，对私有虫群场景价值接近 0
错误表现：
- 建议从头造 KnowledgeHit 抽象
- 没有发现 SkillIndexer 已有完整 skill schema
根本原因：
- 没有读取 SkillIndexer 的代码
- 没有意识到已有的基础设施可以复用
正确做法：
- 先调研已有代码，再提新方案——避免重复造轮子
- 架构质量信号（如死代码、模型不统一）比功能优化更重要
错误表现：
- 没有发现 metadata 已解析但未用于排序
- 没有发现 --broad 实现离谱（重复读文件）
根本原因：
- 读代码时只关注"功能实现"，没有关注"代码质量"
- 没有逐行分析 search_lessons() 的实现细节
正确做法：
- 读代码要逐行分析——不能只看大致逻辑
- 代码质量信号（如重复读文件）往往比功能缺失更重要
- 先读全架构代码，再读文档
- 识别系统层级和割裂点
- 逐行分析关键函数
- 发现代码质量信号（死代码、重复逻辑等）
- 分析实际场景，不简单平移思路
- 调研已有基础设施，避免重复造轮子
- 识别未利用的信号（已解析但未使用的 metadata）
- 区分方法论问题和具体踩坑
- 根据场景判断 DeepWiki 等外部工具的价值
- 确认 P0 优先级是否基于实际代码
search_knowledge.py (grep 字符串匹配)
↓ (完全不互通)
SkillIndexer (BGE-m3 + ChromaDB 语义检索)
↓
vector_store.py (ChromaDB 封装)
要点： search_knowledge.py 和 SkillIndexer 是割裂的，需要对接。
- lessons/ - 错误日志 + 修复方案（136+ 条）
- reference/ - 完整解决方案文档（9+ 条）
- SkillIndexer - 语义索引（BGE-m3 embedding）
- 在执行特定技能前强制检索知识
- 当前只在 Node 1 的 3 个 skill 里部署
- Node 2/3/4 没有同步
核心原则：
- 先读代码，再读文档
- 读全架构，不只看单个文件
- 区分方法论问题和具体踩坑
- 调研已有基础设施
- 逐行分析，发现代码质量信号
避免的陷阱：
- 过度依赖评估文档
- 错误平移优化思路
- 低估已有基础设施
- 忽略代码质量信号