前言¶
在 DeepSeek Harness（DSH）里做带私有语料的智能体，常见做法是外挂向量库或自建 RAG 服务，再在会话里挂检索工具。文档入库、图谱、条目级线索和「命中后按篇续读」往往分散在不同系统里，面板与 agent 工具也不在同一套绑定关系上。
chenzhiya77/dsh-harness-rag 是社区目录分类为「记忆」的 DSH 插件（维护者 chenzhiya77）。它把摄取、加工、向量 / 图谱 / wiki 三路检索、文档感知工具，以及右栏知识库面板收进一条链路：默认由插件托管本地 knowledge 服务（便携 Python、Qdrant、引擎）；配置 backendUrl 非空时可改走外部服务。插件以 MIT 许可发布，当前 GitHub 星标为 1；package 版本为 0.1.4，要求 DSH >=0.2.1-rc.2 <0.3.0、Node ^22.19.0 || >=24.0.0。
这是什么¶
一句话定位：面向 DeepSeek Harness 的 Agentic RAG 插件——三路检索（hybrid / graph / wiki）、文档续读，以及知识库管理面板；内置或外部 knowledge 服务二选一。
结构上三块协作：DSH 插件（host 半提供 hrag_* 工具与摄取后台，client 半渲染右栏「知识库」tab）、浏览器面板、knowledge 服务。对象模型统一文档、切片、实体与 wiki 条目；写入时变更沿派生关系向下传播，读取时三路检索向上回溯，再配合只读工具枚举与读回。
架构与安全边界¶
Host 与 client 各自声明依赖，不共用对面侧服务。托管模式下运行时落在 <root>/runtime/<version>/，数据落在 <root>/state/；外部模式不下载、不起本地进程，数据由外部服务持有，以 apiToken 保护接口。
访问规则在 README 中写得很明确：
- 六件
hrag_*仅在会话绑定知识库后挂入该会话，解绑即从工具表移除。 - Agent 侧无写入工具；上传、删除、触发解析、生成 wiki 由人在面板完成。
- 工具名、槽位
dsh-harness-rag/harness-rag、代理路由/dsh-harness-rag/api等与其他插件隔离。
核心功能¶
摄取与解析¶
支持 MinerU 解析 PDF / Word / PPT / 图片，本地直读 Markdown 与纯文本；CSV / Excel / TSV 归一为 GFM 表格（文档称全部开启共 19 种后缀）。视频格式含 .mp4 / .mov / .mkv / .webm，语音与关键帧等进入切片；ASR 可本地 funasr 或 whisper，托管运行时不自带 funasr / torch，需另装或走服务档。默认 MinerU 云解析，也可填自建 MinerU 4.x 地址。
加工与联动¶
结构感知切分保留 heading_path；实体归一化与 wiki 按门槛与跨切片规则生成，上游编辑、重抽、删片、增删文档会级联更新向量、图谱与 wiki（详见仓库 README 中的传播表）。
检索与文档感知（六件工具）¶
| 工具 | 作用 |
|---|---|
hrag_hybrid_search |
dense + sparse → RRF → 重排（故障可降级） |
hrag_graph_search |
关系检索，约 1–2 跳 |
hrag_wiki_search |
条目正文，含用户「我的条目」 |
hrag_list_documents |
枚举文档及状态 |
hrag_read_document |
按篇分页或按片续读 |
hrag_list_wiki_entries |
枚举 wiki 条目 |
命中结果带 chunk_id / doc_id / chunk_index，便于续读。绑定知识库的会话会收到检索纪律（向量保底、图谱路、语料边界、读取上限、拒答等），不向模型强行注入引用格式要求。
面板与质量闭环¶
右栏六个 tab：文档、图谱、Wiki、召回、投影、评测。会话检索可叠加到向量投影与图谱染色。评测含 Layer-1 IR 指标与 Layer-2 RAGAS 类 LLM 评分；可从文档生成评测题，人工采纳后入库。
RAG 功能模型（嵌入、重排、图谱抽取、VLM、wiki、考题合成等）在「功能模型设置」中配置；聊天模型由 DSH 同步。完整参数见仓库 docs/plugin-manual.md。
安装与启用¶
官方 README 要求 GitHub 安装钉 tag v0.1.4，不要跟 main。npm 包在 v0.1.4 状态表中为「待发布」；下列 npm 行供发布后使用。
将 <name> 换成你的 DSH profile 名：
# 本地目录（开发安装，改码即被读取）
dsh plugin --profile <name> add link:<本仓绝对路径>
# GitHub（钉 tag；运行时包从同仓 Release 下载）
dsh plugin --profile <name> add git+https://github.com/chenzhiya77/dsh-harness-rag.git#v0.1.4
# npm（发布后可用）
dsh plugin --profile <name> add dsh-harness-rag
装完后重启该 profile 的 DSH，打开右栏「知识库」tab。快速开始步骤如下：
- 确认运行根 — 默认
<DSH_HOME>/harness-rag（DSH_HOME缺省~/.dsh），可更改父目录，实际根为<父目录>/harness-rag。 - 准备运行时 — 下载运行时包（约 471 MB）并解压（约 1.2 GB），启动内置 Qdrant 与知识服务；首次约 1–2 分钟。
- 配置嵌入模型 — 未配置时无法上传；在「功能模型设置」或「智能识别配置」中完成后再上传文档。
首期托管运行时仅提供 Windows x64 包；其他平台面板会提示无可用运行时包，可改外部服务（见操作手册）。部署、升级回滚、清理卸载见 插件操作手册。
典型用法¶
下面是从 README 可复现的主路径，不涉及具体业务 prompt。
- 安装插件并重启 DSH，在知识库面板完成运行时准备与嵌入模型配置。
- 通过面板上传 PDF、Office、表格、视频或 Markdown 等，等待向量 / 图谱 / wiki 三条解析腿就绪（可在文档 tab 看逐路径状态）。
- 在顶栏将当前知识库「绑定」到要使用语料的会话；该会话工具列表中出现六件
hrag_*。 - 在对话中让 agent 先用
hrag_hybrid_search/hrag_graph_search/hrag_wiki_search查内容，必要时用hrag_list_documents枚举、hrag_read_document按片续读原文。 - 在「召回」tab 对同一查询对比三路命中；需要量化时到「评测」tab 跑题库或从召回结果存题。
外部模式：在插件配置中设置非空 backendUrl（及 apiToken），不再下载本地运行时；行为与面板能力仍以操作手册为准。
适用场景与注意¶
适合需要在 DSH 会话内做私有文档 RAG、且希望图谱与 wiki 与向量同库联动、并能在 UI 里管库与评检索质量的开发者。
安装前请自行审阅 GitHub 源码 与 MIT 许可证；插件与托管 knowledge 服务以当前 DSH 进程权限运行，数据默认落在本机 state/。MinerU 云、嵌入与各类 LLM 调用可能产生外网请求与费用；视频 ASR 在托管包缺依赖时需额外安装或服务档。
社区目录 skillhub.cn 插件页 与 GitHub 仓库为独立社区项目，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-harness-rag 把 Agentic RAG 的写入传播、三路检索与文档续读工具，以及知识库面板收进 DSH 插件形态；默认可托管 Windows x64 运行时，也可 backendUrl 对接外部引擎。更多细节以 GitHub README 与 v0.1.4 操作手册 为准。
