前言¶
在 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
