OpenGem + Claude Code + Obsidian：构建代码函数调用关系图谱

工具链职责一览

┌─────────────────────────────────────────────────────────┐
│  OpenGem   →  分析代码，生成函数调用图谱 (graph.html)      │
│  Obsidian CLI →  将分析结果写入 Obsidian 知识库           │
│  Claude Code →  AI 驱动：一条指令自动完成分析 + 写库       │
└─────────────────────────────────────────────────────────┘

• OpenGem：负责"看懂代码"，提取函数之间的调用关系，生成可视化图谱。
• Obsidian CLI：负责"写入知识库"，把图谱和调用关系变成 Obsidian 中的笔记。
• Claude Code：负责"自动化"，一条 /opengem 指令串起整个流程。

---

为什么用 Obsidian CLI，而不是普通命令行？

如果你只会在终端里 echo > xxx.md 或 cp graph.html，那你只是在操作文件系统——Obsidian 根本不知道发生了什么。

核心差异

操作	普通命令行 (cp/echo/mv)	Obsidian CLI
创建笔记	文件出现在磁盘上，Obsidian 不知道	obsidian create → Obsidian 立即索引，双链生效
写入内容	需要知道完整绝对路径	file="笔记名" 即可，自动解析 wiki 链接
打开文件	只能用编辑器手动打开	obsidian open 直接在 Obsidian 工作区打开
静默写入	无法控制 Obsidian 是否弹窗	silent 参数：后台写入，不打断当前工作
读取笔记	cat 只能看原始 Markdown	obsidian read 可读取渲染后内容
属性操作	需要解析 YAML 手动改	obsidian property:set 直接修改 frontmatter
搜索	grep 搜原始文本	obsidian search 走 Obsidian 索引，更快更准
多仓库	需要记住每个仓库的绝对路径	vault="仓库名" 自动定位

最关键的三个场景

场景 1：AI 自动写入笔记

Claude Code 分析完代码后，需要把调用关系写成 Markdown 存入 Obsidian。用普通命令行：

# 你需要知道 vault 的绝对路径，而且 Obsidian 不会自动索引新文件
echo "..." > "/D:/Note/Git/YY-sWork/YY-Wiki/raw/relationship/xxx.md"

用 Obsidian CLI：

# vault 名自动定位，silent 不弹窗，自动加入索引和图谱
obsidian vault="YY-sWork" create path="YY-Wiki/raw/relationship/xxx.md" content="..." silent

场景 2：静默写入，不打断工作流

你正在 Obsidian 里写另一篇笔记，Claude Code 在后台生成了调用关系图谱。如果 AI 直接用 cp 写文件，文件是放进去了，但 Obsidian 的搜索、双链、图谱视图都需要等下一次索引才能发现它。

obsidian create ... silent 解决了这个问题：文件入库后 Obsidian 立刻知道它存在，双链立即可用，而且不会弹出新标签页打断你。

场景 3：操作 frontmatter 属性

如果想把分析结果标记为"已处理"：

# 普通命令行：需要写脚本解析 YAML，改 `status: done`，再写回去
# Obsidian CLI：一行搞定
obsidian property:set name="status" value="done" file="opengem-main"

一句话总结

普通命令行 = 操作磁盘文件。Obsidian CLI = 操作 Obsidian 知识库。

对于"AI 自动写笔记"这个场景，Obsidian CLI 是唯一的正确选择——它让写入的笔记立即成为知识网络的一部分，而不是躺在磁盘上等 Obsidian 慢慢发现。

---

1. 安装前提

在开始之前，确保以下工具已安装并可在 PATH 中运行：

工具	用途	验证命令
OpenCode	OpenGem 的运行环境	opencode --version
Obsidian 桌面应用	知识管理，图谱展示	打开 Obsidian 即可
Obsidian CLI	命令行操作 Obsidian	obsidian --version
Bun	CLI 和 MCP 服务器运行时	bun --version

Obsidian CLI 是这里的"胶水层"
没有它，OpenGem 分析出的结果只能停在终端里——有它，结果能自动变成知识库中可检索、可双链的笔记。详见上一节。

2. 安装 OpenGem

npx @cubocompany/opengem init

初始化完成后，项目根目录会出现 .opengem/ 配置目录。

3. OpenGem CLI 命令

命令速查

opengem graph [dir]       # 对指定目录建立代码索引和图谱
opengem watch [dir]       # 持续监听文件变化，增量更新索引
opengem query <search>    # 按名称或文件名搜索图中的节点
opengem explain <symbol>  # 展示某个符号的完整调用关系（入边+出边）
opengem path <from> <to>  # 找出两个符号之间的最短调用路径

使用示例

# 仅索引 src/ 目录
opengem graph ./src

# 搜索 buildGraph 相关的所有符号
opengem query buildGraph

# 查看 parseFile：谁调用了它，它又调用了什么？
opengem explain parseFile

# 找 main → detectCommunities 的最短调用链
opengem path main detectCommunities

explain 输出示例：

4. 输出文件：opengem-out 文件夹

执行 opengem graph ./src 后，会生成 opengem-out/ 目录：

graph.html — 交互式调用图

打开 graph.html 可以直观看到函数之间的调用关系：

相比 VS Code 逐个函数查看调用链，这张图能一眼看清全局调用结构——改接口、重构代码时尤其有用。

GRAPH_REPORT.md — 自动分析报告

包含 God Nodes（高频调用节点）、社区划分、语言统计等概要信息。

5. Claude Code 集成：让 AI 驱动全流程

把以下 Skill 定义放到 Claude Code 的 skills 目录中，之后只需输入 /opengem 就能让 AI 自动完成：索引代码 → 分析图谱 → 写入 Obsidian 知识库。

name: opengem
description: 使用 OpenGem 代码知识图谱工具分析函数调用关系。当用户输入 /opengem 或需要查看函数调用链、代码依赖关系时调用。支持生成交互式调用图（graph.html），并可将结果导出为 Markdown 同步到 Obsidian。
user-invocable: true

# OpenGem 代码知识图谱技能

使用 `opengem` CLI 分析代码库中的函数调用关系、依赖图和符号路径。

## 前置条件

运行任何 `opengem` 命令前，先检查当前目录是否存在 `.opengem/graph-state.json`：

test -f .opengem/graph-state.json && echo "ready" || echo "需要先运行 opengem graph 索引代码库"

如果图谱不存在，提示用户：

> 当前项目尚未索引，需要先运行 `opengem graph` 生成知识图谱。是否现在执行？

用户同意后执行 `opengem graph`。

## 核心命令

### 1. 无参数调用 `/opengem`

执行完整图谱生成流程：

opengem graph

完成后：

1. 告知用户图谱已生成

2. `opengem-out/graph.html` 为交互式可视化调用图

3. `opengem-out/GRAPH_REPORT.md` 为图谱分析报告

4. 使用 Read 工具读取 `opengem-out/GRAPH_REPORT.md`，向用户展示摘要（God nodes、社区划分、语言统计等）

5. 询问用户：**"是否需要将 graph.html 上传到 Obsidian 仓库 (YY-sWork)？"**

6. 若用户同意，将 `opengem-out/graph.html` 复制到 Obsidian vault

### 2. 指定函数名 `/opengem <function>`

对指定符号执行 `opengem explain`，展示完整调用关系：

opengem explain <function>

按以下格式输出：

## <symbol> (<type>)  <file-path>

### Incoming (<N>):
  ← <edge-type>  <target-symbol>  (<source-file>)

### Outgoing (<N>):
  → <edge-type>  <target-symbol>  (<source-file>)

输出后询问用户：

> 是否需要将此调用关系打包为 Markdown 文件并同步到 Obsidian 仓库 (YY-sWork)？

用户同意后执行 Obsidian 同步流程。

### 3. 通用查询 `/opengem query <name>`

opengem query <search>

按名称或文件搜索图中的节点，展示匹配结果。

### 4. 路径查找 `/opengem path <a> <b>`

opengem path <symbol-a> <symbol-b>

查找两个符号之间的最短调用路径，展示链路。

## Obsidian 同步流程

Obsidian vault 信息：

- **名称**: `YY-sWork`

- **路径**: `D:\Note\Git\YY-sWork`

### 同步 graph.html

cp opengem-out/graph.html "D:/Note/Git/YY-sWork/YY-Wiki/raw/relationship/opengem-graph.html"
obsidian vault="YY-sWork" open path="YY-Wiki/raw/relationship/opengem-graph.html"

### 同步调用关系 Markdown

1. 构造 Markdown 内容，格式如下：

---
tags: [opengem, code-graph]
date: YYYY-MM-DD
---

# <function> 调用关系分析

## 基本信息
- **符号**: `<function>`
- **类型**: `<type>`
- **文件**: `<file-path>`

## 入边 (Incoming)
| 关系 | 来源 | 文件 |
|------|------|------|
| calls | `xxx` | `file.ts` |

## 出边 (Outgoing)
| 关系 | 目标 | 文件 |
|------|------|------|
| calls | `xxx` | `file.ts` |

2. 使用 Obsidian CLI 创建笔记（存入 `YY-Wiki/raw/relationship/`）：

obsidian vault="YY-sWork" create path="YY-Wiki/raw/relationship/opengem-<function>.md" content="<escaped-markdown>" silent

如果文件已存在则覆盖。

3. 在 Obsidian 中打开：

obsidian vault="YY-sWork" open path="YY-Wiki/raw/relationship/opengem-<function>.md"

## 注意事项

- 所有 `opengem` 命令必须在包含 `.opengem/graph-state.json` 的目录下运行

- 如果操作的是 monorepo，确保在正确的子项目目录下执行

- graph.html 较大时（>1MB），复制到 Obsidian 前提醒用户

- 调用关系 Markdown 文件名使用 `opengem-<函数名>` 命名规范，统一管理

---

6. 结合 LLM Wiki 的完整工作流

这套工具链与你的 LLM Wiki 知识库天然契合：

你写代码 (C/Python/Shell)
      ↓
OpenGem 分析代码 → 生成调用图谱
      ↓
Claude Code 读取图谱 → 提炼关键调用链
      ↓
Obsidian CLI 写入 wiki → 调用关系变成可检索、可双链的知识页
      ↓
未来 /query "XX函数的调用链" → 即刻从 wiki 中拿到答案

技能文件已经写好，根据自己的项目路径稍作修改，交给 AI 执行即可。