两种开发模式

AweeClaw 提供两种场景开发模式，适用于不同的开发需求和技能水平。

对比总览

维度	声明式 (Declarative)	编程式 (Programmatic)
定义方式	JSON 配置文件	TypeScript 代码
编程门槛	无需编程	需要 TypeScript / React 知识
自定义 UI	仅内置面板	完整 React 组件
工具逻辑	模板配置	任意 TypeScript 逻辑
构建方式	直接复制文件	Vite 编译为 ESM Bundle
包大小	小（配置文件）	较大（含编译产物）
开发速度	快	相对慢
灵活性	有限	完全灵活
适用场景	对话助手、模板工具	复杂应用、数据仪表盘

声明式场景

声明式场景通过 scenario.json 配置文件定义所有行为，无需编写任何代码。

核心组成

my-declarative-scenario/
├── scenario.json           # 主配置文件（必填）
├── prompts/
│   ├── system.md           # 系统提示词
│   ├── security.md         # 安全规则
│   └── workflow.md         # 工作流
├── scripts/
│   ├── onActivate.js       # 激活时执行的脚本
│   └── onDeactivate.js     # 停用时执行的脚本
├── db/
│   ├── install.sql         # 初始化数据库
│   └── uninstall.sql       # 清理数据库
└── assets/                 # 静态资源

配置示例

{
  "id": "travel-planner",
  "version": "1.0.0",
  "name": "Travel Planner",
  "nameZh": "旅行规划师",
  "type": "declarative",
  "identity": {
    "systemPromptFile": "prompts/system.md",
    "workflowFile": "prompts/workflow.md"
  },
  "capabilities": {
    "builtinTools": ["web_search", "ask_user", "remember"],
    "customTools": [
      {
        "name": "search_flights",
        "description": "搜索航班信息",
        "parameters": {
          "origin": { "type": "string", "description": "出发城市", "required": true },
          "destination": { "type": "string", "description": "到达城市", "required": true },
          "date": { "type": "string", "description": "出发日期" }
        },
        "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"]
  }
}

开发流程

1. 使用 aweeclaw-scenario init --type declarative 创建项目
2. 编辑 scenario.json 配置
3. 编写提示词文件
4. （可选）编写数据库脚本和生命周期脚本
5. 使用 aweeclaw-scenario build 构建
6. 使用 aweeclaw-scenario package 打包

编程式场景

编程式场景使用 TypeScript 编写，提供完整的编程能力。

核心组成

my-programmatic-scenario/
├── scenario.json           # 主配置文件
├── package.json            # 依赖管理
├── tsconfig.json           # TypeScript 配置
├── src/
│   ├── index.ts            # 入口文件，导出 ScenarioModule
│   ├── tools/
│   │   └── index.ts        # 工具定义
│   └── components/
│       └── DashboardPanel.tsx  # 自定义面板组件
├── prompts/
│   └── system.md
└── assets/

入口文件示例

import type { ScenarioModule, ScenarioModuleContext } from '@aweeclaw/scenario-sdk'
import { DashboardPanel } from './components/DashboardPanel.js'

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', 'web:search'],
    }
  },

  getPlugin() {
    return {
      id: 'my-scenario',
      name: 'My Scenario',
      nameZh: '我的场景',
      version: '1.0.0',
      category: 'development',
      identity: {
        systemPrompt: '你是一个专业的开发助手。',
        conventions: '请使用 TypeScript 最佳实践。',
      },
      capabilities: {
        toolPacks: ['code-analysis', 'git-operations'],
        modes: [
          { id: 'chat', name: 'Chat', nameZh: '对话', description: '对话模式' },
          { id: 'agent', name: 'Agent', nameZh: '代理', description: '代理模式' },
        ],
        contextTypes: [
          { type: 'file', name: 'File', nameZh: '文件', description: '文件上下文' },
        ],
        outputFormats: ['text', 'code', 'json'],
      },
      ui: {
        layout: 'dashboard-centric',
        panels: [
          {
            id: 'dashboard',
            component: 'DashboardPanel',
            region: 'primary',
            defaultVisible: true,
            resizable: true,
          },
        ],
        sidebarItems: [
          {
            id: 'dashboard',
            icon: 'LayoutDashboard',
            label: 'Dashboard',
            labelZh: '仪表盘',
            component: 'DashboardPanel',
            position: 0,
          },
        ],
        statusBarItems: [],
        defaultSidePanel: 'dashboard',
      },
      dataSources: { workspace: true },
    }
  },

  getTools() {
    return [
      {
        name: 'analyze_code',
        definition: {
          name: 'analyze_code',
          description: '分析代码质量',
          parameters: {
            type: 'object',
            properties: {
              code: { type: 'string', description: '要分析的代码' },
            },
            required: ['code'],
          },
        },
        executor: async (args, context) => {
          const { code } = args
          // 执行代码分析逻辑
          return {
            success: true,
            data: `分析完成，代码行数: ${code.split('\n').length}`,
          }
        },
      },
    ]
  },

  getComponents() {
    return { DashboardPanel }
  },

  async onActivate(context: ScenarioModuleContext) {
    console.log('场景已激活')
  },

  async onDeactivate(context: ScenarioModuleContext) {
    console.log('场景已停用')
  },
} satisfies ScenarioModule

开发流程

1. 使用 aweeclaw-scenario init --type programmatic 创建项目
2. 安装依赖：npm install
3. 编写 src/index.ts 入口文件
4. 开发工具和组件
5. 使用 aweeclaw-scenario dev 本地开发
6. 使用 aweeclaw-scenario build 构建
7. 使用 aweeclaw-scenario package 打包

选择建议

你的需求	推荐模式
创建一个简单的客服助手	声明式
创建一个代码审查工具	编程式
创建一个数据可视化面板	编程式
创建一个翻译助手	声明式
创建一个项目管理工具	编程式
快速原型验证	声明式
生产级复杂应用	编程式

下一步

• 声明式场景详解
• 编程式场景详解