前言¶

DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。现有的 DSH 工具生态主要处理“文本形态”的数据，例如 CSV 或 JSON。当 Agent 会话中出现 .db 或 .sqlite 文件（例如爬虫结果导出、本地应用数据快照）时，直接调用 bash 命令行往往不够灵活。

dsh-tool-sqlite 插件补齐了这一块，它提供了零依赖的数据库处理能力，允许 Agent 在工作区内直接操作 SQLite 文件。

插件简介¶

插件名称：dsh-tool-sqlite
维护者：WODE25500
许可证：MIT

该插件直接使用 Node.js 内置的 node:sqlite 模块，不引入任何第三方数据库库。它主要解决三个问题：列出工作区内的数据库文件、查看表结构、以及执行只读 SQL 查询。

安装与启用¶

在 DSH 的配置文件（如 cordis.yml 或 dsh.profile）中引入即可。启动后，控制台出现 [tool-sqlite] 相关日志即表示加载成功。

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

核心功能¶

插件提供了以下 5 个核心工具：

1. sqlite_list
   扫描工作区（限制 2 层深度，跳过 node_modules 与隐藏目录），找出所有 .db、.sqlite、.sqlite3、.db3 文件。

2. sqlite_tables
   列出指定数据库内的所有表与视图。

3. sqlite_schema
   查看指定表的列结构，包含列类型、NOT NULL 约束、默认值、主键信息。

4. sqlite_summary
   生成单表的列统计摘要，包含总行数、每列类型、distinct 值、min/max/avg。该工具旨在减少 token 消耗，避免全表扫描。

5. sqlite_query
   执行只读 SQL 查询，返回 { columns, rows } JSON 格式结果。

典型用法¶

以下是插件提供的可复现示例：

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]

安全模型与限制¶

插件内置了严格的安全与性能限制，以确保运行环境的稳定。

• 只读硬约束：数据库始终以 readOnly: true 打开。任何写操作（INSERT/UPDATE/DELETE/CREATE/DROP/ATTACH）都会被 SQLite 拒绝（attempt to write a readonly database）。
• 语句白名单：仅放行以 SELECT / WITH / PRAGMA / EXPLAIN / VALUES 开头的单条语句。只走 prepare 执行，不走多语句 exec。
• 路径边界：所有 db 参数解析后必须位于工作区内，防止路径穿越攻击（../ 与绝对路径越界直接报错）。
• 输出预算：结果默认显示 100 行，硬上限为 500 行。超限时明确标注截断，防止输出膨胀。
• 超时兜底：查询操作限制 5000ms，其他操作限制 3000ms。

开发与依赖¶

• Node.js 版本：要求 ^22.19.0 || >=24.0.0（node:sqlite 需要 Node 22.5+）。
• Peer Dependencies：
  • @deepseek-ai/dsh-tools
  • @deepseek-ai/cordis
• 开发命令：使用 npm run check 进行类型检查、测试和构建。

结语¶

dsh-tool-sqlite 通过直接利用 Node 内置模块，为 DSH 插件生态提供了处理本地数据库文件的能力。开发者无需配置数据库环境，即可在工作区中对 .db 文件进行结构化探索。更多细节可参考 GitHub 仓库。