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