dsh-okf-knowledge
English | 简体中文
A DeepSeek Harness plugin that gives every project a human-readable, human-editable knowledge
base in the Open Knowledge Format (OKF) v0.2.
Knowledge is plain Markdown with YAML frontmatter — never an invisible vector store — so users
can inspect, audit, and edit every entry.
Not to be confused with dsh-knowledge, a
RAG-style plugin (chunking, embeddings, SQLite). This plugin keeps knowledge as editable
OKF Markdown scoped per project. The two can coexist in one profile — tool names, routes,
and UI entries do not collide.
What it adds
- Per-project OKF bundles at
<project root>/.dsh/knowledge/, plus shared bundles
(default <dsh home>/knowledge/shared) for cross-project standards and runbooks.
- Conversation tools —
okf_search, okf_read, okf_validate — scoped
to the calling session's project (nearest .git ancestor of the session cwd) and the shared
roots. Results carry document ids for citation and validation caveats (e.g. missing sources).
- Web UI entry — a Knowledge button in the sidebar footer opens a browser/editor panel:
scope picker, directory tree, rendered Markdown + frontmatter view, raw source view, and an
editor with save-time OKF validation and optimistic-concurrency conflict detection (no
silent overwrites).
- Bundled
okf-authoring skill that teaches the agent how to split source material into
concepts, fill OKF frontmatter, preserve provenance, link concepts, and maintain index.md
and log.md — used only when the user explicitly asks for knowledge work.
Installation
Node.js 22.19 or later. Install into a DSH profile (replace web as needed):
dsh plugin --profile web add dsh-okf-knowledge
Installing through dsh plugin add activates the bundled default configuration automatically.
Verify the composed config without starting DSH:
dsh --profile web --dump-config
Configuration
Override defaults in the profile's cordis.patch.yml:
- id: knowledge
config:
projectDir: .dsh/knowledge # bundle dir relative to the project root
sharedRoots: # shared OKF bundles usable from every project
- /Users/me/.dsh/knowledge/shared
maxResults: 8 # okf_search result cap
Scope and authorization
Scopes are derived from trusted context only (R-009):
- Tools resolve the project bundle from the calling agent's session
cwd; the model addresses
documents by scoped ids (project/<path>, shared/<path>) and can never name absolute
filesystem paths.
- The Web API (
/okf-knowledge/api/*) resolves project scopes from the workspace registry and
shared scopes from the plugin config, requires loopback origin, and rejects path traversal.
Knowledge format
Every concept is Markdown with YAML frontmatter: required type; recommended title,
description; provenance via sources and generated (actor convention human:<id> /
<producer>/<version> / process:<id>). Reserved files: index.md (listing, bundle root
carries okf_version: "0.2") and log.md (dated change history). Other OKF fields
(verified, status, stale_after) and unknown frontmatter keys are preserved but not
interpreted by this plugin.
Development
npm install
npm run check # typecheck
npm test # vitest
npm run build # dist/index.js (host, ESM) + dist/client.js (web loader factory)
Install a local checkout instead of the npm release:
dsh plugin --profile web add /path/to/dsh-okf-knowledge
License
MIT
