前言¶
在使用 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 卡片管理憑據，通過緩存和重試機制優化了性能與穩定性，適合需要在對話中頻繁操作知識庫的開發者使用。
