dsh-okf-knowledge

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