内容
# `@samchon/graph`
`@samchon/graph` 是 `@ttsc/graph` 的语言中立继任者。
它公开了一个 MCP 工具，`inspect_code_graph`，它返回一个存储库的有界源代码索引：声明、源代码范围和它们之间的关系 - 导入、调用、类型引用、成员访问、包含、继承、装饰器和重写 - 以及当语言服务器可以提供时诊断，和一个 `next` 契约，告诉代理是否回答、再次检查、离开图表或请求澄清。
该软件包遵循 `@ttsc/graph` 架构：
- 一个工具，而不是一堆狭隘的工具；
- 请求分支前需要 `question`、`draft` 和 `review` 字段；
- 仅图形证据，从不源代码主体；
- 可用的编译器/LSP 真相；
- 没有安装语言服务器时的静态索引回退。
## 安装
```bash
npm install -D @samchon/graph
```
将其添加到 MCP 客户端：
```json
{
"mcpServers": {
"samchon-graph": {
"command": "npx",
"args": ["-y", "@samchon/graph"]
}
}
}
```
从项目根目录启动客户端。服务器构建一个常驻图，并从内存中回答所有 MCP 调用。
## 命令行界面
```bash
# 通过 stdio 启动 MCP 服务器
npx @samchon/graph
# 以 JSON 格式打印图形转储
npx @samchon/graph dump --cwd .
# 强制静态索引
npx @samchon/graph dump --mode static
# 为一种语言强制 LSP 索引
npx @samchon/graph dump --language go --mode lsp --server gopls
```
默认的 `auto` 模式尝试使用 LSP 服务器，如果服务器已配置或在 `PATH` 上找到，则使用静态索引器作为回退，如果服务器丢失或失败。
当混合语言存储库只有一些语言服务器可用时，可用的 LSP 图形被保留，失败的语言由静态回退填充；转储被标记为 `hybrid`，并带有警告，解释哪种语言回退。
## 支持的语言默认值
内置注册表了解常见的扩展名和服务器命令：
- TypeScript / JavaScript：`typescript-language-server --stdio`
- Go：`gopls`
- Rust：`rust-analyzer`
- C / C++：`clangd`
- Java：`jdtls`
- C#：`csharp-ls`
- Kotlin：`kotlin-language-server`
- Swift：`sourcekit-lsp`
- Scala：`metals`
- Zig：`zls`
- Python：`pyright-langserver --stdio`
- Ruby：`ruby-lsp`
- PHP：`intelephense --stdio`
- Lua：`lua-language-server`
- Bash：`bash-language-server start`
- Dart：`dart language-server`
静态回退处理相同系列的声明和导入，并在安装语言服务器之前保持输出有用。
语言服务器不捆绑。在需要编译器/LSP 诊断和引用边时，在目标存储库环境中安装匹配的服务器。
## 关系
LSP 和静态索引器都发出相同类型的关系，因此操作行为相同，无论哪种图形产生：
- **结构**：`contains`（所有者 → 成员），`imports`。
- **执行**：`calls`，`instantiates`，`accesses`，`references`。
- **类型**：`type_ref`，`extends`，`implements`，`overrides`，`decorates`。
继承、装饰器和重写从声明和装饰器行中解析，并针对索引符号解析，因此即使对于不公开类型层次结构的语言服务器（包括 `typescript-language-server`），它们也会被捕获。
## 调整
`buildGraph` / `buildGraphDump` 接受几个 LSP 路径的旋钮：
- `lspConcurrency`（默认为 16）- 保留多少个 `textDocument/references` 请求。
- `lspReferenceLimit`（默认为 250）- 引用预算；产品代码符号优先于测试文件。
- `lspReadyQuietMs`（默认为 1500）/ `lspReadyTimeoutMs`（默认为 30000）- 在收集引用之前，等待服务器的初始索引（`$/progress`）稳定下来。
- `lspTimeoutMs`（默认为 10000）- 每个请求的超时时间。
## 程序 API
```ts
import { buildGraph, SamchonGraphApplication } from "@samchon/graph";
const graph = await buildGraph({ cwd: process.cwd(), mode: "auto" });
const app = new SamchonGraphApplication(graph);
const result = app.inspect_code_graph({
question: "What are the main entrypoints?",
draft: { reason: "Broad orientation needs a tour.", type: "tour" },
review: "A tour is the smallest source-free answer.",
request: { type: "tour" },
});
```
## 基准测试
`tests/benchmark` 中的代理成本 A/B 在多个语言上移植了 codegraph 的头条基准测试（与 `@ttsc/graph` 一样）：对于每个存储库的一个问题，代理 CLI 运行一次无头 - 基线（无 MCP）vs `@samchon/graph` vs codegraph vs serena - 报告按回合汇总的令牌数、工具调用和墙上时间。提示是 codegraph 自己的话语，按 SHA-256 固定；检出按提交固定；图形分支如果缺少语言服务器，则拒绝运行，而不是静默测量静态回退。
```bash
pnpm --filter @samchon/graph-benchmark corpus # 15 repos / 15 languages, pinned
pnpm --filter @samchon/graph-benchmark preflight # zero-spend go/no-go
pnpm --filter @samchon/graph-benchmark suite-codex -- --runs=1 # spends credits
pnpm --filter @samchon/graph-benchmark render # results -> SVG charts
```
参见 `tests/benchmark/README.md` 以获取完整的方法论。
## 设计笔记
源代码链接的设计目标与 `@ttsc/graph` 描述的目标相同：保持图形作为索引，让代理通过类型化契约选择一个请求，并信任已解析的编译器/LSP 事实，以便在图形证据回答问题后停止读取文件。
源代码布局遵循 `@ttsc/graph` 文件规范：一个 TypeScript 文件可以定义和导出一个顶级符号，文件名必须与该符号完全匹配。仅重新导出其他文件的 文件是唯一的例外。
E2E 套件扫描 `packages/graph/src/**/*.ts` 和 `tests/test-graph/src/**/*.ts`，如果违反此约定，则失败。
## 验证
存储库是一个 pnpm 工作区，包含 `packages/graph` 用于发布的软件包，`tests/test-graph` 用于覆盖率受控的图形测试，`tests/experiment` 用于实际的语言服务器实验，`tests/benchmark` 用于基准测试工具工作。
```bash
pnpm install
pnpm build
pnpm test
pnpm coverage
```
E2E 套件涵盖：
- 通过静态回退夹具的每种语言；
- 通过契约图涵盖的每种图形节点类型、边缘类型和请求分支；
- MCP stdio 服务器和 CLI 转储命令；
- LSP JSON-RPC 路径通过伪造语言服务器，包括诊断、引用、缺少服务器回退和每种语言的混合回退；
- 实际的 `@samchon/graph` 存储库作为真实代码库夹具。
GitHub Actions 在 Linux、Windows 和 macOS 上为 `master` 的每次推送和拉取请求运行构建、E2E 和覆盖率防护。
