本地文档知识库 PerryLink/dsh-library

📚 dsh-library

- 1024 商店渠道：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-library（计入 deepseek1024.com 的安装排名）。

dshfind

DeepSeek Harness 的本地文档知识库。

导入、检索、核验 —— 带引用的混合搜索，你的智能体可以逐条核对。

dsh-doctor
DSH Market

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

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

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

- git 渠道（最新 main）：dsh plugin --profile web add github:PerryLink/dsh-library —— prepare 脚本只用生产依赖构建。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-library。
- tarball 渠道：在本仓库执行 pnpm pack，再执行 dsh plugin --profile web add ./dsh-library-<version>.tgz。
- 卸载：dsh plugin --profile web remove dsh-library（或从配置档补丁里删掉对应行）。
如果 pnpm 对这个包报出 ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制校验，本身无害），在 pnpm-workspace.yaml 里加上 allowBuilds: { esbuild: true } —— dsh 命令行会打印出这段配置的原文。

⭐ 如果它帮到了你

这个插件是 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.

dsh-library 是什么？

DeepSeek Harness 的本地文档知识库。

导入、检索、校验 —— 混合搜索，附带智能体能核查的引用。

![dsh-library 终端演示：dsh-library —— 安装，然后用 [n] 引用提问](docs/assets/dsh-library-flow.svg)

dsh-library 工作流图：安装 → 打开面板 → 操作。

工作流概览：安装 → 打开面板 → 操作。下面的示例都用真实的命令接口。

兼容性

| 层面 | 状态 |
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（2026-09-25 验证：双类型检查标尺 + 89 个测试 + 自包含/产物门禁；peer 范围 >=0.1.2-rc.1 <0.2.0 \|\| >=0.1.5-alpha.1 <0.2.0 \|\| >=0.1.6-0 <0.2.0 \|\| >=0.1.7-0 <0.2.0）。家族里唯一实际跑过的 alpha.2 宿主冒烟测试（2026-09-11）就在这里。 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 存储 | 任意存储域后端（JSON 或 SQLite）；索引存放在宿主的存储域里 |
| 模型 | 不需要 —— 内置嵌入器是确定性哈希（零下载） |

你能得到什么

dsh-library 把本地 md/txt 文档变成可查询的知识库，配一条智能体能信得过的质量流水线：

- library_add / library_remove / library_list —— 按路径导入文档（分块并嵌入），删除时做清除校验（拿被删内容的签名去探测剩余索引，有残留就报告），以及列出文档元数据。
- library_search —— 语义 + 关键词混合排序，最大边际相关性多样性重排，相关性过滤，还有避免中间迷失（最强的块钉在头尾）。加 inject: true 时，结果页会注入到调用方智能体；每条命中都带 [n] 来源标记，注入内容可以从 library/inject 会话事件重建（受宿主门控；见「权限与数据」）。
- library_cite_check —— 拿答案里的 [n] 引用对照搜索结果页，做模糊 token 匹配和语义相似度检查。
- library_diagnose —— 块大小直方图、近似重复块对、自检索探针，以及中间惩罚信号。
- /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)

快速开始 sh
dsh plugin --profile web add github:PerryLink/dsh-library
sh

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'

然后让智能体导入并使用文档：

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

示例

下面是插件的真实入口，安装一次，之后调用其中一个即可。

详细示例

命令

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

输出

~~~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…

来源：README.md:161-167; tests/index.spec.ts:46-64; src/index.ts:830-836

失败分支

输入

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

输出

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

来源：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

简要示例

- library_search
- library_list

配置

所有可调项都是 Schemastery Config 字段，可在 cordis.yml 中修改。按 id 定向覆盖会替换整行，你需要把用到的键全部重写一遍。cordis.patch.yml 在每个键旁都有行内说明。

| 键 | 默认值 | 含义 |
| chunkSize | 900 | 滑动窗口分块大小，单位为字符（≤ 4000） |
| chunkOverlap | 120 | 相邻窗口之间的重叠量，必须小于 chunkSize |
| maxFileBytes | 5242880 | 超过此大小的文件会在 library_add 时被拒绝 |
| embedding.dims | 256 | 哈希嵌入维度（≥ 8） |
| embedding.provider | hash | 嵌入后端：hash（内置，零下载）、command（外部子进程，需要 embedding.command）或 ollama（本地 Ollama，连不上时探测并降级为 hash） |
| embedding.command | '' | 可选的外部嵌入命令（空格分隔的 argv，不经 shell），通过 ctx.subprocess 执行；设置后即选用 command 服务商 |
| embedding.ollamaUrl / ollamaModel | http://127.0.0.1:11434 / nomic-embed-text | ollama 服务商使用的本地 Ollama 端点与模型（全程不碰云端） |
| embedding.timeoutMs / graceMs / maxOutputBytes / maxBatchItems | 30000 / 1000 / 1048576 / 64 | 嵌入子进程的预算 |
| search.topK | 8 | 完整流水线跑完后返回的结果数 |
| search.hybridWeight | 0.6 | 0 = 仅关键词，1 = 仅语义 |
| search.minRelevance | 0.15 | 相关性低于此阈值的分块会被过滤掉 |
| search.diversityLambda | 0.5 | MMR 权衡：1 = 纯相关性，0 = 纯多样性 |
| search.lostMiddleHead / lostMiddleTail | 1 / 1 | 最强的分块固定在头部 / 尾部 |
| search.maxResultChars | 16000 | 面向模型的结果页字符预算 |
| injection.enabled / maxChars | true / 12000 | library_search 的注入行为与预算 |
| citation.windowChars / minScore / minSemantic | 150 / 40 / 0.1 | library_cite_check 的阈值 |
| purge.signatureLength / maxProbes | 4 / 24 | 清除校验签名与探测预算 |
| diagnose.maxDuplicatePairs / sampleCap / positionBins | 24 / 200 / 5 | library_diagnose 的预算上限 |

工具与入口

| 工具 | 说明 |
| library_add | { path, library, name? } → 文档 id；文件通过 harness 文件系统服务读取 |
| library_remove | { library, documentId } → 删除摘要 + 清除判定（报告残留） |
| library_list | { library? } → 文档元数据（绝不返回文本） |
| library_search | { query, library, topK?, inject? } → 带 [n] 标记的排序命中；inject: true 会为发起调用的智能体注入结果 |
| library_cite_check | { library, query, answer } → 逐条引用的有效 / 无效判定（模糊 + 语义） |
| library_diagnose | { library } → 分块统计、重复、自检索、中段惩罚 |
| /library [name] | 命令：按库汇总文档 / 分块 |

权限与数据

- 权限：插件只读取你用 library_add 指向的文件（经由 harness 文件系统服务及其策略），并且只写入自己的 dsh_library 存储域。不发网络请求；可选的外部嵌入器通过 ctx.subprocess 运行，不经 shell 解释。
- 数据：分块文本与嵌入存放在宿主存储后端（信任级别与该部署的其他持久数据相同）；插件不额外加密。文档路径与嵌入永远不会进入会话日志。
- 会话日志：library/inject（id、query、chunk ids、page size）和 library/purge（verdict）都是只写日志的审计事件——模型可见的注入页面可以从这些事件重建。追加写入由宿主控制：已知类型集合覆盖这套词汇的宿主会收到这些事件，带 ignorable 信封的构建会收到带标记的事件，而无信封的构建（0.1.1-rc.2、0.1.2-rc.1）跳过追加——在那里，记录下来的 tool/call + tool/result 事件仍是可重建的审计线索。
0.1.2-rc.1（适配于 2026-09-02）：会话信封保留 ignorable 字段，仅用于兼容已存储日志的读取——Session.append 仍然无法写入该字段，所以审计门控行为不变。

安全边界

- 默认本地运行。 零模型下载、零网络调用——打分是确定性哈希和 token 运算。只有显式配置的 embedder 命令才会运行代码，其协议会做完整性检查，输出也有上限。
- 不编造。 引用检查只报告流水线能验证的内容；修复失败和可疑引用会如实暴露，绝不猜测。
- 清除有验证。 library_remove 用被移除内容的确定性签名探测剩余索引，报告残留，而不是假定成功。
- 出错就大声报。 非法库名、超大文档、无法读取的文件、已配置但缺失的 embedder 接缝，都会让调用失败并给出明确错误。

已知限制

- 词法级嵌入。 内置哈希 embedder 打的是表面相似度，不是语义；改写句上的检索质量低于真正的嵌入模型——配置 embedding.command（任意子进程 embedder）或 embedding.provider: ollama（本地 Ollama 嵌入模型）可获得更强的语义。
- 本地引用模型。 library_cite_check 对照搜索结果页（[n] 编号）校验，而不是对照自由格式的来源名；模糊分数是有界的 token 序列部分比率。
- 没有摄取流水线。 文档必须按路径导入（md/txt）；PDF/docx 提取不在 v0.1.0 范围内。
- 审计事件由宿主控制。 library/inject / library/purge 只在能承载它们的宿主上追加（见权限与数据）；在已发布的 0.1.2-rc.1 线上（与更早的无信封线一样）不会追加，所有事实仍可从工具调用/结果日志重建。

开发 sh
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

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

贡献者

- @PerryLink — 创建者与维护者：八个质量端口、存储域索引、混合检索流水线、引用/清除校验，以及五种语言的文档。

PerryLink DSH 插件家族

本项目属于 PerryLink 的 DeepSeek Harness 插件家族。下面这份名单默认折叠，好让每个 README 的首屏都保持简短；展开即可看到每一行及其状态。

展开全部插件

| 插件 | 状态 |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | 🧊 FROZEN — 见仓库 README |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | 🧊 FROZEN — 见仓库 README |
| 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 | 🧊 已冻结 —— 见仓库 README |
| dsh-claude-move | 🧊 已冻结 —— 见仓库 README |
| dsh-defend | 🧊 已冻结 —— 见仓库 README |
| dsh-draw | 🧊 已冻结 —— 见仓库 README |
| dsh-reach | 🧊 已冻结 —— 见仓库 README |
| dsh-background-agents | 🚫 已退役 —— 见仓库 README |
| dsh-session-pin | 🚫 已退役 —— 见仓库 README |
| dsh-team-rooms | 🚫 已退役 —— 见仓库 README |

许可证

Apache License 2.0 © 2026 dsh-library contributors