dsh-okf

DSH OKF Plugin (dsh-okf)

A production-ready DeepSeek Harness (DSH) plugin implementing the Open Knowledge Format (OKF v0.2) standard.

Instead of unstructured chunks and probabilistic embeddings that cause agent hallucinations, OKF models complex systems as a verifiable, deterministic knowledge graph of Markdown documents with strict YAML frontmatter, backlinks, freshness tracking, and audit trails.

---

Features

• 6 DSH Agent Tools:

  • okf_init: Initialize a standards-compliant OKF v0.2 bundle (index.md, log.md, starter concepts).
  • okf_validate: Deterministic linter checking frontmatter, required type, broken links, orphan concepts, and stale status.
  • okf_search: Search concepts by keyword, type, tag, or verification status.
  • okf_concept_read: Read concept frontmatter, markdown body, and computed incoming backlinks.
  • okf_concept_write: Create or update concept files with frontmatter validation and automatic audit logging in log.md.
  • okf_visualize: Export interactive force-directed HTML graph (viz.html) powered by Cytoscape.js.

• Interactive Web UI & REST API:

  • GET /api/okf/view: Full-screen browser visualizer with search, category filtering, layout switching, and inspector sidebar.
  • GET /api/okf/graph: Cytoscape-compatible JSON graph (nodes, edges, backlinks, metadata).
  • GET /api/okf/status: Health and conformance stats for the active workspace.

• DSH System Prompt & Skill Integration:

  • Bundled DSH skill under skills/okf/SKILL.md.
  • Injects runtime guidance into DSH agent context so the agent automatically uses OKF practices.

---

Installation in DeepSeek Harness

Method 1: CLI Install (Recommended)

Run the dsh plugin add command to install directly from GitHub into your profile:

dsh plugin --profile web add github:TorRient/dsh-okf

This will automatically:

• Download and link dsh-okf into your profile's node_modules/.
• Register dsh-okf into your active profile bundles (dsh.profile.bundles).
• Mount the 6 OKF agent tools, web visualizer routes, and the bundled OKF agent skill.

Method 2: Local Link (For Development)

1. Symlink or link the package to your DSH profile (~/.dsh/profiles/web/node_modules/):

ln -s /path/to/dsh-okf ~/.dsh/profiles/web/node_modules/dsh-okf

2. Register the bundle in your DSH profile manifest (~/.dsh/profiles/web/package.json):

{
  "dsh": {
    "profile": {
      "bundles": [
        "...",
        "dsh-okf"
      ]
    }
  }
}

Or add the entry directly into ~/.dsh/cordis.patch.yml:

- insert:
    - id: okf
      name: 'dsh-okf'
    - id: okf-skill-filesystem
      name: '@deepseek-ai/dsh-skill-filesystem'
      config:
        providerName: okf-plugin
        includeDefaultRoots: false
        bundledSkillDir: !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-okf/package.json')), 'skills')

---

OKF Bundle Structure

my-knowledge-base/
├── index.md           # Bundle root manifest & table of contents
├── log.md             # Append-only revision changelog
└── concepts/          # Domain, Architecture, API, and Schema concepts
    ├── architecture.md
    └── payment-service.md

Concept Frontmatter Example

---
type: Architecture
title: Payment Gateway
description: "Processes credit card transactions and settlements."
status: verified
stale_after: "2026-12-31"
tags:
  - payments
  - billing
sources:
  - "https://internal.wiki/pay-v2"
---

# Payment Gateway

Payment Gateway communicates with [Auth Service](https://github.com/TorRient/dsh-okf/blob/cdc707bcff081176a1b7070a191f6318b75d2069/auth-service.md).

---

Testing

Run the built-in test suite:

node --test test/**/*.test.js

Includes 22 automated tests covering parser, serializer, bundle scanner, conformance validator, agent tools, web routes, and Cordis lifecycle.

---

License

MIT