PerryLink/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 · हिन्दी

dsh plugin --profile <name> add dsh-library

📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.

Install & uninstall

• git channel (latest main): dsh plugin --profile web add github:PerryLink/dsh-library — 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-.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.

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

What is dsh-library?

Local document knowledge base for DeepSeek Harness.

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

![Terminal demo of dsh-library: dsh-library — install, then ask with [n] citations](docs/assets/dsh-library-flow.svg)

*Workflow overview: install → open panel → act. The examples below use the real command surface.*

Compatibility

Surface · Status Harness · DeepSeek Harness dsh-v0.2.1-alpha.1 (verified 2026-09-25: dual typecheck rulers + 89 tests + self-contained/artifacts gates; peer range >=0.1.2-rc.1 =0.1.5-alpha.1 =0.1.6-0 =0.1.7-0 =24.0.0 Storage · Any storage-domain backend (JSON or SQLite); the index lives in the host's storage domain Models · None required — the built-in embedder is deterministic hashing (zero downloads)

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

dsh plugin --profile web add github:PerryLink/dsh-library

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

# 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.

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

~~~sh library_search({ library: "docs", query: "what is the harness built on", inject: true }) ~~~

Output

~~~text Library docs: 2 result(s) for "what is the harness built on" [1] DeepSeek Harness is a plugin-based agent harness built on vendored Cordis. Everything in the harness is a plugin row inside a cordis.yml composition. The tools/pre-execute waterfall lets plugins gate… [2] The recipe for sourdough starts with a levain fed the night before. Bulk fermentation takes four to six hours at room temperature. Bake in a dutch oven at 230 degrees Celsius for the first twenty min… ~~~

*Observed from README.md:161-167; tests/index.spec.ts:46-64; src/index.ts:830-836*

Failure branch

Input

~~~text {"path":"/nonexistent/dsh-library-missing.txt","library":"docs"} ~~~

Output

~~~text isError=true; error.message=cannot read "/nonexistent/dsh-library-missing.txt": not found; error.info={"name":"FsError","code":"FS_NOT_FOUND"} ~~~

*Observed from plugins/dsh-library/src/index.ts:695-696 (fs.resolve/readText); plugins/dsh-library/tests/index.spec.ts:143-151 (unreadable path); plugins/dsh-library/README.md:195 (unreadable files fail loud); exercised through plugins/dsh-library/tests/harness.ts*

Brief examples

• library_search
• library_list

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.

Key · Default · Meaning chunkSize · 900 · Sliding-window chunk size in characters (≤ 4000) chunkOverlap · 120 · Overlap between consecutive windows; must be smaller than chunkSize maxFileBytes · 5242880 · Files larger than this are rejected on library_add embedding.dims · 256 · Hash-embedding dimensionality (≥ 8) embedding.provider · hash · Embedder backend: hash (built-in, zero downloads), command (external subprocess, requires embedding.command), or ollama (local Ollama, probed and degraded to hash when unreachable) embedding.command · '' · Optional external embedder command (space-separated argv, no shell) over ctx.subprocess; setting it selects the command provider embedding.ollamaUrl / ollamaModel · http://127.0.0.1:11434 / nomic-embed-text · Local Ollama endpoint + model for the ollama provider (zero cloud) embedding.timeoutMs / graceMs / maxOutputBytes / maxBatchItems · 30000 / 1000 / 1048576 / 64 · Embedder subprocess budget search.topK · 8 · Results returned after the full pipeline search.hybridWeight · 0.6 · 0 = keyword-only, 1 = semantic-only search.minRelevance · 0.15 · Chunks below this relevance threshold are filtered out search.diversityLambda · 0.5 · MMR trade-off: 1 = pure relevance, 0 = pure diversity search.lostMiddleHead / lostMiddleTail · 1 / 1 · Strongest chunks pinned to head / tail search.maxResultChars · 16000 · Character budget of the model-facing result page injection.enabled / maxChars · true / 12000 · library_search inject behavior and budget citation.windowChars / minScore / minSemantic · 150 / 40 / 0.1 · library_cite_check thresholds purge.signatureLength / maxProbes · 4 / 24 · Purge verification signatures and probe budget diagnose.maxDuplicatePairs / sampleCap / positionBins · 24 / 200 / 5 · library_diagnose budget caps

Tools & surfaces

Tool · Notes library_add · { path, library, name? } → document id; file read through the harness filesystem service library_remove · { library, documentId } → removal summary + purge verdict (residue reported) library_list · { library? } → document metadata (never text) library_search · { query, library, topK?, inject? } → ranked hits with [n] markers; inject: true seeds the calling agent library_cite_check · { library, query, answer } → per-citation valid/invalid verdicts (fuzzy + semantic) library_diagnose · { library } → chunk stats, duplicates, self-retrieval, middle penalty /library [name] · Command: per-library document/chunk summaries

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.7-rc.2 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 part of the DeepSeek Harness plugin family from PerryLink. The roster stays collapsed below so every README keeps a short first screen; expand it to see every row and its status.

Expand all plugins

Plugin · Status dsh-aqua-input-check · dsh-archive-check · dsh-auto-review · dsh-autotier · dsh-bid-ca-precheck · dsh-bid-qual-check · dsh-cert-mcp · dsh-checkpoint-rewind · dsh-click · dsh-composer-history · dsh-contract-stance · dsh-customs-doc-check · dsh-data-quality · dsh-demurrage-ledger · dsh-doublecheck · dsh-drill-script-check · dsh-eia-guide-check · dsh-emergency-plan · dsh-essay-rubric-check · dsh-evidence-check · dsh-export-ctl-check · dsh-fast · dsh-fmea-table-check · dsh-forecast-penalty · dsh-fund-research · dsh-github · dsh-gongwen-flow-check · dsh-gongwen-word-check · dsh-guard-plan-qc · dsh-hazchem-check · dsh-hazplan-check · dsh-hidden-risk-map · dsh-hs-classify · dsh-icd-rule-check · dsh-industry-research · dsh-lawcite-adapter · dsh-laya · dsh-lc-doc-check · dsh-learning-gap-check · dsh-library · dsh-local-ai · dsh-lsp-actions · dsh-mask · dsh-mcp-panel · dsh-medrec-qc · dsh-memento · dsh-nsfc-form-check · dsh-nurse-record-check · dsh-observe · dsh-origin-rvc-check · dsh-ota-review-check · dsh-output-styles · dsh-paper-doc-adapter · dsh-permission-rules · dsh-permit-report-check · dsh-pipeline-check · dsh-pleading-draft · dsh-plugin-doctor · dsh-plugin-guide · dsh-plugin-kit · dsh-plugin-upgrade · dsh-policy-brief-draft · dsh-power-loss-split · dsh-power-ticket-check · dsh-ppap-check · dsh-protest-deadline · dsh-railway-window · dsh-repair-order-qc · dsh-research-report · dsh-review-reply-check · dsh-rulefile-check · dsh-safety-brief-check · dsh-score · dsh-session-sync · dsh-site-log-check · dsh-skill-pack-security · dsh-soe-decision-check · dsh-soilwater-check · dsh-sop-sync-check · dsh-spc-gbt-adapter · dsh-talk · dsh-tender-extract · dsh-tender-matrix · dsh-test-drive · dsh-ticktick · dsh-translate · dsh-warranty-calc · dsh-budget · 🧊 FROZEN — see the repo README dsh-claude-move · 🧊 FROZEN — see the repo README dsh-defend · 🧊 FROZEN — see the repo README dsh-draw · 🧊 FROZEN — see the repo README dsh-reach · 🧊 FROZEN — see the repo README dsh-background-agents · 🚫 RETIRED — see the repo README dsh-session-pin · 🚫 RETIRED — see the repo README dsh-team-rooms · 🚫 RETIRED — see the repo README

License

Apache License 2.0 © 2026 dsh-library contributors