{"_id":"@aweeclaw/scenario-sdk","_rev":"3-29b1938be5b5cfcc0cd93855bbcd974e","name":"@aweeclaw/scenario-sdk","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@aweeclaw/scenario-sdk","version":"1.0.0","license":"MIT","_id":"@aweeclaw/scenario-sdk@1.0.0","maintainers":[{"name":"awee","email":"402661910@qq.com"}],"dist":{"shasum":"fd4ce9e1fa738cbf18888d239f6f61672ba1c42c","tarball":"https://registry.npmjs.org/@aweeclaw/scenario-sdk/-/scenario-sdk-1.0.0.tgz","fileCount":8,"integrity":"sha512-uzDjcmTOrfZSC2BUlLOSUzifUOX9uCHdqzModhrA8IzUKtHC3QawKKCwVgAUQ/L75OPUYtzOb55fKIIQzwKYSw==","signatures":[{"sig":"MEQCIAqgznjtQ08VmdhtgvWAjncVA6n6KKDSENI3KR1t/DkVAiA9Pt0IwbWX5NEnL4SZQktS93UWm+gkWQXBOoHp75vrjA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37209},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"67ce35608347807fd3b1e2b76df03cb75cef8c2a","scripts":{"dev":"tsup --watch","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"awee","email":"402661910@qq.com"},"_npmVersion":"11.2.0","description":"SDK type definitions for AweeClaw scenario development","directories":{},"_nodeVersion":"23.9.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","typescript":"^5.3.3"},"peerDependencies":{"react":"^18.3.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/scenario-sdk_1.0.0_1779522599034_0.7321653080987658","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aweeclaw/scenario-sdk","version":"1.1.0","license":"MIT","_id":"@aweeclaw/scenario-sdk@1.1.0","maintainers":[{"name":"awee","email":"402661910@qq.com"}],"dist":{"shasum":"55070daafd16806a414e20f502520b6a66f75c2d","tarball":"https://registry.npmjs.org/@aweeclaw/scenario-sdk/-/scenario-sdk-1.1.0.tgz","fileCount":8,"integrity":"sha512-jJjCcLPZ00Wm9cSAhrOYcgUaB4TfWv7cg28CI9FKEUEsrY8edX3Fy109O1EDFi9HEduFSNq5rp391aA1eHocMQ==","signatures":[{"sig":"MEYCIQD6zvNYDqShUwqkf+AfWJd7FG9RIPdvJWLXawXvV0J5pgIhAPOZG812fV71bu52xbF0tsicRdsIGTF8MpDPI/0oVriS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":142451},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"20785ae20f45eddf5ebb553456d5cf537db92129","scripts":{"dev":"tsup --watch","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"awee","email":"402661910@qq.com"},"_npmVersion":"11.2.0","description":"SDK type definitions for AweeClaw scenario development","directories":{},"_nodeVersion":"23.9.0","dependencies":{"zod":"^4.4.3"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","typescript":"^5.3.3"},"peerDependencies":{"react":"^18.3.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/scenario-sdk_1.1.0_1782657202842_0.7950967929916901","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"_id":"@aweeclaw/scenario-sdk@1.1.1","dist":{"shasum":"d2024a2a8b1bc73c70d24805319296fe3a12f28f","tarball":"https://registry.npmjs.org/@aweeclaw/scenario-sdk/-/scenario-sdk-1.1.1.tgz","fileCount":8,"integrity":"sha512-q7YyId/Ht6UMs2YTY1KWLCVMn7HWBOI2dNNKYHz+fS+A5zk25sD0NltDDtuHXkB+eqYP8QrKXgkNCpjdcN6vjw==","signatures":[{"sig":"MEQCID6WI5FS2KL38ZF34UGNqcA3xV4UTpYGxU8cAlfy+TJgAiAg8V8rivS9nf0tMYyRNFfPiRoMLHcgxQRJ0EihCRfTPg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDZT5VbARfugPUGGihBTW5DuTlGxGlpxcb1bhrWsFQspAIgPRbJ1m3F/7HVnLR+/JJcZcSIF6LQR8K1KwTRgu3ztr8="}],"unpackedSize":142695},"main":"./dist/index.cjs","name":"@aweeclaw/scenario-sdk","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"fcc2a5536d2a531518d9f68baebc8dfa23c39ad1","license":"MIT","scripts":{"dev":"tsup --watch","build":"tsup","prepublishOnly":"npm run build"},"version":"1.1.1","_npmUser":{"name":"awee","email":"402661910@qq.com"},"_npmVersion":"11.17.0","description":"SDK type definitions for AweeClaw scenario development","directories":{},"maintainers":[{"name":"awee","email":"402661910@qq.com"}],"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.4.3"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","typescript":"^5.3.3"},"peerDependencies":{"react":"^18.3.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/scenario-sdk_1.1.1_1789634963550_0.11290760699193014"}}},"time":{"created":"2026-05-23T07:49:58.909Z","modified":"2026-09-17T08:49:23.950Z","1.0.0":"2026-05-23T07:49:59.183Z","1.1.0":"2026-06-28T14:33:22.994Z","1.1.1":"2026-09-17T08:49:23.630Z"},"license":"MIT","description":"SDK type definitions for AweeClaw scenario development","maintainers":[{"name":"awee","email":"402661910@qq.com"}],"readme":"# @aweeclaw/scenario-sdk\n\nAweeClaw 场景开发 SDK 类型定义包，为场景开发者提供完整的 TypeScript 类型支持。\n\n## 安装\n\n```bash\nnpm install @aweeclaw/scenario-sdk --save-dev\n```\n\n## 概述\n\nAweeClaw 支持两种场景开发模式：\n\n- **编程式（Programmatic）**：使用 TypeScript 编写完整的场景模块，包含 UI 组件、工具定义、生命周期钩子等\n- **声明式（Declarative）**：通过 `scenario.json` 配置文件 + Prompt 文件 + 脚本文件定义场景，无需编写代码\n\n本 SDK 为两种模式提供完整的类型定义。\n\n## 类型导出\n\n### 枚举类型\n\n| 类型 | 说明 |\n|------|------|\n| `ScenarioCategory` | 场景分类：`development` / `data` / `creative` / `productivity` 等 |\n| `WorkMode` | 工作模式：`chat` / `agent` / `plan` |\n| `UILayout` | UI 布局：`chat-centric` / `editor-centric` / `canvas-centric` 等 |\n\n### 场景核心类型\n\n| 类型 | 说明 |\n|------|------|\n| `ScenarioPlugin` | 场景插件完整定义，包含 identity / capabilities / ui / dataSources |\n| `ScenarioIdentity` | 场景身份定义（系统提示词、安全规则、工作流等） |\n| `ScenarioCapabilities` | 场景能力声明（工具包、模式、上下文类型、输出格式） |\n| `ScenarioUI` | UI 配置（布局、面板、侧边栏、状态栏、欢迎页） |\n| `ScenarioDataSources` | 数据源配置 |\n| `ScenarioContext` | 场景运行时上下文 |\n\n### 模块系统类型\n\n| 类型 | 说明 |\n|------|------|\n| `ScenarioModule` | 编程式场景模块接口，需实现 `getManifest` / `getPlugin` 等方法 |\n| `ScenarioModuleContext` | 模块运行时上下文，提供工具注册、IPC、数据通信、SQL 执行等能力 |\n| `ScenarioManifest` | 场景清单元数据 |\n| `ScenarioToolDefinition` | 工具定义（含 JSON Schema 参数和执行器） |\n| `ScenarioIpcHandler` | IPC 通道处理器 |\n| `ScenarioComponentRegistry` | UI 组件注册表 |\n| `ScenarioHealthCheck` | 健康检查项 |\n| `ScenarioLifecycleState` | 生命周期状态枚举 |\n| `ScenarioPermission` | 权限标识枚举 |\n\n### 声明式场景类型\n\n| 类型 | 说明 |\n|------|------|\n| `DeclarativeScenarioConfig` | 声明式场景完整配置 |\n| `DeclarativeIdentity` | 身份配置（支持内联文本或文件引用） |\n| `DeclarativeCapabilities` | 能力声明（内置工具 + 自定义工具） |\n| `DeclarativeCustomTool` | 自定义工具定义（声明式执行器：sql_query / run_command 等） |\n| `DeclarativeToolParam` | 工具参数 Schema |\n| `DeclarativeUI` | UI 配置 |\n| `DeclarativeDatabase` | 数据库脚本配置（安装/卸载脚本文件或内联 SQL） |\n| `DeclarativeScripts` | 生命周期脚本配置（激活/停用/健康检查 + 脚本工具） |\n| `DeclarativeScriptTool` | 脚本工具定义 |\n\n## 使用示例\n\n### 编程式场景\n\n```typescript\nimport type {\n  ScenarioModule,\n  ScenarioModuleContext,\n  ScenarioToolDefinition,\n} from '@aweeclaw/scenario-sdk'\n\nexport default {\n  id: 'my-scenario',\n  version: '1.0.0',\n\n  getManifest() {\n    return {\n      id: 'my-scenario',\n      version: '1.0.0',\n      name: 'My Scenario',\n      nameZh: '我的场景',\n      description: 'A custom scenario',\n      descriptionZh: '自定义场景',\n      author: 'developer',\n      icon: 'Package',\n      category: 'productivity',\n      tags: ['demo'],\n      entryPoint: 'bundle/index.js',\n    }\n  },\n\n  getPlugin() {\n    return {\n      id: 'my-scenario',\n      name: 'My Scenario',\n      nameZh: '我的场景',\n      icon: 'Package',\n      description: 'A custom scenario',\n      descriptionZh: '自定义场景',\n      version: '1.0.0',\n      author: 'developer',\n      category: 'productivity',\n      tags: ['demo'],\n      identity: {\n        systemPrompt: 'You are a helpful assistant.',\n        securityRules: '',\n        conventions: '',\n        workflow: '',\n      },\n      capabilities: {\n        toolPacks: [],\n        modes: [],\n        contextTypes: [],\n        outputFormats: [],\n      },\n      ui: {\n        layout: 'chat-centric',\n        panels: [],\n        sidebarItems: [],\n        statusBarItems: [],\n      },\n      dataSources: { workspace: false },\n    }\n  },\n\n  getTools(): ScenarioToolDefinition[] {\n    return [\n      {\n        name: 'greet',\n        definition: {\n          name: 'greet',\n          description: 'Send a greeting',\n          parameters: {\n            type: 'object',\n            properties: {\n              name: { type: 'string', description: 'Name to greet' },\n            },\n            required: ['name'],\n          },\n        },\n        executor: async (args) => ({\n          success: true,\n          data: `Hello, ${args.name}!`,\n        }),\n      },\n    ]\n  },\n\n  async onActivate(context: ScenarioModuleContext) {\n    context.publishData('scenario:activated', {\n      scenarioId: 'my-scenario',\n    })\n  },\n\n  async onDeactivate(context: ScenarioModuleContext) {\n    context.publishData('scenario:deactivated', {\n      scenarioId: 'my-scenario',\n    })\n  },\n\n  async onHealthCheck() {\n    return [{ name: 'module', status: 'healthy' as const, message: 'OK' }]\n  },\n} satisfies ScenarioModule\n```\n\n### 声明式场景\n\n声明式场景通过 `scenario.json` 配置，无需编写 TypeScript 代码：\n\n```json\n{\n  \"id\": \"travel-planner\",\n  \"version\": \"1.0.0\",\n  \"name\": \"Travel Planner\",\n  \"nameZh\": \"旅行规划师\",\n  \"description\": \"AI travel planning assistant\",\n  \"descriptionZh\": \"AI 旅行规划助手\",\n  \"author\": \"aweeclaw\",\n  \"icon\": \"Plane\",\n  \"category\": \"productivity\",\n  \"tags\": [\"travel\", \"planning\"],\n  \"type\": \"declarative\",\n  \"identity\": {\n    \"systemPromptFile\": \"prompts/system.md\",\n    \"securityRulesFile\": \"prompts/security.md\",\n    \"workflowFile\": \"prompts/workflow.md\"\n  },\n  \"capabilities\": {\n    \"builtinTools\": [\"web_search\", \"ask_user\", \"remember\"],\n    \"customTools\": [\n      {\n        \"name\": \"search_flights\",\n        \"description\": \"Search for flights\",\n        \"parameters\": {\n          \"origin\": { \"type\": \"string\", \"description\": \"Departure city\", \"required\": true },\n          \"destination\": { \"type\": \"string\", \"description\": \"Arrival city\", \"required\": true },\n          \"date\": { \"type\": \"string\", \"description\": \"Travel date\" }\n        },\n        \"executor\": \"web_search\",\n        \"template\": \"search flights from {origin} to {destination} on {date}\"\n      }\n    ]\n  },\n  \"ui\": {\n    \"layout\": \"chat-centric\"\n  },\n  \"database\": {\n    \"installScriptFiles\": [\"db/install.sql\"],\n    \"uninstallScriptFiles\": [\"db/uninstall.sql\"]\n  },\n  \"scripts\": {\n    \"onActivateFile\": \"scripts/onActivate.js\",\n    \"onDeactivateFile\": \"scripts/onDeactivate.js\"\n  }\n}\n```\n\n## 项目结构\n\n```\naweeclaw-scenario-sdk/\n├── src/\n│   ├── index.ts          # 统一导出入口\n│   ├── enums.ts          # 场景枚举类型\n│   ├── scenario.ts       # 场景插件核心接口\n│   ├── module.ts         # 编程式模块系统接口\n│   └── declarative.ts    # 声明式场景配置类型\n├── dist/                 # 构建产物（ESM + CJS + .d.ts）\n├── package.json\n├── tsconfig.json\n└── tsup.config.ts\n```\n\n## 构建\n\n```bash\nnpm run build\n```\n\n输出格式：\n- **ESM**: `dist/index.js`\n- **CJS**: `dist/index.cjs`\n- **类型声明**: `dist/index.d.ts`\n\n## 与 CLI 配合使用\n\n使用 `@aweeclaw/scenario-cli` 快速初始化场景项目：\n\n```bash\n# 编程式场景\nnpx aweeclaw-scenario init my-scenario --type programmatic\n\n# 声明式场景\nnpx aweeclaw-scenario init my-scenario --type declarative\n```\n\n初始化后的项目会自动引入本 SDK 作为开发依赖。\n\n## 许可证\n\nMIT\n","readmeFilename":"README.md"}