@cxxl/dsh-sqlite 0.1.1 → 0.3.0

package/README.md

@@ -45,6 +45,20 @@ dsh plugin --profile web add @cxxl/dsh-sqlite
 - `to` / `from` 建议使用绝对路径
 - 部分导出时注意表间外键引用关系
 
+## 稳定触发（v1.2）
+
+插件向每个会话注入一段常驻提示词规则（约 40 token/回合）：用户要求"记住/记录/跟踪/保存"或表达"以后查/对比/统计"意图时，使用 sqlite 工具而非文本文件。规则不覆盖模型判断，最终决策权在模型。
+
+## 跨会话协作（v2）
+
+多会话并行同一任务时的对齐机制（设计见 DESIGN.md 第 15 节）：
+
+- 协作数据放**命名库**（任务名，kebab-case），同一任务的会话共用同一个命名库
+- 会话开工时自动收到**协作库清单**（含各库 meta 描述与表说明）
+- 其他会话对命名库的写入会**自动提醒**相关会话（直到你查询确认）；**新库出现会广播**
+- 库表带描述：新建协作库后先建 meta 表（label / description / table:<名>）
+- 默认库 agent.db 是个人数据区，不参与协作提醒
+
 ## 引擎
 
 Node 内置 `node:sqlite`（实验性，Node ≥ 22.5），零原生依赖；所有引擎调用隔离在 `lib/engine.js`，可整体替换为 better-sqlite3 而不动其余代码。

package/lib/client.js

@@ -0,0 +1,179 @@
+window.__ModuleLoader__.load({
+  id: '@cxxl/dsh-sqlite',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+    const React = require('react')
+
+    const CSS = `
+      .dsql-root { display: flex; flex-direction: column; gap: 10px; font-family: inherit; font-size: 12px; color: var(--dsw-alias-label-primary, #1a1a1a); }
+      .dsql-head { display: flex; align-items: center; gap: 8px; }
+      .dsql-title { font-size: 13px; font-weight: 600; flex: none; }
+      .dsql-select { flex: 1; min-width: 0; padding: 4px 6px; border: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,0.12)); border-radius: 6px; background: var(--dsw-alias-bg-base, #ffffff); color: inherit; font: inherit; }
+      .dsql-btn { flex: none; border: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,0.12)); background: transparent; color: var(--dsw-alias-label-secondary, #666666); border-radius: 6px; padding: 4px 10px; cursor: pointer; font: inherit; }
+      .dsql-btn:hover { background: var(--dsw-alias-interactive-bg-hover-solid, rgba(127,127,127,0.16)); color: var(--dsw-alias-label-primary, #1a1a1a); }
+      .dsql-btn:disabled { opacity: 0.5; cursor: default; }
+      .dsql-error { padding: 8px 10px; border-radius: 6px; background: rgba(224, 49, 49, 0.1); color: #c92a2a; }
+      .dsql-status { color: var(--dsw-alias-label-secondary, #666666); }
+      .dsql-tables { display: flex; flex-direction: column; gap: 4px; }
+      .dsql-table-row { display: flex; align-items: center; gap: 8px; text-align: left; border: 1px solid transparent; background: transparent; border-radius: 6px; padding: 6px 8px; cursor: pointer; font: inherit; color: inherit; }
+      .dsql-table-row:hover, .dsql-table-row-active { background: var(--dsw-alias-interactive-bg-hover-solid, rgba(127,127,127,0.16)); }
+      .dsql-table-name { font-weight: 600; }
+      .dsql-table-meta { color: var(--dsw-alias-label-secondary, #666666); font-size: 11px; }
+      .dsql-empty { padding: 12px 8px; color: var(--dsw-alias-label-secondary, #666666); text-align: center; }
+      .dsql-preview { border: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,0.12)); border-radius: 8px; overflow: hidden; }
+      .dsql-preview-head { display: flex; align-items: center; gap: 8px; padding: 8px 10px; border-bottom: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,0.12)); font-weight: 600; }
+      .dsql-preview-note { margin-left: auto; font-weight: 400; font-size: 11px; color: var(--dsw-alias-label-secondary, #666666); }
+      .dsql-cols { padding: 6px 10px; border-bottom: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,0.12)); color: var(--dsw-alias-label-secondary, #666666); font-size: 11px; }
+      .dsql-scroll { overflow-x: auto; }
+      table.dsql-grid { border-collapse: collapse; width: 100%; font-size: 12px; }
+      table.dsql-grid th, table.dsql-grid td { border-bottom: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,0.08)); padding: 4px 8px; text-align: left; white-space: nowrap; }
+      table.dsql-grid th { position: sticky; top: 0; background: var(--dsw-alias-bg-layer-1, #f7f7f7); font-weight: 600; }
+    `
+
+    function injectCss(ctx) {
+      const tag = document.createElement('style')
+      tag.dataset.plugin = 'dsh-sqlite-browser'
+      tag.textContent = CSS
+      document.head.appendChild(tag)
+      ctx.effect(() => () => tag.remove(), 'dsh-sqlite: panel stylesheet')
+    }
+
+    async function api(path) {
+      const res = await fetch(path)
+      const data = await res.json().catch(() => null)
+      if (!res.ok || data === null || data.ok !== true) {
+        throw new Error((data && data.error) || ('HTTP ' + res.status))
+      }
+      return data
+    }
+
+    function fmtBytes(n) {
+      if (n < 1024) return n + ' B'
+      if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB'
+      return (n / 1024 / 1024).toFixed(1) + ' MB'
+    }
+
+    function dbOptions(files) {
+      return (files || []).map((f) => ({
+        value: f.name === 'agent.db' ? 'default' : f.name.replace(/\.db$/, ''),
+        label: f.name + ' (' + fmtBytes(f.bytes) + ')',
+      }))
+    }
+
+    function cellText(v) {
+      if (v === null || v === undefined) return 'NULL'
+      return String(v)
+    }
+
+    function SqliteBrowser() {
+      const [files, setFiles] = React.useState([])
+      const [db, setDb] = React.useState('default')
+      const [info, setInfo] = React.useState(null)
+      const [preview, setPreview] = React.useState(null)
+      const [error, setError] = React.useState(null)
+      const [loading, setLoading] = React.useState(false)
+
+      const loadTables = React.useCallback(async (target) => {
+        setLoading(true)
+        setError(null)
+        setPreview(null)
+        try {
+          setInfo(await api('/dsh-sqlite-api/tables?db=' + encodeURIComponent(target)))
+        } catch (err) {
+          setError((err && err.message) || String(err))
+        } finally {
+          setLoading(false)
+        }
+      }, [])
+
+      React.useEffect(() => {
+        api('/dsh-sqlite-api/list-dbs')
+          .then((d) => setFiles(d.dbs || []))
+          .catch((err) => setError((err && err.message) || String(err)))
+        loadTables('default')
+      }, [loadTables])
+
+      const onTable = async (t) => {
+        setError(null)
+        try {
+          setPreview(await api('/dsh-sqlite-api/preview?db=' + encodeURIComponent(db) + '&table=' + encodeURIComponent(t)))
+        } catch (err) {
+          setError((err && err.message) || String(err))
+        }
+      }
+
+      const tables = (info && info.tables) || []
+
+      return React.createElement('div', { className: 'dsql-root' },
+        React.createElement('div', { className: 'dsql-head' },
+          React.createElement('span', { className: 'dsql-title' }, 'SQLite 数据库'),
+          React.createElement('select', {
+            className: 'dsql-select',
+            value: db,
+            onChange: (e) => { const v = e.target.value; setDb(v); loadTables(v) },
+          },
+            dbOptions(files).map((o) => React.createElement('option', { key: o.value, value: o.value }, o.label)),
+          ),
+          React.createElement('button', { className: 'dsql-btn', type: 'button', disabled: loading, onClick: () => loadTables(db) }, loading ? '加载中…' : '刷新'),
+        ),
+        error !== null && React.createElement('div', { className: 'dsql-error' }, String(error)),
+        files.length === 0 && React.createElement('div', { className: 'dsql-empty' }, '尚无数据库文件（~/.dsh/data/）。先让 AI 用 sqlite_exec 建表即可。'),
+        info !== null && React.createElement('div', { className: 'dsql-status' },
+          'quick_check：' + String(info.quickCheck || 'ok') + '　·　' + tables.length + ' 张表',
+        ),
+        tables.length > 0 && React.createElement('div', { className: 'dsql-tables' },
+          tables.map((t) => React.createElement('button', {
+            key: t.name,
+            type: 'button',
+            className: 'dsql-table-row' + (preview !== null && preview.table === t.name ? ' dsql-table-row-active' : ''),
+            onClick: () => onTable(t.name),
+          },
+            React.createElement('span', { className: 'dsql-table-name' }, t.name),
+            React.createElement('span', { className: 'dsql-table-meta' }, t.columns.length + ' 列 · ' + t.rowCount + ' 行'),
+          )),
+        ),
+        tables.length === 0 && files.length > 0 && React.createElement('div', { className: 'dsql-empty' }, '（暂无表，可用 sqlite_exec 建表）'),
+        preview !== null && React.createElement('div', { className: 'dsql-preview' },
+          React.createElement('div', { className: 'dsql-preview-head' },
+            React.createElement('span', null, preview.table),
+            React.createElement('span', { className: 'dsql-preview-note' },
+              preview.rows.length + ' 行' + (preview.truncated ? '（截断至前 50 行）' : ''),
+            ),
+          ),
+          React.createElement('div', { className: 'dsql-cols' },
+            '列：' + preview.columns.join('　'),
+          ),
+          React.createElement('div', { className: 'dsql-scroll' },
+            React.createElement('table', { className: 'dsql-grid' },
+              React.createElement('thead', null,
+                React.createElement('tr', null,
+                  preview.columns.map((c) => React.createElement('th', { key: c }, c)),
+                ),
+              ),
+              React.createElement('tbody', null,
+                preview.rows.map((r, i) => React.createElement('tr', { key: i },
+                  preview.columns.map((c) => React.createElement('td', { key: c }, cellText(r[c]))),
+                )),
+              ),
+            ),
+          ),
+        ),
+      )
+    }
+
+    function apply(ctx) {
+      injectCss(ctx)
+      ctx.slots.inject('settings.section', () => ctx.slots.register(
+        { name: 'settings.section', id: 'sqlite-browser', order: 30, label: 'SQLite 数据库' },
+        () => React.createElement(SqliteBrowser),
+      ))
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots']
+    exports.name = 'dsh-sqlite-browser'
+    return module.exports
+  },
+})

package/lib/engine.js

@@ -349,3 +349,52 @@ export function importFromFile(dbName, from, signal) {
   db.exec(text)
   return { path: resolve(src), statements: stmts.length, bytes: st.size }
 }
+
+// 面板只读数据源：指定表的前 N 行（硬上限 50），返回 JSON 安全的结构化数据。
+export function tablePreview(dbName, table, limit, signal) {
+  assertNotAborted(signal)
+  const name = String(table ?? '')
+  if (name === '') throw new Error('table 参数为空')
+  const existing = allTableNames(dbName, signal)
+  if (!existing.includes(name)) {
+    throw new Error(`表不存在：${name}（现有表：${existing.join(', ') || '无'}）`)
+  }
+  const cap = Math.max(1, Math.min(50, Number.isFinite(limit) ? Math.floor(limit) : 50))
+  const { db } = openDb(dbName)
+  const prepared = db.prepare(`SELECT * FROM ${quoteIdent(name)} LIMIT ${cap}`)
+  const rows = 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 && rows.length > 0) columns = Object.keys(rows[0])
+  const clean = rows.map((r) => {
+    const o = {}
+    for (const c of columns) {
+      const v = r[c]
+      o[c] = v === undefined || v === null ? null
+        : v instanceof Uint8Array ? '<blob>'
+        : typeof v === 'bigint' ? String(v)
+        : v
+    }
+    return o
+  })
+  return { table: name, columns, rows: clean, truncated: rows.length >= cap }
+}
+
+// 读取库内 meta 约定表（label/description/table:<名> 键值对）；无表/读失败返回空对象。
+export function readDbMeta(dbName, signal) {
+  assertNotAborted(signal)
+  const { file } = dbFile(dbName)
+  if (!existsSync(file)) return {}
+  const { db } = openDb(dbName)
+  const out = {}
+  try {
+    const rows = db.prepare('SELECT key, value FROM meta').all()
+    for (const r of rows) {
+      if (r.key !== undefined && r.value !== undefined) out[String(r.key)] = String(r.value)
+    }
+  } catch { /* 无 meta 表：返回空 */ }
+  return out
+}

package/lib/index.js

@@ -1,20 +1,126 @@
 // index.js — 插件入口：注册五个工具 + 可选挂载自测。
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { CallId } from '@deepseek-ai/dsh-llm'
+import { CallId, createUserMessage } 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'
+import { COLLAB_RULE, createCoordination, frame, onPostExecute, preStepTexts } from './coordination.js'
 
 export const name = '@cxxl/dsh-sqlite'
-export const inject = ['tools']
+export const inject = ['tools', 'webServer', 'systemPrompt']
+
+function sendJson(res, code, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(body)
+}
+
+function queryOf(req) {
+  return Object.fromEntries(new URL(req.url ?? '/', 'http://x').searchParams.entries())
+}
+
+// 面板只读 API：三个 HTTP 路由（与页面同源，client 直接 fetch）。
+// webServer 声明为硬依赖（inject），cordis 会等服务就绪后再挂载本插件。
+function registerPanelRoutes(ctx) {
+  const webServer = ctx.webServer
+  ctx.effect(() => {
+    const disposers = [
+      webServer.register({
+        kind: 'exact',
+        path: '/dsh-sqlite-api/list-dbs',
+        handler: async (req, res) => {
+          try {
+            sendJson(res, 200, { ok: true, dbs: engine.listDbFiles() })
+          } catch (err) {
+            sendJson(res, 400, { ok: false, error: (err && err.message) || String(err) })
+          }
+        },
+      }),
+      webServer.register({
+        kind: 'exact',
+        path: '/dsh-sqlite-api/tables',
+        handler: async (req, res) => {
+          try {
+            const q = queryOf(req)
+            sendJson(res, 200, { ok: true, ...engine.listTables(q.db ?? 'default') })
+          } catch (err) {
+            sendJson(res, 400, { ok: false, error: (err && err.message) || String(err) })
+          }
+        },
+      }),
+      webServer.register({
+        kind: 'exact',
+        path: '/dsh-sqlite-api/preview',
+        handler: async (req, res) => {
+          try {
+            const q = queryOf(req)
+            sendJson(res, 200, { ok: true, ...engine.tablePreview(q.db ?? 'default', q.table, 50) })
+          } catch (err) {
+            sendJson(res, 400, { ok: false, error: (err && err.message) || String(err) })
+          }
+        },
+      }),
+    ]
+    console.log('[dsh-sqlite] panel routes registered: /dsh-sqlite-api/list-dbs|tables|preview')
+    return () => { for (const d of disposers) d() }
+  }, 'dsh-sqlite panel routes')
+}
+
+// v1.2：常驻短规则注入——把"持久化场景 → sqlite 工具"的触发率推向接近确定。
+// 机制依据：官方 dsh-plan-mode 的 systemPrompt.section 先例（DESIGN.md 第 14 节）。
+function registerPersistenceRule(ctx) {
+  const dispose = ctx.systemPrompt.section({
+    name: 'dsh-sqlite:persistence-rule',
+    order: 1000,
+    text: '持久化规则：当用户要求记住、记录、跟踪、保存结构化数据，或表达"以后还要查/对比/统计"的意图时，使用 sqlite_exec（写）与 sqlite_query（读）工具，不要用普通文本文件替代数据库；不确定库里有什么时先调 sqlite_tables。' + COLLAB_RULE,
+  })
+  console.log('[dsh-sqlite] persistence rule section registered (order 1000)')
+  ctx.effect(() => dispose, 'dsh-sqlite persistence rule')
+}
+
+// v2：跨会话协作感知（DESIGN.md 第 15 节）。观察者语义：绝不修改执行链路。
+function registerCoordination(ctx) {
+  const coord = createCoordination()
+  const names = new Set()
+  try {
+    for (const f of engine.listDbFiles()) {
+      if (f.name !== 'agent.db') names.add(f.name.replace(/\.db$/, ''))
+    }
+  } catch { /* 启动快照失败则按空处理 */ }
+  coord.knownDbs = names
+
+  ctx.on('tools/post-execute', (exec, result, next) => {
+    try { onPostExecute(coord, exec, result) } catch { /* 观察者绝不抛 */ }
+    return next()
+  })
+
+  ctx.on('agent/pre-step', async (payload, next) => {
+    const decision = await next()
+    if (decision === undefined || decision.kind === 'reject') return decision
+    try {
+      const texts = preStepTexts(coord, payload.agent, engine)
+      if (texts.length === 0) return decision
+      const msgs = texts.map((text) => createUserMessage({
+        content: [{ type: 'text', text: frame(text) }],
+        source: { kind: 'plugin', plugin: 'dsh-sqlite' },
+      }))
+      return { ...decision, messages: [...msgs, ...decision.messages] }
+    } catch {
+      return decision
+    }
+  })
+}
 
 export function apply(ctx) {
   for (const key of Object.keys(toolDefs)) {
     ctx.tools.register(defineTool(toolDefs[key]))
   }
   ctx.effect(() => () => engine.closeAll())
+  registerPanelRoutes(ctx)
+  registerPersistenceRule(ctx)
+  registerCoordination(ctx)
 
   // 挂载自测：DSH_PLUGIN_SELFTEST=1 时在临时数据目录跑一遍真实执行管线。
   if (process.env.DSH_PLUGIN_SELFTEST === '1') void selfTest(ctx)

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@cxxl/dsh-sqlite",
-  "version": "0.1.1",
-  "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.",
+  "version": "0.3.0",
+  "description": "DSH plugin: persistent SQLite tools for the agent (sqlite_query / sqlite_exec / sqlite_tables / sqlite_export / sqlite_import), a read-only table browser settings page, and a persistence-usage prompt rule — zero runtime deps beyond Node 22 node:sqlite.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
@@ -13,6 +14,7 @@
     "lib/index.js",
     "lib/tools.js",
     "lib/engine.js",
+    "lib/client.js",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -28,6 +30,10 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": []
     }
   },
   "keywords": [