@aweeclaw/scenario-sdk
v1.2.1
Published
SDK type definitions for AweeClaw scenario development
Readme
@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 | 权限标识枚举 |
外壳布局(自定义区域树)
场景默认使用宿主排好的外壳,只按需隐藏个别元素(ui.chrome.hideXxx)。想把
整块界面重新摆位(改分栏、换顺序、用部件自己拼布局),用区域树:
| 类型 / 常量 | 说明 |
|------|------|
| ScenarioUI.shellMode | 放权档位:chrome(宿主排壳,缺省)/ regions(场景摆位)/ full(接管整壳) |
| ScenarioUI.regions | 区域树根节点;未声明时回退宿主默认布局 |
| ScenarioUI.regionsSchemaVersion | 契约版本,2 才允许 part / spacer 节点(缺省视为 1) |
| RegionNode | 节点联合类型:split / slot / panel / sandbox / part / spacer |
| HostPartId | 宿主部件 id,如 chat / sidebar / rail / quota / scene-switcher |
| PartPresentation | 部件呈现形态:inline / drawer / modal |
| REGIONS_SCHEMA_VERSION | 当前客户端支持的契约版本 |
| RESERVED_PART_IDS | full 档位必须存在的三项:scene-switcher / window-controls / drag-region |
| createFullShellTemplate() | 生成一棵已通过校验的 full 档位骨架,在其上增删面板即可 |
约束(违反时整棵树被拒绝并回退宿主默认布局):
- 每个槽位 / 部件最多引用一次(重复挂载会让会话流与编辑器状态各走一套)
- 槽位只能引用
SHELL_SLOTS五项,chat/editor归主内容区自己管理 ratio长度需与子节点数量一致- 嵌套深度:
full档位 12 层,其余 8 层
import { createFullShellTemplate } from '@aweeclaw/scenario-sdk'
const ui = {
layout: 'editor-centric' as const,
panels: [],
sidebarItems: [...],
statusBarItems: [],
shellMode: 'full' as const,
regionsSchemaVersion: 2,
regions: createFullShellTemplate({
defaultPanel: 'my-list',
chatPresentation: 'drawer',
}),
}自定义渲染(React)
主入口是纯类型与纯函数,无 React 依赖;需要自己组合排版时从子路径引入:
import {
ScenarioRenderProvider,
useHostParts,
useHasHostPart,
useScenarioRender,
} from '@aweeclaw/scenario-sdk/react'
function MyDock() {
const parts = useHostParts()
const Chat = parts.chat
// 宿主没提供该部件时安静跳过,而不是渲染空白
if (!Chat) return null
return <Chat presentation="drawer" visible defaultOpen />
}| 导出 | 说明 |
|------|------|
| ScenarioRenderContext | 场景渲染上下文,由宿主提供 |
| ScenarioRenderProvider | 上下文提供者(宿主使用;单测可自行构造 value) |
| useScenarioRender() | 读取完整上下文(scenarioId / shellMode / hostParts / slots / renderRegions),缺上下文时抛错 |
| useHostParts() | 读取部件表,缺上下文时返回空对象 |
| useHostPart(id) | 按 id 取单个部件 |
| useHasHostPart(id) | 判断宿主是否提供某部件 |
部件自身的显隐(visible)与形态(presentation)由调用方决定,部件不读布局
状态;因此切换 inline ↔ drawer ↔ modal、或收起再展开,都不会重建内部
内容(对话区的消息 DOM 与滚动位置都会保留)。
声明式场景类型
| 类型 | 说明 |
|------|------|
| 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 # 统一导出入口(纯类型 + 纯函数)
│ ├── react.ts # React 绑定(子路径 @aweeclaw/scenario-sdk/react)
│ ├── regions.ts # 外壳区域树契约与宿主部件清单
│ ├── templates.ts # full 档位外壳模板工厂
│ ├── 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/dist/react.js - CJS:
dist/index.cjs/dist/react.cjs - 类型声明:
dist/index.d.ts/dist/react.d.ts
与 CLI 配合使用
使用 @aweeclaw/scenario-cli 快速初始化场景项目:
# 编程式场景
npx aweeclaw-scenario init my-scenario --type programmatic
# 声明式场景
npx aweeclaw-scenario init my-scenario --type declarative初始化后的项目会自动引入本 SDK 作为开发依赖。
许可证
MIT
