xiaoxue_admin
/
xiaowei-system
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
xiaowei-system/skills/software-development/cbm-code-analysis/SKILL.md

5.3 KiB
Raw Permalink Blame History

name version date description domain trigger
cbm-code-analysis 1.1.0 2026-07-30 代码分析自动调用 CBM（codebase-memory-mcp）知识图谱。 当需要理解代码结构、查找函数定义、分析调用链、追踪代码变更时自动调用 CBM 工具。 替代传统 grep/文件浏览，用图查询一次获取完整上下文。 software-development 分析代码 | 查找函数 | 调用链 | 代码结构 | 重构 | 影响分析 | 索引项目

CBM 代码分析

触发场景

你说的话（关键词） 动作
"这个项目什么结构" / "项目架构" get_architecture
"XXX 函数在哪" / "找 XXX" search_graph + get_code_snippet
"谁调用了 XXX" / "XXX 被谁调用" trace_path
"这段代码的影响范围" / "改了这个会怎么样" detect_changes + trace_path
"索引这个项目" / "建图" index_repository
"项目里有哪些模块" / "代码概览" get_graph_schema + get_architecture
"查一下这个符号" / "搜索代码" search_code / search_graph

工作流

1. 项目检查

# 先查项目列表
list_projects → 确认项目名

# 如果不在列表里，先索引
index_repository(repo_path="/path/to/project")

2. 代码分析

# 按需要选一个或多个：

# 架构概览
get_architecture(project="project-name")

# 搜索函数/类
search_graph(project="project-name", name_pattern=".*Handler.*", label="Function")

# 追踪调用
trace_path(project="project-name", function_name="ProcessOrder", direction="both")

# 获取源码
get_code_snippet(project="project-name", qualified_name="pkg/handler.OrderHandler")

# 变更影响
detect_changes(project="project-name")

3. 结果整合

  • CBM 返回结构化 JSON
  • 组织成清晰的中文回答
  • 关键节点标注文件和行号

效率技巧

  • 先 get_graph_schema — 了解图结构再查
  • search_graph 用正则 — name_pattern=".*Handler"
  • trace_path 限深度 — depth=3 够用就别 5
  • 项目名用 list_projects 确认 — CBM 自动从路径生成
  • qualified_name 格式 — <project>.<path_with_dots>.<FunctionName>，如 tmp-memoryweave.go.internal.storage.NewRecallPipeline。必须用 search_graph 返回的精确值，不要手拼
  • search_graph 字段比 trace_path 丰富 — 直接返回 in_degree(调用者数)、out_degree(被调用数)、signature、return_type、param_count、is_exported、complexity。先看这些再做 trace_path
  • trace_path 方向明确 — inbound=谁调用我，outbound=我调用谁
  • 先 read_file 再 get_code_snippet — 知道文件路径时 read_file 更直接；get_code_snippet 适合已知 qualified_name 的情况

已知陷阱

  • get_code_snippet 的 qualified_name 必须来自 search_graph 的精确输出，手拼容易错
  • trace_path 对跨包/跨语言的调用链可能返回 0 结果（索引深度不够，重试有时能解决）
  • search_graph 的 total_results 字段可能显示为 ?，看 results[] 数组长度更可靠
  • 项目名是路径自动生成的（如 /tmp/memoryweave → tmp-memoryweave），用 list_projects 确认
  • MCP unreachable 先查进程数再怀疑坏了（2026-08-02）：CBM 是 hermes gateway 的子进程（ps -eo pid,ppid,etime,cmd | grep codebase-memory-mcp，PPid 是 gateway 的 python 进程，不是 systemd）——gateway 可能短暂拉起第二个实例，两个进程抢同一个 ~/.cache/codebase-memory-mcp/home-muc-.hermes.db sqlite 锁导致 MCP 瞬时 unreachable；新进程退出后单进程即恢复，不需要任何修复。诊断顺序：① ps 看进程数 ② 直接调一个 CBM 工具（如 get_graph_schema）重试 ③ 全挂再查 db 文件锁
  • home-muc-.hermes.db.corrupt 是正常备份：CBM 索引 db 目录里 .corrupt 后缀文件是旧备份机制（非故障），主库 home-muc-.hermes.db 一直在更新就是健康

已知陷阱（2026-09-05 补充）

  • ~/.cache/codebase-memory-mcp/ 是索引数据库，不是普通缓存！ 2026-09-05 磁盘清理把它当"可重建缓存"手工删了（1.5G）→ 所有项目索引丢失 → list_projects 空 → 任何查询报 "CBM 查询失败"。删除 = 全部索引丢失，重建要重扫全仓数十分钟+吃 5GB 内存。磁盘清理白名单必须排除它（backup-cleanup.py 不删 ~/.cache 是对的；手工清理清单曾误删）。
  • 索引 worker 内存黑洞：cli index_repository（尤其大目录 fast 模式）worker RSS 可达 5GB+，swap 打满会触发系统级 OOM（可能误杀 gateway/zhiyid）。索引期间：不并行跑第二个索引、监控 free -h、必要时 SIGTERM worker 止血（已完成项目不受影响，project 已写盘）。
  • CBM 索引会自动被每日 cron 触发：~/.hermes/scripts/cbm-index-all.sh（每日刷新 ~/.hermes + mc/ 下知识库，fast 模式）——CBM 索引丢失后它会自动重建，别手动重复触发。
  • 修复清单：索引丢失 → 跑 cbm-index-all.sh 或 cli index_repository --repo-path <path> --mode fast → list_projects 验证。

边界

  • ❌ 不做：运行时诊断、日志分析、数据库查询
  • ❌ 不做：需要语义理解而非结构分析的问题
  • ✅ 做：代码结构查询、调用链、架构概览、变更影响