dsh-library

📚 dsh-library

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-library (counts toward the deepseek1024.com install ranking).

Local document knowledge base for DeepSeek Harness.

*Import, retrieve, verify — hybrid search with citations your agent can check.*

English · 简体中文 · Español · Português · हिन्दी

Compatibility

What you get

dsh-library turns local md/txt documents into a queryable knowledge base with a quality pipeline your agent can trust:

• library_add / library_remove / library_list — import a document by path (chunked and embedded), remove one with purge verification (signatures of the removed content are probed against the remaining index and any residue is reported), and list document metadata.
• library_search — hybrid semantic + keyword ranking, maximal-marginal-relevance diversity re-rank, relevance filtering, and lost-in-the-middle avoidance (strongest chunks pinned to head and tail). With inject: true the result page is injected into the calling agent; every hit carries a [n] source marker and the injection is reconstructable from the library/inject session event (host-gated; see Permissions & data).
• library_cite_check — verify the [n] citations in an answer against the search result page with a fuzzy token match AND a semantic similarity check.
• library_diagnose — chunk-size histogram, near-duplicate chunk pairs, a self-retrieval probe, and the middle-penalty signal.
• /library — one-line index summaries per library.

document ── library_add ─▶ chunk (sliding window) ─▶ embed (hash / external cmd)
                                  │
                        storage domain (documents / chunks / purges)
                                  │
query ── library_search ─▶ hybrid score ─▶ MMR re-rank ─▶ relevance filter
                                  │                    ─▶ lost-in-middle order
                                  ▼
                    result page with [n] markers ── inject: true ─▶ agent + library/inject event (host-gated)

Quick start

# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-library#main"

# or from npm (published releases)
dsh plugin --profile web add dsh-library

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A2 'id: dsh-library'

Then ask the agent to import and use a document:

> Add ./docs/spec.md to library docs, then answer: what does the spec say about retries? Cite [n] markers.

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-library#main" — the prepare script builds with production dependencies only.
• npm channel (published releases): dsh plugin --profile web add dsh-library.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-library-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-library (or remove the row from the profile patch).

If pnpm reports ERR_PNPM_IGNORED_BUILDS for this package (esbuild's harmless platform-binary validation), add allowBuilds: { esbuild: true } to your pnpm-workspace.yaml — the dsh CLI prints the exact snippet.

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. cordis.patch.yml documents each key inline.

Tools & surfaces

Permissions & data

• Permissions: the plugin only reads files you point library_add at (through the harness filesystem service and its policy) and writes into its own dsh_library storage domain. No network requests; an optional external embedder runs through ctx.subprocess without shell interpretation.
• Data: chunk text and embeddings live in the host's storage backend (same trust as the deployment's other durable data); the plugin adds no encryption. Document paths and embeddings never enter the session log.
• Session log: library/inject (id, query, chunk ids, page size) and library/purge (verdict) are log-only audit events — the model-visible injected page is reconstructable from them. The append is host-gated: harnesses whose known-type set covers the vocabulary get the events, ignorable-envelope builds get them with the marker, and envelope-less builds (0.1.1-rc.2, 0.1.2-rc.1) skip the append — the logged tool/call + tool/result events remain the reconstructable audit trail there.

0.1.2-rc.1 (adapted 2026-09-02): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it, so audit-gate behavior is unchanged.

Security boundaries

• Local by default. Zero model downloads, zero network calls — scoring is deterministic hashing and token math. Only an explicitly configured embedder command runs code, and its protocol is completeness-checked and output-capped.
• No fabrication. Citation checks report what the pipeline can verify; failed repairs and suspicious citations are surfaced honestly, never guessed.
• Purge is verified. library_remove probes the remaining index with deterministic signatures of the removed content and reports residue instead of assuming success.
• Fail loud. Invalid library names, oversized documents, unreadable files, and a configured-but-absent embedder seam all fail the call with a clear error.

Known limitations

• Lexical-grade embeddings. The built-in hash embedder scores surface similarity, not meaning; retrieval quality on paraphrases is lower than a real embedding model — configure embedding.command (any subprocess embedder) or embedding.provider: ollama (a local Ollama embedding model) for stronger semantics.
• Local citation model. library_cite_check validates against the search result page (the [n] numbering), not against free-form source names; the fuzzy score is a bounded token-sequence partial ratio.
• No ingestion pipeline. Documents must be imported by path (md/txt); PDF/docx extraction is out of scope for v0.1.0.
• Host-gated audit events. library/inject / library/purge are only appended on harnesses that can carry them (see Permissions & data); on the published 0.1.2-rc.1 line (as on earlier envelope-less lines) they are not appended, and every fact stays reconstructable from the tool call/result log.

Development

pnpm install        # node ^22.19 || >=24
pnpm run typecheck  # tsc: src + tests against the local harness checkout
pnpm run typecheck:ci  # tsc against the published 0.1.5-rc.1 types (no paths)
pnpm test           # vitest: quality ports, core vocabulary, real-stack assembly
pnpm run build      # tsdown bundle + tsc declarations (lib/)
pnpm run verify:self-contained  # dependency specs resolve from the registry
pnpm run verify:artifacts       # built ESM face + bundle patch present
pnpm pack           # the published tarball

Topics

dsh, dsh-plugin, deepseek-harness, deepseek, cordis, rag, knowledge-base, retrieval, embedding, vector-search, citation-validation, document-library

Contributors

• @PerryLink — creator and maintainer: the eight quality ports, storage-domain index, hybrid retrieval pipeline, citation/purge verification, and the five-language docs.

PerryLink DSH Plugin Family

This project is one of the 37 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

Install from the DSH Desktop Market

All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.

License

Apache License 2.0 © 2026 dsh-library contributors