zachsaw/graphify-csharp

来源：https://github.com/zachsaw/graphify-csharp

graphify-csharp 🚀

为编码代理提供编译器精确的“查找使用处”功能，支持C#。

NuGet 版本 (https://www.nuget.org/packages/Graphify.CSharp)
CI (https://github.com/zachsaw/graphify-csharp/actions/workflows/ci.yml)
许可证：MIT

graphify-csharp 是一个免费的、无头的 Roslyn/MSBuild 索引器，可将 C# 源代码转化为确定性的、可查询的语义证据：编译器解析的调用者、引用、实现、继承和重写——即使在重载、泛型和跨项目的情况下也能工作。

可以将其视为 Rider/ReSharper 的语义导航切片，专门为 Codex、Claude Code 和其他编码代理导出。

MIT 许可证 · 无需 IDE · 无需编译后的项目 DLL · 无需数据库 · Graphify 可选

停止让你的代理猜测

假设你问：

哪些方法仅被测试使用？

文本搜索可以找到匹配的拼写。但它无法可靠地判断绑定了哪个重载、调用者属于哪个项目，或者接口实现是否是你想要的那个符号。

Graphify C# 通过 MSBuild 加载项目，并询问 Roslyn 每个符号的实际含义。它输出稳定的标识符和有向关系，供代理直接检查而非推断：

例如，此仓库包含一个内部方法 DeclarationCatalogBuilder.ForTesting(...)。从提取的图中，代理可以看到一个经过编译器解析的传入调用：

Graphify.CSharp.Roslyn.DeclarationCatalogBuilder.ForTesting(...)
└── called by Graphify.CSharp.Tests.Roslyn.CSharp14FeatureTests
    at tests/Graphify.CSharp.Tests/Roslyn/CSharp14FeatureTests.cs:143

这是语义证据，而不是文本匹配计数。消费者可以根据项目或命名空间约定对调用者进行分类，并将该方法报告为仅供测试使用以供人工审查。

快速开始

1. 安装

dotnet tool install --global Graphify.CSharp --framework net10.0

2. 为你的代码库建立索引

graphify-csharp \
  --input ./src/MyProduct.sln \
  --root . \
  --configuration Release \
  --output ./graphify-out/csharp.json

结果是一个完整的 JSON 文档，包含 nodes、edges 和 hyperedges。代理可以直接读取、使用 jq 查询、从你自己的代码中消费，或传递给 Graphify。

支持的输入格式为 .sln、.slnx、.csproj 和基于 SDK 文件的 .cs 应用。仓库的 SDK、包和 MSBuild 输入必须在本地可用。

3. 教你的代理如何使用它

包含的 graphify-csharp 技能 教会代理何时刷新索引、如何遵循语义边，以及静态分析的边界在哪里。

在兼容 Codex 的项目中安装它：

mkdir -p .agents/skills/graphify-csharp
curl -fsSL \
  https://raw.githubusercontent.com/zachsaw/graphify-csharp/main/.agents/skills/graphify-csharp/SKILL.md \
  -o .agents/skills/graphify-csharp/SKILL.md

对于 Claude Code，请使用 .claude/skills/graphify-csharp/SKILL.md。安装或更新技能后，请重新加载代理会话。

如果你不使用技能，请将以下内容添加到你的项目说明中：

对于 C# 结构和使用问题，回答前请使用 graphify-csharp 刷新 graphify-out/csharp.json。通过 symbol_key 识别声明，并检查传入的 calls 和 references 边。将零入边视为观察到的静态证据，而非运行时不可达的证明。

现在向你的代理提问：

• 谁调用了这个确切的重载或构造函数？
• 哪些源声明引用了此字段、属性、事件或类型？
• 哪些类实现了此接口？
• 哪些成员重写了此虚方法或接口成员？
• 哪些声明具有零观察到的传入引用？
• 哪些方法仅从测试项目中引用？

从 IDE 导航到代理证据

提取器提供事实。你的代理或下游消费者决定这些事实意味着什么：仅供测试使用、零观察到的引用、删除候选项，还是需要人工审查的内容。

定位

Graphify C# 故意专注于一个聚焦的层：

• Rider 和 ReSharper 为 IDE 内的开发者提供交互式导航、检查、重构和快速修复。
• NDepend 提供一个广泛的、商业化的架构和代码质量套件，围绕依赖分析、度量、规则、报告、基线和可视化构建。
• Graphify C# 为编码代理提供源码级的 C# 语义证据，无头且采用开放格式。

在调用者、依赖、继承和死代码调查方面与 NDepend 有真正的重叠。区别在于产品边界：Graphify C# 不是免费的 NDepend 克隆，也不是 IDE 替代品。它是一个 Roslyn 原生的语义索引，可供其他工具和代理构建。

与 Graphify 一起使用——或不与之一起使用

Graphify C# 是独立的。它不调用、加载或依赖 Graphify。

如果没有 Graphify，你可以使用代理、jq、C#、Python 或任何其他消费者来查询 JSON。例如，列出所有已索引的方法：

jq '.nodes[] | select(.properties.node_kind == "method")' \
  graphify-out/csharp.json

如果使用 Graphify，可以刷新 C# 证据并使用其更高级的查询、路径、解释、聚类和导出工作流：

graphify-csharp \
  --input ./src/MyProduct.sln \
  --root . \
  --configuration Release \
  --output ./graphify-out/csharp.json

graphify query "哪些方法调用了订单服务？" \
  --graph ./graphify-out/csharp.json

Graphify 仍然是通用的图工作流。graphify-csharp 贡献的是编译器绑定至关重要的 C# 层。

索引内容

源声明

• 命名空间、类、结构体、接口、记录、枚举和委托
• 构造函数、方法、运算符和局部函数
• 属性、索引器、字段、枚举成员和事件
• 参数、局部变量、类型参数、别名、标签和查询范围变量

编译器解析的关系

• 直接调用、构造函数调用、方法组和成员访问
• 字段、类型、属性、泛型、typeof 和声明头引用
• inherits、implements 和 overrides
• 编译器选择的运算符、转换、解构、foreach、await、using、模式、范围和集合表达式
• 绑定到源形式参数的调用和构造函数参数
• 具有重载感知、项目/TFM 感知标识的跨项目关系

每条边都从观察到关系的声明指向 Roslyn 解析的声明。源位置和来源信息得以保留。不支持的语义形状会作为诊断信息报告，而不是静默消失或导致整个提取崩溃。

有关完整的语言和编译器功能矩阵，请参见 兼容性。

保持索引热缓存

对于重复的代理工作，可以启动一个观察器：

graphify-csharp \
  --input ./src/MyProduct.sln \
  --root . \
  --configuration Release \
  --output ./graphify-out/csharp.json \
  --watch

观察器保持 Roslyn 工作区热缓存，并在后台准备已更改的项目。一次常规的 graphify-csharp 调用会充当显式的刷新屏障，并在完整的 JSON 快照更新后才返回。

如果没有匹配的观察器在运行，相同的命令将执行一次性刷新。使用 --rebuild 使增量缓存失效。

有关观察器所有权、过滤、恢复和缓存行为，请参见 用法 和 增量索引。

运行时和语言支持

该包包含两个工具资产：

使用 dotnet tool ... --framework 安装或更新包以选择工具运行时和 Roslyn 资产：

dotnet tool update --global Graphify.CSharp --framework net11.0

这与可选的 --target-framework 参数是分开的，后者用于在输入项目以多个框架为目标时选择一个分析编译。单目标项目不需要 --target-framework。

静态分析边界

Graphify C# 报告 Roslyn 能够静态观察到的内容。反射、依赖注入、原生回调、动态调用以及加载的编译中缺失的代码可能会创建未表示为直接边的运行时关系。

因此：

• 零传入引用意味着 零观察到的静态引用；
• 仅测试使用的结果取决于你的项目或命名空间分类；并且
• 每个删除候选项仍然需要判断。

该工具暴露了这个边界，而不是假装静态证据是运行时可达性的证明。

开发

dotnet restore Graphify.CSharp.sln
dotnet build Graphify.CSharp.sln --configuration Release
dotnet test Graphify.CSharp.sln --configuration Release
dotnet pack src/Graphify.CSharp.Cli --configuration Release

更多详情：

• 用法
• 兼容性
• 增量索引设计
• 发布和 NuGet 发布

许可证

MIT。详见 LICENSE。