前言¶
在使用 DeepSeek Harness（DSH）构建智能体时，如果对话内容需要与现有的知识库（如 Outline）交互，最直接的痛点在于：如何在不离开对话界面的情况下，快速检索知识库内容，并在需要时安全地更新它。手动复制粘贴效率低下且容易出错。dsh-outline 插件旨在解决这个问题，它将 Outline 知识库的能力直接集成到 DSH 的 Web 交互流中，提供从搜索、阅读到受控写入的全链路支持。
插件简介¶
这是一个由 huangfuren 维护的 DSH Web 插件，分类为“联网工具”。它的核心定位是作为 DSH 与 Outline 之间的桥梁：允许你在对话中通过关键词搜索文档，阅读全文内容，并经过用户授权后安全地创建、更新或删除文档。
插件采用 MIT 许可证，基于 Node.js 22.19 或更新版本开发。
核心能力¶
该插件提供了十三种工具，覆盖了知识库管理的主要场景：
- 搜索与阅读：支持按作者名称过滤搜索（服务端过滤），提供上下文搜索（返回命中片段，便于引用），支持点击跳转文档链接。提供列表集合、统计文档数、列出用户、解析路径、列出子项等基础管理工具。
- 本地保存：支持将文档保存为本地 Markdown 文件（支持单文件或多文件合并，并自动生成目录）。
- 写入控制：提供创建、更新和删除文档的工具。为了安全，写入操作（如
outline_save_local）默认是只读的，必须进行额外配置才能启用写入，且每次写入都会触发用户审批。
安全与性能机制：
* HTTPS 强制：公共 URL 必须使用 HTTPS（localhost 和内网地址除外），确保 API Token 在传输中不泄露。
* 重试机制：遇到 429 限流错误时，会自动重试最多 3 次，并支持指数退避（最大延迟 5 秒）。
* 缓存配置：支持配置读取缓存（默认 TTL 60 秒，有最大条目限制），避免重复读取同一文档。
用户体验：
* GUI 配置：无需编辑配置文件，通过 Settings → Plugins → Plugin configuration 中的“Outline Knowledge Base”卡片即可填写。
* 多用户支持：每个用户可以在 GUI 中配置自己的凭据（存储在 $DSH_HOME/settings.yaml 中），适合团队分发。
* 即时生效：配置保存后无需重启，支持启用/禁用。
安装¶
安装前请确保环境满足以下要求：
* Node.js 版本 >= 22.19
* DSH 基线版本 >= 0.1.5-rc.2 或 0.2.x 系列版本
使用官方推荐的管理命令进行安装：
dsh plugin --profile web add git+https://github.com/huangfuren/dsh-outline.git#v0.8.3
安装完成后，需要重启 dsh web 进程。该插件不依赖本地构建步骤，直接安装即可运行。
配置¶
插件安装并重启后，通过 GUI 配置卡片进行设置。
- 进入 Settings → Plugins → Plugin configuration。
- 找到 Outline Knowledge Base 卡片。
- 填写必要信息：
| 字段 | 说明 |
|---|---|
| Service URL (baseUrl) | Outline 实例的根地址，例如 https://outline.example.com |
| API Token | 在 Outline 的 Settings → API keys 中创建的 Token |
| Writable paths | 可写入的目录路径（逗号分隔），留空则默认只读 |
| Local save directory | 本地 Markdown 保存路径，留空则使用默认的 $DSH_HOME/outline-auto-saves |
点击 Save 即可应用配置。配置优先级为：GUI 卡片 > 环境变量 > 插件配置行。
使用示例¶
场景一：搜索文档
在对话中给出关键词，插件会返回匹配文档的标题、摘要和链接。
示例指令：帮我搜索关于“架构设计”的文档
场景二：读取全文
选择一个搜索结果，插件会返回该文档的完整 Markdown 内容。
示例指令：读取第一个搜索结果的内容
场景三：团队配置
每个团队成员的配置步骤保持一致：
1. 安装插件
2. 重启 DSH
3. 在 GUI 中填写各自的 API Token
注意事项¶
- 默认只读：在未配置
Writable paths或未进行写入审批流程前，插件处于只读状态。 - 环境依赖：插件需要 Node.js 22.19 或更新版本，且 DSH 版本需满足 0.1.5-rc.2 至 1.0.0 之间的兼容范围。
- 网络要求：Outline 实例必须能从你的机器访问（支持内网或 VPN）。
- HTTPS 限制：强制要求公共 API 端点使用 HTTPS 协议。
插件在未配置时也能正常加载，工具会返回清晰的错误提示，不会阻塞 GUI。
结语¶
dsh-outline 通过将 Outline 的搜索、阅读和受控写入能力引入 DSH，简化了知识库集成的流程。它利用 GUI 卡片管理凭据，通过缓存和重试机制优化了性能与稳定性，适合需要在对话中频繁操作知识库的开发者使用。
