@cxxl/dsh-sqlite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 happyCxxl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# dsh-sqlite
+
+给 DeepSeek Harness 的 agent 提供持久关系型 SQL 能力的插件：跨会话、跨工作区、跨机器可同步的结构化数据存储。
+
+## 安装
+
+```powershell
+dsh plugin --profile web add @cxxl/dsh-sqlite
+# 装完重启一次（bundle 层只在启动时读取）
+```
+
+## 五个工具
+
+| 工具 | 作用 |
+|---|---|
+| `sqlite_query` | 只读查询（SELECT / WITH / EXPLAIN / 只读 PRAGMA），结果 Markdown 表格，默认 100 行、上限 500 |
+| `sqlite_exec` | 写操作（标准 DDL/DML，可多语句）；危险操作需 `confirm: true` |
+| `sqlite_tables` | 列库文件、表结构、行数，附 quick_check 完整性检查 |
+| `sqlite_export` | 导出为 SQL 文本（全部表或指定表），用于备份 / git 同步 |
+| `sqlite_import` | 从 SQL 文本恢复（覆盖式：替换文件中包含的表，其余保留） |
+
+## 数据位置
+
+- 默认库：`~/.dsh/data/agent.db`；命名库：`~/.dsh/data/<库名>.db`（库名仅允许 `[a-zA-Z0-9_-]{1,64}`）
+- WAL 模式 + busy_timeout 3000ms，多会话并发安全；首次调用才打开，插件停用自动关闭
+
+## 安全边界
+
+- `sqlite_exec` 拒绝：ATTACH / DETACH / LOAD_EXTENSION / 全部 PRAGMA
+- 危险操作必须显式 `confirm: true`：DROP、无 WHERE 的 DELETE/UPDATE、含 DROP 的 ALTER、VACUUM/REINDEX
+- 单次 SQL ≤ 64KB；大批量写入请分批（每批约 1000 行）
+
+## 跨机器同步
+
+```
+机器A：sqlite_export(to: "<仓库>/data/agent.sql") → git commit & push
+机器B：git pull → sqlite_import(from: "<仓库>/data/agent.sql")
+```
+
+## 已知限制（v1）
+
+- SQL 字符串值内不要包含分号（语句按分号切分）
+- 大表查询请用 WHERE/LIMIT 收窄；查询结果最多返回 500 行
+- SQLite 动态类型：列声明类型是"亲和性建议"，值与类型不符时以存储为准
+- `to` / `from` 建议使用绝对路径
+- 部分导出时注意表间外键引用关系
+
+## 引擎
+
+Node 内置 `node:sqlite`（实验性，Node ≥ 22.5），零原生依赖；所有引擎调用隔离在 `lib/engine.js`，可整体替换为 better-sqlite3 而不动其余代码。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-sqlite bundle patch: mounts the plugin into a dsh profile composition.
+# Install: `dsh plugin --profile <name> add <pkg-or-dir>`
+# Row id must stay unique within the profile's bundle layer.
+- insert:
+    - id: dsh-sqlite
+      name: '@cxxl/dsh-sqlite'

package/lib/engine.js

@@ -0,0 +1,351 @@
+// engine.js — 所有 node:sqlite / 文件 IO 调用隔离于此。
+// 实验性 API 集中在这一层：将来替换 better-sqlite3 只改本文件。
+import { DatabaseSync } from 'node:sqlite'
+import { homedir } from 'node:os'
+import { join, resolve, sep, dirname } from 'node:path'
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  readdirSync,
+  statSync,
+} from 'node:fs'
+
+export const MAX_SQL_LEN = 64 * 1024
+export const MAX_ROWS = 500
+export const MAX_IMPORT_BYTES = 64 * 1024 * 1024
+export const DEFAULT_DB = 'default'
+const DB_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/
+
+// 只读 PRAGMA 白名单（query 通道唯一放行的 PRAGMA）
+const READONLY_PRAGMAS = new Set([
+  'table_info',
+  'table_list',
+  'index_list',
+  'index_info',
+  'foreign_key_list',
+  'quick_check',
+  'integrity_check',
+  'freelist_count',
+  'page_count',
+  'database_list',
+])
+
+// exec 放行的语句类型（标准 DDL/DML）
+const EXEC_ALLOW = new Set([
+  'CREATE', 'INSERT', 'UPDATE', 'DELETE', 'DROP', 'ALTER', 'REPLACE',
+  'WITH', 'BEGIN', 'COMMIT', 'ROLLBACK', 'END', 'VACUUM', 'REINDEX',
+])
+
+// exec 一律拒绝的语句类型
+const EXEC_DENY = new Set(['ATTACH', 'DETACH', 'LOAD_EXTENSION', 'PRAGMA'])
+
+const QUERY_ALLOW = new Set(['SELECT', 'WITH', 'EXPLAIN', 'PRAGMA'])
+
+export function getDataDir() {
+  return process.env.DSH_SQLITE_DATA_DIR || join(homedir(), '.dsh', 'data')
+}
+
+function ensureDataDir() {
+  const dir = getDataDir()
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+export function dumpFileName(dbName) {
+  return `${dbName === DEFAULT_DB ? 'agent' : dbName}.sql`
+}
+
+export function dbFile(dbName) {
+  const name = dbName === undefined || dbName === null || dbName === '' ? DEFAULT_DB : String(dbName)
+  if (name !== DEFAULT_DB && !DB_NAME_RE.test(name)) {
+    throw new Error(`db 名不合法："${name}"（仅允许字母/数字/_/-，1-64 位）`)
+  }
+  const dataDir = ensureDataDir()
+  const file = name === DEFAULT_DB ? 'agent.db' : `${name}.db`
+  const p = resolve(dataDir, file)
+  if (!p.startsWith(resolve(dataDir) + sep)) throw new Error('db 路径越界')
+  return { name, file: p }
+}
+
+const openDbs = new Map()
+
+function openDb(dbName) {
+  const { name, file } = dbFile(dbName)
+  let db = openDbs.get(name)
+  if (db === undefined) {
+    db = new DatabaseSync(file)
+    db.exec('PRAGMA journal_mode = WAL')
+    db.exec('PRAGMA busy_timeout = 3000')
+    openDbs.set(name, db)
+  }
+  return { name, db }
+}
+
+export function closeAll() {
+  for (const db of openDbs.values()) {
+    try { db.close() } catch { /* noop */ }
+  }
+  openDbs.clear()
+}
+
+// 分号切分语句。v1 已知限制：字符串字面量中的分号会破坏切分——
+// 文档已提示"值内不要包含分号"。
+export function splitStatements(sql) {
+  return String(sql)
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+}
+
+function stripLeadingComments(s) {
+  let out = s
+  for (;;) {
+    const t = out.trimStart()
+    if (t.startsWith('--')) {
+      const nl = t.indexOf('\n')
+      out = nl === -1 ? '' : t.slice(nl + 1)
+      continue
+    }
+    if (t.startsWith('/*')) {
+      const end = t.indexOf('*/')
+      out = end === -1 ? '' : t.slice(end + 2)
+      continue
+    }
+    break
+  }
+  return out.trimStart()
+}
+
+export function firstKeyword(stmt) {
+  const m = /^([A-Za-z]+)/.exec(stripLeadingComments(stmt))
+  return m ? m[1].toUpperCase() : ''
+}
+
+function dangerOf(stmt) {
+  const kw = firstKeyword(stmt)
+  if (kw === 'DROP' || kw === 'VACUUM' || kw === 'REINDEX') return `${kw} 属危险操作`
+  if ((kw === 'DELETE' || kw === 'UPDATE') && !/\bWHERE\b/i.test(stmt)) {
+    return `${kw} 未带 WHERE，将影响整张表`
+  }
+  if (kw === 'ALTER' && /\bDROP\b/i.test(stmt)) return 'ALTER 含 DROP 属危险操作'
+  return null
+}
+
+function assertNotAborted(signal) {
+  if (signal && signal.aborted) throw new Error('执行已取消')
+}
+
+function rowsToMarkdown(columns, rows, truncated) {
+  const head = `| ${columns.join(' | ')} |`
+  const sep = `| ${columns.map(() => '---').join(' | ')} |`
+  const body = rows.map((r) => {
+    const cells = columns.map((c) => {
+      let v = r[c]
+      if (v === null || v === undefined) return 'NULL'
+      if (v instanceof Uint8Array) return '<blob>'
+      let s = String(v).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+      if (s.length > 200) s = s.slice(0, 200) + '…'
+      return s
+    })
+    return `| ${cells.join(' | ')} |`
+  })
+  const lines = [head, sep, ...body]
+  if (truncated) lines.push('', `（已截断：还有更多行未显示，请用 WHERE/LIMIT 收窄查询）`)
+  return lines.join('\n')
+}
+
+export function runQuery(sql, dbName, maxRows, signal) {
+  assertNotAborted(signal)
+  const text = String(sql ?? '')
+  if (text.length === 0) throw new Error('sql 参数为空')
+  if (text.length > MAX_SQL_LEN) throw new Error(`SQL 超过 ${MAX_SQL_LEN / 1024}KB 上限，请拆分`)
+  const limit = Math.max(1, Math.min(MAX_ROWS, Number.isFinite(maxRows) ? Math.floor(maxRows) : 100))
+  const stmts = splitStatements(text)
+  if (stmts.length === 0) throw new Error('未解析到任何语句')
+  for (const stmt of stmts) {
+    const kw = firstKeyword(stmt)
+    if (!QUERY_ALLOW.has(kw)) {
+      throw new Error(`sqlite_query 仅允许 SELECT / WITH / EXPLAIN / 只读 PRAGMA，收到以 ${kw || '?'} 开头的语句——修改数据请改用 sqlite_exec`)
+    }
+    if (kw === 'PRAGMA') {
+      const m = /^PRAGMA\s+([a-zA-Z_]+)/i.exec(stripLeadingComments(stmt))
+      if (!m || !READONLY_PRAGMAS.has(m[1].toLowerCase())) {
+        throw new Error(`PRAGMA ${m ? m[1] : '?'} 不在只读白名单内（仅允许 ${[...READONLY_PRAGMAS].join(' / ')}）`)
+      }
+    }
+  }
+  const { db } = openDb(dbName)
+  const sections = []
+  for (const stmt of stmts) {
+    assertNotAborted(signal)
+    const prepared = db.prepare(stmt)
+    const all = prepared.all()
+    let columns = []
+    try {
+      const raw = prepared.columns()
+      if (Array.isArray(raw) && raw.length > 0) {
+        columns = raw.map((c) => (typeof c === 'string' ? c : c.name))
+      }
+    } catch { /* older node fallback */ }
+    if (columns.length === 0 && all.length > 0) columns = Object.keys(all[0])
+    const truncated = all.length > limit
+    const rows = truncated ? all.slice(0, limit) : all
+    sections.push(rowsToMarkdown(columns, rows, truncated))
+  }
+  return sections.join('\n\n')
+}
+
+export function runExec(sql, dbName, confirm, signal) {
+  assertNotAborted(signal)
+  const text = String(sql ?? '')
+  if (text.length === 0) throw new Error('sql 参数为空')
+  if (text.length > MAX_SQL_LEN) throw new Error(`SQL 超过 ${MAX_SQL_LEN / 1024}KB 上限，大批量写入请分批`)
+  const stmts = splitStatements(text)
+  if (stmts.length === 0) throw new Error('未解析到任何语句')
+  const dangers = []
+  for (const stmt of stmts) {
+    const kw = firstKeyword(stmt)
+    if (EXEC_DENY.has(kw)) {
+      throw new Error(`拒绝执行：${kw} 语句被禁用（安全边界：不允许挂载外部文件 / 修改引擎配置）`)
+    }
+    if (!EXEC_ALLOW.has(kw)) {
+      throw new Error(`不支持的语句类型：${kw || '?'}（sqlite_exec 仅支持标准 DDL/DML）`)
+    }
+    const d = dangerOf(stmt)
+    if (d !== null) dangers.push(`「${stmt.slice(0, 60)}${stmt.length > 60 ? '…' : ''}」${d}`)
+  }
+  if (dangers.length > 0 && confirm !== true) {
+    throw new Error(`危险操作需确认，请显式传 confirm: true 后重试：\n${dangers.join('\n')}`)
+  }
+  const { db } = openDb(dbName)
+  assertNotAborted(signal)
+  db.exec(text)
+  return stmts.length
+}
+
+export function listTables(dbName, signal) {
+  assertNotAborted(signal)
+  const { name, db } = openDb(dbName)
+  const tables = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+  ).all()
+  const out = []
+  for (const t of tables) {
+    assertNotAborted(signal)
+    const info = db.prepare(`PRAGMA table_info(${quoteIdent(t.name)})`).all()
+    const columns = info.map((c) => ({
+      name: c.name,
+      type: c.type || '',
+      notnull: c.notnull === 1,
+      pk: c.pk === 1,
+    }))
+    const cnt = db.prepare(`SELECT COUNT(*) AS c FROM ${quoteIdent(t.name)}`).all()
+    out.push({ name: t.name, columns, rowCount: cnt[0] ? Number(cnt[0].c) : 0 })
+  }
+  let quickCheck = 'ok'
+  try {
+    const q = db.prepare('PRAGMA quick_check').all()
+    quickCheck = q[0] && q[0].quick_check !== undefined ? String(q[0].quick_check) : 'ok'
+  } catch (err) {
+    quickCheck = `quick_check 失败：${err.message}`
+  }
+  return { dbName: name, tables: out, quickCheck }
+}
+
+export function listDbFiles() {
+  const dataDir = ensureDataDir()
+  const entries = []
+  for (const f of readdirSync(dataDir)) {
+    if (!f.endsWith('.db')) continue
+    try {
+      const st = statSync(join(dataDir, f))
+      entries.push({ name: f, bytes: st.size })
+    } catch { /* noop */ }
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name))
+  return entries
+}
+
+export function allTableNames(dbName, signal) {
+  assertNotAborted(signal)
+  const { db } = openDb(dbName)
+  return db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+  ).all().map((t) => t.name)
+}
+
+function quoteIdent(s) {
+  return `"${String(s).replace(/"/g, '""')}"`
+}
+
+function quoteValue(v) {
+  if (v === null || v === undefined) return 'NULL'
+  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : 'NULL'
+  if (typeof v === 'bigint') return String(v)
+  if (v instanceof Uint8Array) return `X'${Buffer.from(v).toString('hex')}'`
+  return `'${String(v).replace(/'/g, "''")}'`
+}
+
+export function dumpSql(dbName, tables, signal) {
+  assertNotAborted(signal)
+  const { db } = openDb(dbName)
+  const existing = allTableNames(dbName, signal)
+  const selected = tables === undefined || tables === null || tables.length === 0
+    ? existing
+    : [...new Set(tables.map((t) => String(t)))]
+  for (const t of selected) {
+    if (!existing.includes(t)) throw new Error(`表不存在：${t}（现有表：${existing.join(', ') || '无'}）`)
+  }
+  const lines = [`-- dsh-sqlite export · db=${dbName} · tables=${selected.join(',')}`, 'BEGIN;']
+  let rowCount = 0
+  for (const t of selected) {
+    assertNotAborted(signal)
+    const schema = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?").get(t)
+    lines.push(`DROP TABLE IF EXISTS ${quoteIdent(t)};`)
+    lines.push(`${schema && schema.sql ? schema.sql : `CREATE TABLE ${quoteIdent(t)} (x)`};`)
+    const rows = db.prepare(`SELECT * FROM ${quoteIdent(t)}`).all()
+    const cols = rows.length > 0 ? Object.keys(rows[0]) : []
+    for (const r of rows) {
+      if (cols.length === 0) break
+      const values = cols.map((c) => quoteValue(r[c]))
+      lines.push(`INSERT OR REPLACE INTO ${quoteIdent(t)} (${cols.map(quoteIdent).join(', ')}) VALUES (${values.join(', ')});`)
+      rowCount++
+    }
+  }
+  lines.push('COMMIT;')
+  return { text: lines.join('\n'), tableCount: selected.length, rowCount }
+}
+
+export function exportToFile(dbName, tables, to, signal) {
+  const { name } = dbFile(dbName)
+  const dump = dumpSql(dbName, tables, signal)
+  const target = to !== undefined && to !== null && String(to).trim() !== ''
+    ? String(to).trim()
+    : join(ensureDataDir(), dumpFileName(name))
+  const dir = dirname(resolve(target))
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(target, dump.text, 'utf8')
+  return { path: resolve(target), tables: dump.tableCount, rows: dump.rowCount }
+}
+
+export function importFromFile(dbName, from, signal) {
+  assertNotAborted(signal)
+  const { name } = dbFile(dbName)
+  const src = from !== undefined && from !== null && String(from).trim() !== ''
+    ? String(from).trim()
+    : join(getDataDir(), dumpFileName(name))
+  if (!existsSync(src)) throw new Error(`文件不存在：${src}`)
+  const st = statSync(src)
+  if (st.size > MAX_IMPORT_BYTES) {
+    throw new Error(`导入文件超过 ${MAX_IMPORT_BYTES / 1024 / 1024}MB 上限（${st.size} 字节）`)
+  }
+  const text = readFileSync(src, 'utf8')
+  const stmts = splitStatements(text)
+  if (stmts.length === 0) throw new Error(`文件内容为空或无法解析：${src}`)
+  const { db } = openDb(dbName)
+  assertNotAborted(signal)
+  db.exec(text)
+  return { path: resolve(src), statements: stmts.length, bytes: st.size }
+}

package/lib/index.js

@@ -0,0 +1,58 @@
+// index.js — 插件入口：注册五个工具 + 可选挂载自测。
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { toolDefs } from './tools.js'
+import * as engine from './engine.js'
+
+export const name = '@cxxl/dsh-sqlite'
+export const inject = ['tools']
+
+export function apply(ctx) {
+  for (const key of Object.keys(toolDefs)) {
+    ctx.tools.register(defineTool(toolDefs[key]))
+  }
+  ctx.effect(() => () => engine.closeAll())
+
+  // 挂载自测：DSH_PLUGIN_SELFTEST=1 时在临时数据目录跑一遍真实执行管线。
+  if (process.env.DSH_PLUGIN_SELFTEST === '1') void selfTest(ctx)
+}
+
+async function selfTest(ctx) {
+  const prev = process.env.DSH_SQLITE_DATA_DIR
+  let tmp = null
+  try {
+    tmp = mkdtempSync(join(tmpdir(), 'dsh-sqlite-selftest-'))
+    process.env.DSH_SQLITE_DATA_DIR = tmp
+    const signal = new AbortController().signal
+    const call = (n, args) => ctx.tools.execute({ callId: CallId(`sqlite-self-${n}`), name: n, arguments: args, signal })
+
+    let r = await call('sqlite_exec', { sql: 'CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, v TEXT); INSERT OR REPLACE INTO t (id, v) VALUES (1, \'hello\');' })
+    if (r.isError) throw new Error(`exec 失败: ${JSON.stringify(r.error)}`)
+
+    r = await call('sqlite_query', { sql: 'SELECT * FROM t' })
+    if (r.isError || !String(r.value).includes('hello')) throw new Error(`query 失败: ${r.isError ? JSON.stringify(r.error) : r.value}`)
+
+    r = await call('sqlite_exec', { sql: 'DROP TABLE t' })
+    if (r.isError || !String(r.value).includes('confirm')) throw new Error(`危险拦截失效: ${r.isError ? JSON.stringify(r.error) : r.value}`)
+
+    r = await call('sqlite_exec', { sql: 'DROP TABLE t', confirm: true })
+    if (r.isError) throw new Error(`confirm 执行失败: ${JSON.stringify(r.error)}`)
+
+    r = await call('sqlite_tables', {})
+    if (r.isError) throw new Error(`tables 失败: ${JSON.stringify(r.error)}`)
+
+    console.log('[dsh-sqlite] self-test PASS')
+  } catch (err) {
+    console.log(`[dsh-sqlite] self-test FAIL: ${(err && err.message) || err}`)
+  } finally {
+    if (prev === undefined) delete process.env.DSH_SQLITE_DATA_DIR
+    else process.env.DSH_SQLITE_DATA_DIR = prev
+    engine.closeAll()
+    if (tmp) {
+      try { rmSync(tmp, { recursive: true, force: true }) } catch { /* noop */ }
+    }
+  }
+}

package/lib/tools.js

@@ -0,0 +1,168 @@
+// tools.js — 五个模型工具的定义（纯对象，不依赖 DSH 包，可独立冒烟测试）。
+// 描述即接口：写清 做什么 / 何时用 / 何时别用 / 副作用 / 防错提示。
+// 注意：描述文本禁用双花括号（会破坏 code-mode prompt 组装）。
+import * as engine from './engine.js'
+
+function renderText(_args, value) {
+  return [{ type: 'text', text: value }]
+}
+
+function catchText(fn) {
+  return async (args, exec) => {
+    try {
+      return await fn(args, exec)
+    } catch (err) {
+      return `错误：${(err && err.message) || String(err)}`
+    }
+  }
+}
+
+export const toolDefs = {
+  query: {
+    name: 'sqlite_query',
+    description:
+      '只读查询 DSH 持久 SQLite 数据库（agent 跨会话保存的结构化数据）。' +
+      '何时用：需要读取、统计、核对之前保存的数据时。' +
+      '仅支持 SELECT / WITH / EXPLAIN 及少量只读 PRAGMA（如 table_info）；任何修改请改用 sqlite_exec。' +
+      '结果以 Markdown 表格返回，默认最多 100 行、硬上限 500，超出会截断并提示。' +
+      'db 参数：默认 "default"（对应 ~/.dsh/data/agent.db），其它值对应 ~/.dsh/data/<值>.db。' +
+      '注意：SQL 字符串值内不要包含分号；大表请用 WHERE/LIMIT 收窄查询。',
+    parameters: {
+      sql: {
+        type: 'string',
+        required: true,
+        description: '只读 SQL：SELECT / WITH / EXPLAIN / 只读 PRAGMA，可用分号分隔多条。',
+      },
+      db: {
+        type: 'string',
+        description: '库名，默认 "default"。命名库对应 ~/.dsh/data/<库名>.db。',
+      },
+      maxRows: {
+        type: 'number',
+        description: '返回行数上限：默认 100，最大 500。',
+      },
+    },
+    output: { schema: { type: 'string' }, render: renderText },
+    execute: catchText(async (args, exec) => {
+      return engine.runQuery(args.sql, args.db, args.maxRows, exec && exec.signal)
+    }),
+  },
+
+  exec: {
+    name: 'sqlite_exec',
+    description:
+      '执行写操作 SQL（可多条，以分号分隔）并持久化到 DSH SQLite 数据库。' +
+      '何时用：用户要求记录、跟踪、保存结构化数据，或需要建表/更新/删除时。' +
+      '支持 CREATE/INSERT/UPDATE/DELETE/DROP/ALTER/REPLACE 及 BEGIN/COMMIT/ROLLBACK；ATTACH/DETACH/LOAD_EXTENSION/PRAGMA 一律拒绝。' +
+      '危险操作必须显式传 confirm: true 才执行：DROP 语句、无 WHERE 的 DELETE/UPDATE、含 DROP 的 ALTER、VACUUM/REINDEX。' +
+      '建议写防御性 SQL：CREATE TABLE IF NOT EXISTS、INSERT OR REPLACE。' +
+      '大批量写入请分批（每批约 1000 行），单次 SQL 不超过 64KB。db 参数同 sqlite_query。',
+    parameters: {
+      sql: {
+        type: 'string',
+        required: true,
+        description: '写操作 SQL（标准 DDL/DML），可用分号分隔多条。',
+      },
+      db: {
+        type: 'string',
+        description: '库名，默认 "default"。',
+      },
+      confirm: {
+        type: 'boolean',
+        description: '危险操作（DROP / 无 WHERE 的 DELETE、UPDATE / 含 DROP 的 ALTER / VACUUM / REINDEX）必须为 true。',
+      },
+    },
+    output: { schema: { type: 'string' }, render: renderText },
+    execute: catchText(async (args, exec) => {
+      const n = engine.runExec(args.sql, args.db, args.confirm, exec && exec.signal)
+      return `执行成功：${n} 条语句已写入数据库。`
+    }),
+  },
+
+  tables: {
+    name: 'sqlite_tables',
+    description:
+      '列出 SQLite 数据库文件与表结构，了解库里已有什么。' +
+      '返回 ~/.dsh/data/ 下的库文件清单、指定库（默认 default）中每张表的列定义与行数，并附完整性检查（quick_check）结果。' +
+      '何时用：不确定库里有哪些表时，先调用本工具，再决定查询、写入或导出。',
+    parameters: {
+      db: {
+        type: 'string',
+        description: '库名，默认 "default"。',
+      },
+    },
+    output: { schema: { type: 'string' }, render: renderText },
+    execute: catchText(async (args, exec) => {
+      const signal = exec && exec.signal
+      const info = engine.listTables(args.db, signal)
+      const files = engine.listDbFiles()
+      const lines = []
+      lines.push(`库文件（~/.dsh/data/）：${files.length === 0 ? '尚无' : files.map((f) => `${f.name}（${f.bytes} 字节）`).join('、')}`)
+      lines.push('')
+      lines.push(`数据库 "${info.dbName}" 的表：`)
+      if (info.tables.length === 0) {
+        lines.push('（暂无表，可用 sqlite_exec 建表）')
+      }
+      for (const t of info.tables) {
+        const cols = t.columns.map((c) => `${c.name} ${c.type}${c.pk ? ' PK' : ''}${c.notnull ? ' NOT NULL' : ''}`).join(', ')
+        lines.push(`- ${t.name}：${t.rowCount} 行；列：${cols || '（无列信息）'}`)
+      }
+      lines.push('')
+      lines.push(`完整性检查（quick_check）：${info.quickCheck}`)
+      return lines.join('\n')
+    }),
+  },
+
+  export: {
+    name: 'sqlite_export',
+    description:
+      '把数据库导出为 SQL 文本文件，用于跨机器同步或备份（手动操作）。' +
+      '导出全部表，或用 tables 参数指定表名数组。' +
+      '默认写到 ~/.dsh/data/<名>.sql；to 参数可指定其它路径（如仓库内路径以便 git 提交，建议绝对路径）。' +
+      '返回目标路径、表数与行数。何时用：用户要求备份/同步，或你判断需要保存快照时。' +
+      '注意：部分导出时确认表间外键引用关系。',
+    parameters: {
+      db: {
+        type: 'string',
+        description: '库名，默认 "default"。',
+      },
+      tables: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '要导出的表名数组；省略 = 全部表。',
+      },
+      to: {
+        type: 'string',
+        description: '目标文件路径（建议绝对路径）；省略 = 本地默认路径 ~/.dsh/data/<名>.sql。',
+      },
+    },
+    output: { schema: { type: 'string' }, render: renderText },
+    execute: catchText(async (args, exec) => {
+      const r = engine.exportToFile(args.db, args.tables, args.to, exec && exec.signal)
+      return `已导出 ${r.tables} 张表、${r.rows} 行 → ${r.path}`
+    }),
+  },
+
+  import: {
+    name: 'sqlite_import',
+    description:
+      '从 SQL 文本文件恢复数据到数据库（覆盖式：替换文件中包含的表，库中其余表保留）。' +
+      '默认读 ~/.dsh/data/<名>.sql；from 参数指定源文件（建议绝对路径）。' +
+      '何时用：换机器后、或拉取仓库中的导出文件后恢复数据。导入前建议先 sqlite_export 备份当前数据。',
+    parameters: {
+      db: {
+        type: 'string',
+        description: '目标库名，默认 "default"。',
+      },
+      from: {
+        type: 'string',
+        description: '源 SQL 文件路径（建议绝对路径）；省略 = ~/.dsh/data/<名>.sql。',
+      },
+    },
+    output: { schema: { type: 'string' }, render: renderText },
+    execute: catchText(async (args, exec) => {
+      const r = engine.importFromFile(args.db, args.from, exec && exec.signal)
+      return `导入完成：执行 ${r.statements} 条语句（${r.bytes} 字节）← ${r.path}`
+    }),
+  },
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cxxl/dsh-sqlite",
+  "version": "0.1.0",
+  "description": "DSH plugin: persistent SQLite tools for the agent (sqlite_query / sqlite_exec / sqlite_tables / sqlite_export / sqlite_import) — zero runtime deps beyond Node 22 node:sqlite.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/tools.js",
+    "lib/engine.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh-plugin",
+    "sqlite",
+    "database",
+    "persistence",
+    "sync",
+    "deepseek-harness"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/happyCxxl/dsh-plugins.git",
+    "directory": "plugins/dsh-sqlite"
+  }
+}