前言¶
在 DeepSeek Harness（DSH）里做带长期资料的智能体会遇到一类反复出现的问题：对话侧只有通用检索工具时，向量命中不稳定、关系型问题难回答，且 agent 无法可靠地「翻完」一篇长文档。常见做法是在对话里挂一个纯向量库，或把检索交给外部服务，但枚举文档、按片续读、图谱与条目线索往往要另写集成。
下面介绍社区插件 dsh-agentic-rag（维护者 chenzhiya77，SkillHub 分类「记忆」）。它在 DSH 内提供内置或可外接的 knowledge 服务、六件 hrag_* 会话工具，以及右栏「知识库」管理面板，覆盖摄取、三路检索、文档读回与质量评测。
这是什么¶
dsh-agentic-rag 是 DSH 上的 Agentic RAG 知识库插件：默认由插件托管本地知识服务（便携 Python、Qdrant、引擎），backendUrl 非空时改走外部服务。对象模型贯通文档、切片、实体与 wiki 条目；向量、图谱、wiki 是同一套对象的三种表示，写入时改动沿派生关系向下传播，读取时三路检索再回溯到可读的文档与切片。
插件 npm 包名 dsh-agentic-rag，当前公开版本 0.2.0（MIT）。package.json 要求 dsh 为 >=0.2.1-rc.2 <0.3.0，Node 为 ^22.19.0 || >=24.0.0。
架构：三块与安全边界¶
插件由三块组成：DSH 宿主工具、浏览器右栏面板、knowledge 服务。
宿主分为 Host 半与 Client 半：Host 持有 hrag_* 工具、面板数据桥与摄取后台任务；Client 只渲染右栏「知识库」tab。解析、切片、嵌入、图谱、wiki、评测与存储在 knowledge 服务侧；托管模式下运行时目录为 <root>/runtime/<version>/，数据为 <root>/state/。
访问边界值得先看清：
- 六件
hrag_*仅在会话绑定知识库后挂载，解绑即从该会话工具表移除。 - Agent 侧无写入工具——上传、删除、解析、生成 wiki 由人在面板完成。
- 托管模式数据与 token 落在运行根
state/；外部模式由apiToken保护服务。 - 包名
dsh-agentic-rag，路由与 localStorage 沿用dsh-harness-rag/harness-rag等兼容标识，降低与旧安装及其他插件的冲突面。
核心能力¶
摄取与多格式解析¶
支持 MinerU 解析 PDF / Word / PPT / 图片，本地直读 Markdown 与纯文本，表格类统一为 GFM（共 19 种后缀）。Excel 按 sheet 成表并保留表头；文档内图片可由 VLM 配文。视频（.mp4 等）将语音、关键帧文字与分镜卡并入切片；ASR 可本地 funasr 或 whisper，托管运行时不自带 funasr / torch，需另装或走转录服务。MinerU 默认云解析，也可自建 MinerU 4.x 并只填服务地址。
加工与全链路联动¶
切片带 heading_path；实体经别名与嵌入阈值归一化；wiki 按门槛与跨切片规则生成并可增量重生成。编辑、重抽、删除切片或增删文档会沿图谱与 wiki 向下传导，读侧则沿来源关系枚举与读回。
三路检索与文档感知¶
绑定同一知识库后，模型可用六件工具：
| 工具 | 作用 |
|---|---|
hrag_hybrid_search |
稠密 + 稀疏 → RRF → 重排（失败自动降级） |
hrag_graph_search |
关系检索，约 1–2 跳 |
hrag_wiki_search |
wiki 条目全文，含用户「我的条目」 |
hrag_list_documents |
枚举文档及状态 |
hrag_read_document |
按篇分页或按片续读 |
hrag_list_wiki_entries |
枚举 wiki 条目 |
命中结果带 chunk_id / doc_id / chunk_index，便于续读。绑定会话会获得检索纪律（向量保底、图谱路、语料边界、读取上限、拒答等），对话人格仍由 DSH 侧配置。
面板、可视化与评测¶
右栏面板含文档 / 图谱 / Wiki / 召回 / 投影 / 评测等 tab，可上传、绑定会话、配置功能模型。会话检索可叠加到向量投影与图谱视图。评测分 Layer-1 确定性 IR 指标与 Layer-2 RAGAS 类 LLM 评分；支持从文档生成考题题库并看趋势。
聊天模型由 DSH 同步；图谱抽取、VLM、wiki 生成、嵌入与 MinerU 等在「功能模型设置」中按角色配置，并支持用 DSH 视觉模型从截图识别厂商配置草稿。
安装与首次启用¶
README（v0.2.0 tag）给出的安装方式如下；不要自行拼接未文档化的 github:owner/repo 形式。
# 本地目录（开发安装，改码即被读取）
dsh plugin --profile <name> add link:<本仓绝对路径>
# GitHub（钉 tag；运行时包从同仓 Release 下载）
dsh plugin --profile <name> add git+https://github.com/chenzhiya77/dsh-agentic-rag.git#v0.2.0
# npm（0.2.0）
dsh plugin --profile <name> add dsh-agentic-rag
安装后重启对应 profile 的 DSH，打开右栏「知识库」tab：
- 默认运行根为
<DSH_HOME>/harness-rag（DSH_HOME缺省~/.dsh），可更改父目录。 - 首次「开始准备」会下载运行时包（约 471 MB，解压约 1.2 GB）并启动内置 Qdrant 与知识服务，首次约 1–2 分钟。
- 须先配置嵌入模型后再上传；未配置时上传会被拦截并引导至「功能模型设置」。
README 状态表中标注 GitHub / npm 安装入口为 v0.2.0 待发布；若以 tag 文档安装，请以仓库 Release 与 npm 实际可用性为准。托管运行时包首期仅 Windows x64；其他平台面板会提示无可用运行时包，可改外部 backendUrl 模式（见仓库 docs/plugin-manual.md）。
典型用法（可复现流程）¶
- 在面板创建或选择知识库，配置嵌入与解析相关功能模型。
- 通过面板上传 PDF、Office、表格、视频或 Markdown 等，等待向量 / 图谱 / wiki 各腿就绪。
- 在顶栏将知识库绑定到当前会话，使六件
hrag_*进入该会话工具列表。 - 在对话中提问：需要语义匹配时用 hybrid；问实体关系时用 graph；需要条目摘要时用 wiki；需要通读长文时先
hrag_list_documents，再hrag_read_document按片续读。 - 在「召回」tab 用同一条查询对比三路命中，必要时存为评测题，在「评测」tab 观察指标趋势。
适用场景与注意¶
适合：希望在 DSH 内自建或可切换外接知识库、需要向量 + 图谱 + wiki 分工检索，并要在 UI 里管理文档与评测检索质量的开发者。
注意：
- 插件与托管 knowledge 服务以当前 DSH 进程权限运行；安装前请阅读 源码 与 MIT 许可证，以及
THIRD_PARTY_NOTICES.md。 - Agent 不能通过工具改库内容，知识更新依赖面板人工操作。
- 视频 ASR、部分解析依赖额外模型或服务；外接模式需自行保护
apiToken与backendUrl。 - SkillHub 目录（dsh-agentic-rag 插件页）为社区站点，与 DeepSeek / 幻方无官方从属关系；GitHub 仓库标明为独立项目。
结尾¶
dsh-agentic-rag 把 Agentic RAG 收成 DSH 内可运维的一条链：托管或外接 knowledge 服务、三路检索加文档续读工具、面板上的图谱 / wiki / 评测与模型配置。若你正在 DSH 上搭建「带记忆」的智能体，可从上述安装命令与绑定会话流程做起，细节以 GitHub README 与操作手册 为准。
