📚 dsh-library

DeepSeek Harness 的本地文档知识库。

导入、检索、核验 —— 带引用标记的混合检索，agent 可以自证引用。

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

兼容性

| 方面 | 状态 | |---|---| | Harness | DeepSeek Harness 0.1.1-rc.2（声明兼容 0.1.1-rc.2） | | Node | ^22.19.0 \|\| >=24.0.0 | | 存储 | 任意 storage-domain 后端（JSON 或 SQLite）；索引存放在宿主的存储域中 | | 模型 | 无需任何模型 —— 内置嵌入为确定性哈希（零下载） |

你能得到什么

dsh-library 把本地 md/txt 文档变成可查询的知识库，并带一套 agent 可信任的质量管线：

• library_add / library_remove / library_list —— 按路径导入文档（分块 + 嵌入）、删除文档并做清除验证（用被删内容的签名探测剩余索引，残留即报告）、列出文档元数据。
• library_search —— 语义 + 关键词混合排序、最大边际相关多样性重排、相关性过滤与中段丢失规避（最强切片钉在首尾）。inject: true 时结果页注入调用 agent；每条命中带 [n] 来源标记，注入可从 library/inject 会话事件重建。
• library_cite_check —— 用模糊词面匹配 + 语义相似度双重校验答案中的 [n] 引用。
• library_diagnose —— 切片大小直方图、近似重复切片对、自检索探针与中段惩罚信号。
• /library —— 每个知识库一行索引摘要。

文档 ── library_add ─▶ 切片（滑窗） ─▶ 嵌入（哈希 / 外部命令）
                              │
                  存储域（documents / chunks / purges）
                              │
查询 ── library_search ─▶ 混合打分 ─▶ MMR 重排 ─▶ 相关性过滤
                              │                ─▶ 中段规避排序
                              ▼
                带 [n] 标记的结果页 ── inject: true ─▶ agent + library/inject 事件

快速开始

# 1. 把 bundle 装进你的 profile
dsh plugin --profile web add "github:PerryLink/dsh-library#main"

# 或从 npm 安装（正式发布版）
dsh plugin --profile web add dsh-library

# 2. 重启并核实行
dsh --profile web --dump-config | grep -A2 'id: dsh-library'

然后让 agent 导入并使用文档：

> 把 ./docs/spec.md 加入 docs 知识库，然后回答：规范里关于重试是怎么说的？用 [n] 标记引用。

安装与卸载

• git 通道（最新 main）：dsh plugin --profile web add "github:PerryLink/dsh-library#main" —— 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（或从 profile patch 中删除该行）。

如果 pnpm 对本包报 ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制无害校验），在你的 pnpm-workspace.yaml 中加入 allowBuilds: { esbuild: true } —— dsh CLI 会打印确切片段。

配置

所有可调项都是 Schemastery Config 字段（可在 cordis.yml 中修改）。按 id 定向覆盖会替换整行 —— 需要重新声明每个键。cordis.patch.yml 内联说明了每个键。

| 键 | 默认值 | 含义 | |---|---|---| | chunkSize | 900 | 滑窗切片大小（字符，≤ 4000） | | chunkOverlap | 120 | 相邻窗口重叠；必须小于 chunkSize | | maxFileBytes | 5242880 | 超过该大小的文件在 library_add 被拒绝 | | embedding.dims | 256 | 哈希嵌入维度（≥ 8） | | embedding.command | '' | 可选外部嵌入命令（空格分隔 argv、无 shell）走 ctx.subprocess；'' = 内置哈希嵌入 | | 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 注入调用 agent | | library_cite_check | { library, query, answer } → 逐条引用有效/无效判定（模糊 + 语义） | | library_diagnose | { library } → 切片统计、重复、自检索、中段惩罚 | | /library [name] | 命令：每个知识库的文档/切片摘要 |

权限与数据

• 权限：插件只读取你让 library_add 指向的文件（经 harness 文件系统服务及其策略），并只写入自己的 dsh_library 存储域。无网络请求；可选外部嵌入命令经 ctx.subprocess 执行、无 shell 解释。
• 数据：切片文本与嵌入存放在宿主的存储后端（与部署的其他持久数据同级信任）；插件不额外加密。文档路径与嵌入向量绝不进入会话日志。
• 会话日志：library/inject（id、查询、切片 id、页大小）与 library/purge（判定）是仅日志审计事件 —— 模型可见的注入页可从中重建。

安全边界

• 默认本地。 零模型下载、零网络调用 —— 打分是确定性哈希与词法数学。只有显式配置的嵌入命令会执行代码，且其协议做完整性检查与输出上限。
• 不伪造。 引用检查只报告管线能验证的结论；可疑引用如实呈现，绝不猜测。
• 清除即验证。 library_remove 用被删内容的确定性签名探测剩余索引并报告残留，而不是假定成功。
• 失败大声。 非法知识库名、超大文档、不可读文件、配置了却缺失的嵌入接缝，都以明确错误失败。

已知限制

• 词法级嵌入。 内置哈希嵌入打分的是表面相似而非语义；对改写表达的检索质量低于真实嵌入模型 —— 配置 embedding.command 可获得更强语义。
• 本地引用模型。 library_cite_check 针对搜索结果页（[n] 编号）验证，不支持自由形式的来源名；模糊分数是有界的词序列部分匹配率。
• 无摄取管线。 文档须按路径导入（md/txt）；PDF/docx 抽取不在 v0.1.0 范围。

开发

pnpm install        # node ^22.19 || >=24
pnpm run typecheck  # tsc：src + tests 对照本地 harness checkout
pnpm run typecheck:ci  # tsc：对照已发布的 0.1.1-rc.2 类型（无 paths）
pnpm test           # vitest：八移植回归、核心词汇、真实栈装配
pnpm run build      # tsdown bundle + tsc 声明（lib/）
pnpm run verify:self-contained  # 依赖声明全部来自 registry
pnpm run verify:artifacts       # 构建产物 ESM 面 + bundle patch 齐全
pnpm pack           # 发布用 tarball

Topics

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

Contributors

• @PerryLink —— 创建者与维护者：八项质量移植、存储域索引、混合检索管线、引用/清除验证与五语文档。

PerryLink DSH Plugin Family

本项目是由 PerryLink 维护的 29 个 DeepSeek Harness 插件之一。如果这个对你有用，其他插件很可能也会：

| Plugin | One-liner | |---|---| | dsh-auto-review | 审批链上的第二模型自动审查，默认失败关闭 | | dsh-background-agents | 持久化后台子代理，带 Web UI 侧边栏、消息与打断 | | dsh-budget | DeepSeek Harness 的成本治理：预算、碳排与延迟一屏呈现。 | | dsh-checkpoint-rewind | Claude Code /rewind 等价物：快照、会话分叉、一次性恢复 | | dsh-claude-move | 将 Claude Code 会话、记忆、技能与 CLAUDE.md 迁入 DSH | | dsh-click | 跨平台原生桌面控制（DeepSeek Harness），Windows 优先。 | | dsh-composer-history | Web 输入框的终端式输入历史：方向键、Ctrl+R 搜索 | | dsh-defend | DeepSeek Harness 的提示注入、越狱与密钥泄露防护。 | | dsh-doublecheck | 工程纪律门禁：需求质询、测试门禁、对抗式审查 | | dsh-draw | DeepSeek Harness 的统一静态图像生成路由。 | | dsh-fast | DeepSeek Harness 的只读性能诊断。 | | dsh-github | DSH 的 GitHub PR/issue 集成，每次写入都经审批门 | | dsh-library | DeepSeek Harness 的本地文档知识库。 | | dsh-local-ai | DeepSeek Harness 的本地模型（Ollama）接入。 | | dsh-lsp-actions | 经语言服务器的 LSP 诊断、格式化、补全、代码操作与重命名 | | dsh-mask | DeepSeek Harness 的 PII 脱敏中间件——数据到模型前匿名化，展示层还原。 | | dsh-mcp-panel | 只读 MCP 运行时面板：/mcp 命令 + 带状态、工具与错误的设置页 | | dsh-memento | 带审批门的跨会话记忆：ctx.memory 接缝 + SQLite + memory 工具 | | dsh-observe | DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测导出器。 | | dsh-output-styles | Claude Code outputStyles 等价的运行时样式切换 | | dsh-permission-rules | Claude Code 风格声明式 allow/deny/ask 权限规则，带审计 | | dsh-plugin-guide | 按需 agent 技能形式的插件开发知识库 | | dsh-score | DeepSeek Harness 插件的多指标质量评分。 | | dsh-session-pin | 在 Web 侧边栏置顶会话，顺序持久化 | | dsh-session-sync | DeepSeek Harness 的跨设备会话同步——会话存储的专用 git 镜像。 | | dsh-skill-pack-security | 安全审计技能包：密钥扫描、依赖与供应链审查 | | dsh-talk | DeepSeek Harness 的语音优先会话闭环：对它说，听它答。 | | dsh-test-drive | DeepSeek Harness 插件的隔离式安装冒烟实测。 | | dsh-translate | DeepSeek Harness 的厂商参数翻译与确定性 JSON 修复。 |

License

Apache License 2.0 © 2026 dsh-library contributors