前言¶
在 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 與操作手冊 爲準。
