@aweeclaw/scenario-sdk

AweeClaw 场景开发 SDK 类型定义包，为场景开发者提供完整的 TypeScript 类型支持。

安装

npm install @aweeclaw/scenario-sdk --save-dev

概述

AweeClaw 支持两种场景开发模式：

• 编程式（Programmatic）：使用 TypeScript 编写完整的场景模块，包含 UI 组件、工具定义、生命周期钩子等
• 声明式（Declarative）：通过 scenario.json 配置文件 + Prompt 文件 + 脚本文件定义场景，无需编写代码

本 SDK 为两种模式提供完整的类型定义。

类型导出

枚举类型

| 类型 | 说明 | |------|------| | ScenarioCategory | 场景分类：development / data / creative / productivity 等 | | WorkMode | 工作模式：chat / agent / plan | | UILayout | UI 布局：chat-centric / editor-centric / canvas-centric 等 |

场景核心类型

| 类型 | 说明 | |------|------| | ScenarioPlugin | 场景插件完整定义，包含 identity / capabilities / ui / dataSources | | ScenarioIdentity | 场景身份定义（系统提示词、安全规则、工作流等） | | ScenarioCapabilities | 场景能力声明（工具包、模式、上下文类型、输出格式） | | ScenarioUI | UI 配置（布局、面板、侧边栏、状态栏、欢迎页） | | ScenarioDataSources | 数据源配置 | | ScenarioContext | 场景运行时上下文 |

模块系统类型

| 类型 | 说明 | |------|------| | ScenarioModule | 编程式场景模块接口，需实现 getManifest / getPlugin 等方法 | | ScenarioModuleContext | 模块运行时上下文，提供工具注册、IPC、数据通信、SQL 执行等能力 | | ScenarioManifest | 场景清单元数据 | | ScenarioToolDefinition | 工具定义（含 JSON Schema 参数和执行器） | | ScenarioIpcHandler | IPC 通道处理器 | | ScenarioComponentRegistry | UI 组件注册表 | | ScenarioHealthCheck | 健康检查项 | | ScenarioLifecycleState | 生命周期状态枚举 | | ScenarioPermission | 权限标识枚举 |

声明式场景类型

| 类型 | 说明 | |------|------| | DeclarativeScenarioConfig | 声明式场景完整配置 | | DeclarativeIdentity | 身份配置（支持内联文本或文件引用） | | DeclarativeCapabilities | 能力声明（内置工具 + 自定义工具） | | DeclarativeCustomTool | 自定义工具定义（声明式执行器：sql_query / run_command 等） | | DeclarativeToolParam | 工具参数 Schema | | DeclarativeUI | UI 配置 | | DeclarativeDatabase | 数据库脚本配置（安装/卸载脚本文件或内联 SQL） | | DeclarativeScripts | 生命周期脚本配置（激活/停用/健康检查 + 脚本工具） | | DeclarativeScriptTool | 脚本工具定义 |

使用示例

编程式场景

import type {
  ScenarioModule,
  ScenarioModuleContext,
  ScenarioToolDefinition,
} 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: '我的场景',
      description: 'A custom scenario',
      descriptionZh: '自定义场景',
      author: 'developer',
      icon: 'Package',
      category: 'productivity',
      tags: ['demo'],
      entryPoint: 'bundle/index.js',
    }
  },

  getPlugin() {
    return {
      id: 'my-scenario',
      name: 'My Scenario',
      nameZh: '我的场景',
      icon: 'Package',
      description: 'A custom scenario',
      descriptionZh: '自定义场景',
      version: '1.0.0',
      author: 'developer',
      category: 'productivity',
      tags: ['demo'],
      identity: {
        systemPrompt: 'You are a helpful assistant.',
        securityRules: '',
        conventions: '',
        workflow: '',
      },
      capabilities: {
        toolPacks: [],
        modes: [],
        contextTypes: [],
        outputFormats: [],
      },
      ui: {
        layout: 'chat-centric',
        panels: [],
        sidebarItems: [],
        statusBarItems: [],
      },
      dataSources: { workspace: false },
    }
  },

  getTools(): ScenarioToolDefinition[] {
    return [
      {
        name: 'greet',
        definition: {
          name: 'greet',
          description: 'Send a greeting',
          parameters: {
            type: 'object',
            properties: {
              name: { type: 'string', description: 'Name to greet' },
            },
            required: ['name'],
          },
        },
        executor: async (args) => ({
          success: true,
          data: `Hello, ${args.name}!`,
        }),
      },
    ]
  },

  async onActivate(context: ScenarioModuleContext) {
    context.publishData('scenario:activated', {
      scenarioId: 'my-scenario',
    })
  },

  async onDeactivate(context: ScenarioModuleContext) {
    context.publishData('scenario:deactivated', {
      scenarioId: 'my-scenario',
    })
  },

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

声明式场景

声明式场景通过 scenario.json 配置，无需编写 TypeScript 代码：

{
  "id": "travel-planner",
  "version": "1.0.0",
  "name": "Travel Planner",
  "nameZh": "旅行规划师",
  "description": "AI travel planning assistant",
  "descriptionZh": "AI 旅行规划助手",
  "author": "aweeclaw",
  "icon": "Plane",
  "category": "productivity",
  "tags": ["travel", "planning"],
  "type": "declarative",
  "identity": {
    "systemPromptFile": "prompts/system.md",
    "securityRulesFile": "prompts/security.md",
    "workflowFile": "prompts/workflow.md"
  },
  "capabilities": {
    "builtinTools": ["web_search", "ask_user", "remember"],
    "customTools": [
      {
        "name": "search_flights",
        "description": "Search for flights",
        "parameters": {
          "origin": { "type": "string", "description": "Departure city", "required": true },
          "destination": { "type": "string", "description": "Arrival city", "required": true },
          "date": { "type": "string", "description": "Travel date" }
        },
        "executor": "web_search",
        "template": "search flights from {origin} to {destination} on {date}"
      }
    ]
  },
  "ui": {
    "layout": "chat-centric"
  },
  "database": {
    "installScriptFiles": ["db/install.sql"],
    "uninstallScriptFiles": ["db/uninstall.sql"]
  },
  "scripts": {
    "onActivateFile": "scripts/onActivate.js",
    "onDeactivateFile": "scripts/onDeactivate.js"
  }
}

项目结构

aweeclaw-scenario-sdk/
├── src/
│   ├── index.ts          # 统一导出入口
│   ├── enums.ts          # 场景枚举类型
│   ├── scenario.ts       # 场景插件核心接口
│   ├── module.ts         # 编程式模块系统接口
│   └── declarative.ts    # 声明式场景配置类型
├── dist/                 # 构建产物（ESM + CJS + .d.ts）
├── package.json
├── tsconfig.json
└── tsup.config.ts

构建

npm run build

输出格式：

• ESM: dist/index.js
• CJS: dist/index.cjs
• 类型声明: dist/index.d.ts

与 CLI 配合使用

使用 @aweeclaw/scenario-cli 快速初始化场景项目：

# 编程式场景
npx aweeclaw-scenario init my-scenario --type programmatic

# 声明式场景
npx aweeclaw-scenario init my-scenario --type declarative

初始化后的项目会自动引入本 SDK 作为开发依赖。

许可证

MIT