BIGboss248/nextjs-wordpress

代码库记忆与图谱智能（codebase-memory）

此技能定义了使用 codebase-memory MCP 知识图谱 探索、搜索和理解代码的工程标准、操作流程和工具使用契约。

---

核心不变项：索引优先协议

[!重要] 索引优先不变项： 后台监视重新索引在此工作区已永久禁用（auto_watch = false），以防止在主动编辑文件时出现磁盘抖动、zstd 序列化开销和系统卡顿。

因此，代理在针对代码知识图谱执行搜索前，必须始终验证索引的新鲜度或触发按需重新索引（index_repository）。

每当您被要求查找符号、理解模块、调查错误或准备重构时，请在调用搜索工具之前执行索引优先门控。

---

工具层次结构：图谱优先，Grep 其次

在发现、导航或审查代码时，请严格遵守以下优先级层次结构：

flowchart TD
    Task[代码发现/调查任务] --> Freshness{索引新鲜?}
    Freshness -->|否 / 未知 / 编辑后| Sync[index_repository 模式: 'fast' 或 'moderate']
    Freshness -->|是| Strategy{查询类型}
    Sync --> Strategy

    Strategy -->|符号 / 函数 / 接口| SearchGraph[search_graph BM25 或 semantic_query]
    Strategy -->|调用者 / 被调用者 / 依赖| TracePath[trace_path callers / callees]
    Strategy -->|变更影响范围| DetectChanges[detect_changes diff to impact set]
    Strategy -->|精确源码| GetSnippet[get_code_snippet precise lines]
    Strategy -->|系统层与中心模块| GetArch[get_architecture high centrality nodes]
    Strategy -->|字面字符串 / 非代码 / 资源| GrepFallback[search_code 或 run_command grep]

1. search_graph > 文本 grep：BM25 排名结构搜索，支持驼峰命名拆分、标签提升（函数 +10，路由 +8，接口 +5）和向量嵌入。
2. trace_path > 手动文件跳转：即时解析多跳调用者和被调用者图谱。
3. get_code_snippet > 在大文件上使用 view_file：检索符号的精确声明和主体，包含起始/结束行和调用者计数，而不会膨胀代理上下文。
4. detect_changes > 手动 diff 检查：将 git diff（since: "HEAD~1"，base_branch: "main"）直接映射到其传递影响范围。
5. Grep 回退：仅在以下情况下使用 search_code 或 run_command（git grep，rg）：
   • markdown（.md）、配置（.json）或样式表（.css）中的字面文本。
   • 在 index_status 中通过 parse_partial 明确标记的行范围。
   • 根据设计通过 .cbmignore 排除的文件。

---

标准操作工作流程

第 1 步：索引同步门控（强制性的第一步操作）

在发出搜索查询之前，确定项目名称并确保图谱反映最近的文件系统更改。

1. 识别项目名称： 如果项目标识符未知，请调用 list_projects：

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   （在此工作区中，推导出的项目名称为 "D-Scripts-aminwebsite"。）

2. 检查状态或刷新索引： 如果在会话期间创建或修改了文件，请调用 index_repository：

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • 模式选择：
     • mode: "fast"：增量解析，过滤文件，不进行语义向量嵌入。对于活跃开发来说快速且轻量。
     • mode: "moderate"：增量解析 + 向量相似性嵌入，用于自然语言概念桥接。
   • 覆盖范围检查：检查响应中的：
     • parse_partial：某些行范围存在解析错误的文件。
     • skipped：完全跳过的文件（例如二进制文件或超大文件）。

---

第 2 步：符号与结构发现（search_graph）

查找函数、接口、类型、组件和路由定义。

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• 自然语言发现： 使用 query 进行关键字/BM25 搜索（例如 "theme toggle transition"、"locale routing"）。
• 精确名称模式： 使用 name_pattern 进行正则表达式过滤（例如 ".*Provider.*"、".*Skeleton.*"）。
• 语义概念搜索： 使用 semantic_query: ["i18n", "language", "switch"]（需要字符串数组）来弥合词汇差距。
• 处理截断（has_more）： 如果响应返回 "has_more": true，则通过添加 "offset": <current_offset + limit> 进行分页。

---

第 3 步：关系追踪与影响范围

在未检查其依赖项的情况下，永远不要修改函数或接口。

1. 追踪调用者与被调用者（trace_path）：

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound"：识别所有依赖此函数的调用者（影响范围）。
   • direction: "outbound"：识别此符号调用的下游函数。
   • direction: "both"：完整的双向调用链。

2. 映射 Git Diff 影响集（detect_changes）： 在提交或最终确定更改之前，评估影响范围：

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

第 4 步：精确代码检索（get_code_snippet）

无需通过 view_file 查看整个文件来消耗上下文，而是检索精确的符号实现：

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

响应包括：

• 精确的 start_line 和 end_line
• 符号的干净源代码
• 直接调用者和被调用者计数

---

第 5 步：高层架构探索（get_architecture）

当需要了解新子系统或理解系统拓扑时：

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

识别出顶级的架构中心组件、核心依赖和层次结构。

---

MCP 惰性工具参考矩阵

能力	工具名称	必需参数	关键可选参数
验证状态	index_status	project	不适用
触发索引	index_repository	repo_path	mode（"fast"、"moderate"、"full"）、persistence
列出项目	list_projects	无	不适用
搜索符号	search_graph	project	query、name_pattern、semantic_query、limit、offset
追踪调用链	trace_path	project、function_name	direction（"inbound"、"outbound"、"both"）、depth、mode
检索源码	get_code_snippet	project、qualified_name	include_neighbors
影响范围	detect_changes	project	base_branch、since、scope（"impact"、"files"）、depth
架构	get_architecture	project	aspects（["hub_nodes"]、["layers"]、["all"]）
字面文本	search_code	project、query	file_pattern、case_sensitive、limit

---

护栏与常见反模式

反模式	正确的操作标准
未检查索引新鲜度就进行搜索	由于后台自动监视已禁用，始终先调用 index_repository(mode: "fast") 或通过 index_status 验证。
使用 grep 查找函数定义	使用符号名称调用 search_graph；它会返回限定名称、精确文件路径、行范围和调用者计数。
读取 1000 行的文件来查看 1 个函数	使用符号的 qualified_name 调用 get_code_snippet。
手动读取每个文件以查找调用者	使用 direction: "inbound" 调用 trace_path。
假设图谱 100% 完整	图谱是尽力而为的。如果 index_status 列出了 parse_partial 下的文件，则对该特定标记的行范围使用文本 grep。
启用 auto_watch	永远不要启用 auto_watch；保持其为 false 以维持峰值交互式开发性能。