Preface¶
When building agents with DeepSeek Harness (DSH), if the conversation content needs to interact with an existing knowledge base (such as Outline), the most direct pain point is: how to quickly retrieve knowledge base content without leaving the conversation interface, and safely update it when necessary. Manual copying and pasting is inefficient and error-prone. The dsh-outline plugin aims to solve this problem by integrating the capabilities of the Outline knowledge base directly into DSH’s Web interaction flow, providing end-to-end support from searching and reading to controlled writing.
Plugin Overview¶
This is a DSH Web plugin maintained by huangfuren, categorized as “Web Tools”. Its core positioning is to serve as a bridge between DSH and Outline: allowing you to search documents by keywords in a conversation, read full document content, and safely create, update, or delete documents after user authorization.
The plugin is licensed under the MIT License and is developed for Node.js 22.19 or later.
Core Capabilities¶
The plugin provides thirteen tools, covering the main scenarios for knowledge base management:
- Search and Reading: Supports filtering searches by author name (server-side filtering), provides context search (returns matching snippets for easy citation), and supports click-through links to documents. Provides basic management tools such as listing collections, counting documents, listing users, parsing paths, and listing child items.
- Local Saving: Supports saving documents as local Markdown files (single-file or multi-file merging, with automatic table of contents generation).
- Write Control: Provides tools for creating, updating, and deleting documents. For safety, write operations (such as
outline_save_local) are read-only by default and must be enabled through additional configuration. Each write operation triggers user approval.
Security and Performance Mechanisms:
* HTTPS Enforcement: Public URLs must use HTTPS (except localhost and internal network addresses) to ensure API Tokens are not leaked during transmission.
* Retry Mechanism: When a 429 rate-limit error is encountered, it automatically retries up to 3 times and supports exponential backoff (maximum delay of 5 seconds).
* Cache Configuration: Supports configuring read caching (default TTL of 60 seconds, with a maximum entry limit) to avoid repeated reads of the same document.
User Experience:
* GUI Configuration: No need to edit configuration files. Simply fill in the “Outline Knowledge Base” card under Settings → Plugins → Plugin configuration.
* Multi-User Support: Each user can configure their own credentials in the GUI (stored in $DSH_HOME/settings.yaml), making it suitable for team distribution.
* Immediate Effect: After saving configuration, no restart is required, and enable/disable is supported.
Installation¶
Before installation, ensure the environment meets the following requirements:
* Node.js version >= 22.19
* DSH base version >= 0.1.5-rc.2 or a 0.2.x series version
Use the officially recommended management command to install:
dsh plugin --profile web add git+https://github.com/huangfuren/dsh-outline.git#v0.8.3
After installation, the dsh web process needs to be restarted. The plugin does not depend on local build steps and can run directly after installation.
Configuration¶
After installing the plugin and restarting, configure it using the GUI configuration card.
- Go to Settings → Plugins → Plugin configuration.
- Find the Outline Knowledge Base card.
- Fill in the required information:
| Field | Description |
|---|---|
| Service URL (baseUrl) | Root address of the Outline instance, for example https://outline.example.com |
| API Token | Token created under Settings → API keys in Outline |
| Writable paths | Directory paths that are writable (comma-separated); leave empty to default to read-only |
| Local save directory | Local Markdown save path; leave empty to use the default $DSH_HOME/outline-auto-saves |
Click Save to apply the configuration. The configuration precedence is: GUI card > environment variables > plugin configuration entries.
Usage Examples¶
Scenario 1: Search for Documents
Provide keywords in the conversation, and the plugin returns matching document titles, summaries, and links.
Example instruction: Search for documents about “architecture design”
Scenario 2: Read Full Text
Select a search result, and the plugin returns the complete Markdown content of that document.
Example instruction: Read the content of the first search result
Scenario 3: Team Configuration
The configuration steps are consistent for each team member:
1. Install the plugin
2. Restart DSH
3. Fill in each person’s API Token in the GUI
Notes¶
- Read-Only by Default: Before configuring
Writable pathsor completing the write approval process, the plugin remains in read-only mode. - Environment Dependencies: The plugin requires Node.js 22.19 or later, and the DSH version must be within the compatible range from 0.1.5-rc.2 to 1.0.0.
- Network Requirements: The Outline instance must be accessible from your machine (internal network or VPN supported).
- HTTPS Limitation: Public API endpoints are required to use the HTTPS protocol.
The plugin can load normally even when not configured; the tools return clear error messages and do not block the GUI.
Conclusion¶
By bringing Outline’s search, reading, and controlled writing capabilities into DSH, dsh-outline simplifies the knowledge base integration process. It uses GUI cards to manage credentials and optimizes performance and stability through cache and retry mechanisms, making it suitable for developers who need to frequently interact with a knowledge base during conversations.
- GitHub repository: https://github.com/huangfuren/dsh-outline
- Community directory: https://www.skillhub.cn/plugins/huangfuren/dsh-outline
