通过 CodeGraph 为编码智能体提供 AST 抽象语法树与代码调用关系知识图谱支持。

CodeGraph 集成

Mopheus 支持集成开源代码智能工具 CodeGraph，为平台内的编码智能体（开发、修复、重构、审计等）提供基于 AST（抽象语法树）与调用依赖图的高效代码检索与架构理解能力。

协议与开源说明

开源项目：colbymchenry/codegraph
开源协议：MIT License
商业化支持：MIT 协议允许自由用于商业化集成、修改与闭源/开源分发。

为什么集成 CodeGraph？

在传统基于大模型的代码探索过程中，智能体通常需要多次调用 grep 和全量读取文件内容，不仅交互轮次多、响应慢，还会大量消耗 Token。

CodeGraph 在底层通过 Tree-sitter 和 SQLite 将代码仓库解析为结构化的 AST 与调用依赖图谱：

一步到位探索：通过 codegraph explore 一次性返回关键符号的真实源码（带精确行号）、上下游调用路径和改动爆炸半径，智能体无需重复读取磁盘文件。
精准依赖追踪：通过 codegraph callers / callees 精确定位函数或结构体的调用方与被调用方。
变更影响与单测定位：通过 codegraph impact 评估改动影响范围，通过 codegraph affected 自动找出需要回归测试的文件。

架构与生命周期机制

Mopheus Daemon 运行时在底层对 CodeGraph 进行了深度虚拟化集成：

零开销快速派发：
- 在 Bare Cache 旁路维护基于 Commit SHA 命名的 Sidecar 快照缓存（.repos/.../<repo>.git.codegraph-cache/<sha>.db）。
- 派生任务 Worktree 时，直接以独立文件复制（<10ms）注入到 <worktree>/.codegraph/codegraph.db，彻底消除并发任务间的 SQLite 锁冲突。
智能增量刷新：
- 当远端代码更新产生新的 Commit 时，Daemon 自动从最近的邻近快照执行增量同步（codegraph sync，耗时仅约 50ms），无需每次重新执行耗时的全量索引（init）。
Git 隔离保护：
- Worktree 创建时自动将 .codegraph 写入 .git/info/exclude，确保图谱数据库永远不会被误提交进业务分支。
自动 GC 淘汰：
- 结合 Git 活跃 Worktree 元数据与分支 HEAD，在定期维护周期中自动执行过期快照（超过 7 天）与超出配额快照（LRU 保留最近 5 个）的清理回收。
故障安全（Fail-Open）：
- 若宿主机未安装 codegraph 或索引异常，仅记录日志，绝不阻断 Worktree 创建与智能体任务执行。
基于仓库关联的智能按需注入（Repo-Aware Injection）：
- 在任务派发阶段（agent_task.go），后端自动检测当前任务是否关联了有效的 Git 代码仓库（包括项目专属仓库和工作区默认仓库）。
- 仅在任务拥有代码仓库时自动注入 using-codegraph；纯文本对话、客服问答、运营流程等非研发任务自动跳过注入，确保非编码智能体的 Prompt 上下文与工作环境纯净无干扰。

平台提供开箱即用的内置技能 using-codegraph，同时支持 CLI 命令行 与 CodeGraph MCP Server Tools（如 codegraph_explore）两种交互模式。系统采用**按仓库关联智能动态注入（Repo-Aware）**机制，在派发研发工单时自动注入，无需在前端手动分配。智能体在检出并进入代码仓库（Worktree）目录后即可开箱即用：

指令	用途	示例
`codegraph explore "<query>"`	检索代码流、符号源码与调用链	`codegraph explore "CreateComment flow"`
`codegraph callers <symbol>`	查询指定符号的所有上游调用方	`codegraph callers ProvisionCodeGraph`
`codegraph callees <symbol>`	查询指定符号调用的所有下游函数	`codegraph callees CreateWorktree`
`codegraph impact <symbol>`	修改代码前评估受影响的代码范围	`codegraph impact Cache`
`codegraph affected [files...]`	查询受代码变更影响的单测文件	`codegraph affected server/internal/daemon/repocache/git.go`
`codegraph sync`	代码编辑后增量同步 AST 变更	`codegraph sync`

安装与环境准备

[!NOTE] 安装说明：当前版本 Mopheus 暂不通过 install.sh 脚本默认预装 codegraph（后续版本会根据实际需要评估纳入一键安装流程）。如果需要使用该能力，请在运行 Mopheus Daemon 的宿主机或容器环境中手动安装。

1. 安装方法

CodeGraph 提供了**独立预编译二进制（自包含运行时，无需安装 Node.js）**和 Node.js npm 包两种安装途径：

途径一：官方一键安装脚本（推荐，无需 Node.js）

官方脚本会自动从 GitHub Releases 下载适配当前 Linux / macOS 架构的独立预编译二进制文件：

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

也可以直接前往 GitHub Releases 下载对应架构的压缩包（如 codegraph-linux-x64.tar.gz、codegraph-linux-arm64.tar.gz 或 codegraph-darwin-arm64.tar.gz）并解压到 PATH 目录。

途径二：通过 Node.js 包管理器安装（已有 Node 环境）

如果宿主机或容器已有 Node.js 环境，也可通过 npm / pnpm 全局安装：

# 使用 npm 全局安装
npm install -g @colbymchenry/codegraph

# 或使用 pnpm 全局安装
pnpm add -g @colbymchenry/codegraph

2. 验证安装

安装完成后，确保 codegraph 命令已加入系统的 PATH 环境变量中：

codegraph --version

验证成功后，重启 Mopheus Daemon（或重新派发 Agent 任务），系统即可自动开启 CodeGraph 代码图谱加速与内置技能支持。