cndn/dsh-d1

dsh-d1

ci
npm

用于 DeepSeek Harness 的 Cloudflare D1（基于 HTTP 的无服务器 SQLite）工具——只读优先。

D1 是 Cloudflare 的无服务器 SQLite。与普通数据库不同，它没有 TCP 套接字——只能通过 Cloudflare REST API 访问。因此，优秀的 dsh-sql 插件（它池化到 SQLite/MySQL/Postgres 的 TCP 连接）无法与它通信。dsh-d1 填补了这一空白：它直接使用 D1 HTTP API，为 dsh 智能体提供六个工具，用于内省和查询你配置的任何 D1 数据库。

它默认只读。写入需要将 readOnly:false 并且通过交互式审批门禁。

工具

| 工具 | 模式 | 功能 |
|---|---|---|
| d1_list | 读 | 列出已配置的数据库并逐一探测（SELECT 1）。 |
| d1_query | 读 | 运行一条只读语句（SELECT / VALUES / WITH … SELECT / 内省 PRAGMA / EXPLAIN），可选绑定 params。有行数上限。 |
| d1_exec | 写 | 运行写入/DDL 语句。在 readOnly 下被拒绝；否则需要交互式审批。 |
| d1_schema | 读 | 列出用户表，或描述某张表的列（通过 PRAGMA table_info）。 |
| d1_stats | 读 | 表数量、每张表的行数（批量）、数据库大小。 |
| d1_health | 读 | 探测每个数据库并打印安全配置（以及任何配置错误）。 |

每个工具都会将 harness 的取消信号转发给 D1 请求，因此被取消或超时的调用会中止 HTTP 调用，而不是在后台继续运行至完成。对于 d1_exec，这只会放弃请求：D1 已收到的语句可能仍会被应用，因此在重试被取消的写入之前，请先用 d1_query 检查。这五个读取工具被标记为并发安全，因此 harness 可以并行运行它们。

安装

从 npm 安装。profile 目录是一个 pnpm 工作区根目录，因此 pnpm 需要 -w：

dsh plugin --profile web add -w dsh-d1

npm tarball 附带预构建的 lib/，因此无需批准构建步骤。该包由 CI 发布，带有 provenance；npm audit signatures 可验证该证明。

在开发期间，从本地检出安装：

cd dsh-d1 && npm install && npm run build
dsh plugin --profile web add -w /absolute/path/to/dsh-d1

直接从 git 安装（github:cndn/dsh-d1）会通过 prepare 脚本构建 lib/。pnpm 10 会阻止该构建，直到你允许一次：将它打印出的 onlyBuiltDependencies 条目（固定到 git 提交）复制到 profile 的 pnpm-workspace.yaml 中，然后重新运行安装。

配置
该包已经向你的 profile 中插入了一行 d1。请通过 profile 的 cordis.patch.yml 中的以 id 为目标的条目覆盖其 config（不要再用一个 insert，那会导致插件被加载两次）。API token 永远不属于此配置的一部分——见下文。

- id: d1
name: 'dsh-d1'
config:
accountId: 'your-32-hex-cloudflare-account-id'   # 或在环境变量中设置 CLOUDFLARE_ACCOUNT_ID
databases:
- name: prod                                   # agent 使用的友好名称
databaseId: 00000000-0000-0000-0000-000000000000
- name: analytics
databaseId: 11111111-1111-1111-1111-111111111111
accountId: 'another-32-hex-account-id'       # 可选的按数据库覆盖
maxRows: 1000            # d1_query 行数上限（1–10000；更大的值会被截断）
readOnly: true           # 默认 true——d1_exec 被拒绝；设为 false 以允许写入
writeApproval: true      # 写入必须交互式确认（默认 true）
queryTimeoutMs: 60000    # 5 秒 – 10 分钟（会被截断）
execTimeoutMs: 120000    # 5 秒 – 10 分钟（会被截断）

在没有任何数据库的情况下，插件仍会加载（所有工具都会注册，d1_health 会报告“no databases configured”），因此可用于诊断。如果配置无效，插件会回退到只读且无数据库的状态，并且 d1_health 会打印配置错误。

API token（仅通过环境变量）

Cloudflare API token 在调用时从环境变量读取，绝不存储在配置中、写入 patch、记录日志、渲染输出或包含在任何错误消息中。

用于每个数据库的全局 token：
export CLOUDFLARE_API_TOKEN='...'
可选的按数据库覆盖：DSH_D1_TOKEN_，其中 NAME 是数据库
名称转为大写并将非字母数字字符替换为 "_"（my-db → DSH_D1_TOKEN_MY_DB）：
export DSH_D1_TOKEN_PROD='...'

在 Cloudflare 仪表板中创建一个 token，对于只读 agent 需要 D1 → Read 权限（如果你打算启用写入，则需要 D1 → Edit）。account id（32 个十六进制字符）可以来自配置中的 accountId 或 CLOUDFLARE_ACCOUNT_ID 环境变量。

只读，分两层

1. d1_query 在词法层面受到防护。 在剥离注释、字符串字面量和带引号的标识符之后（遵循 SQLite 自身的引号规则——反斜杠不是转义符），只允许恰好一条语句，且它必须是 SELECT / VALUES / WITH … SELECT / PRAGMA（仅限内省形式——不允许 PRAGMA x = y，不允许 PRAGMA x(value) 这类 setter，不允许 PRAGMA optimize）/ 上述之一的 EXPLAIN。在 SQLite 中，这些都无法修改数据，因此没有内部关键字黑名单，诸如 release 或 set 这样的列名也没问题。SELECT 会被包裹在 SELECT * FROM (…) LIMIT maxRows+1 中，因此失控的查询传输的数据永远不会超过上限。
2. 当 readOnly:true 时，d1_exec 会被拒绝——预执行门禁会在任何提示之前就拒绝它。当 readOnly:false、writeApproval:true（默认值）时，每次写入都会经由 dsh 的审批服务：在 Web UI 中你会看到一张确认卡片，显示目标数据库、语句数量和 SQL。在无人能够应答的场景下——没有交互式应答器的无头 profile、完全没有审批服务的 profile，或 DSH_PERMISSION_MODE=danger-full-access（dsh 将审批策略设为 never）——该询问会被自动拒绝，写入也会被拒绝，因此在这些模式下，当 writeApproval:true 时 d1_exec 根本无法运行。writeApproval:false 会完全移除该门禁——当两个标志都关闭时，插件会在启动时记录一条警告。

这有意比通用 SQL 插件更严格：安全的默认行为是 agent 可以读取你的生产数据，但在你主动选择加入之前不能修改它。

安全说明

- token 仅通过环境变量提供，且必须是可打印 ASCII 字符；随附的 cordis.patch.yml 不包含任何机密，也不包含真实的数据库 id。
- 错误信息会被脱敏：失败的请求会暴露原因（超时、取消、HTTP 状态、D1 错误消息），但绝不会暴露 token 或请求头，并且 Cloudflare 回显的请求路径中的账户和数据库 id 会被移除。
- 表名在用于 PRAGMA table_info / COUNT(*)（d1_schema、d1_stats）之前会进行双引号转义，因此表名无法逃逸为任意 SQL。
- CSV 输出会中和字符串单元格中的电子表格公式前缀（=、+、-、@）。

许可证

MIT