bkn-dsh

bkn-dsh

中文

Bring governed OpenBKN business knowledge into DeepSeek Harness conversations.

Why

Enterprise decisions need trusted business objects, metrics, rules, relationships, and permission-aware evidence. General-purpose chat alone does not provide that governed context.

What

bkn-dsh is an additive DeepSeek Harness plugin that lets authorized users select one OpenBKN business knowledge network for a conversation, analyze within that explicit scope, and inspect available business provenance for each completed answer.

Version prerequisite: the provenance views need a valid OpenBKN token and a businessDomain the deployment allows (x-business-domain; the stock chart allow-lists bd_public, no admin action needed). Verified against OpenBKN 0.1.4: the observability read routes have no license gate, so community deployments show the full provenance panel; the business graph may carry fewer enriched references there (enterprise optimizer, unverified). No upgrade prompt is ever shown for reads — a 403 always means the domain or account was refused.

Who it serves

• Business users and analysts who need explainable, governed analysis.
• Knowledge-network owners who want their business semantics reused consistently.
• Enterprise AI platform teams that need least-privilege knowledge access without exposing unrestricted data interfaces.

Business value

• Grounds analysis in authorized business semantics and current platform data.
• Keeps each conversation in one explicit, immutable knowledge-network scope.
• Preserves native DeepSeek Harness workflows while adding traceable OpenBKN context.
• Reduces the cost of reaching trusted business insight without requiring query-language expertise.

The published package README contains the same product overview for package consumers.

Install and start

Recommended: OpenBKN-compatible DSH Runtime

For users of DSH 0.2.0-rc.2, download the matching OpenBKN Runtime archive from the project releases. It contains the pinned DSH runtime, the version-fenced compatibility bridge, and the bkn-dsh plugin artifact. It uses DSH's native plugin manager on first start; it does not patch or change an existing DSH installation.

The only prerequisite is Node.js ^22.19.0 or >=24.0.0 (matching the pinned DSH release). Runtime archives are published for darwin-arm64 and win32-x64; there is no Intel-mac (darwin-x64) build. The release profile is created with DSH's native plugin manager at build time and is copied into the isolated home on first start, so customers do not need pnpm or registry access.

1. In the download directory, verify the archive with its adjacent .sha256 file, then unpack it:

   shasum -a 256 -c openbkn-dsh-runtime-*.sha256
   

2. Start the bundled DSH Web runtime:

   ./openbkn-dsh-runtime-*/bin/dsh web
   

   On Windows, run bin\\dsh.cmd web from the unpacked directory and verify the release checksum with Get-FileHash before unpacking.

3. In DSH Web, click OpenBKN in the sidebar. Enter the OpenBKN platform address, complete the guided CLI sign-in or enter a platform token, and test the connection.

4. Select an authorized business knowledge network. Create its local workspace or continue an existing one, then start the business conversation.

The runtime keeps its profile under an isolated OpenBKN DSH home (OPENBKN_DSH_HOME can override it), so it does not alter ~/.dsh. The platform address is a non-sensitive DSH setting; the token is stored only in DSH credentials. Do not put an OpenBKN token in Cordis YAML.

Official DeepSeek Harness desktop app

The plugin also runs on the official DeepSeek Harness desktop app 0.2.0-rc.2 without changing the app. Verified on macOS arm64: install, binding, Q&A with tool calls, business provenance, and reopening a session after an app restart (evidence). This needs a plugin build that keeps its state out of the DSH session log (#48, on main after the 0.2.0-rc.2-openbkn.0.2.0 release). The published 0.2.0-rc.2-openbkn.0.2.0 predates it: sessions it binds in the desktop app refuse to reopen after a restart. Until the next plugin release, build the package from main (pnpm --filter @openbkn/dsh-business-context pack).

1. Start the desktop app once so it initializes its profile, then quit it completely.

2. Install the plugin with the app's bundled command (the app menu Manage dsh command… can also put dsh on your PATH):

   "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" plugin --profile desktop add file:<path-to-plugin-tgz>
   

3. Set the platform address in the desktop profile's patch layer, ~/.dsh/profiles/desktop/cordis.patch.yml (under $DSH_HOME if you set one):

   - id: openbkn-business-context
     config:
       baseUrl: https://<your-openbkn-platform>
   

4. Sign in once with openbkn auth login <platform-url>. The plugin reads the token through the openbkn CLI, so the CLI must be on the PATH your login shell sets up (the desktop app loads the login-shell environment).

5. Reopen the app, click OpenBKN in the sidebar, pick a network and a workspace, and start the business conversation.

Self-signed platform certificates are verified only with the app started from a terminal as NODE_EXTRA_CA_CERTS=<platform CA pem> "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness"; exporting the variable from the login shell for a Dock launch is untested. The Windows desktop app is untested. Uninstall with dsh plugin --profile desktop remove @openbkn/dsh-business-context while the app is closed.

Source-build path: plugin package + compatibility patch

Two artifacts work together on your own DSH source checkout at the exact upstream revision dsh-v0.2.0-rc.2:

1. Plugin package — openbkn-dsh-business-context-<version>.tgz (from the project releases, or build it with pnpm --filter @openbkn/dsh-business-context pack). It installs and uninstalls through DSH's native plugin manager.

2. Compatibility patch script — compat/dsh-0.2.0-rc.2/ in this repository, applied to the DSH source tree before you build it:

   git clone --depth 1 --branch dsh-v0.2.0-rc.2 https://github.com/deepseek-ai/deepseek-harness.git ~/dsh-src
   node compat/dsh-0.2.0-rc.2/apply.mjs  --dsh ~/dsh-src   # from this repository
   node compat/dsh-0.2.0-rc.2/verify.mjs --dsh ~/dsh-src
   cd ~/dsh-src && pnpm install && pnpm build
   pnpm dsh plugin --profile web add file:<path-to-plugin-tgz>
   

Plugin builds from #48 on no longer need the patch at run time. They write nothing to the DSH session log: the network binding lives in $DSH_HOME/openbkn/session-bindings/, and provenance and conversation continuity are re-derived from DSH's own logged tool results. Sessions therefore reload on an unpatched DSH and stay readable after the plugin is uninstalled (verified on the official desktop app, which ships the same unpatched session code). The series is still what builds the plugin package and the Runtime from source: patch 0001 lets DSH's Typert generator recognize the plugin's published protocol. Plugin builds released before #48 — including the published 0.2.0-rc.2-openbkn.0.2.0 — still need patch 0002 (the ignorable session-event write side): on an unpatched DSH their persisted session events are rejected on every restart. The patch is fail-closed and must not be applied to a desktop bundle or another DSH version; revert it with apply.mjs --revert before changing DSH versions. See the compatibility package and the step-by-step install guide (configuration, credentials, uninstall, known caveats).

Known upstream limitation: running DSH directly from source in dev form breaks tool dispatch for any plugin (Cannot read properties of undefined (reading 'prepare')); full Q&A requires a packaged form — the recommended Runtime above, or scripts/build-compatible-runtime.mjs --dsh <clean-checkout> --output <dir> from this repository.

Known plugin limitation: binding records are not removed when a DSH session is deleted (a few hundred bytes each under $DSH_HOME/openbkn/session-bindings/); delete stale ones by hand if needed.

Known plugin limitation: a turn that is cancelled or fails between bkn_start_interaction and bkn_finish_interaction leaves that Interaction unclosed on the platform side. The plugin deliberately does not auto-finish it (the platform semantics of an injected finish are not yet verified); it logs a payload-free warning instead, and observability should track the unclosed-Interaction count. Automatic closing is future work.

Prerequisites and trial path

The plugin needs a reachable OpenBKN platform with at least one knowledge network you can access.

1. Platform — run one locally with bkn-foundry (deploy/dev/mac.sh on macOS; Docker engine with ≥16 GB memory), or use your organization's deployment.
2. Sample data — import a sample knowledge network from bkn-samples (supply_ontology_hand is the primary end-to-end dataset).
3. Credentials — openbkn auth login <platform-url> once; the plugin reads the token through the CLI handshake only.
4. Bind — open the OpenBKN panel in DSH, pick the network, and start a session in its workspace.

Upgrade and uninstall

• Runtime N → N+1: download the new archive into a fresh directory and start it; the isolated OpenBKN DSH home (OPENBKN_DSH_HOME, default under your data directory) carries sessions and settings across runtime versions, so nothing is migrated by hand.
• Source-build trees: before changing the DSH revision, revert the compatibility series (apply.mjs --revert), switch, and re-apply the matching series if one exists for the new revision.
• Uninstall the plugin: dsh plugin --profile <name> remove @openbkn/dsh-business-context, then remove the leftover node_modules/@openbkn inside that profile directory. Sessions written by plugin builds from #48 on contain no plugin events and stay readable on any DSH; their binding records under $DSH_HOME/openbkn/session-bindings/ stay behind and can be deleted by hand. Sessions written by earlier builds stay readable only if they were written on a patched DSH (their plugin events are ignorable); on an unpatched DSH they are refused on reload, and neither uninstalling nor upgrading the plugin repairs them.

Supported DSH versions

Exactly one upstream DSH revision is supported at a time — currently dsh-v0.2.0-rc.2, pinned by the compatibility manifest. A scheduled workflow (upstream-dsh-watch) watches upstream tags and opens a tracking issue whenever a release moves ahead of the pin; until the compatibility series is regenerated for it, newer DSH revisions are out of scope.

Check your version with dsh --version, then pair it like this:

Your DSH version	Compatibility series	Plugin to install	Prebuilt runtime archive
dsh-v0.2.0-rc.2 (current pin)	compat/dsh-0.2.0-rc.2/	@openbkn/dsh-business-context@0.2.0-rc.2-openbkn.0.2.0 (needs the patch), or build from this repository (main; no patch needed at run time)	openbkn-dsh-runtime-v0.2.0-rc.2-openbkn.0.2.0
DeepSeek Harness desktop app 0.2.0-rc.2	not applicable (the app is not patched)	build from this repository (main) until the next plugin release — the published 0.2.0-rc.2-openbkn.0.2.0 does not reload sessions there	not applicable
dsh-v0.1.7-rc.2 (previous series)	compat/dsh-0.1.7-rc.2/ (archived)	@openbkn/dsh-business-context@0.1.7-rc.2-openbkn.0.2.0 from npm, or build from git tag v0.1.7-rc.2-openbkn.0.2.0	openbkn-dsh-runtime-v0.1.7-rc.2-openbkn.0.2.0
dsh-v0.1.6-alpha.2 (previous series)	compat/dsh-0.1.6-alpha.2/ (archived)	@openbkn/dsh-business-context@0.1.5-rc.2 from npm, or a source build from git tag v0.1.5-rc.2	openbkn-dsh-runtime-v0.1.6-alpha.2-openbkn.1

Since the 0.2.0-rc.2 round, the plugin and the runtime bundle share one version scheme — <dsh-version>-openbkn.<openbkn-platform-version> — so the version number declares both compatibility dimensions at a glance: 0.2.0-rc.2-openbkn.0.2.0 pairs DSH 0.2.0-rc.2 with OpenBKN platform 0.2.0. The runtime manifest validator rejects any manifest whose plugin version does not carry its pinned DSH revision. Releases before this round keep their historical version numbers.

The plugin's declared DSH peers must match your runtime — DSH's version fence refuses mismatched installs. Do not build the plugin from current main for a 0.1.6-alpha.2 runtime: since the 0.2.0-rc.2 retarget its peers declare 0.2.0-rc.2, and the install will be rejected. The runtime archives are self-contained (patched DSH runtime plus the matching plugin), so they sidestep pairing entirely. compat/dsh-0.1.2-rc.1/ is a historical archive with no npm pairing.