前言¶
在 DSH 裏用 ima 知識庫，常見做法是讓模型直接調 MCP 的 get_doc_content。這篇筆記原文通常幾十萬字，而 ima 的 OpenAPI 裏 get_doc_content 沒有分頁參數——一次性返回整篇，上下文被一篇筆記喫掉。另一個問題是瀏覽：想翻一翻庫裏有哪些筆記、某篇講了什麼，只能把目錄和正文都餵給模型，等於爲了看一眼目錄付一次上下文。
dsh-ima-kb-panel 處理的就是這兩件事：把瀏覽搬到左側欄（不佔上下文），把正文讀取改成「檢索 + 按字符偏移分頁」，並且全部按需、帶上限。插件由 how8088 維護，屬於客戶端類插件，在社區目錄 SkillHub 有收錄。
下面按它是什麼、裝怎麼裝、怎麼用、有哪些要注意的來講。
一、這是什麼¶
給 DeepSeek Harness（DSH）用的 ima 知識庫插件，包名 dsh-ima-kb-panel，當前版本 2.7.0，許可證 MIT，要求 Node >= 18。它做三件事：
- 在 DSH 左側欄放一個入口，下分「筆記」和「知識庫」兩個頁籤，瀏覽、檢索、滾動閱讀都在瀏覽器側完成；
- 在對話裏註冊一組只讀工具，讓 AI 按需取筆記與個人知識庫的內容，返回內容有字符上限；
- 在 Host 側把筆記正文和個人知識庫緩存到本地，重啓後只補新增或改動的內容。
插件對 ima 賬號沒有硬編碼，它列出當前憑證能看到的全部筆記。所以「換知識庫」等於換憑證或加過濾，不用改代碼。
二、核心功能¶
側邊欄面板¶
左側欄一個入口，兩個頁籤：
- 筆記：按分類（課程原文 / 學員總結 / 盤中記錄 / 公衆號文章…）摺疊瀏覽、全文檢索、滾動閱讀。分類由插件根據標題自動歸組，列表帶篇數與字數徽標，可隨分類展開收起。
- 知識庫：選知識庫後看到麪包屑 + 文件夾樹 + 文件名檢索，進入文件詳情可以「下載原文」，下載走 Host 代理拿到帶簽名的 Word/PDF。
面板字面檢索無命中時，插件會自動補一輪模糊檢索，結果可以直接點開。
對話工具¶
| 工具 | 用途 | 上限 |
|---|---|---|
kb_list(query?) |
列出全部筆記：標題、note_id、字數、開頭預覽；筆記多時可用 query 只列標題含該詞的 |
有界 |
kb_search(query, note_id?, limit?) |
全庫子串檢索，一篇可回多段，帶字符偏移量 | 片段 ≤ 600 字，默認 8 段 |
kb_read(note_id, offset?, limit?) |
按偏移分頁讀正文 | 默認 6000 字，上限 3 萬字 |
kb_find(query, start?) |
ima 官方分詞檢索：換一種說法也能找到，返回命中筆記列表 | 每頁 20 篇 |
kb_space_list() |
列出可見的知識庫（kb_id、文件數、說明、角色） |
有界 |
kb_space_browse(kb_id, folder_id?, limit?) |
列目錄：文件夾 / 文件（media_id、類型） |
單頁 ≤ 50 條 |
kb_space_search(kb_id, query, limit?) |
按文件名/文件夾名檢索，不搜正文 | ≤ 50 條 |
kb_search 和 kb_find 是互補關係：前者是本地字面匹配、帶 offset，後者走 ima 官方分詞召回。不確定原文措辭時先用 kb_find 找候選篇，再用 kb_read 讀。
檢索是字面匹配，不是語義檢索：搜「止損」能找到，搜「虧了怎麼辦」不一定能找到「止損」。
緩存與性能¶
- 正文落盤：正文緩存在
~/.dsh/cache/ima-kb-panel/，重啓 DSH 後不再全量重取，只補modify_time變過的筆記，通常幾篇、秒級完成。 - 默認不自動預熱：
autoWarm默認off，首次裝完要點面板裏的「⋯ → 緩存全部正文」纔會開始取正文，進度顯示在面板頭部。既有庫 70+ 篇、約 200 萬字，逐篇一次請求，這一步需要等一會兒。 - 主機端併發控制：爲規避 ima 限流
code=200001，取正文時控制併發與節拍，配指數退避重試。 - 個人知識庫本地緩存（v2.4.0 起）：只緩存筆記和
base_type爲「個人知識庫」的庫，緩存到kb-<hash>.json（列表 + 目錄樹 + md/docx/txt 正文）及可選的pdf/<mediaId>.bin。訂閱 / 加入的共享知識庫（如「宏觀研報精選」「深證信公告庫」）不寫磁盤，仍走在線讀取。斷網時目錄、正文、文件名檢索、PDF 查看都可從本地走。
只讀約束¶
不寫筆記、不上傳、不刪除，本機正文緩存文件除外。插件不做任何修改 ima 側內容的操作。
三、安裝與啓用¶
前置條件¶
| 需要 | 說明 |
|---|---|
| DSH | 桌面版或 Web 版都行，插件是 profile 級安裝 |
| ima 憑證 | Client ID + API Key，在 https://ima.qq.com/agent-interface 生成 |
| 網絡 | 能訪問 https://ima.qq.com |
裝了什麼¶
裝完都要重啓 DSH 纔會加載新插件。插件通過 plugin_manager 的 install_bundle 安裝，來源是 release 裏的 .tgz 包或本機源碼目錄。
方式 A，把 release 裏的 .tgz 交給 DSH 裏的 AI（最省事）：
請幫我安裝本地插件：<路徑>\dsh-ima-kb-panel-2.7.0.tgz
用 plugin_manager 的 install_bundle 安裝，裝完告訴我是否需要重啓。
方式 B，自己調工具：
plugin_manager(action="install_bundle", target="<tgz 的絕對路徑>")
方式 C，從源碼目錄安裝（只在改代碼時用）：
plugin_manager(action="install_bundle", target="<本倉庫目錄的絕對路徑>")
用目錄安裝是軟鏈接（link:），DSH 會報 restart-required；用 .tgz 安裝是真實拷貝，熱應用更順。改完代碼要重新 pnpm pack 再裝。
方式 D，從 GitHub 升級（換電腦或升版本推薦）：每個 v* tag 由 Actions 自動打包併發 Release，下載地址是 github.com/how8088/dsh-ima-kb-panel/releases，下載最新的 dsh-ima-kb-panel-<版本>.tgz，然後在 DSH 裏新開會話說：
請用 plugin_manager 安裝本地插件：<tgz 完整路徑>
重啓 DSH（或刷新頁面）即可。倉庫是公開的，不用登錄。
首次運行要補的兩件事¶
插件本體之外，換新電腦時還有兩件事各處理一次：
| 東西 | 怎麼弄 |
|---|---|
| ima 憑證 | 把 ~/.config/ima/client_id 與 api_key 複製到新電腦同路徑，絕不要進倉庫 |
| AGENTS.md 聯動段 | 把 docs/AGENTS-聯動段.md 的內容追加到 ~/.dsh/AGENTS.md（v2.3.0 起這份文檔隨包安裝，位在插件目錄的 docs/ 下） |
兩個技能（market-research / ima-kb）自 v2.2.0 起插件啓動時會自動裝到 ~/.dsh/skills/，已存在不覆蓋，不用再手工複製。桌面版（Electron）自 v2.3.0 起也不要手工改 import：插件啓動時先按裸包名解析 @deepseek-ai/dsh-tools / @deepseek-ai/schemastery，失敗再按 process.execPath 反推安裝目錄從 app.asar 裏讀，換安裝路徑也不用改代碼。
憑證放哪¶
默認兩個文件：
~/.config/ima/client_id ← Client ID
~/.config/ima/api_key ← API Key
Windows 上就是 C:\Users\<你>\.config\ima\。一行一個，不要引號，不要多餘空格。也可以用環境變量 IMA_CLIENT_ID / IMA_API_KEY，優先級高於文件。面板的「首次運行」界面會把這兩個絕對路徑直接顯示出來。
確認可用¶
- 重啓 DSH，左側圖標欄應出現書本 + 放大鏡圖標；
- 點它，左側應列出全部筆記（不只是 20 篇），頭部顯示
N 篇 · M 字；正文還在後臺載入時顯示「載入正文 N/M」和進度條； - 在對話裏問：「查一下我的知識庫：倉位管理我是怎麼講的？」AI 應調用
kb_search並引用原文。
如果面板顯示「還沒連接 ima 賬號」，說明憑證沒放好，回到上一節檢查路徑。
四、配置項¶
在 設置 → 插件 → ima 知識庫面板 裏改，或直接改 profile 的 cordis.patch.yml：
- id: ima-kb-panel
name: 'dsh-ima-kb-panel'
config:
credentialsDir: 'D:/ima-creds' # 憑證目錄換地方
titleFilter: '雪球,宏觀' # 只納入標題含這些詞的筆記
maxNotes: 200
contentTtlMinutes: 360
| 配置項 | 默認 | 作用 |
|---|---|---|
credentialsDir |
空（= ~/.config/ima） |
憑證目錄 |
baseUrl |
https://ima.qq.com |
接口根地址，一般不用改 |
clientIdEnv |
IMA_CLIENT_ID |
client_id 讀哪個環境變量 |
apiKeyEnv |
IMA_API_KEY |
api_key 讀哪個環境變量 |
maxNotes |
500 | 最多收錄多少篇（1–500，插件自動翻頁；list_note 單頁上限 20，插件會翻到 is_end） |
contentTtlMinutes |
10080 | 磁盤正文最長保留期（分鐘）；是否重取看 modify_time |
cacheDir |
空（= ~/.dsh/cache/ima-kb-panel） |
正文緩存目錄，填 - 表示不落盤 |
titleFilter |
空 | 只看標題含這些詞的筆記，逗號分隔 |
skillsDir |
空（= ~/.dsh/skills） |
隨包技能安裝到哪 |
autoInstallSkills |
on |
啓動時自動裝隨包技能（已存在跳過）；填 off 關閉 |
autoWarm |
off |
是否自動把全部筆記正文拉到本地。默認 off：只有手動點「⋯ → 緩存全部正文」才取；填 on 恢復啓動/檢索時後臺自動預熱 |
五、典型用法¶
瀏覽¶
點左側書本圖標，切到「筆記」頁籤瀏覽分類，用頂部檢索框搜內容；切到「知識庫」頁籤選庫、進目錄、按文件名找文件，進文件詳情後下載原文。整個瀏覽過程不出面板，不進上下文。
在對話裏取內容¶
不確定原文措辭時，先用分詞檢索找候選篇：
kb_find(query="減倉的理由", start=0)
拿到候選 note_id 後按偏移讀正文：
kb_read(note_id="xxx", offset=0, limit=6000)
需要字面定位時用子串檢索，返回片段帶字符偏移量，可以直接拿 offset 繼續讀：
kb_search(query="止損", limit=8)
個人知識庫的目錄與文件名檢索：
kb_space_list()
kb_space_browse(kb_id="xxx", folder_id=null, limit=50)
kb_space_search(kb_id="xxx", query="年報", limit=50)
把整庫正文拉到本地¶
首次安裝後，面板頭部點「⋯ → 緩存全部正文」，進度在面板頭部顯示。預熱完成後寫入磁盤緩存，之後重啓 DSH 是秒開，只用補充 modify_time 變過的那幾篇。個人知識庫整棵緩存走 GET /ima-kb/api/kb-warm?kb=<kb_id>，阻塞到取完，進度快照見 GET /ima-kb/api/kb-warm-status。
本機 HTTP 接口¶
面板使用的接口全部要求瀏覽器同源會話，未授權返回 401/403。常用幾個：GET /ima-kb/api/state 看連接診斷（是否配置、憑證來源、路徑、過濾詞、筆記數、預熱進度）；GET /ima-kb/api/notes 取全部筆記列表；GET /ima-kb/api/search?q=&limit= 檢索；GET /ima-kb/api/kb-files?kb=&folder=&cursor= 取目錄內容加麪包屑；GET /ima-kb/api/kb-raw?media_id=&title= 代理下載帶簽名的原件。面板裏出錯時會顯示真實 HTTP 狀態與服務端消息，而不是一句籠統的「沒有權限」。
六、適用場景與注意¶
適合把 ima 當個人資料庫用、筆記量比較大（幾十篇到上百篇、百萬字量級）、又不想每次瀏覽都燒上下文的人。也適合需要 AI 按原始片段引用知識庫內容的場景，因爲工具返回帶偏移量的片段，模型可以自行決定讀不讀、讀哪一段。
幾點注意：
- 插件不改動 ima 側任何內容，但以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證（本倉庫爲 MIT）。
- 不要改用 MCP 的
mcp__ima-kb__get_note_content讀大筆記：無分頁，一次返回整篇，最長出現過 54.8 萬字符。 - 共享知識庫不落盤：訂閱 / 加入的庫文件量級可達幾十萬上百萬，插件一律在線讀取，別指望離線可用。
- 正文緩存目錄裏的文件屬於本機臨時數據，
cacheDir改成-可以完全不落盤。 - 星標數目前爲 0，生態較新，遇到版本差異以 README 與
package.json爲準。
結尾¶
這個插件的價值不在功能多，而在補了兩個具體的缺口：get_doc_content 缺的分頁，和「看一眼目錄就要付上下文」這件事。前者靠 kb_search + kb_read 的偏移分頁補齊，後者靠側邊欄面板和本地緩存拿掉。如果你的筆記量大、正文需要反覆引用，值得先按上面的步驟裝上試一下。
目錄頁：https://www.skillhub.cn/plugins/how8088/dsh-ima-kb-panel
倉庫：https://github.com/how8088/dsh-ima-kb-panel
