Introduction

The core idea of DeepSeek Harness (DSH) is “everything is a plugin.” When an agent needs to connect to an external knowledge base, developers often face complex integration and coarse-grained permission management. doco-dsh is a native plugin for DeepSeek Harness, designed to provide agents with block-level addressing, full-text search, structured reading, and draft-saving capabilities for the Doco knowledge base.

What is it

doco-dsh is a native Doco knowledge base plugin maintained by songofhawk. It connects DeepSeek Harness with Doco through 9 tools and supports block-level addressing.

The plugin reuses the DocoClient logic from doco-agent-cli (HTTP / ETag / Token) and depends on @deepseek-ai/dsh-tools and @deepseek-ai/cordis provided by the host. In default mode it is read-only; write operations must pass DSH native approval and Scope gating.

Core Features

The plugin provides the following 9 tools, divided into read and write categories:

Read Capabilities

  1. doco_status: Connection health check; displays the current user, Scope, API address, and read/write capabilities.
  2. doco_list_knowledge_bases: Lists the knowledge base IDs visible to the agent.
  3. doco_search: Invokes Search v2 for full-text search and returns completeness attestation (projection.complete / freshness).
  4. doco_outline: Retrieves the structural outline of a document, returning stable block_id values and heading paths.
  5. doco_read: Locally reads body content according to a token budget, supporting around / cursor continuation.
  6. doco_get_spreadsheet: Retrieves worksheet structure, active sheet, dimensions, and top-level version.
  7. doco_get_cells: Reads the raw strings of cells in a specified range.

Write Capabilities

  1. doco_update_cells: Atomically submits batch cell updates; requires version validation with if_match.
  2. doco_save_draft: Saves agent output as a new draft, using an idempotency key and never overwrites existing drafts.

Installation and Enablement

It is recommended to install it directly through DSH’s plugin manager. This package declares dsh.bundle.patch, and after installation it is automatically mounted into the profile-level stack.

dsh plugin --profile <name> add doco-dsh

If manual mounting is required, install the dependency first:

pnpm add doco-dsh   # 或 npm i doco-dsh

Then append the configuration in DSH’s Composition YAML (name can be the package name or a local path):

- id: doco
  name: 'doco-dsh'

Dependency Notes:
- Runtime dependency: doco-agent-cli@^0.1.3
- Peer dependencies: @deepseek-ai/dsh-tools / @deepseek-ai/cordis (provided by the host DSH)

Configuration

The plugin does not support YAML config: blocks; all configuration is done via environment variables. Priority order: startup arguments > doco-agent-cli configuration > plugin-level environment variables > built-in defaults.

Environment variable Default value Description
DOCO_API_BASE_URL https://api.doco.page/api/v1 API address
DOCO_API_TOKEN — Authentication token (can also be obtained via /doco connect)
DOCO_DEFAULT_KB — Default knowledge base ID
DOCO_WEB_ORIGIN https://doco.page Web origin for citation links
DOCO_READ_MAX_TOKENS 4000 Default budget for doco_read
DOCO_READ_CONTEXT_BEFORE / AFTER 2 / 4 Default number of context blocks
DOCO_DSH_TOOL_PREFIX doco Tool name prefix
DOCO_DSH_ALLOW_WRITES false Global write switch

Typical Usage

Connection and Authentication

Authorization is required for first-time use. Default is read-only; writes require explicitly specifying permission.

/doco connect                     # 默认 read_only
/doco connect --access read_write # 需要写入时选 read_write

After successful authorization, the Token is written to ~/.config/doco/config.json. Subsequent status can be managed with the following commands:

/doco status
/doco disconnect
/doco set-kb <kb_id>

Spreadsheet Operation Flow

For documents with document_type=spreadsheet, the dedicated tool flow must be used; generic TipTap writes or browser operations are prohibited.

  1. Get structure: Call doco_get_spreadsheet to obtain the top-level version and sheet ID.
  2. Read data: Call doco_get_cells to read the target range.
  3. Update data: Call doco_update_cells with cells and if_match (the read version or ETag).

Example update payload:

cells={"C15":"10","C16":"20","C17":"=SUM(C15:C16)","C18":""}

Notes

  1. Write safety: Default is read-only. Writes require enabling DOCO_DSH_ALLOW_WRITES and passing dsh native approval and Scope validation. doco_save_draft only creates a new draft and does not overwrite existing drafts.
  2. Spreadsheet limitations: Spreadsheet-type documents must use the doco_get_spreadsheet / doco_get_cells / doco_update_cells tools.
  3. Error handling: When a tool fails, it returns a structured error value (kind:'doco_error') with a next_step suggestion instead of throwing an exception.
  4. MCP conflicts: If Doco MCP is loaded at the same time, tools with the same names will skip registration to avoid conflicts. Using the native plugin is recommended.

Conclusion

doco-dsh provides DeepSeek Harness with deep integration capabilities for the Doco knowledge base. Through block-level addressing and structured tools, developers can control agents’ read and write operations on knowledge bases more safely and precisely. For full documentation and source code, see the project directory and GitHub repository.