xiajingchun/dsh-nebulagraph-v5

dsh-nebula

A DeepSeek Harness plugin that connects to a NebulaGraph v5 server and executes ISO-GQL statements, in the spirit of the ngql console.

The plugin speaks the native NebulaGraph v5 wire protocol (gRPC + nebula.proto.graph.GraphService) with a pure-JS client — no native modules, no external gateway. Results come back as structured JSON rows plus an ngql-style ASCII table render.

Features

• Connect / authenticate against a graphd (nebula_connect), execute GQL on the same server-side session (nebula_execute), and close it (nebula_disconnect).
• Named instance profiles (Settings → NebulaGraph): manage any number of connection presets in the DSH settings page — each with its own host/port/user/passwordRef/TLS policy — addressed by a short alias. The model then just says "connect to the prod Nebula" and calls nebula_connect(instance: "prod"); the profile supplies the parameters. An instance can be marked as the default, used when no alias is given. Per-call tool arguments still override the profile.
• Decodes the columnar VectorResultTable payload exactly like the official nebula-go v5 client: scalars, strings, temporal values, lists, sets, maps, records, vertices, edges, paths, embedding vectors, geography, Any-typed columns, const vectors, and null bitmaps.
• Schema exploration (nebula_schema): one call runs SHOW GRAPHS, resolves the target graph (explicit graph= argument, the session working graph from SESSION SET graph, or the sole graph), then DESC GRAPH TYPE and returns the graph type's node types and edge types — labels, primary/multiedge keys, and properties. Read-only: the session working graph is never changed.
• Interactive graph rendering (Web Client): when a nebula_execute result contains nodes, edges, or paths, the result is projected into a replayable graph payload and the bundled Web Client plugin renders it as an interactive AntV G6 graph (drag / zoom / hover), alongside the normal table output.
• Bundles the gql-query-generator skill: the plugin registers a ctx.skills provider so the agent's skill tool can load NebulaGraph GQL-writing guidance (reference docs ship in gql-query-generator/references/ and resolve against the packaged directory).
• Plugin config supplies default connection parameters; every tool argument can override them per call.
• Password never travels through the model: nebula_connect takes a passwordRef (a credential reference / environment variable name), not the password value. The value is resolved per connection through the DSH credentials seam (ctx.credentials, falling back to the process environment) and cleared from memory right after authentication. Tool arguments, output, and the registry never carry the plaintext.
• TLS by default, plaintext fallback available: connections try TLS first (tls: "auto", the default) and fall back to plaintext only when the server has no TLS listener — the fallback is reported to the caller as a warning. Set tls: "on" to require TLS (fails if the server does not speak it) or tls: "off" to force plaintext. CA / client certificate / key / server name overrides are configurable for private CAs and mutual TLS.
• Unloading the plugin closes every open session (effect-based cleanup).