dsh-knowledge-graph

English | 中文

DSH (DeepSeek Harness) Cordis plugin: turn any piece of source text — or an AI session execution trace — into an AI-generated knowledge graph, with two-way linking between the graph and the original text.

> Paste text → AI asynchronously builds the graph → two-way anchor navigation. A standalone, reusable plugin realization of NovelStudio's "资料 ⇄ 知识图" (Source ⇄ Knowledge Graph).

---

What it does

• Asynchronous AI extraction: paste any text (chapters, technical docs, study notes…); a background task calls the LLM and returns a knowledge graph in ~15–40 s. documentId is a random stable logical-document UUID, sourceId is a SHA-256 identity of the complete immutable source version, and each chunkId binds sourceId + batch + paragraph range, so different documents and appended source versions cannot overwrite one another through local chunk-0001 reuse. In persistent mode the full source, canonical graph, and lossless checkpoint live in SQLite; the browser restores by documentId/runId, and only a running task orphaned by a Host restart may resume from checkpoint. Explicit failed/cancelled tasks are never auto-retried.
• 8 node types / 12 relation types:

- Nodes: fact · claim · inference · concept · definition · example · counter_example · rule. - Relations: supports · example · counter_example · defines · infers · causes · is_a · contains · driven_by · not_is · analogy · aims_at. - Minimal semantic contract: one node expresses one atomic proposition; source/author theories and empirical generalizations use claim rather than fact; qualifiers such as “possible / most / usually / must / if” must be preserved; use a precise semantic relation instead of falling back to supports when the source makes that relation explicit. - Explanatory coverage review: after the first extraction passes deterministic admission, a bounded second look runs only when a multi-step mechanism appears underrepresented or the source explicitly states a correction / anti-misinference boundary / answer deferred to later text that the graph omitted. It may also recover a stable concept anchor reused by multiple core propositions. The review may only add missing nodes plus necessary incident relations; it cannot rewrite the accepted graph or add knowledge merely to improve connectivity.

• Relation-aware layered layout: layered mode treats causes/infers as the reasoning backbone and keeps examples, analogies, counter-examples, definitions, and concept relations as nearby branches. New users default to layered layout; existing saved layout preferences are preserved.
• Two-way linking:

- Click a graph node → opens a detail card (full content + verbatim quote + locate button) and smoothly scrolls to and highlights the matching content unit; - Click a source content unit → the graph centers on and pulses the corresponding node. - Nodes in the graph render only the first 4 lines (overflow collapses to …); the full content is always available in the detail card; - Anchoring primarily uses the content-unit index the AI reports directly (deterministic — long natural paragraphs are split into numbered units at sentence boundaries), with exact-quote matching and token-overlap scoring as fallbacks; nodes that cannot be linked are never guessed into an offset — they go to a diagnostics list.

• Graph rendering: SVG canvas + 8-color node palette / 4 switchable layouts (dropdown at the graph's top right, choice remembered): Force (embedded d3-force engine, zero dependencies: collision avoids node overlap, edge–node repulsion keeps arrows from crossing nodes), Circular, Radial (central hub + BFS rings; edges drawn as polylines: radial exit → outer arc → radial entry), Layered (edges drawn as orthogonal right-angle polylines: inter-row channels + per-row obstacle corridors; segments never cross nodes) / relation edges carry type labels, and edges sharing a source fan out by target angle (quadratic Bézier) / drag to pan / Ctrl+wheel to zoom / toolbar − 100% + (50%–200%, 10% steps) / long-press a node to see the verbatim quote / keyboard accessible.
• Verify & question the graph: once a graph exists, check whether it is faithful to the source text —

- ⚡ Quick check: instant local rules (self-loops/dangling edges, quote grounding, paragraph-vs-quote mismatch, type–relation semantic rules, duplicate / suspected-contradiction nodes, isolated nodes, coverage stats); - 🤖 AI deep audit: an asynchronous LLM pass adversarially reviews each node/edge; every issue must cite verbatim source evidence, and the standard mode runs a second confirmation pass to suppress false positives; - Human-in-the-loop fix: issues are listed by severity (error / warning / suggestion); clicking an issue tints the graph target by severity and scrolls to the source paragraph; each issue can be applied (patched immediately, written to an audit log) or dismissed; a fix all button applies every automatically fixable issue at once, and the fix log shows concrete old → new diffs; - Ask questions: the node detail card offers question this node, selecting an edge shows an edge card with question this relation, and the verification panel lets you question the whole graph; the AI answers with one of supported / contradicted / insufficient / out-of-scope plus source evidence; - 🔎 External fact-check of the source: fact/claim/inference/rule/definition/counter-example nodes become checkable claims and are judged against external evidence (built-in free Wikipedia retrieval plus optional pasted domain-rule sources); verdicts are supported / contradicted / partially supported / insufficient / unverifiable / out-of-scope, every conclusion carries an evidence link and a verbatim evidence quote (quotes that cannot be located in the retrieved snippets are automatically downgraded); - Verification / fact-check results are persisted with the graph; appending new content marks them stale for re-running. The trajectory graph tab supports all of the same capabilities.

• Floating workbench: draggable, resizable window; the width ratio between text and graph and the result area height are both drag-adjustable and remembered.
• Select-to-split: select any text inside a chat message; a "拆成知识图" (split into graph) button floats above the selection — one click opens the workbench and splits the selection; selecting text in the result's source column splits it as a sub-graph; selecting part of the input textarea also offers "split selection".
• Incremental append (追加拆分): once a result exists, the input panel's primary button becomes 追加拆分 (append split) — paste the next passage / document and the AI extracts ONLY the new content, linking it into the existing graph via cross-passage edges (a concept that reappears is not duplicated — it gets an edge straight to the existing node); the result merges in place, paragraph numbering stays unified across the whole text, and the history entry updates in place. Selecting text in a chat message while a result exists appends it to the current graph automatically.
• History: every successful split records a lightweight browser index (up to 20 entries, deletable one-by-one or all); the browser keeps only documentId, title, counts, and timestamps, then reloads the source and canonical graph from Host/SQLite instead of copying book-sized payloads into localStorage.
• Chapter filtering and candidate review: filter the graph and source paragraphs by chapter; review evidence-bearing entity / claim candidates as candidate / accepted / rejected and click a candidate to jump back to its source. Decisions sync through the Host to SQLite (dynamic plugins retain them in the Host session, with browser localStorage as fallback).
• Knowledge graph export: the graph toolbar exports the current rendered graph as a high-resolution PNG image, and the result toolbar exports the complete graph as JSON (including source, chunk, evidence, verification, and audit data) or as separate node and edge CSV files. Data exports always contain the full graph, independent of the active chapter filter; trajectory graphs support the same exports.
• Persistent entry: a permanent 「知识图」button on the right of each conversation header; run cards also get a launch bar.
• Trajectory knowledge graph (conversation view tab): a third tab 「轨迹知识图」(beside 对话 / 轨迹) turns the current session's full execution trace (user messages, tool calls, tool results, assistant replies) into a knowledge graph — visualizing what the agent found, inferred, and did — with two-way linking between graph and trace events. Results are canonical Host/SQLite documents; the browser stores only the trajectory documentId/revision reference, so tab switches or page reloads rehydrate from canonical state rather than from a copied graph. Leaving mid-extraction and returning resumes polling automatically. Once the session produces new events, 追加新事件 (append new events) submits the same document id plus the expected revision, reloads the complete canonical graph Host-side, and merges only the new events; hidden nodes beyond the 800-node browser window therefore cannot be lost. The event-column / graph-column width and result height remain drag-adjustable and remembered.

Screenshots

Floating workbench:

<img width="1538" height="945" alt="image" src="https://github.com/user-attachments/assets/824ab99b-d291-4d06-8eb7-b91e947b1af4" />

┌────────────────────────── Floating Workbench ──────────────────────────┐
│ ● Knowledge · Source ⇄ Knowledge Graph                     [ × ]        │
│ [Source text ────────────── collapse ▴]                                 │
│ [Source ⇄ Knowledge Graph]                                              │
│ One-line summary: …                                                     │
│ N nodes · M relations · X/Y linkable ─────────────────────┐             │
│ [paragraphs…badges]  ‖  [graph SVG…]  [− 100% +]  ← drag  │             │
│ ─────────────── drag height ───────────────               │             │
└────────────────────────────────────────────────────────────────────────┘

Trajectory knowledge graph tab:

<img width="3377" height="1720" alt="image" src="https://github.com/user-attachments/assets/5dfef153-25a0-431e-970c-dc344eef53d5" />

┌────────────────────── Trajectory ⇄ Knowledge Graph ─────────────────────┐
│ Split this session's trace: user / tool call / tool result / AI reply   │
│ One-line summary: …                                                     │
│ [trace events…badges]  ‖  [graph SVG…]  [− 100% +]  ← drag width        │
│ ────────────── drag height ──────────────                               │
│ (result restored after tab switch / page reload)                        │
└─────────────────────────────────────────────────────────────────────────┘

Installation

This is a DSH dynamic Cordis plugin: one Host half (Node process) + one Client half (browser), plain JS, zero dependencies, no build step. It loads through DSH Web's Cordis plugin mechanism and works in any DSH Web session.

0. Prerequisites

• DSH Web is running (dsh web) and you are inside a session;
• An AI model provider is configured (Settings → Models, or agentDefaultModel). The plugin follows the system default by default; both the workbench and the “Trajectory Knowledge Graph” tab include a model dropdown so you can manually choose the model used for extraction, appends, AI audit, questioning, and external fact-checking (the choice is saved in browser local storage). If none is configured, it shows a clear Chinese error message.

1. Get the source

git clone https://github.com/cwbcheng/dsh-knowledge-graph.git
cd dsh-knowledge-graph

2. Install (pick one)

Option A: let an Agent install it (recommended)

Send this to the Agent in any session (replace the path with your clone location):

> Please read src/index.host.js and src/index.client.js from the dsh-knowledge-graph repo, define these two files as the Host half and Client half of a Cordis plugin, and run it.

The Agent runs cordis_define (define) → cordis_run (run); an approval card pops up in the UI.

Option B: paste the source and define it yourself

1. Run a cordis_define in any session (have the Agent do it, or follow your environment's Cordis tool flow); 2. Paste src/index.host.js into the Host half and src/index.client.js into the Client half; 3. Paste the function body: strip the export default function hostPlugin() { / export default function clientPlugin() { line and the matching trailing }, keep the return { ... }; part in between (the header comment may be kept or dropped).

> Not familiar with cordis_define? Use Option A — the Agent handles the function-body extraction automatically.

Option C: persistent install (recommended — survives restarts)

Install the repo as a web-profile composition plugin (same community-plugin package shape as dsh-hud): the Host half serves a webServer route, the Client half is a __ModuleLoader__ browser module; it auto-loads with dsh web — no redefinition after every restart, no approval.

# 1. Add the dependency and bundle to the profile ($DSH_HOME defaults to ~/.dsh)
cd ~/.dsh/profiles/web
#    add to package.json dependencies:
#    "dsh-knowledge-graph": "github:cwbcheng/dsh-knowledge-graph#main"
#    add to package.json dsh.profile.bundles:
#    "dsh-knowledge-graph"
pnpm install

# 2. Restart dsh web (Ctrl+C, then `dsh web` again)

After the restart: the 「知识图」button appears at the right of each conversation header. Browser localStorage keeps only lightweight UI state such as layout and history indexes; source text, graph, checkpoints, and revisions are persisted by Host/SQLite.

> src/ and lib/ are two deployment shapes of the same plugin: src/ for the dynamic plugin (Options A/B), lib/ for the persistent composition (Option C); the logic stays in sync.

3. Approve the run

After defining, the run enters awaiting approval:

• The plugin panel (bottom-left Cordis Plugin button) pops up automatically and highlights the row awaiting approval;
• Click ✓ (single check): authorize this run only; click ✓✓ (double check): also authorize automatic runs of future versions (recommended);
• After approval the plugin activates in the browser and the panel shows running.

4. Verify the install

• The 「知识图」button appears at the right of the conversation title (header action row);
• Click it → the floating workbench opens; paste a text → AI 拆分; a knowledge graph appears in ~15–40 s;
• A third tab 「轨迹知识图」appears at the top of the conversation area (对话 / 轨迹 / 轨迹知识图); click it → 拆解本会话轨迹; the session's trajectory graph appears in ~15–40 s.

5. SQLite persistence and CLI

The CLI uses Node node:sqlite and currently requires Node 22.5+; it has no extra npm dependency. It persists a KnowledgeGraphDto, then exposes evidence-bearing entity and claim candidates for human review.

npm run kg -- init --db ./data/knowledge.sqlite
npm run kg -- import-graph --db ./data/knowledge.sqlite --input ./graph.json
npm run kg -- list-candidates --db ./data/knowledge.sqlite --kind entity --status candidate
npm run kg -- list-candidates --db ./data/knowledge.sqlite --kind claim --status candidate
npm run kg -- set-candidate --db ./data/knowledge.sqlite --kind entity --id ent_xxx --status accepted
npm run kg -- set-candidate --db ./data/knowledge.sqlite --kind claim --id clm_xxx --status rejected
npm run kg -- list-documents --db ./data/knowledge.sqlite
npm run kg -- show-document --db ./data/knowledge.sqlite --id document_xxx
npm run kg -- save-checkpoint --db ./data/knowledge.sqlite --input checkpoint.json --run-id run_xxx
npm run kg -- load-checkpoint --db ./data/knowledge.sqlite --run-id run_xxx

The persistent lib/index.js writes each successful chunk and completed graph to SQLite automatically. Set DSH_KG_DB to choose the database path; otherwise it uses .dsh-knowledge-graph.sqlite in the current working directory. npm run test:kg verifies graph/chunk/evidence persistence, candidate state changes, checkpoint storage, and document restoration in an in-memory SQLite database; npm run test:kg-candidates additionally covers dynamic Host RPC and persistent HTTP/SQLite candidate list/update flows. The persistent build also copies [lib/kg-store.mjs](lib/kg-store.mjs).

Updating

• Dynamic install (A/B): repeat Option A after repo updates — have the Agent re-read both source files and cordis_define (append a new Package under the same plugin), then cordis_run (update mode) to switch versions; if you previously clicked the double check, new versions run automatically.
• Persistent install (C): after updates, re-run pnpm install (pulls latest #main) and restart dsh web.

Uninstalling

• Dynamic install: open the Cordis Plugin panel → click Stop on the plugin row to pause; use cordis_undefine to delete the definition entirely.
• Persistent install: remove the dependency and bundles entries from the profile's package.json, then pnpm install and restart.

Window layout, history indexes, and other lightweight UI state live in browser localStorage; book-sized sources, canonical graphs, checkpoints, and graph revisions live in Host/SQLite in persistent mode. Keep the SQLite database or export JSON/CSV before uninstalling if you need long-term retention.

Notes

• A dynamic plugin runs inside the DSH process: it disappears after a process restart and must be reinstalled (Option A, or switch to persistent Option C; browser data remains); the persistent plugin loads with the service and is unaffected by restarts;
• The Host half needs a working LLM (see prerequisites); AI calls happen only inside your own DSH environment — whether they leave it depends on the model provider you configured;
• This project has no paid / quota features: extraction, history, and two-way linking all run locally.

Usage

1. Click the 「知识图」button at the right of the conversation title to open the floating workbench; 2. Paste text into 「输入资料」(title optional), click AI 拆分 (the input area collapses; result height and text/graph width ratio are drag-adjustable and remembered); 3. Once th

…