DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

EveGoodEvening /

EveGoodEvening/dsh-llmwiki

Verified

This plugin has no description yet.

★ 0 Stars0 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHubProject homepage
READMESource: master@7a62c692

dsh-llmwiki

English | 简体中文

Third-party, local-first, source-linked Markdown wiki storage and retrieval plugin for DeepSeek Harness (DSH), inspired by Karpathy's LLM Wiki.

Maintained by EveGoodEvening, this is not an official DeepSeek or DeepSeek Harness project. References to DeepSeek Harness and Andrej Karpathy describe compatibility and inspiration only; they do not imply affiliation, sponsorship, or endorsement.

  • Preserve immutable sources by SHA-256 and write Markdown pages that cite them.
  • Search page sections with a deterministic lexical index; rebuild it when stale.
  • Check structure, links, and integrity with model-free lint.

The plugin makes no model or network calls. The calling agent handles synthesis and semantic review; a source citation proves record existence, not claim support.

Requirements

DSH (@deepseek-ai/dsh) Cordis (@deepseek-ai/cordis) Status
0.2.2-rc.1 4.1.0 Recommended (tested)
Later 0.2.x (>=0.2.1-rc.5 <0.3.0-0) Must satisfy both host and plugin peers DSH service versions admitted by range; not individually tested
0.2.1-rc.5 4.0.5 Supported
0.2.1-rc.2 4.0.5 Supported
0.2.0-rc.2 4.0.4 or 4.0.5 Supported
0.1.7-rc.2 4.0.4 Supported
0.1.1-rc.2 4.0.1 Supported legacy
0.1.0-rc.6 4.0.1 Supported legacy
  • Node.js: ^22.23.4 || ^24.22.1 || >=26.12.1. CI pins 24.22.1; earlier 24.x and odd-numbered 23/25 releases are not supported. DSH 0.2.2-rc.1 itself requires Node >=24.9.0, so use patched Node 24 or newer for that host; Node 22 is only for retained older hosts. Use npm 12.2.1 for the release/pack probes and pnpm below for dependency management.
  • pnpm: 11.7.0, on PATH for dsh plugin and development.
  • Use a coherent DSH service family, not mixed release candidates. The 0.1.0-rc.6 host resolves its five DSH service peers to 0.1.0-rc.8; the other rows use same-version services.
  • Peer ranges. Older hosts are listed exactly; DSH admission and pnpm also match prereleases in >=0.2.1-rc.5 <0.3.0-0. The additional exact 0.2.2-rc.1 entry supports npm's strict semver, which otherwise excludes prereleases outside the lower bound's 0.2.1 tuple. Other new prerelease tuples still require explicit entries for npm consumers. Cordis supports 4.0.1 || >=4.0.4 <4.1.0-0 || 4.1.0; 4.0.2/4.0.3 remain excluded, and later 4.1.x releases are not yet declared. The scheduled compatibility monitor tests npm latest and opens an issue on failure; alpha/next tags are not separately monitored. DSH 0.3.0 and later require an explicit update.
  • Cordis 4.1.0 requires Loader ~1.1.0 and Include ~1.1.0; the retained Cordis 4.0.5 family uses Loader ~1.0.6 and Include ~1.0.10. Update the host's companion packages together rather than forcing Cordis onto older companions.
  • Direct Cordis loading also needs DSH tools, commands, and systemPrompt services and one shared @deepseek-ai/schemastery@^3.18.1 installation (3.19.0 for the recommended host). DSH 0.2.2-rc.1 additionally needs a host-selected tool executor; tools no longer accepts mode: native. See peer ranges and the standalone example.

The plugin's version in package.json is independent of the DSH and dependency versions above.

Install

Use @evegoodevening/dsh-llmwiki. The unscoped dsh-llmwiki package belongs to a different project.

From this checkout, pack and install 0.0.5 with a supported DSH host on PATH (web is the example profile):

pnpm install --frozen-lockfile
pnpm pack
dsh plugin --profile web add ./evegoodevening-dsh-llmwiki-0.0.5.tgz

When the package is available on npm, the equivalent registry command is dsh plugin --profile web add @evegoodevening/dsh-llmwiki@latest.

Installation leaves the plugin disabled: its bundled patch is empty. To enable it, merge the following into the profile's $DSH_HOME/profiles/web/cordis.patch.yml. Preserve existing patches; if the file contains only [], replace that empty list. Insert llmwiki only once, and replace the example root with your own writable absolute path. Plain YAML does not expand $HOME.

- insert:
    - id: llmwiki
      name: '@evegoodevening/dsh-llmwiki'
      config:
        root: /var/lib/dsh/llmwiki/web

insert creates the plugin instance; a plain - id: llmwiki only overrides an existing instance. DSH automatically loads the profile patch. Inspect the composed configuration, then start:

dsh --profile web --dump-config
dsh --profile web

If migrating from an external --patch file, move its llmwiki entry here with the same root and remove that command-line argument. Do not load both copies. Restart a running profile after changes.

Use /wiki status to inspect the repository. Before changing the installed package, stop all writers and back up the root. Retain the same explicit root to reuse existing wiki data, and check the filesystem requirements below before enabling it.

To uninstall without deleting wiki data, first remove the llmwiki entry and any resulting empty insert block from the profile patch (use [] if no patches remain), then remove the package:

dsh plugin --profile web remove @evegoodevening/dsh-llmwiki

For local-tarball installation or standalone Cordis loading, use the runnable example.

Usage

Commands

Command Purpose
/wiki status Report initialization, source/page counts, and index state; also the default /wiki action
/wiki lint Report structural errors and warnings without repairing anything
/wiki reindex Rebuild the derived search index

Agent tools

Tool Purpose
llmwiki_status Inspect storage and read the human-owned schema
llmwiki_add_source Preserve exact UTF-8 content; return its source ID
llmwiki_list_sources Browse source metadata with pagination
llmwiki_read_source Read preserved content and provenance
llmwiki_search Find ranked page-section matches
llmwiki_list_pages Browse page metadata and hashes with pagination
llmwiki_read_page Read exact page Markdown and its SHA-256 by logical ID
llmwiki_upsert_page Create or conditionally update a page citing existing source IDs
llmwiki_lint Check structure, integrity, links, and index freshness

Start with status and the schema. Preserve sources and maintain affected pages only with user authorization. Run structural lint before semantic review, even without writes, and again after any updates. Semantic findings are agent judgments, not lint results. Full workflow: runtime prompt; parameters: tool schemas.

Search uses deterministic NFKC/lowercase tokens and BM25 field weighting; ties sort by page ID and section start line. Snippets show contiguous normalized body context around the earliest fitting scored query token (whole letter/number run or existing CJK two-code-point gram), with same-position ties resolved by UTF-16 lexical token order. They stay within maxSnippetBytes without splitting UTF-8 code points; no omission markers are added. Dispersed query terms need not all appear. Title/heading-only matches and body tokens too large for the cap use a bounded body prefix instead.

Page-write preconditions

Every page write requires expectedSha256: use null to create an absent page, or the exact raw-Markdown sha256 returned by a page read or catalog to update an existing page. On PAGE_CONFLICT, reread and reconcile the page before retrying; do not overwrite with a stale hash or blindly retry.

Configuration

All keys are optional. Numeric values are integers; unknown keys are rejected.

Key Default Meaning / limits
root .llmwiki Non-empty path, resolved once from the host process cwd
maxSourceBytes 2097152 Source content limit: 2 MiB; minimum 1 byte
maxPageBytes 524288 Rendered page body limit: 512 KiB; minimum 1 byte
maxResults 20 Search and catalog page-size cap; 1..100
maxSnippetBytes 1200 Search snippet limit; 64..16384 bytes
commandDiagnosticLimit 20 Diagnostics printed by /wiki lint; 1..100

Storage and safety

<root>/
  schema.md                  # human-owned guidance; created only if absent
  sources/<sha256>/
    content                  # immutable UTF-8 source
    metadata.json            # provenance and capture metadata
  pages/<page-id>.md          # Markdown with title, summary, and source IDs
  .index/{search,state}.json  # derived, rebuildable search data
  • Host storage, not a DSH sandbox. Direct Node filesystem I/O bypasses ctx.fs, DSH permission modes, approval, read-before-edit, and remote/workspace providers. Do not enable this plugin where those controls are required; enforce boundaries with OS permissions and process isolation.
  • One fixed root per activation. Session/workspace cwd changes do not switch storage. Use distinct roots for isolation; mutually untrusted tenants must not share a root or activation. Concurrent writers across activations/processes are unsupported. Do not let untrusted processes modify the root.
  • Filesystem backend. Descriptor-contained storage requires Linux, numeric nofollow/directory-open flags, and a mounted, usable /proc/self/fd. Unsupported or unavailable capabilities fail closed with UNSAFE_FILESYSTEM; there is no pathname fallback. Non-Linux descriptor backends are not supported or claimed proven. Root and child directories are pinned per operation, final files are opened without following symlinks, and an initialized root's device/inode identity must remain unchanged.
  • Adversary limits. Pinned traversal prevents symlink substitution from redirecting filesystem operations into an outside symlink target. It is not a whole-tree transaction or a compare-and-rename guarantee. An already-authorized directory can remain accessible after being renamed outside its former lexical root. Ordinary file/hardlink injection, privileged mount or process access, and hostile replacement of procfs are outside this guarantee; OS isolation and the no-untrusted-writers requirement still apply.
  • Some reads can write. Status, catalog listings, and lint never write. Source/page reads and search may initialize storage; search may also rebuild the index. Read-only deployments need an initialized repository and a fresh index.
  • Sources are never edited or deleted by the plugin. Existing schema.md is preserved; there is no schema-editing API.

Interrupted source writes

Retry llmwiki_add_source (or ctx.llmwiki.addSource) with identical content after an interrupted source write. Recovery is limited to the final source directory with no committed metadata.json, containing only an empty state, matching durable content, and/or recognized regular writer temporary files. Matching durable content is preserved; metadata commits last using the retry's provenance. The recovered receipt has deduplicated: false; the next identical-content retry deduplicates.

A valid complete record always deduplicates without changing its first committed metadata/provenance bytes. Corrupt content or metadata, unknown children, and symlink/nonregular children are refused without changing the rejected record. Reads, catalogs, and lint do not repair partial records or treat them as valid; source/page reads can still initialize the storage layout as described above. This is narrow crash retry, not a generic repair/quarantine facility or a multi-page transaction.

Development

pnpm install --frozen-lockfile
pnpm run build
pnpm run typecheck
pnpm run lint
pnpm test
pnpm run test:e2e
pnpm run check:determinism
pnpm run smoke

The Linux unit suite's read-only tmpfs test requires root and mount-namespace capability. E2E builds first and exercises packed packages across the supported host matrix; run it separately from other builds because it temporarily hides shared checkout paths. Ordinary smoke uses the development baseline below.

The development baseline is DSH 0.2.2-rc.1, Cordis 4.1.0, Loader 1.1.0, Schemastery 3.19.0, and node-addon-require-builtin 0.1.9. Current-development tests and smoke mount dsh-tool-executor-native and use the batch tool API; the unused dsh-ptc-runtime development dependency is removed. The plugin itself does not select a host executor. Supported legacy hosts remain unchanged; the independent agent-smoke runner keeps its legacy DSH 0.1.1-rc.2 closure with security overrides only. The fixed 0.2.1-rc.2, 0.2.1-rc.5, and 0.2.2-rc.1 E2E rows use native host dependencies and a strict standalone consumer, independently of the rolling latest-version probes.

  • Upstream compatibility: pnpm run check:compatibility probes latest DSH with native dependencies and, separately, forced latest Cordis. Disposable hosts and consumers apply the repository's @deepseek-ai/* release-age exception so fresh vendor companions can resolve together; other dependency age settings are unchanged. Networked, model-free; it checks peer compatibility and runtime behavior rather than treating a range match as proof. See the scheduled workflow.
  • Real-agent smoke: set DEEPSEEK_API_KEY, LLMWIKI_AGENT_SMOKE_MODEL, and LLMWIKI_AGENT_SMOKE_NETWORK=allow, then run pnpm run smoke:agent. This separate, credentialed check uses a pinned DSH 0.1.1-rc.2 runner; offline checks do not prove model behavior.
  • Publishing: the release workflow uses npm Trusted Publishing for a v* tag matching package.json.

References / Acknowledgements

The design and integration work consulted these sources:

  • Andrej Karpathy's LLM Wiki idea file — the primary conceptual inspiration: immutable raw sources, a persistent LLM-maintained Markdown wiki, schema guidance, and ingest/query/lint workflows. It describes a pattern, not a required implementation or API.
  • Astro-Han/karpathy-llm-wiki — the raw/wiki/schema separation, evidence requirements, and explicit ingest/query/lint workflows in its agent skill. The specific triage and cascade-update guidance is covered by the scoped attribution and retained MIT license in Third-party notices.
  • ddsyasas/llm-wiki — persisted source/page records, index-first navigation, and the separation of deterministic lint from model judgment. Its Next.js/SQLite/FTS application architecture is not adopted here.
  • Praney Behl's llm-wiki-plugin — section-level lexical retrieval and stable evidence output in its search tooling, plus surgical page updates, citations, and user-review boundaries in its ingest workflow. Its Python/uv/FastEmbed/sqlite-vec runtime is not adopted here.
  • DeepSeek Harness — Cordis plugin and service conventions, lifecycle ownership, tool/command/system-prompt registration, and profile bundle integration. The initial integration research used revision fa7e9f5a; supported runtime versions are listed above.

These acknowledgements identify design influences and integration references; they do not imply endorsement by the referenced authors or projects. This package's MIT license does not relicense the referenced works, which remain subject to their own copyright and licensing terms.

License

MIT © EveGoodEvening.

See Third-party notices for the scope and complete upstream license retained for workflow guidance. The project's MIT license does not replace that notice.

—/ 5

No ratings yet

Verified DSH bundle

Commit 7a62c692efcb

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout