bkn-dsh (openbkn-business-context)

bkn-dsh

Revision 0.2.1-rc.3-openbkn.0.2.1-2 admits DSH 0.2.1-rc.3 and every newer version, including alpha, rc, stable and future major releases; 0.2.0-rc.2 remains admitted. Loading admission is distinct from verified compatibility. Build/test anchors remain pinned, and existing interface, permission and dependency-identity checks remain enabled.

Current rc: 0.2.1-rc.3-openbkn.0.2.1-2. See the plugin instructions for automatic login, packaged MCP and trust boundaries; development records below retain their historical verdicts.

Recent updates (September 21–October 12): English · 中文.

Illustrated user guide: English · 中文 · PDF (中文). Includes installation, CLI setup, sign-in, supply-chain Q&A, provenance, and diagnostics with numbered screenshots.

Published -7 history: GitHub Release, cumulative update notes, and publication verification. Historical -5/-6 packages and earlier -7 candidates retain their original identities; acceptance remains limited to the recorded artifacts and scenarios.

中文

Bring governed OpenBKN business knowledge into DeepSeek Harness conversations.

0.2.1 version and compatibility

The unpublished -3 increment also prepares platform0.2.1 compatibility: its explicit CLI installer adds fixed0.2.1 while retaining0.1.5/0.2.0 and existing-installation protection. A fresh login requires the CLI version matching the platform; CLI0.2.0 rejects platform0.2.1. Final0.2.1 artifact and isolated acceptance are pending; rc/source probes are separate evidence. See the compatibility work and release gate. Published npm instructions below still select -2.

This release line uses 0.2.1-rc.3-openbkn.0.2.1-2 and permits loading on official DSH 0.2.0-rc.2 or >=0.2.1-rc.3, with no upper version bound. The OpenBKN 0.2.1 component is the version identity requested by the maintainer. Actual platform evidence remains on retained official OpenBKN 0.2.0 and CLI 0.2.0; it does not establish acceptance on an unreleased OpenBKN 0.2.1 platform. Consult the matching GitHub Release acceptance record for the tested coverage and known limitations.

This revision ships the native MCP same-origin protection with the plugin and loads it through the business module; no separate profile companion or official Host modification is required. Companion instructions for the earlier base release remain historical. Frozen -30/-31/-32 and historical verdicts are preserved.

Historical development checkpoints

This branch now targets official DSH 0.2.0-rc.2 and 0.2.1-rc.3, with formal OpenBKN v0.2.0 and CLI 0.2.0. The old build generator remains pinned. The local development candidate is -32; it is not a final CI candidate or formal acceptance result. Frozen -30/-31 and their rc.2 handoff evidence remain unchanged and do not establish rc.3 acceptance.

Local round 34 fixes a reproduced native Cordis MCP-owner lifetime defect, reuses the official Desktop directory bridge, and fixes diagnostic text contrast in dark hosts. Both source baselines and the same packed artifact pass local checks; actual Desktop B1 protocol checks are recorded separately from model G6. The platform remains unchanged official 0.2.0, with Sandbox-related acceptance held and the remaining G6 cases classified individually. See current evidence and G6 pending items. No push or CI is authorized before local convergence.

CSV delivery in this local development version uses the scoped openbkn_export_csv tool when the Host offers the required file services. After an existing platform CSV is created, the tool verifies and copies its exact UTF-8 bytes (up to 512 KiB) to a new file in the current DSH workspace. It requires the current bound Interaction and workspace write access; read-only sessions refuse delivery. Open the returned local file link only after export succeeds. Host read/grep/present remain unavailable. Managed guidance requires source precision in answers and CSV serialization, including avoiding Python default general formatting unless rounding is requested by the user or a disclosed platform rule. Model answer and file contents still require independent validation.

Export results include a verified markdown_link; repeat it with the answer and scope in the final message after finishing the Interaction, because progress messages may be collapsed. Count scope and requested calculation signs follow the platform contract; the plugin does not recalculate business results.

Formal capture-disabled responses retain managed Conversation/Interaction IDs: business calls still send the required bkn_context, and finish uses the current Interaction ID. Provenance preserves the disclosed identities, labels the absence of recorded evidence and keeps the local timeline. The earlier explicit no-identity downgrade remains a separate compatibility path. The plugin does not recalculate business results or alter model answers.

Source tests, controlled official npm runtime checks, fixed CI artifacts, real platform calls and human acceptance are separate gates. The eight Desktop/npm and Mac/Windows combinations across both DSH versions remain pending on a fixed CI candidate. Existing installations are not upgraded automatically.

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: provenance availability depends on the deployed OpenBKN version, routes and account permissions. On formal 0.2.0 Community, standard Interaction/operation records are available, while the optional native business-provenance routes are not mounted. Nonempty native business interpretation requires the corresponding extension. Historical 0.1.4 read-route results do not establish 0.2.0 feature availability; a 404 alone is not a license diagnosis.

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

Have an existing name-qualified override from a version <= -4? See the package migration note. Fresh installs do not need this migration.

From plugin 0.2.0-rc.2-openbkn.0.2.0-1 on, an unpatched DeepSeek Harness 0.2.0-rc.2 is all you need: install the plugin package with DSH's own plugin manager. The same package works on all three forms of DSH:

DSH form	How you run it
Official desktop app 0.2.0-rc.2	the DeepSeek Harness app
npm CLI	npm install -g @deepseek-ai/dsh@0.2.0-rc.2, then dsh web
Source checkout, built	dsh-v0.2.0-rc.2 checkout after pnpm install && pnpm run build, then node apps/cli/lib/bin.js web

Historical acceptance of earlier packages on macOS arm64 covered all three forms: install, binding, Q&A with tool calls, business provenance, reopening a session after a restart, and continuing its platform conversation (evidence). On Windows 10, the desktop app and the npm CLI were verified too: with the default configuration, sign-in, binding, and Q&A pass (round 2, after the CLI-lookup fix); the remaining items — provenance, restart and continue, unbound and PTC refusals, uninstall — passed in round 1 with cliPath set, before that fix (results). The source-checkout form was not run on Windows in that baseline. These dated results do not replace acceptance of a new package or the configuration flow described below.

Before you start

1. OpenBKN CLI. For the tested formal OpenBKN 0.2.0, use official CLI @openbkn/bkn-sdk@0.2.0; retain an existing compatible installation. For historical OpenBKN 0.1.5, use npm install -g @openbkn/bkn-sdk@0.1.5; for 0.1.4, use @openbkn/bkn-sdk@0.1.4 (0.1.5-rc.1 also works). CLI 0.1.5-rc.2 and later require the platform health/version endpoint, which 0.1.4 lacks. You can configure the plugin before signing in; the panel starts CLI authorization when needed. DSH must find openbkn on its own process PATH. The macOS desktop app reads the login-shell environment; Windows uses openbkn.cmd. If discovery fails, set the CLI's absolute path in 设置 → 高级设置 (Settings → Advanced settings). On Windows, name the shim itself, for example C:/Users/<you>/AppData/Roaming/npm/openbkn.cmd; where.exe openbkn shows its location.
2. pnpm, for the npm CLI only. The npm dsh hands plugin add to the pnpm on PATH; install it first (npm install -g pnpm@11.7.0, the version DSH itself uses). The desktop app bundles its own.
3. Private-platform authorization. This rc uses installed Chrome/Edge and the official CLI in an owned authorization flow. The plugin automatically records the private peer and pins its connection; no manual CA import, shell profile or user-wide CA environment setting is required. First-contact identity is observed rather than authenticated by public CA/hostname checks; identity changes require fresh browser authorization. See the plugin trust boundaries. Existing global CA settings are preserved.
4. Use Standard mode. A session bound to an OpenBKN network must run in DSH's Standard mode (标准模式). PTC mode is not supported yet: the plugin refuses run_code there and the model asks you to start a new session in Standard mode. The mode is chosen in the mode menu before the first message is sent and cannot be changed afterwards.

1. Install the plugin

In DSH's Plugins page, choose Add plugin and enter @openbkn/dsh-business-context@0.2.1-rc.3-openbkn.0.2.1-2. Select your registry and install the package. You can also install from a terminal while DSH is stopped; the desktop app must have been started once to create its profile:

# Desktop app (macOS). “Manage dsh command…” can also add dsh to PATH.
"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" plugin --profile desktop add @openbkn/dsh-business-context@0.2.1-rc.3-openbkn.0.2.1-2

# npm CLI
dsh plugin --profile web add @openbkn/dsh-business-context@0.2.1-rc.3-openbkn.0.2.1-2

# Source build, from the DSH checkout root
node apps/cli/lib/bin.js plugin --profile web add @openbkn/dsh-business-context@0.2.1-rc.3-openbkn.0.2.1-2

On Windows, use dsh.cmd in place of dsh. Use the actual profile and DSH_HOME of the Host you run; the default desktop and web profiles are separate. To install a downloaded package, replace the package spec with its absolute .tgz path.

2. Configure in the OpenBKN panel

1. Start DSH and click OpenBKN in the sidebar footer. An unset address is a normal 待配置 (not configured) state: the component stays enabled and diagnostics remains available. The plugin does not contact OpenBKN or read its CLI credentials until an address is configured.
2. Enter your platform's absolute http:// or https:// address and choose 保存并继续 (Save and continue). A malformed address is rejected without changing the saved configuration. Saving the address does not itself prove that the platform is reachable or authorized.
3. If DSH cannot find the CLI, open 高级设置 (Advanced settings) and set cliPath; its default is openbkn. The panel's 设置 (Settings) action lets you edit the same form later. Wait for an active business turn to finish before changing the platform address.
4. When prompted, choose 使用 OpenBKN CLI 登录并同步 (Sign in with OpenBKN CLI and sync), complete browser authorization, and return to DSH. If an existing credential is rejected, use this action to sign in again. A 403 may require the platform administrator to grant access; signing in as the same account does not guarantee recovery.

Settings are saved through DSH's configuration editor to the current profile and applied by its normal component reload. Other configuration fields are preserved. A higher-priority override may prevent a setting from taking effect; the panel reports this instead of silently bypassing it. A temporary network or certificate error does not erase the saved address. Existing sessions keep their original platform and network binding; changing the address does not rebind them.

You do not need to edit YAML or paste an access token for this flow. Tokens remain managed by the OpenBKN CLI and DSH credentials. For administrator-managed advanced configuration, an ID-only profile override still works:

- id: openbkn-business-context
  config:
    baseUrl: https://<your-openbkn-platform>
    # cliPath: /absolute/path/to/openbkn

The platform address is not sensitive. Never put tokens in Cordis YAML. An invalid address supplied in configuration remains a configuration error; it is distinct from an address that has not been set.

3. Bind a network and ask

1. After authorization, pick an accessible knowledge network and create its local workspace (新建工作区 / New workspace opens the folder chooser), or continue its existing workspace.
2. In the new session, keep 标准模式 (Standard mode), then ask. Each completed answer offers 查看业务溯源 (view business provenance: execution trace, business context graph, evidence).
3. For connection or setup problems, open 诊断 (Diagnostics) at the top right of the OpenBKN panel and export the report. Closing the panel keeps it closed when an earlier request finishes; it does not promise to cancel browser authorization already in progress.

With dsh web on macOS, the folder chooser opens on the machine that runs dsh web. A remote or SSH session uses DSH's browse backend, which cannot create a workspace from the plugin panel: associate the network with an existing local workspace first.

Uninstall

Use DSH's Plugins page to remove the @openbkn/dsh-business-context package. If the Host asks you to stop the profile, do so before retrying. Alternatively, stop DSH and run:

dsh plugin --profile <desktop|web> remove @openbkn/dsh-business-context

Removal unloads the package's components and removes its profile dependency. It does not erase user overrides in the profile patch, DSH/OpenBKN credentials, CLI sign-in state, sessions, network/workspace bindings, or workspace files. This is an uninstall, not a logout or data wipe. Do not delete the entire node_modules/@openbkn directory: it may contain other packages.

Sessions written by current plugin versions stay readable because the plugin does not add events to the DSH session log. Retained configuration and bindings can be reused after reinstalling. While installed, the plugin may prune session-binding records whose session no longer exists and whose record is at least seven days old; uninstalling does not run a blanket cleanup. See the historical session-log limitation below for the original 0.2.0-rc.2-openbkn.0.2.0 release.

Backup and known limitations

• Backup and moving machines: copy $DSH_HOME/openbkn/session-bindings/ (per-session network bindings) and $DSH_HOME/storages/openbkn_workspace_bindings.json (workspace ↔ network associations) together with the session logs. Provenance and conversation continuity are re-derived from the session log, but the bindings are not.
• Network scope — important limitation of the platform run_code: in a bound session the plugin refuses any direct query whose kn_id is missing or names another network, and it does not offer action execution. But the platform's run_code, execute_skill where the deployment enables it (and execute_published_tool) run on the platform: from OpenBKN 0.1.5 on, a run_code script can call every other platform tool as a function — including other networks' queries and execute_action — and models often prefer it. Calls made inside the script do not pass through the plugin, so there the bound network and the no-action rule rest on the session prompt only. Every platform operation still appears with its receipt in the business provenance. Platform-side scoping of run_code is being worked out with the OpenBKN team.
• Unbound sessions: OpenBKN tools are refused in any session that is not bound through the OpenBKN panel, including a session whose binding record cannot be read, or conflicts with its log, when the session is opened. Such a session still opens and keeps its history; the plugin logs a payload-free warning, but the UI does not show a binding-error state yet. A record that becomes unreadable while its session is already running does not revoke the running session's access until the session is reopened.
• Associations are shared by every host and profile in one $DSH_HOME (storages/openbkn_workspace_bindings.json): a network associated in dsh web offers continue / new session in the desktop app, not New workspace.
• One running host while changing associations: each host keeps the workspace associations in memory and rewrites the whole store from that copy, so taking turns is not enough — a host that was already running overwrites the other's change on its next write. When the desktop app and dsh web share one $DSH_HOME, quit the other host before creating or changing a workspace association, and restart a host before using it to change associations after the other one did.

Upgrading from 0.2.0-rc.2-openbkn.0.2.0

That release wrote plugin events into the session log. Sessions it bound on an unpatched DSH (desktop app, npm CLI, unpatched source build) are refused on reload, and neither upgrading nor uninstalling the plugin repairs them. Start new sessions after upgrading. Sessions it wrote on a patched DSH or in a Runtime archive stay readable.

Runtime archives (discontinued)

OpenBKN Runtime archives are no longer published: installing the plugin into DSH is the only supported way to use it. The last archive, openbkn-dsh-runtime-v0.2.0-rc.2-openbkn.0.2.0 (patched DSH 0.2.0-rc.2 with plugin 0.2.0-rc.2-openbkn.0.2.0), stays downloadable but receives no updates.

Building from source

The compatibility series is needed only to build the plugin package from this repository, not to use the plugin: patch 0001 lets DSH's Typert generator recognize the plugin's published protocol. Patch 0002 is retired (no plugin build from …-1 on uses it), and patch 0003 served only the discontinued Runtime archives. See the source-build guide.

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. Configure and authorize — enter the platform address in the OpenBKN panel, then use its CLI sign-in action. 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.

Supported DSH versions

The current rc admits 0.2.0-rc.2 || >=0.2.1-rc.3. The host matrix separately pins build/test anchors; its list is not a loading ceiling. The old generator remains the build baseline. Recorded coverage and limitations follow the matching Release and acceptance contract; historical fixture results are not an all-form acceptance claim.

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): desktop app, npm CLI, or source build	not needed to use the plugin; compat/dsh-0.2.0-rc.2/ builds it from source	@openbkn/dsh-business-context@0.2.1-rc.3-openbkn.0.2.1-2 from npm or a published .tgz (Standard mode)	discontinued; last one: openbkn-dsh-runtime-v0.2.0-rc.2-openbkn.0.2.0
>=0.2.1-rc.3 (loading attempts; untested versions remain unverified)	official Host; old build generator retained	@openbkn/dsh-business-context@0.2.1-rc.3-openbkn.0.2.1-2; recorded coverage and limits in the matching Release	no new runtime archive
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, and a republish with the same pair appends -<n> (0.2.0-rc.2-openbkn.0.2.0-7). 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. compat/dsh-0.1.2-rc.1/ is a historical archive with no npm pairing.