NebulaGraph 图库连接 xiajingchun/dsh-nebulagraph-v5

dsh-nebula

一个 DeepSeek Harness 插件，用来连接 NebulaGraph v5 服务器并执行 ISO-GQL 语句，风格贴近 ngql 控制台。

插件用纯 JS 客户端直接说 NebulaGraph v5 原生 wire 协议（gRPC + nebula.proto.graph.GraphService）——不需要原生模块，也不需要外部网关。结果以结构化 JSON 行返回，另外附带 ngql 风格的 ASCII 表格渲染。

功能

- 连接并认证 graphd（nebula_connect），在同一个服务端会话上执行 GQL（nebula_execute），最后关闭会话（nebula_disconnect）。
- 命名实例配置档（Settings → NebulaGraph）：在 DSH 设置页里管理任意数量的连接预设，每个预设都有自己的 host/port/user/passwordRef/TLS 策略，用一个短别名寻址。模型只要说「连接到 prod Nebula」，然后调用 nebula_connect(instance: "prod")；参数由配置档提供。可以把某个实例标为默认，不传别名时就用它。每次调用的工具参数仍然会覆盖配置档。
- 按官方 nebula-go v5 客户端的方式精确解码列式 VectorResultTable 载荷：标量、字符串、时间值、列表、集合、映射、记录、点、边、路径、embedding 向量、地理数据、Any 类型列、const 向量、null 位图。
- Schema 探查（nebula_schema）：一次调用先跑 SHOW GRAPHS，解析出目标图（来自显式 graph= 参数、SESSION SET graph 设置的会话工作图，或者唯一的图），再跑 DESC GRAPH TYPE，返回该图类型的点类型和边类型——标签、主键/多重边键、属性。只读：绝不改动会话工作图。
- 交互式图渲染（Web Client）：当 nebula_execute 的结果里含点、边或路径时，结果会投影成可回放的图载荷，由内置的 Web Client 插件渲染成一张可交互的 AntV G6 图（拖拽 / 缩放 / 悬停），与常规表格输出并列显示。
- 内置 gql-query-generator 技能：插件注册 ctx.skills 服务商，智能体的 skill 工具就能加载 NebulaGraph GQL 编写指南（参考文档随包发布在 gql-query-generator/references/，按打包目录解析）。
- 插件配置提供默认连接参数；每次调用时，任何工具参数都能覆盖它们。
- 密码绝不经过模型：nebula_connect 接收的是 passwordRef（凭据引用 / 环境变量名），不是密码值。密码值在每次连接时通过 DSH 凭据接缝（ctx.credentials，回退到进程环境）解析，认证完成后立刻从内存清除。工具参数、输出、注册表都不会携带明文。
- 默认启用 TLS，可回退到明文：连接先尝试 TLS（tls: "auto"，默认值），只有在服务端没有 TLS 监听时才回退到明文——回退会以警告形式告知调用方。设置 tls: "on" 强制要求 TLS（服务端不支持 TLS 就失败），设置 tls: "off" 强制使用明文。私有 CA 和双向 TLS 场景下，可以配置 CA / 客户端证书 / 密钥 / 服务器名称的覆盖值。
- 卸载插件会关闭所有已打开的会话（基于 effect 的清理）。

工具

| 工具 | 用途 |
| nebula_connect | 连接 graphd 并打开会话。参数：instance（在 Settings → NebulaGraph 中配置的配置档别名）、host、port、user、passwordRef、tls、ca、timeoutMs（全部可选）。解析顺序：显式 instance 别名 → 默认实例（如果设置了）→ 插件配置；单次调用的参数会覆盖配置档。密码本身从不作为参数传入——它通过 passwordRef 从 DSH 凭据接缝 / 环境变量解析。返回 connectionId（相关时还会返回 instance、viaDefault、warning 和 tlsFallback）。 |
| nebula_execute | 在某个连接上执行一条 GQL 语句。参数：connectionId（必填）、gql（必填）、timeoutMs。返回 { ok, columns, rows, numRows, latencyUs, summary?, error? }。 |
| nebula_schema | 内省图的 schema。参数：connectionId（必填）、graph（可选——默认取会话的工作图，再退回到唯一的图）。执行 SHOW GRAPHS + DESC GRAPH TYPE，返回 { graphs, graph, nodes, edges, … }。只读。 |
| nebula_disconnect | 关闭连接并释放服务端会话。 |

技能

插件在 ctx.skills 上注册名为 dsh-nebula 的 bundled 技能服务商，从打包的 gql-query-generator/ 目录提供 gql-query-generator 技能。模型可以通过 skill 工具加载它（或由用户直接调用）；它的 references/.md 通过技能的 resourceBase 解析到打包目录。每次加载都从磁盘读取技能正文，所以对链接安装的插件来说，编辑 SKILL.md 无需重新构建即可生效。

典型的智能体流程：

nebula_connect (host: 192.168.8.6, port: 9669, user: root, passwordRef: NEBULA_PASSWORD)
→ { connectionId: "…", tlsFallback: false }
nebula_execute (connectionId, gql: "SHOW GRAPHS")
nebula_schema (connectionId, graph: "movie")
→ { graphs: […], graph: { name: "movie", graphType: "movie_type", … },
nodes: [ { name: "Actor", labels: [Person], primaryKey: [id], … } ],
edges: [ { name: "Act", source: "Actor", target: "Movie", … } ] }
nebula_execute (connectionId, gql: "SESSION SET graph movie")
nebula_execute (connectionId, gql: "MATCH (n) RETURN n LIMIT 5")
nebula_disconnect (connectionId)

安装

插件是树外 DSH bundle：一个普通 npm 包，其 manifest 声明了 dsh.bundle 补丁。任何 DSH 安装都能一步安装它命令，来源任选其一（release tarball 最省事）：

运行时兼容性。 本次修订面向 dsh 0.2.0-rc.2 运行时世代（所有 @deepseek-ai/dsh- 包都统一到该版本，dsh-settings 0.2.0 用 schema 派生的条目表单替换了 settings-namespace API）。如果某个 bundle 的 peerDependencies 不接受当前运行的 dsh 版本，profile 加载器会拒绝挂载它；此时请安装较旧的 dsh-nebula 修订版（或它的 release tarball）来搭配 0.2.0 之前的运行时，不要用 dsh plugin allow-version 强行打开这道闸门。

recommended — the latest release's prebuilt tarball (stable URL, always current)
dsh plugin --profile web add https://github.com/xiajingchun/dsh-nebulagraph-v5/releases/latest/download/dsh-nebula.tgz

a specific release (versioned, reproducible)
dsh plugin --profile web add https://github.com/xiajingchun/dsh-nebulagraph-v5/releases/download/v0.2.0/dsh-nebula-0.2.0.tgz

from the npm registry (once published)
dsh plugin --profile web add dsh-nebula

straight from the git repository (builds from source — see note below)
dsh plugin --profile web add github:xiajingchun/dsh-nebulagraph-v5#v0.2.0

from a local tarball / checkout while developing
dsh plugin --profile web add /path/to/dsh-nebula-0.2.0.tgz
dsh plugin --profile web add link:/path/to/dsh-nebula

release tarball 就是 pnpm pack 的产物：lib/ 已经预构建好，所以从 release 和 registry 安装都不需要在安装时构建，也不需要批准构建脚本。安装过程会在 profile 目录里执行 pnpm add，然后把 dsh-nebula 追加到 dsh.profile.bundles，因为该包声明了 dsh.bundle 补丁（cordis.patch.yml 会插入插件行）。重启 profile（dsh web）让新 bundle 挂载。

从 git 安装会从源码构建。 pnpm 拉取的是源码，不是构建产物：它会运行包的 prepare 脚本（这里是 pnpm build），这需要开发工具链，而且 pnpm ≥10 在显式允许之前会拒绝运行该脚本——第一次 add 会失败并打印出包名键。把这个键复制到 profile 的 pnpm-workspace.yaml 里的 allowBuilds 下，然后重新运行。想避开这些麻烦，优先用 release tarball 或 registry 安装；如果确实要从 git 安装，请固定到某个提交（github:…/#<sha>）。

nodeLinker: hoisted 的 profile 必须批准 protobufjs 构建脚本（随附的 web profile 已经批准了）。

发布（供维护者参考）

每次 推送 v 标签都会触发 GitHub Actions 工作流（.github/workflows/release.yml）：它会校验标签与 package.json 的版本是否一致，然后安装、跑测试、打包，并把带版本号的 dsh-nebula-<version>.tgz 和稳定的 dsh-nebula.tgz 别名一起上传到 release——所以 releases/latest/download/dsh-nebula.tgz 永远指向最新的构建：

git tag v0.2.0 && git push origin v0.2.0

手动操作（结果相同，不走 CI）：

sh
pnpm build && pnpm pack # → dsh-nebula-0.2.0.tgz

attach the tarball to a GitHub release (optionally also as dsh-nebula.tgz)

如果改用 npm 发布： sh
npm login # once
pnpm publish # runs build + tests via prepublishOnly

tarball（pnpm pack → dsh-nebula-0.2.0.tgz）完全自包含：编译后的 lib/、内置的 protos、打包好的 gql-query-generator/ 技能（含它的 .feature 证据文件）、cordis.patch.yml、README 和 LICENSE。验证方式是把这个 tarball 装进一个全新的临时配置档：bundle 会加入 dsh.profile.bundles，模块能正常解析，技能服务商也能列出并加载 gql-query-generator，其资源基址就在安装好的包内。

配置

插件配置放在配置档的补丁层里（例如 ~/.dsh/profiles/web/cordis.patch.yml）： yaml
- insert:
- id: nebula
name: dsh-nebula
config:
host: 127.0.0.1
port: 9669
user: root
passwordRef: NEBULA_PASSWORD # preferred: credential reference (env var name)
tls: auto # auto | on | off
timeoutMs: 30000
maxConnections: 5

| 字段 | 默认值 | 含义 |
| host | 127.0.0.1 | 默认 graphd 主机。 |
| port | 9669 | 默认 graphd gRPC 端口。 |
| user | root | 默认登录用户名。 |
| passwordRef | （无）* | 凭据引用（环境变量名），通过 DSH 凭据接缝解析出默认密码。优先于 password —— 值永远不会出现在配置界面、工具参数或日志里。 |
| password | '' | 默认登录密码（明文）。仅在 passwordRef 未设置时作为回退；不要写进共享配置文件。 |
| tls | 'auto' | TLS 模式：auto（先试 TLS，服务端没有 TLS 监听时回退到明文）、on（强制 TLS）、off（仅明文）。 |
| ca | （无） | 用于校验服务端证书的 CA 包（PEM）（私有 / 自签名 CA）。 |
| cert / key | （无） | 双向 TLS 的客户端证书和私钥（PEM）。私钥只存在于配置里，永远不会作为工具参数暴露。 |
| servername | （无） | 覆盖用于 SNI 和证书校验的服务端名称。 |
| timeoutMs | 30000 | 默认单请求超时（毫秒）。 |
| maxConnections | 5 | 同时打开的连接数上限。 |

要用 passwordRef，把值存进 DSH 凭据文档（~/.dsh/.credentials.yaml，权限 0600）或进程环境，例如： yaml

~/.dsh/.credentials.yaml

NEBULA_PASSWORD: s3cr3t

密码在 nebula_connect 时按连接解析，认证成功后立即从内存中清除。

实例配置档（Settings → NebulaGraph）

@ Settings
配置档组合出 settings 服务商时（Web GUI 就是这样），插件会拥有一个 Settings → NebulaGraph 页面。在这里你可以：
- 添加连接预设——每个预设包含 alias（字母/数字/_/-，≤ 64 字符）、host、port、user、passwordRef、TLS 模式、每个实例独立的 CA / 客户端证书 / 密钥 / servername、timeoutMs，以及一条备注。
- 编辑 / 删除预设，并将其中一个标记为默认。
- 在同一个页面管理 passwordRef 背后的凭据值：实例引用的每个引用（再加上你额外添加的引用，例如插件配置默认值所用的）都会得到一个只写密码字段和一个清除按钮。值通过 harness credentials RPC（credentials.set / credentials.unset）写入，并持久化到 DSH 凭据文档（~/.dsh/.credentials.yaml）。页面只显示某个值是否已配置——从不显示值本身——输入框始终以空白开始。
- 密码绝不进入存储的配置：只存储 passwordRef（凭据引用 / 环境变量名），连接时通过 DSH 凭据接缝解析，与插件配置默认值一样。

从 dsh-settings 0.2.0 起，该区段存储在插件自己的配置档条目中（cordis.patch.yml 里 nebula 行的 instances、defaultInstance 和 credentialRefs 字段），而不是单独的 settings 文档：dsh 根据每个条目的 Config schema 推导出可编辑表单，只有易变字段可实时编辑，因此这三个字段在那里声明为 .volatile()。插件用 settings.configure({ auto: false }) 注册页面，以退出基于 schema 推导的自动页面。因此升级 0.2.0 之前的安装需要一次性把旧的 dsh-nebula: 区段从 ~/.dsh/settings.yaml（运行时将其重命名为 settings.yaml.imported）移入 nebula 条目的 config: 块；插件的 instances/defaultInstance/credentialRefs 字段名与旧区段键名一致，因此值可原样复制。

nebula_connect 解析顺序：

1. 显式 instance: <alias>——未知 alias 是硬错误，会列出已配置的 alias；
2. 默认实例（若已设置）（连接输出报告 viaDefault: true；过期的默认值引用已删除的实例时回退到插件配置，并给出 warning）；
3. 插件配置（cordis.patch.yml）。

每次调用的 host/port/user/passwordRef/tls/ca/timeoutMs 参数仍会覆盖解析出的配置档。配置档内非 auto 的 TLS 模式与插件配置一样是强制传输策略：冲突的 tls 工具参数会被拒绝。

页面由插件的 Web Client bundle（client/NebulaInstancesSection.tsx）实现，它通过插件自有的 Web 路由（/dsh-nebula/api，见 src/instances-api.ts）读写该区段，使用与 harness gateway 相同的浏览器信任围栏。该路由根据 Loader 记录在插件 fiber 上的 id 解析条目，并在每个视图中回传，因此客户端可以过滤转发 settings/document-updated 事件时，只针对那个命名空间。插件自有的路由仍然必不可少，因为客户端 bundle 无法知道配置档条目 id，也因为 harness 自己的 settings RPC 无法表达插件的跨字段校验（重复别名、空主机），而路由会在每次写入前跑这些校验。宿主在连接时读取同一批实时配置引用（src/instances.ts）。没有 settings 服务商或 web 界面时，路由干脆永不挂载，插件仅靠插件配置照常工作。

开发 sh
pnpm install
pnpm typecheck
pnpm build # tsc → lib/ + copies vendored protos to lib/proto
pnpm test # decoder unit tests + gRPC integration tests (in-process fake GraphService)

本包是纯 ESM（"type": "module"），除 @grpc/grpc-js、@grpc/proto-loader 和 @deepseek-ai/schemastery 外没有运行时依赖（后者是运行时的 schemastery 构建：只有它实现了 settings 集成所需的 .volatile() 配置字段）。

加载链接的开发检出

dsh plugin --profile <name> add link:<checkout> 会把本包以符号链接形式装进配置档，配置档加载器再把该符号链接解析到真实路径——因此 lib/ 内部的每个 import 都针对这个检出解析，而不是配置档的 node_modules。所以，没有自行安装依赖的检出会加载失败，报错如下

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'schemastery' imported from
.../dsh-nebula/lib/index.js

依赖有任何变动后，都要在检出里跑 pnpm install && pnpm build。改用打包好的 tarball 或 git 依赖安装，会得到一份真实副本，依赖嵌在它旁边，代价是无法实时编辑。

工作原理

- 协议 —— src/proto/nebula/ 下的内置 proto 是官方 NebulaGraph 5.0 定义（graph/common/vector），来自 nebula-go v5。AuthRequest.auth_info 是 JSON.stringify({ password })，ClientInfo.lang 声明为 JAVASCRIPT；Status.code == "00000" 表示成功。密码只在一次性的 Authenticate 调用里发送，成功后立即从 client/registry 选项中清除。
- 传输安全 —— 通道按 tls 模式使用 gRPC 凭据：on → createSsl（可选 CA / 客户端证书 / server-name 覆盖），off → createInsecure，auto → 先试 TLS，仅当握手在传输层失败时才用明文凭据重建通道（认证失败绝不重建）。明文回退会在连接输出里以 tlsFallback 呈现，并输出一行警告。
- 登出 —— v5 gRPC 服务没有 signout RPC；关闭会话时先执行 SESSION CLOSE 语句，再释放通道（对应 nebula-go v5 的 connection.Close()），这样服务端会话立即释放，而不是一直滞留到空闲超时。
- Decoder — src/decode/ 是 nebula-go v5 internal/decode 的忠实 TypeScript 移植（列类型 schema、flat/const 向量布局、分块字符串、节点/边属性向量、路径邻接表、复合值编码）。
- Registry — 打开的连接放在每个插件各自的注册表里；销毁插件会关闭全部连接。
- Instance profiles — 实例列表属于插件自己的配置档条目：instances / defaultInstance / credentialRefs 是插件 Config schema 的 .volatile() 字段，dsh-settings ≥ 0.2.0 会把它们投射成可编辑表单，并提交到运行中配置的实时引用里——所以保存设置永远不会重新挂载插件。没有 settings 服务商时，这些字段保持 schema 默认值（空 section），工具则像以前一样回退到配置，同时 Web GUI 通过插件自有的 /dsh-nebula/api 路由编辑同一个条目。别名解析与校验是 src/instances.ts 里的纯函数，由工具和设置界面契约共用。

License

MIT