声明式场景
声明式场景通过 JSON 配置文件定义 AI 应用，无需编写任何代码。适合快速创建对话助手、提示词模板等场景。
项目结构
声明式场景的典型项目结构：
my-scenario/
├── scenario.json # 主配置文件（必填）
├── package.json # 仅用于记录场景元信息
├── prompts/ # 提示词文件
│ ├── system.md # 系统提示词
│ ├── security.md # 安全规则
│ ├── conventions.md # 编码规范
│ └── workflow.md # 工作流
├── scripts/ # 生命周期脚本（可选）
│ ├── onActivate.js # 激活时执行的脚本
│ ├── onDeactivate.js # 停用时执行的脚本
│ └── onHealthCheck.js # 健康检查脚本
├── db/ # 数据库脚本（可选）
│ ├── install.sql # 安装时执行的 SQL
│ └── uninstall.sql # 卸载时清理 SQL
└── assets/ # 静态资源配置文件详解
完整配置示例
json
{
"id": "legal-advisor",
"version": "1.0.0",
"name": "Legal Advisor",
"nameZh": "法律顾问",
"description": "AI legal document reviewer and advisor",
"descriptionZh": "AI 法律文件审查与咨询助手",
"author": "aweeclaw",
"icon": "Scale",
"category": "legal",
"tags": ["legal", "document", "review"],
"type": "declarative",
"permissions": ["web:search", "workspace:read"],
"minAppVersion": "1.0.0",
"dependencies": [
{ "scenarioId": "document-parser", "version": ">=1.0.0" }
],
"identity": {
"systemPrompt": "你是一位经验丰富的法律顾问，专注于中国法律体系。",
"systemPromptFile": "prompts/system.md",
"securityRules": "不得提供具体的法律建议，提醒用户咨询专业律师。",
"securityRulesFile": "prompts/security.md",
"conventions": "使用正式的专业语言，引用相关法律条文时注明出处。",
"conventionsFile": "prompts/conventions.md",
"workflow": "1. 了解用户需求\n2. 分析法律问题\n3. 提供参考意见\n4. 建议专业咨询",
"workflowFile": "prompts/workflow.md"
},
"capabilities": {
"builtinTools": ["web_search", "ask_user", "read_file", "write_file", "remember"],
"customTools": [
{
"name": "search_legal_database",
"description": "搜索法律数据库",
"descriptionZh": "在中国法律数据库中搜索相关法条和案例",
"parameters": {
"query": {
"type": "string",
"description": "搜索关键词",
"required": true
},
"law_type": {
"type": "string",
"description": "法律类型",
"enum": ["civil", "criminal", "administrative", "constitutional", "all"]
}
},
"executor": "web_search",
"template": "site:pkulaw.com OR site:chinalawinfo.com 中国法律 {query} {law_type}"
}
]
},
"ui": {
"layout": "chat-centric",
"panels": [],
"sidebarItems": [
{
"id": "explorer",
"icon": "Files",
"label": "Workspace",
"labelZh": "工作区",
"component": "ExplorerView",
"position": 0
},
{
"id": "knowledge",
"icon": "BookOpen",
"label": "Knowledge",
"labelZh": "知识库",
"component": "KnowledgeView",
"position": 1
}
],
"statusBarItems": [],
"welcomeMessage": "你好，我是法律顾问助手。请告诉我你需要什么帮助？",
"welcomeMessageZh": "你好，我是法律顾问助手。请告诉我你需要什么帮助？",
"defaultSidePanel": "explorer"
},
"database": {
"installScript": "CREATE TABLE IF NOT EXISTS legal_cases (id TEXT PRIMARY KEY, title TEXT, content TEXT);",
"installScriptFiles": ["db/install.sql"],
"uninstallScript": "DROP TABLE IF EXISTS legal_cases;",
"uninstallScriptFiles": ["db/uninstall.sql"]
},
"scripts": {
"onActivate": "console.log('Legal advisor activated');",
"onActivateFile": "scripts/onActivate.js",
"onDeactivate": "console.log('Legal advisor deactivated');",
"onDeactivateFile": "scripts/onDeactivate.js",
"onHealthCheck": "return [{ name: 'legal_db', status: 'healthy' }];",
"onHealthCheckFile": "scripts/onHealthCheck.js",
"scriptTools": [
{
"name": "check_case_status",
"description": "Check case status",
"descriptionZh": "检查案件状态",
"parameters": {
"case_id": {
"type": "string",
"description": "案件编号",
"required": true
}
},
"scriptFile": "scripts/checkCase.js"
}
]
}
}字段说明
顶层字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 是 | 场景唯一标识，小写字母+数字+连字符 |
version | string | 是 | 语义化版本号 |
name | string | 是 | 英文名称 |
nameZh | string | 是 | 中文名称 |
description | string | 否 | 英文描述 |
descriptionZh | string | 否 | 中文描述 |
author | string | 否 | 作者名称 |
icon | string | 否 | 图标名称（lucide-react 图标） |
category | string | 否 | 分类 |
tags | string[] | 否 | 标签 |
type | string | 是 | 固定为 "declarative" |
permissions | string[] | 否 | 所需权限列表 |
minAppVersion | string | 否 | 最低客户端版本要求 |
dependencies | array | 否 | 场景间依赖 |
identity 字段
提示词配置支持两种方式：内联文本和文件引用。文件引用优先级更高。
| 字段 | 说明 |
|---|---|
systemPrompt / systemPromptFile | 系统提示词，定义 AI 角色和行为 |
securityRules / securityRulesFile | 安全规则，限制 AI 的不安全行为 |
conventions / conventionsFile | 编码规范，定义回复格式和风格 |
workflow / workflowFile | 工作流，定义 AI 处理任务的步骤 |
capabilities 字段
| 字段 | 说明 |
|---|---|
builtinTools | 启用的内置工具列表 |
customTools | 自定义工具定义 |
ui 字段
| 字段 | 说明 |
|---|---|
layout | UI 布局类型 |
panels | 面板配置 |
sidebarItems | 左侧菜单项 |
statusBarItems | 状态栏项 |
welcomeMessage / welcomeMessageZh | 欢迎消息 |
defaultSidePanel | 默认打开的侧边面板 |
提示词文件
提示词文件使用 Markdown 格式，支持 YAML frontmatter 元数据。
prompts/system.md 示例：
markdown
---
version: "1.0"
temperature: 0.7
max_tokens: 4096
---
# 角色定义
你是一位专业的法律顾问助手。
# 核心能力
1. 分析法律文件和合同条款
2. 检索相关法律条文和案例
3. 提供法律风险评估
4. 起草法律文书模板
# 行为准则
- 不得提供最终法律意见，始终建议用户咨询专业律师
- 引用法律条文时注明出处和时效性
- 保持客观中立，不偏袒任何一方
- 对敏感信息进行脱敏处理生命周期脚本
脚本在沙箱环境中运行，可访问有限的 API。
scripts/onActivate.js 示例：
javascript
// 场景激活时执行
// 可访问：context, db, logger
logger.info('场景已激活');
// 初始化数据库
const result = db.querySql('SELECT count(*) as cnt FROM legal_cases');
logger.info(`当前案件数: ${result.data[0].cnt}`);
// 发布状态更新
context.publishData('scenario:ready', { status: 'active' });