数据库脚本

场景可以拥有自己的私有数据库，用于存储场景相关数据。数据库使用 SQLite，每个场景拥有独立的数据库文件。

配置方式

声明式场景

{
  "database": {
    "installScript": "CREATE TABLE IF NOT EXISTS tasks (id TEXT PRIMARY KEY, title TEXT, status TEXT);",
    "installScriptFiles": ["db/install.sql"],
    "uninstallScript": "DROP TABLE IF EXISTS tasks;",
    "uninstallScriptFiles": ["db/uninstall.sql"]
  }
}

安装脚本 (install.sql)

场景首次激活时执行：

-- 创建任务表
CREATE TABLE IF NOT EXISTS tasks (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  description TEXT,
  status TEXT NOT NULL DEFAULT 'pending',
  priority INTEGER DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 创建索引
CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);

-- 插入初始数据
INSERT OR IGNORE INTO tasks (id, title, status) VALUES
  ('default-1', '示例任务', 'pending');

卸载脚本 (uninstall.sql)

场景卸载时执行：

DROP TABLE IF EXISTS tasks;

沙箱限制

场景数据库操作受到以下安全限制：

禁止的 DDL 操作

以下操作在沙箱中不允许执行：

• CREATE TABLE / CREATE INDEX / CREATE VIEW / CREATE TRIGGER（运行时）
• ALTER TABLE / ALTER INDEX
• DROP TABLE / DROP INDEX / DROP VIEW
• TRUNCATE
• ATTACH / DETACH
• REINDEX
• VACUUM
• PRAGMA

安装脚本中的 DDL 操作不受此限制。

允许的 DML 操作

• SELECT - 查询数据
• INSERT - 插入数据
• UPDATE - 更新数据
• DELETE - 删除数据

在脚本中访问数据库

声明式脚本工具

{
  "scripts": {
    "scriptTools": [
      {
        "name": "get_tasks",
        "description": "获取任务列表",
        "parameters": {
          "status": {
            "type": "string",
            "description": "按状态筛选"
          }
        },
        "scriptFile": "scripts/getTasks.js"
      }
    ]
  }
}

// scripts/getTasks.js
function execute(args, context) {
  const { status } = args
  let query = 'SELECT * FROM tasks'
  if (status) {
    query += ` WHERE status = '${status}'`
  }
  query += ' ORDER BY priority DESC, created_at DESC'

  const result = context.querySql(query)
  return {
    success: true,
    data: result.data,
    count: result.data.length,
  }
}

编程式场景

getTools() {
  return [{
    name: 'get_tasks',
    definition: {
      name: 'get_tasks',
      description: '获取任务列表',
      parameters: {
        type: 'object',
        properties: {
          status: { type: 'string', description: '按状态筛选' },
        },
      },
    },
    executor: async (args, context) => {
      const { status } = args
      let query = 'SELECT * FROM tasks'
      if (status) {
        query += ` WHERE status = '${status}'`
      }
      const result = await context.querySql(query)
      return result
    },
  }]
}

最佳实践

1. 使用参数化查询：避免 SQL 注入
2. 合理使用索引：为常用查询字段创建索引
3. 控制数据量：避免单表数据过大
4. 定期清理：在生命周期脚本中清理过期数据
5. 备份提示：提醒用户场景数据存储在本地