Luke-Yong/dsh-plugin-knowledge-graph

dsh-plugin-knowledge-graph

一个 DeepSeek Harness (DSH) 插件，它暴露了一个由代码库知识图谱支持的 read_graph 工具。该图谱追踪每个文件、目录、导出的符号及其关系，使 agent 能够比 grep 或阅读文件更快地回答结构和依赖关系问题。

状态：初期阶段。 本项目处于初期阶段。在项目由开源社区迭代和测试期间，执行行为、查询接口和兼容性可能会发生变化。

衍生作品。 本项目衍生自 Luke-Yong/H 中的知识图谱工具，并适配了 DeepSeek Harness 的“一切皆插件”模型。

功能

给定一个工作区根目录，该插件会构建一个内存中的图谱，并回答如下查询：

- structure — 打印完整的目录树
- exports  — 列出某个文件导出的每个符号
- imports_of  — 列出某个文件导入的符号（及其来源文件；标准库/第三方导入会被标记）
- exporters_of  — 找出哪些文件导出了某个符号
- dependents  — 找出哪些文件从某个文件导入
- unused_imports  — 列出文件中从未被引用的导入

符号从 TypeScript/JavaScript（通过 TypeScript 编译器 API）和 Python（模块级 def、class 和 name = value 绑定）中解析。

图谱模型

该图谱使用三种节点类型和四种边类型：

| 节点 | 含义 |
| --- | --- |
| dir | 一个目录 |
| file | 一个源文件 |
| symbol | 一个导出的符号（函数、类、常量、类型、接口、枚举、默认导出） |

| 边 | 含义 |
| --- | --- |
| CONTAINS | 结构上的父 → 子（目录 → 目录/文件，文件 → 符号） |
| EXPORTS | 文件 → 它导出的符号 |
| IMPORTS | 文件级依赖（文件 → 文件） |
| IMPORTS_SYMBOL | 精确的符号级依赖（文件 → 符号） |

安装

使用 DSH CLI 安装到某个 profile 中：

dsh plugin --profile web add github:Luke-Yong/dsh-plugin-knowledge-graph

固定到特定 commit 以保证可复现性：

dsh plugin --profile web add github:Luke-Yong/dsh-plugin-knowledge-graph#

用法

该插件在 ctx.tools 上注册单个工具 read_graph。其参数如下：

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| query | string | 是 | 形如   的查询字符串 |
| root | string | 否 | 要构建图谱的绝对工作区根目录。默认为 process.cwd() |

根目录卫生： root 的默认值（process.cwd()）可能是一个包含多个独立项目的父目录。请始终显式传入 root，指向你正在使用的单个工作区，这样 structure 就不会深入到同级目录树中。

查询示例：

exports src/index.ts
exporters_of buildKnowledgeGraph
imports_of src/query.ts
dependents src/knowledgeGraph.ts
unused_imports app.py
structure
项目结构

src/
index.ts         插件入口 — 注册 read_graph 工具
knowledgeGraph.ts  图构建器（文件系统遍历、导入/导出解析、序列化）
query.ts         查询引擎（runGraphQuery）

构建

npm run build   # tsc -p tsconfig.json

输出生成到 dist/（dist/index.js 是包的入口点）。

许可证

MIT