用途
codegraph-partner 是一个协作型技能,用于让智能体识别并配合 codegraph 工具。codegraph 与 OSB(Open Second Brain)是互补关系而非重叠:OSB 负责 vault(Markdown 文本、Brain 层、偏好设置、付费操作审计),而 codegraph CLI 及其 MCP 服务器负责仓库的代码符号图,包括调用者、被调用者、影响半径和 AST。该技能教智能体在当前范围内检测 codegraph,并根据实际环境选择使用、推荐或保持沉默。
该技能本身从不安装、初始化或为 codegraph 写入数据,这些操作始终由用户或 codegraph 自身的安装程序完成。
主要能力
第一步:检测
按顺序执行以下检查,在第一个匹配的状态处停止:
- CLI 是否存在:运行
which codegraph(或在 Bun 运行时中使用Bun.which("codegraph"))。 - 当前工作目录中的代码项目信号:存在
.git/目录,且至少包含以下之一:package.json、pyproject.toml、Cargo.toml、go.mod、tsconfig.json、Gemfile、composer.json、build.gradle、pom.xml。 - 如果当前目录或用户指定的项目都不是代码项目,则查看 vault 的父目录并检查顶层条目(仅一层)。许多用户将仓库作为 vault 的兄弟目录存放。所有发现的代码项目都是候选,而不仅是第一个。
- 索引状态:代码项目根目录内是否存在
.codegraph/目录。 - 确认索引:
codegraph status -j <project_path>返回{"initialized": true, ...}。对未初始化项目运行同一命令会返回{"initialized": false, ...}而非失败。
结构化的询问方式是 o2b doctor。当 OSB 安装在工作区时,doctor 报告会携带一行 code_graph,汇总检测结果,包含节点数和文件数。
多项目工作区:当发现多个代码项目时,code_graph 行覆盖每个项目。状态按项目分别传递,将每个项目的路径传给 codegraph status,该行聚合每个项目一条记录(N code projects: 后跟每个项目的路径和索引状态/健康度)。这种按查询传递项目路径的能力是特性检测的:如果已安装的 codegraph CLI 未记录 status 的位置参数 [path],OSB 无法信任按项目查询,会降级为仅报告第一个项目,并附加明确说明:codegraph CLI has no per-query project_path support - reported 1 of N discovered projects only。单项目工作区不受影响,其行保持不变。
第二步:根据结果分支
- ok(CLI 存在,已索引):使用 codegraph 进行 AST 和图查询,不谈论安装。
- not_indexed(CLI 存在,无
.codegraph/或initialized: false):提供一行提示:"run codegraph init <path> to index this repo"。除非用户要求,否则不要自行运行。 - missing + 代码项目:给出有论据的推荐(见第五步)。
- missing + 范围内无代码项目:保持沉默。
- error(CLI 存在,
status -j因锁或 schema 问题报错):建议codegraph unlock <path>或重建,但不要运行。
在多项目工作区中,聚合的 code_graph 行可能混合这些状态(一个已索引,一个未索引);逐条阅读并逐项目行动。当该行以 note: ... project_path support 标记结尾时,仅检查了第一个项目——在信任单项目结论前,用 codegraph status <their_path> 显式查询其他项目。
第三步:codegraph init 后的硬性规则
每当代表用户在任何仓库中运行 codegraph init 后,立即读取该仓库的 .gitignore,如果尚未包含 .codegraph/ 行则追加。追加必须是原子的,必须保留现有的尾随换行策略,且不得触碰任何其他行。
如果仓库没有 .gitignore,不要自行创建。告知用户该文件缺失,应由用户决定是否添加。
此规则的存在是为了确保本地 codegraph 索引永远不会进入提交。
第四步:工具间消歧
使用下表为每类问题选择正确的工具。不要通过同时运行 grep 来重复 codegraph 的答案;将其输出视为权威。
- 符号 X 定义在哪里?→
codegraph_search - 谁调用函数 Y?→
codegraph_callers - Y 调用了什么?→
codegraph_callees - 如果我修改 Z 会破坏什么?→
codegraph_impact - 显示 Y 的签名或主体。→
codegraph_node - 一次性调查多个相关符号。→
codegraph_explore - 路径 P 下有哪些文件?→
codegraph_files - 文本、页面正文、MOC 内容、每日笔记。→
brain_search - 已确认的偏好、品味规则。→
brain_query - 两个索引都无帮助时的自由文本回退。→ 普通 grep,最后手段。
第五步:有论据的安装推荐
仅当两个条件同时满足时触发:当前范围内存在代码项目,且 codegraph 不在用户的 PATH 中。
向用户展示一段简短文字,使用其项目中的真实数字,不使用表情符号,不使用营销口吻。模板:
Found a code project at <path> with N source files. Without an index, every structural question (callers, impact, "where is X") spawns a grep+read loop that burns several thousand tokens per answer. codegraph keeps a SQLite knowledge graph and serves the same question in sub-millisecond time. Install it with
npm i -g @colbymchenry/codegraph(other options: https://github.com/colbymchenry/codegraph#1-install-the-cli). After install:codegraph init <path>from inside the repo.
如果用户拒绝,在本次会话剩余时间内不再提及该话题,不要反复催促。
使用方式
该技能在用户明确提到 codegraph,或提出结构化代码问题(如调用者/被调用者/影响范围、符号定义位置等)时被触发。智能体按上述检测流程判断当前环境状态,然后根据状态选择使用 codegraph 查询、给出安装建议或保持沉默。
适用场景
- 用户明确提到 codegraph。
- 用户询问调用者、被调用者、影响范围等结构化代码问题。
- 用户询问符号定义位置。
- 用户询问修改某处代码会破坏什么。
- 用户需要查看函数签名或主体。
- 用户需要一次性调查多个相关符号。
限制
- 不要自动调用
codegraph install、codegraph init或codegraph index。 - 不要读取或写入
.codegraph/codegraph.db。 - 不要将 codegraph 数据镜像到 Brain 或 vault 搜索索引中。
- 不要代表 codegraph 修改
~/.claude.json、.cursor/rules/或任何其他智能体配置。 - 该技能本身不安装、初始化或写入 codegraph 数据。
- 安装推荐仅在存在代码项目且 codegraph 不在 PATH 中时触发。
- 用户拒绝安装后,本次会话不再提及。