前言¶
在 DeepSeek Harness（DSH）里做带知识库的智能体时，常见做法是接一套 RAG：模型能搜文档、能答问题。难点往往不在「能不能搜到」，而在「搜到的内容是否和当前用户有权看到的一致」。很多系统按空间（space）做粗粒度权限，同一空间里两个人问同一个问题，可能看到不该看到的段落，或者结果列表里混着无权文档再事后过滤。
quberi/dsh-quberi 把 Quberi 知识库接到 DSH：支持搜索、浏览、保存笔记和上传文件，并通过 OAuth 登录。权限在文档级生效，且在检索阶段就过滤，而不是按空间一刀切。
这是什么¶
dsh-quberi 由维护者 quberi 发布，在 DSH 社区目录中归类为联网工具。插件在本地以你当前 DSH 进程的权限运行，通过 OAuth 连接 Quberi 账号（或自托管 Quberi 服务，见 README 中的 Configuration）。
一句话：在 Harness 里用自然语言提问，模型可调用 Quberi 相关工具，只返回你有权阅读的文档片段；也可把对话结论写成笔记，或经你确认后上传工作区文件。
权限与检索：和「按空间授权」的差别¶
README 强调，有趣之处不是「能搜索」，而是搜索允许返回什么：
- 权限按文档配置，不是按空间；同一空间里两人问同一问题，答案可以不同，因为向量索引内的检索过滤器会先排除无权文档，被拒绝的文档从一开始就不会进入候选集。
- deny 优先：显式拒绝隐藏某文档时，grant 不能覆盖该决定。
- 检索时过滤，得到的是完整结果集，而不是先拉一长串再挖洞。
- 图片预览链接在权限撤销后再次请求会返回 404。
- 写入只能进你有编辑权限的空间；上传每次都需要你确认。
共享给你的单篇文档，即使读不了其所在空间，仍可被搜到；对你隐藏的文档，即使能读该空间，也不会出现在结果里。
核心功能¶
经 README 与 package.json（当前版本 0.6.0，MIT 许可证）可核对的能力如下。
模型工具¶
| 工具 | 作用 |
|---|---|
quberi_search |
在你选定的组织内，检索你有权阅读的文档段落；可指定空间名只搜该空间 |
quberi_save |
将标题与 Markdown 笔记写入知识库；未指定空间时写入个人空间（0.3.0 起需含 knowledge:write 的登录） |
quberi_upload_file |
从工作区上传文件（0.4.0 起需含 knowledge:upload 的登录；每次上传需你批准） |
quberi_list_spaces / quberi_list_documents |
浏览空间与文档列表 |
quberi_search_images |
按描述找图并在对话中展示 |
各 scope 独立授权：搜索需 knowledge:read，保存需 knowledge:write，上传需 knowledge:upload。若曾用旧版登录，要支持保存或上传需重新执行登录以授予新 scope。
斜杠命令¶
| 命令 | 作用 |
|---|---|
/quberi login |
浏览器打开 Quberi 登录；选组织并授权。首次搜索也会触发；旧版登录后若要保存/上传需再跑一次 |
/quberi status |
显示是否已连接（不打印 token） |
/quberi logout |
在 Quberi 撤销并清除本地登录 |
/quberi mode [text\|image\|both] |
查看或设置搜索范围：仅文档正文、仅图片或两者（默认 both） |
搜索范围（text / image / both）¶
默认 quberi_search 同时查正文与相关图片：纯文本检索看不到图，因此会附带可能相关的图片（仅作可能匹配，不作为唯一答案）。可说「只看文档」或「只看图片」，或由 /quberi mode 固定；text 模式下图片工具会拒绝。both 依赖 Quberi 服务端支持；过旧的服务器只搜文本，插件侧不会返回图片。该选择在 Harness 重启前有效；默认模式可通过配置项 searchMode 设置（见 README Configuration）。
浏览与图片搜索在已有搜索权限下即可；保存与上传需对应 scope 的新登录。
安装与启用¶
需要 ai.quberi.com 账号或自托管 Quberi。运行环境要求 Node >= 22（见 package.json 的 engines）。
在 Harness 中打开 Plugins → Add plugin，输入：
dsh-quberi
或在终端执行（将 desktop 换成你的 profile 名）：
dsh plugin --profile desktop add dsh-quberi
然后重启 Harness。升级时先移除旧版再添加：
dsh plugin --profile desktop remove dsh-quberi
dsh plugin --profile desktop add dsh-quberi
插件体量较小，README 列出主要源码文件：oauth.ts、browser.ts、controller.ts、upload.ts、index.ts；运行时仅依赖 @deepseek-ai/schemastery。安装前建议阅读源码与许可证；插件在本机以你的权限执行。
使用前：组织侧开关与数据去向¶
所选组织须允许外部工具，默认关闭。所有者或管理员在 Admin console → Integrations → Outside tools 开启；审批页上所有者/管理员也可点「Turn on」。
搜索返回的段落会进入 Harness 及 Harness 所使用的模型；此路径不经过 Quberi 的「发送前检查」。每次搜索会记入组织审计日志（工具名与返回的文档，不含问题与正文）。保存笔记同样记入审计（工具名与新文档，不含正文）。保存到共享空间时，能读该空间的人都能搜到该笔记，需有意选择空间。
无图形界面的远程 shell 上不会自动打开浏览器，插件会给出链接，需在另一台设备上打开完成授权。
典型用法¶
- 安装并重启 DSH 后，在对话中向 Harness 提问与 Quberi 文档相关的内容；首次会打开浏览器完成 OAuth，之后模型可调用
quberi_search。 - 需要固定只搜文档或只搜图时，执行
/quberi mode text或/quberi mode image；恢复默认用/quberi mode both。 - 要把结论写入知识库时，在对话中同意模型调用
quberi_save（README 要求模型先提议并等待你同意，但最终仍以你的批准与观察为准）。 - 上传工作区文件时，模型调用
quberi_upload_file后，须按插件流程批准该文件才会真正上传（见 README「Uploading files」）。
断开连接可在 Harness 用 /quberi logout，或在 Quberi Account → Connected tools 中断开。
适用场景与注意¶
适合已在 Quberi 沉淀文档、希望在 DSH 对话中做按人、按文档过滤检索的团队；需要把对话摘要回写知识库或经确认上传附件时也可使用。
注意：
- DSH 生态是「一切皆插件」；社区目录为独立站点（如 插件目录页），与 DeepSeek / 幻方无官方从属关系。
- 插件在本地运行并持有你的 OAuth 权限，安装前请审阅 GitHub 仓库 源码。
- 自托管 Quberi 时需按 README 的 Configuration 配置服务端地址等项。
结尾¶
dsh-quberi 把 Quberi 的文档级权限与检索时过滤接到 DSH，在对话里完成搜索、浏览、记笔记和受控上传，而不是只做「全空间 RAG」。查阅安装细节与配置见仓库 README；社区条目见 SkillHub 目录页，源码与问题跟踪见 https://github.com/quberi/dsh-quberi。
