Quberi 知识库搜索 quberi/dsh-quberi

dsh-quberi

在 DeepSeek Harness 里查询你的 Quberi 知识库：搜索、浏览、保存笔记、上传文件。

有意思的地方不在搜索本身，而在搜索被允许返回什么。Quberi 按每篇文档控制权限，而不是按空间：两个人在同一个空间问同一个问题，可能得到不同答案，因为检索过滤在向量索引内部执行，被拒绝的文档从一开始就不会成为候选。

- 按文档设置访问规则，拒绝优先——授权无法推翻隐藏某篇文档的决定。
- 检索时过滤，所以你拿到的是完整结果集，而不是缺了几块的结果。
- 已撤销的图片链接会失效——在访问权限被移除之前签发的图片预览 URL，下次请求会返回 404。
- 写入只进入你有编辑权限的空间；每次上传都需要你确认。

向 Harness 提问关于你文档的问题。第一次，浏览器会自动打开，让你批准访问；之后模型就能调用 quberi_search，在你选定的那个组织里，找到你在 Quberi 中有权阅读的文档片段（指定空间就只搜那一个）。它还能调用 quberi_save，把一条笔记（聊天中的结论、决定或摘要）加进你的知识库；调用 quberi_upload_file，从你的工作区添加文件。quberi_list_spaces 和 quberi_list_documents 显示有哪些内容，quberi_search_images 按描述找图片并在聊天中展示。保存功能是 0.3.0 新增的，上传功能是 0.4.0 新增的；两者都需要重新登录一次，且登录范围包含对应权限。浏览和图片搜索只需要搜索权限。上传只在你批准该文件之后发生（见「上传文件」）。

每个权限范围单独授权：搜索需要 knowledge:read，保存需要 knowledge:write，上传需要 knowledge:upload。别人单独分享给你的文档，即使你读不了它所在的空间也能找到；对你隐藏的文档，即使你能读它所在的空间也找不到。

安装

在 DeepSeek Harness 中打开 Plugins → Add plugin，输入：

dsh-quberi

或者在终端中执行（把 desktop 换成你的配置档名称）：

dsh plugin --profile desktop add dsh-quberi

然后重启 Harness。升级时先移除旧版本（dsh plugin --profile desktop remove dsh-quberi），再重新添加。

你需要一个 ai.quberi.com 上的 Quberi 账号，或者你自己的 Quberi 服务器（见「配置」）。

插件在你的机器上以你的权限运行，所以先读源码。代码不多：src/oauth.ts（登录辅助）、src/browser.ts（打开浏览器）、src/controller.ts（登录、token 刷新、搜索、保存、上传）、src/upload.ts（哪些文件可以上传，以及审批关卡）和 src/index.ts（/quberi 命令和各个工具）。它唯一的运行时依赖是 @deepseek-ai/schemastery。

从源码安装

npm install
npm test
npm pack # builds lib/ and writes dsh-quberi-<version>.tgz
dsh plugin --profile desktop add /path/to/dsh-quberi-<version>.tgz

使用

| 命令 | 作用 |
| /quberi login | 打开浏览器登录 Quberi（链接也会一并显示，以防浏览器没打开）。选择组织并授权。一般用不到：第一次搜索时会自动完成。如果你用旧版本登录过，再运行一次，以允许保存或上传。 |
| /quberi status | 显示是否已连接。绝不打印 token。 |
| /quberi logout | 在 Quberi 撤销登录，并在本地清除。 |
| /quberi mode [text\|image\|both] | 显示或设置搜索范围：文档的文本、图片，或两者（默认）。见「搜索范围」。 |

登录页会说明 Harness 请求做什么（搜索、保存笔记、上传文件）、不能做什么，并让你选择组织（此处界面为中文）：

The Quberi sign-in page for DeepSeek Harness: permissions requested and the organization to use

你也可以随时在 Quberi 的 Account → Connected tools 里断开连接。

登录完成后，浏览器会显示确认页，Harness 回到前台（macOS）。无需复制粘贴任何内容。

在没有屏幕的机器上（远程 shell），不会打开浏览器；插件会给你一个链接，让你在另一台设备上打开。

使用前提

你选择的组织必须允许外部工具。该选项默认关闭。由所有者或管理员在 Admin console → Integrations → Outside tools 中开启；所有者和管理员在授权页上也会看到「Turn on」按钮。

哪些内容会离开 Quberi

搜索返回的段落会发给 Harness，以及 Harness 使用的任意 AI 模型。Quberi 的「发送前检查」步骤不适用于这条路径。每次搜索都会记入组织的审计日志（工具名称和返回的文档，绝不记录问题或文本）。

quberi_read_around 发送的文档内容比搜索更多：段落前后各最多 3000 个字符，仅在模型请求时发送，且仅限你能在 Quberi 中打开的文档。每次调用都会记入审计日志（文档、版本和字符数，绝不记录文本），并受速率限制。页面图片由 Harness 从你 Quberi 地址上的短期链接获取；该链接只为你指向一个页面，在你退出该工具、失去文档访问权限或约十分钟后失效。组织所有者可以关闭外部工具，这会立即终止上述所有行为。

保存笔记

quberi_save 接收标题、笔记文本（Markdown），以及可选的空间名称。不指定空间时，保存到你的个人空间。该工具会要求模型先提议保存并等你同意，而不是悄悄保存，但那只是给模型的指令，不是保证：真正决定的是你批准了什么，以及你观察模型做了什么。

这里，用户让 Harness 把对话保存到个人空间。模型调用 quberi_save，然后说明笔记去了哪里、什么时候能被搜到：

把对话保存为个人空间中的笔记

保存后的笔记会成为该空间里的一份文档。任何能读取该空间的人都能找到它，所以只在确有需要时才指定共享空间。保存操作会记入审计日志（记录工具名和新文档，不记录正文）。

段落位于文件中的哪个位置

当你的 Quberi 服务器记录这些信息时，每个段落都会带上它的位置，因此回答可以指出该去原文哪里查看：PDF 的页码（page 3、pages 3-4）、演示文稿的幻灯片、电子表格的工作表和行、Word 文件的标题和段落，或文本文件的行号。文件有多个版本时会显示版本号（version 1 (older, replaced by version 2)）。从扫描件读出的段落，或模型对图片的描述，都会标注出来，因为它们可能出错。服务器没有给出位置的段落不显示任何位置信息；旧版服务器则完全保持原有结果。

引用段落

当你的 Quberi 服务器发送结果时，每个段落都带一行 Cite as:（例如 handbook.pdf, page 3, version 2 (latest)），并要求模型在每一点取自某段落的论述末尾附上这一行，照原样复制，绝不写出该行未给出的页码或版本。这是对模型的要求，Harness 无法强制执行。没有记录位置的段落，只引用其文档名。

查看页面，以及阅读段落前后的内容

当你的 Quberi 服务器支持时，搜索结果还会附带另外两样东西。

页面。 来自 PDF 的段落（以及从图片中读出的文字）会附带一个链接，指向该段落所在页面的图像。结果会给模型一行现成的 ...，并告诉它只在你要求查看原文时才显示页面。幻灯片、电子表格和 Word 文件没有可绘制的页面，因此不带图像；它们的位置（幻灯片、工作表和行、段落）仍会标明。Harness 只传递位于你的 Quberi 地址且属于页面路径的链接；其他链接一律丢弃。

段落前后的文字。 quberi_read_around 返回同一文件、同一版本中某段落前后的文字，这样模型无需你打开文件就能结合上下文阅读。搜索结果会把要传入的确切值（document_id、version、char_start、char_end）交给模型，并告诉它只在你想要更多上下文或某段落看起来被截断时才询问。该功能对从扫描件或图片读出的文字无效，因为没有可读取的文本层，它会明确说明这一点。

搜索的范围

文本搜索看不到图片，所以默认情况下 quberi_search 会同时查两边：返回匹配的段落，并在旁边附上几张可能是你想要的图片（比如问「动物母狮」，即使没有文档提到它，也会显示母狮的图片）。这些图片只是候选，绝不是答案，而且只有得分高于下限的才会收录。没有这个机制，按主题找图只会得到「什么都没找到」。

这个例子里，问题是「VMC-850 的设备铭牌和开机前检查」。模型先搜索，再根据操作规程作答，并把找到的铭牌图片放在文字旁边。文本文档对铭牌本身只字未提，图片则说明了。

在 Harness 里向 Quberi 提问：搜索调用和回复中的铭牌图片

回复的其余部分：来自操作规程的文字

回复的结尾：通用的开机前检查清单

- 说「只要文档」或「只要图片」，模型会把 kind 设为 text 或 image。
- /quberi mode text 或 /quberi mode image 替你固定下来，并覆盖模型的设置；/quberi mode both 回到默认。在 text 模式下，图片工具会拒绝执行。这个选择一直有效，直到 Harness 重启；默认值用 searchMode 设置（见下文）。

/quberi mode text，然后 /quberi mode both

- both 需要支持它的 Quberi 服务端。旧版服务端只搜文本，插件也就拿不到图片。
- 找图片会调用 Quberi 的图片模型，所以有单独的限流。如果达到限流，或者图片搜索已关闭，文本结果仍然会返回。

查找图片

quberi_search_images 按描述（「一个带两个孔的红色支架」）在你可读的文档里找图片，最接近的排在前面，也可以限定在某个指定空间里。Harness 无法显示工具返回的图片，但能显示模型回复里的 Markdown 图片，所以每条结果都带一个指向小预览图的链接（JPEG，最大 320 px），并要求模型原样粘贴到回答里。由此有三点：
- 链接有效期很短（约十分钟），且只对应一张图片。它不需要登录头就能打开，所以任何拿到链接的人都能打开那张小预览图，直到过期。如果你在 Quberi 里撤销这个工具、失去该空间的访问权限，或者图片被删除或归档，链接会立即失效。
- 模型必须原样复制链接，不能改动。这是请求，不是保证：模型可能丢弃或改动它，那样就不会出现预览。再问一次。
- 插件只转发指向你 Quberi 地址的链接，所以回复无法把聊天窗口带到其他站点。
搜索与文本搜索使用同一套空间隔离，每次使用都记入审计日志（记录返回的图片，绝不记录你的描述）。它需要带图片搜索的 Quberi 服务器；旧版会明确说明。

浏览

quberi_list_spaces 列出你能读取的空间：你的个人空间和团队空间，每个空间有多少文档，以及你能否编辑（也就是在那里保存或上传是否可行）。quberi_list_documents 列出你指定空间里的文档，最新的在前：名称、类型、大小、最后更新时间和是否已可搜索。每次最多返回 50 条，并给模型一个游标用于翻下一页。传入 type（image、pdf、word、spreadsheet、presentation、text 或 other）只列出该类文件；这需要支持该功能的 Quberi 服务器（旧版会忽略过滤条件）。

被问到「我有哪些空间和文档？」时，模型先列出空间，再列出每个空间的文档。图片标记为可按图片搜索，文本文件标记为可按内容搜索。

列出已登录用户可读取的空间，以及第一个共享空间中的文档

第二个共享空间中的文档，包括那张图片

两个列表工具只显示文件信息。它们从不返回文档内容（那是搜索的职责），也不说明是谁上传的。它们使用与搜索相同的读取权限和相同的实时访问规则，所以你在 Quberi 里看不到的空间或文档不会被列出。每次使用都记入审计日志（记录列表类型和条目数量，绝不记录名称）。

在 Harness 中的呈现方式

Harness 把插件的工具调用显示为普通行（「Tool call · quberi_search」加上参数摘要），不显示插件提供的自定义卡片。你读到的是模型自己的回答。因此这些工具返回纯文本，并要求模型用你的语言回答、把空间显示为列表、把文档显示为表格、标明每个要点来自哪个文档，且不要用代码块包裹任何内容。这是对模型的请求，不是保证，所以不同模型的排版可能不同。上传审批提示则不同：由 Harness 自己显示，包含文件、大小和目标位置。

上传文件

quberi_upload_file 把你当前工作区中的一个文件发送到你的个人空间，或发送到你有编辑权限的指定空间。它的用途是让 Harness 保存你指定的 PDF、Word 或 Excel 文件、幻灯片、图片或文本文件，无需你打开 Quberi 网页应用。
Harness 在每个文件离开工作区之前都会先询问，展示文件、大小和目的地：

Harness 请求批准把 Word 文件上传到个人空间

之后模型会列出空间里的内容。还在建索引的文件会标记为暂不可搜索；已保存的笔记已经可以搜索：

上传后的个人空间：三个文件仍在建索引，一条笔记可搜索

路径由模型选择，而模型又可能被它最后读到的任何文本带偏，所以路径和网络之间隔着三道独立的检查：

1. 每个文件都要你批准。 Harness 会展示确切的文件、大小、一段短哈希和目标空间，只有你允许才会上传。批准只对那一个文件生效一次，没有「始终允许」。没有可用的批准提示时（无头运行），或者处于「完全访问、从不询问」模式时，上传会被拒绝，而不是发出去。
2. 仅限工作区。 解析链接之后，路径必须仍在工作区文件夹内。.git、.ssh、.aws 这类文件夹，以及看起来像密钥的名字（.env、secrets.json、credentials.txt、id_rsa），一律拒绝。这个过滤是尽力而为，不是保证，所以才需要第 1 步。
3. 批准的文件就是发出的文件。 发送时会重新读取文件，必须和你批准的内容一致；如果变了，就什么都不上传。

接着 Quberi 会检查文件的实际内容（不是名字或标签），并由它做最终裁定：接受 png、jpeg、gif、webp、pdf、docx、xlsx、pptx、md、csv、txt 和 json，最大 25 MB。压缩包、HTML、SVG、可执行文件以及旧版 .doc / .xls 一律拒绝。PDF、Office、Markdown、CSV、文本和 JSON 文件在上传后会被索引以供搜索，这不是即时的：短笔记大约一分钟，大 PDF 要几分钟。文件建好索引之前，搜索找不到它；搜索会告诉模型哪些文档还在建索引，这样模型就能如实说明，而不是把不相关的段落当作答案。图片按它展示的内容建索引，所以 quberi_search_images 能根据描述找到它（前提是你的 Quberi 服务器有图片搜索）；quberi_search 本身只返回文本段落。

空间所有者可以要求上传先经批准。在这样的空间里，非空间所有者或管理员上传的文件会以待批准状态等待：它不会被索引，所以搜索找不到它、也引用不了它，只有上传者和空间的审核者能看到。上传工具会报告它正在等待批准，而不是已完成。之后所有者或管理员批准它，它便进入索引队列；或者附上理由拒绝。所有者和管理员直接上传。下面四个文件被上传到一个要求批准的空间：上传到需要审批的空间：第一个文件已提交，正在等待

四个文件都已进入空间，每个都标记为等待审批

审批人做出决定后，向模型查询文件状态就能看到结果：两个已批准、可搜索，两个被拒绝。

审批之后：两个文件已批准，两个被拒绝

只要能读取目标空间，就能找到这个文件。上传是另一项权限（knowledge:upload），审计日志只记录文档及其大小和类型，从不记录内容。要关掉这个工具，并且登录时不再申请该权限，把 uploadFiles 设为 false（见「配置」）。

能做什么，不能做什么

- 它按你的身份行事：搜索只读取你能读的空间，保存只写入你能编辑的空间。每次调用都会重新校验。你的访问权限变了，下一次调用就会反映出来。
- 它只能添加笔记和文件，别的做不了。已存在的内容，它不能编辑，也不能删除。
- 保存（knowledge:write）和上传（knowledge:upload）是两项独立权限。旧版本完成的登录没有这两项权限，也不会在背后悄悄升级；运行 /quberi login 补上。
- 访问令牌有效期一小时，会自动刷新；一次登录最长持续 90 天。刷新令牌若被使用两次，就视为被盗，整次登录随即吊销。
- 为组织关闭外部工具，或在 Quberi 里断开连接，下一次搜索或保存就会立刻停止。

配置

托管服务用默认值即可。自建 Quberi 时，把 baseUrl 指向你的 API（https，开发时可用 http://127.0.0.1:<port>）。登录发生在发布 /.well-known/oauth-authorization-server 并以 issuer 自称的服务器上。托管服务上是 https://ai.quberi.com；自建 Quberi 时与 baseUrl 同源，所以通常什么都不用设。只有当登录服务器与 API 不同源时，才把 authUrl 设为登录服务器地址。openBrowser、autoLogin 和 focusApp（默认都开启）分别控制自动打开浏览器、首次使用时登录、以及返回 Harness。uploadFiles（默认开启）提供上传工具；关掉就移除。searchMode（默认 both，也可为 text 或 image）决定搜索的范围，直到你用 /quberi mode 修改：

- insert:
- id: quberi
name: dsh-quberi
config:
baseUrl: https://api.example.com
authUrl: https://quberi.example.com # only if sign-in is on another origin than the API
openBrowser: false
autoLogin: false
focusApp: false
uploadFiles: false
searchMode: text

兼容性

基于 @deepseek-ai/* 0.2.0-rc.2 构建并测试。Harness 是开发者预览版，插件接口可能变化。token 集通过凭据记录 API（credentials.modifyRecord）存储，因此两个 Harness 进程不会互相覆盖对方轮换后的 refresh token。

许可证

MIT。见 LICENSE。