Introduction

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” The existing DSH tool ecosystem mainly handles data in “text form,” such as CSV or JSON. When .db or .sqlite files appear in an Agent session (for example, exported crawler results or local application data snapshots), directly invoking the bash command line is often not flexible enough.

The dsh-tool-sqlite plugin fills this gap. It provides dependency-free database capabilities and allows the Agent to operate on SQLite files directly within the workspace.

Plugin Overview

Plugin name: dsh-tool-sqlite
Maintainer: WODE25500
License: MIT

The plugin directly uses the Node.js built-in node:sqlite module and does not introduce any third-party database libraries. It primarily addresses three problems: listing database files in the workspace, inspecting table schemas, and executing read-only SQL queries.

Installation and Activation

Simply add it in the DSH configuration file (such as cordis.yml or dsh.profile). After startup, the appearance of [tool-sqlite] related logs in the console indicates successful loading.

plugins:
  - id: tool-sqlite
    name: 'dsh-tool-sqlite'

Core Features

The plugin provides the following five core tools:

  1. sqlite_list
    Scans the workspace (limited to 2 levels of depth, skipping node_modules and hidden directories) to find all .db, .sqlite, .sqlite3, and .db3 files.

  2. sqlite_tables
    Lists all tables and views in the specified database.

  3. sqlite_schema
    Inspects the column structure of the specified table, including column types, NOT NULL constraints, default values, and primary key information.

  4. sqlite_summary
    Generates a column statistics summary for a single table, including total row count, per-column types, distinct values, and min/max/avg. This tool is designed to reduce token consumption and avoid full table scans.

  5. sqlite_query
    Executes read-only SQL queries and returns results in { columns, rows } JSON format.

Typical Usage

The following are reproducible examples provided by the plugin:

sqlite_list → data/app.db

sqlite_tables db: data/app.db → users, orders

sqlite_schema db: data/app.db table: users → id INTEGER PK(1) / name TEXT NOT NULL …

sqlite_query db: data/app.db sql: "SELECT name, age FROM users WHERE age >= ?" params: [30]

Security Model and Limitations

The plugin includes strict security and performance limitations to ensure the stability of the runtime environment.

  • Read-only hard constraint: Databases are always opened with readOnly: true. Any write operation (INSERT/UPDATE/DELETE/CREATE/DROP/ATTACH) is rejected by SQLite (attempt to write a readonly database).
  • Statement whitelist: Only single statements starting with SELECT / WITH / PRAGMA / EXPLAIN / VALUES are allowed. Execution uses prepare only and does not use multi-statement exec.
  • Path boundary: After resolution, all db parameters must be located within the workspace to prevent path traversal attacks (../ and out-of-bounds absolute paths directly result in errors).
  • Output budget: Results default to 100 rows, with a hard limit of 500 rows. Truncation is clearly marked when limits are exceeded to prevent output bloat.
  • Timeout fallback: Query operations are limited to 5000 ms, and other operations are limited to 3000 ms.

Development and Dependencies

  • Node.js version: Requires ^22.19.0 || >=24.0.0 (node:sqlite requires Node 22.5+).
  • Peer Dependencies:
    • @deepseek-ai/dsh-tools
    • @deepseek-ai/cordis
  • Development command: Use npm run check for type checking, testing, and building.

Conclusion

By directly utilizing built-in Node modules, dsh-tool-sqlite adds the ability to process local database files to the DSH plugin ecosystem. Developers can perform structured exploration of .db files in the workspace without configuring a database environment. For more details, refer to the GitHub repository.