模块接口

ScenarioModule 是编程式场景的核心接口，定义了场景模块必须实现的方法。

接口定义

interface ScenarioModule {
  /** 场景唯一标识 */
  id: string

  /** 场景版本 */
  version: string

  /** 获取场景清单 */
  getManifest(): ScenarioManifest

  /** 获取场景插件定义 */
  getPlugin(): ScenarioPlugin

  /** 获取工具定义 */
  getTools(): ScenarioToolDefinition[]

  /** 获取 UI 组件（可选） */
  getComponents?(): ScenarioComponentRegistry

  /** 获取 IPC 处理器（可选） */
  getIpcHandlers?(): ScenarioIpcHandler[]

  /** 激活钩子（可选） */
  onActivate?(context: ScenarioModuleContext): Promise<void>

  /** 停用钩子（可选） */
  onDeactivate?(context: ScenarioModuleContext): Promise<void>

  /** 健康检查钩子（可选） */
  onHealthCheck?(): Promise<ScenarioHealthCheck[]>
}

方法详解

getManifest()

返回场景的元数据清单，用于场景注册和版本管理。

getManifest(): ScenarioManifest

interface ScenarioManifest {
  id: string
  version: string
  name: string
  nameZh: string
  description?: string
  descriptionZh?: string
  author?: string
  icon?: string
  category?: ScenarioCategory
  tags?: string[]
  minAppVersion?: string
  permissions?: ScenarioPermission[]
  dependencies?: ScenarioDependency[]
}

getPlugin()

返回场景的完整插件定义，包括身份、能力、UI 和数据源。

getPlugin(): ScenarioPlugin

interface ScenarioPlugin {
  id: string
  name: string
  nameZh: string
  icon?: string
  description?: string
  descriptionZh?: string
  version: string
  author?: string
  category?: ScenarioCategory
  tags?: string[]
  identity: ScenarioIdentity
  capabilities: ScenarioCapabilities
  ui: ScenarioUI
  dataSources: ScenarioDataSources
}

getTools()

返回场景提供的工具定义列表。

getTools(): ScenarioToolDefinition[]

interface ScenarioToolDefinition {
  name: string
  definition: {
    name: string
    description: string
    descriptionZh?: string
    parameters: {
      type: string
      properties: Record<string, ToolParameter>
      required?: string[]
    }
  }
  executor: ToolExecutor
}

getComponents()

返回自定义 UI 组件的映射表。

getComponents?(): ScenarioComponentRegistry

interface ScenarioComponentRegistry {
  [key: string]: React.ComponentType<any>
}

onActivate()

场景激活时调用，用于初始化资源（如注册 i18n、初始化工具、连接数据源）。

onActivate?(context: ScenarioModuleContext): Promise<void>

onDeactivate()

场景停用时调用，用于清理资源（如反注册 i18n、断开连接、释放内存）。

onDeactivate?(context: ScenarioModuleContext): Promise<void>

onHealthCheck()

定期健康检查，返回检查结果列表。

onHealthCheck?(): Promise<ScenarioHealthCheck[]>

interface ScenarioHealthCheck {
  name: string
  status: 'healthy' | 'degraded' | 'error'
  message?: string
}

完整示例

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

export default {
  id: 'my-scenario',
  version: '1.0.0',

  getManifest() {
    return {
      id: 'my-scenario',
      version: '1.0.0',
      name: 'My Scenario',
      nameZh: '我的场景',
      category: 'development',
      tags: ['demo'],
      permissions: ['workspace:read'],
    }
  },

  getPlugin() {
    return {
      id: 'my-scenario',
      name: 'My Scenario',
      nameZh: '我的场景',
      version: '1.0.0',
      category: 'development',
      identity: {
        systemPrompt: 'You are a helpful assistant.',
      },
      capabilities: {
        toolPacks: [],
        modes: [],
        contextTypes: [],
        outputFormats: [],
      },
      ui: {
        layout: 'chat-centric',
        panels: [],
        sidebarItems: [],
        statusBarItems: [],
      },
      dataSources: { workspace: false },
    }
  },

  getTools() {
    return [{
      name: 'hello',
      definition: {
        name: 'hello',
        description: 'Say hello',
        parameters: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Your name' },
          },
          required: ['name'],
        },
      },
      executor: async (args) => ({
        success: true,
        data: `Hello, ${args.name}!`,
      }),
    }]
  },

  async onActivate(context: ScenarioModuleContext) {
    context.logger.info('Activated!')
  },

  async onDeactivate(context: ScenarioModuleContext) {
    context.logger.info('Deactivated!')
  },

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