常见问题

场景开发

声明式和编程式如何选择？

• 如果只需要对话功能 + 内置工具 → 声明式
• 如果需要自定义 UI 面板 → 编程式
• 如果需要复杂工具逻辑 → 编程式
• 如果想快速原型 → 声明式

场景 ID 有什么要求？

• 只能包含小写字母、数字和连字符
• 必须以字母开头
• 长度 3-64 个字符
• 全局唯一

可以同时使用内联和文件引用吗？

可以，但文件引用优先级更高。如果同时设置，会使用文件内容。

共享依赖是什么？

编程式场景的 React、zustand 等依赖由客户端注入，不打包进场景包。这样可以避免版本冲突和 React hooks 崩溃。

发布

发布需要审核吗？

是的，所有场景发布都需要经过管理员审核，确保内容合规和安全。

审核需要多久？

通常 1-3 个工作日。

发布后可以修改吗？

可以修改场景信息（描述、价格等），但修改场景内容需要发布新版本。

如何定价？

在 scenario.json 中设置 price 字段（人民币元）。平台抽成 10%，开发者获得 90%。

运行时

场景数据存储在哪里？

每个场景有独立的 SQLite 数据库文件，存储在客户端本地。

场景可以访问网络吗？

需要声明 web:search 或 web:fetch 权限。

场景可以执行命令吗？

需要声明 system:shell 权限，且该权限审核较严格。

场景卸载后数据还在吗？

如果定义了卸载脚本，会执行清理。否则数据会保留。

故障排查

场景加载失败

1. 检查 scenario.json 格式是否正确
2. 运行 validate 命令检查
3. 查看客户端日志

工具调用失败

1. 检查是否声明了对应权限
2. 检查工具参数是否正确
3. 查看执行器日志

构建失败

1. 检查 entryPoint 路径是否正确
2. 检查 TypeScript 配置
3. 检查依赖是否安装

发布失败

1. 检查是否已登录
2. 检查是否已完成实名认证
3. 检查网络连接
4. 检查包大小是否超过 50MB