ima 知识库连接器 0131kikimy/dsh-ima

dsh-ima

让 DeepSeek Harness 能调用 腾讯 ima 知识库：把 ima 的检索、问答、知识库能力暴露成模型可直接调用的原生工具。

DSH 插件（bundle）形态，零第三方运行时依赖，装上即用。

在 DSH 里让模型调用，或直接：
plugin_manager(action: "install_bundle", target: "<本仓库的绝对路径>")

工具

| 工具 | 作用 | 需要什么 |
| ima_health | 体检两条通道，回报当前哪些能力真的可用。排障第一步 | 无 |
| ima_settings | 给出可视化设置页地址（填 Client ID / API Key，保存即生效） | 无 |
| ima_open | 唤起 ima 桌面客户端（必要时拉起、把托盘窗口显示出来、摆回屏幕内），可让它打开一个网址 | 本机 ima |
| ima_ask | 提问：配了 HTTP 接口 → 返回答案 + 引用；否则桌面「投递」（默认关闭的实验能力） | HTTP（推荐） |
| ima_search | 在知识库里检索（官方 API 下只返回标题，不含正文） | HTTP |
| ima_kb_list | 列知识库（id / 名称 / 文档数） | HTTP |
| ima_list_docs | 列知识库里的文档与文件夹（递归，给出 mediaId） | ima 官方 API |
| ima_get_doc | 按 mediaId 取正文：下载原件 + pdftotext 抽 PDF 文本 | ima 官方 API |
| ima_import | 把 URL 或纯文本写入知识库（写操作） | HTTP |

需要引用原文的任务（知识卡片、备课摘要、逐字核对）走这条链： ima_kb_list → ima_list_docs（拿 mediaId）→ ima_get_doc（拿正文）。
ima_search 只返回标题；ima_ask 在官方 API 下也只是标题级检索结果。

能力边界

不同通道能做什么差别很大，这里按实测结论列清楚，避免调用方误以为「投递成功 = 问到了」。

| 通道 | 结论 | 说明 |
| HTTP 接口 | ✅ 能读回 | 问答、检索、列库、写入。路径与响应字段全可配；本地 mock 全链路 18 项自检通过 |
| 桌面 · 唤起 | ✅ 可用 | EnumWindows 按 PID 找到 Chrome_WidgetWin_1 真窗口 → ShowWindow。注意 Get-Process.MainWindowHandle 对托盘态返回 0，不能用 |
| 桌面 · 读回内容 | ❌ 不可用 | 该客户端忽略 --remote-debugging-port（干净环境实测无 DevToolsActivePort），且渲染器 DOM 不向 UIA 暴露，只到浏览器外壳 |
| 桌面 · 投递问题 | ⚠️ 实验，默认关闭 | 靠窗口矩形比例猜输入框位置 + 模拟击键，不同布局下可能点不中。app.allowDelivery 默认 false |

结论：要答案和检索结果，必须配 HTTP 后端；桌面端只保证「唤起」。

安装

plugin_manager(action: "install_bundle", target: "<本仓库绝对路径>")

DSH 会把 dsh-ima 写进 profile 的 bundle 列表，工具立即出现在模型侧。
卸载：plugin_manager(action: "remove_bundle", target: "dsh-ima")。

自检（不依赖宿主）：

node test/selfcheck.mjs

可视化设置（推荐）

装好之后直接对模型说「打开 ima 设置」/ 调用 ima_settings，它会给你一个本机设置页地址：

http://127.0.0.1:<dsh端口>/dsh-ima/settings?token=<一次性令牌>

页面上可以直接填写 Client ID / API Key / 接口地址 / 默认知识库 / 检索条数 / ima 客户端路径，点「保存」立即生效（写入 $DSH_HOME/dsh-ima/settings.json，无需重启），点「测试连接」会同时探测 HTTP 接口与桌面客户端两条通道并回显真实状态。

- 页面只监听本机，且必须带令牌才能读写（令牌首次启动生成并持久化，URL 跨重启稳定）。
- 设置页保存的值优先于 cordis.patch.yml 里的 config。
- 若宿主没有 webServer 服务（非 Web 部署），设置页不出现，此时用下面的 YAML 方式配置。

配置（YAML 方式）

目前设置面板会显示 unsupported（本包用纯对象校验器，不依赖宿主包；以 link: 方式安装时也解析不到 schemastery）。
请直接在 profile 的 cordis.patch.yml 末尾追加下面这段（$DSH_PROFILE_DIR 是当前 profile 目录）。

方式一：接 ima 官方 OpenAPI（推荐，能读回你账号里的知识库）

在 <https://ima.qq.com/agent-interface> 领取 API Key（页面会给 Client ID 与 API Key），然后：

- id: dsh-ima
config:
http:
preset: ima # 走腾讯 ima 官方 OpenAPI clientId: 'YOUR_CLIENT_ID' # 32 位十六进制 apiKey: 'YOUR_API_KEY' skillVersion: 1.1.10 # 作为 ima-openapi-ctx 上报，按官方客户端默认值即可 knowledgeBase: '' # 可选：默认知识库 id（ima_kb_list 可查） topK: 8

协议来自官方 ima-skills 包里的 ima_api.cjs：POST https://ima.qq.com/<apiPath>，请求头 ima-openapi-clientid / ima-openapi-apikey / ima-openapi-ctx: skill_version=…。

能力边界（重要）：ima 官方 OpenAPI 只有知识库与笔记接口，没有问答生成接口。
所以接上之后：ima_kb_list / ima_search 返回真实数据；ima_ask 会退化为检索汇总，并在答案首行标注「ima 开放接口没有问答生成能力」。要真正的问答，需要另接带 LLM 的问答服务。

方式二：接你自己的 REST 接口

- id: dsh-ima
config:
backend: auto # auto | http | app；auto = 配了 http.baseUrl 就走 HTTP，否则走桌面 knowledgeBase: '' # 可选：默认知识库 id 或名称 topK: 8 # 可选：检索条数 http: preset: generic baseUrl: 'https://your-ima-endpoint.example.com' token: 'YOUR_TOKEN' authHeader: Authorization # 默认 Authorization authScheme: 'Bearer ' # 默认 'Bearer '；不需要前缀就留空 headers: # 可选：任意附加请求头（非 Bearer 鉴权用得上） X-Client-Id: 'YOUR_CLIENT_ID' X-Api-Key: 'YOUR_API_KEY' paths: ask: /v1/ask search: /v1/search kbList: /v1/knowledge_bases import: /v1/documents mapping: # 响应字段路径，支持 a.b[0].c answer: answer citations: citations hits: hits hitTitle: title hitSnippet: snippet hitUrl: url hitScore: score timeoutMs: 60000 app: executable: '' # 留空 = 自动探测（运行中进程路径 / 常见安装位置） launchTimeoutMs: 20000 allowDelivery: false # 桌面投递（实验），默认关闭

配置非法会在加载期响亮失败，不会静默回落默认值。

HTTP 接口契约

插件按「你填的路径 + 字段映射」发请求，不绑定某一家 API 形状：

POST {baseUrl}{paths.ask} {"question","knowledge_base","top_k"} → {answer, citations[]}
POST {baseUrl}{paths.search} {"query","knowledge_base","top_k"} → {hits[]}
GET {baseUrl}{paths.kbList} → {knowledge_bases[]}
POST {baseUrl}{paths.import} {"url"|"text","title","knowledge_base"} → {id, status}

mapping.answer 也可以写成 choices[0].message.content——OpenAI 兼容的 /chat/completions 直接能接。

安全设计

桌面端做键盘输入时，任何一步失误都可能把内容打进别的应用。因此脚本里是先验证、再动作：

1. SetProcessDPIAware() 在任何坐标计算之前执行——否则拿到的是逻辑像素，算出的点击点会偏；
2. 点击前用 WindowFromPoint + GetWindowThreadProcessId 校验该点属于 ima 进程，不属于就报错、不点；
3. 每次击键前用 GetForegroundWindow 校验前台是 ima，不是就报错、不打；
4. 返回值如实回报 foregroundVerified / pointPid / deliveredWhileImaForeground，并提供 dryRun: true 只演练不动作。

ima_ask 在桌面形态下会先用 dryRun 探一次；app.allowDelivery 未打开时直接拒绝并说明原因，而不是假装成功。

已知限制 / Roadmap

1. 桌面读回：唯一可行方向是截图 OCR（定位占位符 + 读答案），本版未做——误读成本高，没有可靠判据不如不做。
2. 桌面投递：启发式定位，默认关闭；打开后建议先 ima_ask({ dryRun: true }) 看坐标与归属再小步试。
3. 深链接：imacopilot://open?url=<encoded> 是 ima 注册的唤起路由（只开窗、不返结果），ima_open 用它把网页丢给 ima。
4. HTTP 后端：无重试、无流式；按需再加。

许可

MIT。图标为本项目原创 SVG。