dsh-ima：让你的 AI 助手用上腾讯 ima 知识库

装好之后，你的 AI 助手就能翻你自己的 ima 知识库：列知识库、搜文档、把某份文档的正文读出来。

全程不用写代码：装好插件 → 点左侧栏的「ima」图标 → 粘贴两个值 → 保存。

---

装之前准备两样东西

1. DeepSeek Harness（已安装并能正常打开）。

2. 一个 ima API Key。打开 https://ima.qq.com/agent-interface，页面会给你两串东西：

   • Client ID（32 位字母数字）
   • API Key（一串较长的字符）

   ⚠️ 这两串只显示一次，先复制到记事本里存好。

---

安装（两步）

第一步：把插件装进 DSH。在 DSH 里让 AI 执行：

plugin_manager(action: "install_bundle", target: "github:0131kikimy/dsh-ima")

第二步：重启 DSH（关掉再打开）。重启后左侧边栏会多出一个 ima 图标。

---

填 API Key（就是那个左侧栏图标）

1. 点左侧边栏的 ima 图标；
2. 页面里填 Client ID 和 API Key；
3. 点「保存」——立即生效，不用重启；
4. 点「测试连接」看到 reachable: true 就成功了。

填错了也不要紧：再点一次图标就能改。数据只存在你自己电脑上（~/.dsh/dsh-ima/settings.json）。

---

装好后能做什么

直接对 AI 说人话就行，它会自己挑工具：

你可以说	插件会做
「我 ima 里有哪些知识库？」	列出所有知识库和文档数量
「AI 通识课里都有什么文件？」	列出这个知识库的文档清单
「把《人工智能概念解析》那份课件的内容读出来」	下载原件并抽出正文
「在知识库里搜一下 transformer」	关键词搜索，返回命中的文档
「打开 ima」	帮你把 ima 客户端调出来

对应 16 个工具（AI 自动调用，你不用记名字）：

读（安全的，随便用）

工具	作用
ima_health	检查配置对不对、两条通道通不通
ima_settings	给出设置页地址
ima_kb_list	列出知识库
ima_list_docs	列出某个知识库里的文档（带 mediaId）
ima_get_doc	按 mediaId 下载原件并抽出正文
ima_search	关键词搜索
ima_ask	检索汇总（见下面「说明」）
ima_list_notebooks	列出笔记本
ima_list_notes	列出笔记
ima_get_note	读一篇笔记的正文
ima_open	打开 ima 客户端

写（会真的改你的账号，必须带 confirm: true）

工具	作用
ima_create_note	新建笔记（Markdown）
ima_append_note	往已有笔记末尾追加
ima_add_note_to_kb	把笔记归档进知识库
ima_upload_file	把本机文件上传进知识库
ima_import	把网址写进知识库

写操作有硬护栏：不传 confirm: true 一律直接拒绝，并且提示 AI 先跟你确认目标。 另外腾讯没有删除接口——写进去的东西要删得你在 ima 里手动删。

---

能读什么格式的正文

ima_get_doc 下载原件后会自动抽文字：

格式	支持
PDF	✅ 用 pdftotext（扫描版需 OCR，会如实提示）
Word .docx / PPT .pptx / Excel .xlsx	✅ 内置解析（自己解 ZIP + XML，不依赖第三方库）
Markdown / TXT / CSV / HTML	✅ 直接读文本
图片 / 音频 / 其他	⬇️ 只下载原件，不解析

---

说明（三件事，避免误会）

• ima_ask 返回的是"检索汇总"，不是 AI 生成的答案。腾讯 ima 的开放接口只提供知识库检索与文档读取，没有问答生成接口；所以插件会如实标注，不会假装答出来。
• 只想读某份文档的正文，用「读某份文档」这类说法。插件会走「列文档 → 下载 → 抽文字」这条链路，抽不出文字时也会明确告诉你（比如扫描版 PDF 需要 OCR），不会糊弄。
• 不能新建知识库。官方开放接口没有这个能力，只能往你已有的知识库写；要新建库请直接在 ima 客户端里建。

---

常见问题

问：侧边栏没有 ima 图标？ 答：先确认重启过 DSH；再看 DSH 的插件列表里 dsh-ima 是否已启用。Web 版 DSH 才有侧边栏。

问：点图标后页面打不开 / 空白？ 答：点面板右上角的「刷新」；仍然不行就重启一次 DSH。

问：测试连接显示不可达？ 答：三个常见原因——API Key 复制少了字符、Client ID 和 API Key 贴反了、网络到不了 ima.qq.com。

问：会把我电脑上的文件传走吗？ 答：不会自动传。只有你明确让 AI「把这个文件传到知识库」，并且确认后，ima_upload_file 才会把你指定的那一个文件上传到 ima（走腾讯云 COS 中转）。其余工具只读取 ima 里的内容。

问：写错了能撤销吗？ 答：不能。腾讯开放接口没有删除接口，笔记和知识库内容需要你到 ima 客户端里手动删。所以写操作都要求 confirm: true。

问：支持哪些系统？ 答：核心功能（知识库/搜索/读正文/写笔记）跨平台可用；「打开 ima 客户端」只有 Windows 能用。

---

卸载

plugin_manager(action: "remove_bundle", target: "dsh-ima")

本地存的 API Key 在 ~/.dsh/dsh-ima/settings.json，不需要就删掉这个文件夹。

---

许可

MIT