生命周期脚本

场景支持在生命周期的不同阶段执行自定义脚本，用于初始化、清理和监控。

生命周期阶段

安装 → 激活 → 运行中 → 健康检查 → 停用 → 卸载

阶段	说明	触发时机
安装	首次安装场景时	安装完成后
激活	场景被激活时	每次切换到该场景
运行中	场景正常运行	持续的
健康检查	定期检查场景状态	定时/手动触发
停用	场景被停用时	切换到其他场景时
卸载	场景被卸载时	卸载时

声明式生命周期脚本

配置

{
  "scripts": {
    "onActivate": "console.log('activated');",
    "onActivateFile": "scripts/onActivate.js",
    "onDeactivate": "console.log('deactivated');",
    "onDeactivateFile": "scripts/onDeactivate.js",
    "onHealthCheck": "return [{ name: 'status', status: 'healthy' }];",
    "onHealthCheckFile": "scripts/onHealthCheck.js"
  }
}

激活脚本

// scripts/onActivate.js
function execute(context) {
  // context 提供以下 API：
  // - context.logger    日志记录
  // - context.querySql  数据库查询
  // - context.publishData  发布数据事件
  // - context.getSharedData  获取共享数据
  // - context.scenarioId   场景 ID
  // - context.workspacePath  工作区路径

  context.logger.info('场景正在激活...')

  // 初始化数据
  const result = context.querySql('SELECT count(*) as cnt FROM tasks')
  context.logger.info(`当前任务数: ${result.data[0].cnt}`)

  // 发布激活事件
  context.publishData('scenario:activated', {
    scenarioId: context.scenarioId,
    timestamp: Date.now(),
  })

  return { success: true }
}

停用脚本

// scripts/onDeactivate.js
function execute(context) {
  context.logger.info('场景正在停用...')

  // 清理临时数据
  context.querySql('DELETE FROM temp_data WHERE created_at < datetime("now", "-1 day")')

  return { success: true }
}

健康检查脚本

// scripts/onHealthCheck.js
function execute(context) {
  const checks = []

  // 检查数据库连接
  try {
    context.querySql('SELECT 1')
    checks.push({
      name: 'database',
      status: 'healthy',
      message: '数据库连接正常',
    })
  } catch (error) {
    checks.push({
      name: 'database',
      status: 'error',
      message: error.message,
    })
  }

  // 检查数据完整性
  const taskCount = context.querySql('SELECT count(*) as cnt FROM tasks')
  checks.push({
    name: 'tasks',
    status: 'healthy',
    message: `任务总数: ${taskCount.data[0].cnt}`,
  })

  return checks
}

编程式生命周期

编程式场景在模块接口中定义生命周期钩子：

import type { ScenarioModule, ScenarioModuleContext } from '@aweeclaw/scenario-sdk'

export default {
  // 激活
  async onActivate(context: ScenarioModuleContext) {
    context.logger.info('场景已激活')

    // 注册 IPC 处理器
    context.registerIpcHandler('my-scenario:get-data', async (payload) => {
      return { data: 'some data' }
    })

    // 订阅数据
    context.subscribeData('workspace:file-changed', (data) => {
      context.logger.info('文件已变更', data)
    })
  },

  // 停用
  async onDeactivate(context: ScenarioModuleContext) {
    context.logger.info('场景已停用')
    // 清理资源、取消订阅等
  },

  // 健康检查
  async onHealthCheck() {
    return [
      { name: 'module', status: 'healthy', message: 'OK' },
    ]
  },
} satisfies ScenarioModule

脚本沙箱环境

脚本在受限的沙箱环境中运行：

可用的全局 API

API	说明
context.logger	日志记录（info/warn/error）
context.querySql(query)	执行 SQL 查询
context.publishData(channel, data)	发布数据事件
context.getSharedData(key)	获取共享数据
context.scenarioId	当前场景 ID
context.workspacePath	工作区路径

限制

• 不能访问文件系统
• 不能进行网络请求
• 不能使用 require() 或 import()
• 不能访问 process 或 global
• 执行超时 30 秒

最佳实践

1. 轻量级：脚本应快速执行，避免阻塞启动
2. 幂等性：激活脚本应可重复执行
3. 错误处理：捕获异常并记录日志
4. 资源清理：停用脚本中清理临时资源
5. 健康检查：定期检查关键功能是否正常