扩展不再强制是一个 TypeScript 项目。目录结构取决于它是否包含程序。

​
纯界面扩展

新建扩展的初始结构： 
my-extension/
├── extension.json
├── .gitignore
└── ui/
    └── main-panel.json
ui/ 下每个 JSON 文件是一份可视化界面。文件名由 Studio 管理，界面显示名称可以在编辑器中修改。 纯界面扩展的 extension.json 不声明 entry。Studio 因此不会尝试加载程序 bundle。

​
初始化程序后

点击「初始化程序」会在现有目录中追加： 
my-extension/
├── extension.json
├── package.json
├── tsconfig.json
├── vite.config.ts
├── README.md
├── sdk/
├── ui/
│   └── main-panel.json
├── src/
│   ├── index.tsx
│   └── welcome-ui.tsx
└── dist/
    └── index.js
  • src/：TypeScript / React 源码；
  • sdk/：@avg-studio/sdk 的本地副本；
  • dist/index.js：Studio 和玩家端实际加载的程序；
  • ui/：仍由可视化编辑器管理，可以通过 ctx.visualUI 和程序协作。

​
extension.json

纯界面扩展的清单示例： 
{
  "id": "user.my-shell",
  "name": "我的游戏壳",
  "description": "一套自定义系统界面",
  "author": "your-name",
  "version": "1.0.0",
  "sdkVersion": "^1.0.0"
}
初始化程序后会加入： 
{
  "entry": "dist/index.js"
}

​
字段

字段必填说明
id是全局唯一标识，长度 2～128；Studio 会生成合法值
name是Studio 中显示的扩展名称
version是语义化版本号
sdkVersion是需要的最低 SDK 版本，见下方说明
author否作者标识，可以为空
description否简介
entry程序扩展是程序 bundle 相对路径；存在即表示扩展带程序
icon否图标相对路径
propsSchema否程序 UI 接受的 props 定义
overrides否接管 DialogueBox、Choice 或 InputBox
permissions / network否权限和网络能力声明
id 是设置、存档、界面引用和系统绑定的命名空间。项目开始使用后不要随意修改。

​
sdkVersion 的版本校验

v1.9.0 起：SDK 版本号与 Studio 版本号保持一致，版本校验精确到次版本和补丁号（此前只比较主版本）。
sdkVersion 声明「这个扩展至少需要哪个版本的引擎」：
  • >=1.8.0、^1.8、1.8 三种写法等价，语义统一为「至少需要 1.8.0」。
  • 主版本必须与当前引擎相同；同主版本内，声明的版本不高于当前引擎即可加载。
  • 声明高于当前引擎版本的扩展会被跳过加载，并给出明确提示；扩展工坊中不兼容的扩展会置灰并显示「需要 SDK x.x.x」。
声明建议：用到了某个版本新增的 API，就把 sdkVersion 提到那个版本（例如使用 ctx.dialogue.useStyle 需要声明 >=1.9.0）；只用基础 API 时保持较低的声明，让老版本引擎的用户也能安装。Studio 新建扩展时会自动填入当前 SDK 版本。
hasProgram 是 Studio 校验清单后生成的内部状态，不需要手写。原始清单是否声明 entry，决定扩展有没有程序。

​
程序入口

src/index.tsx 导出一个或多个 Extension 子类。也可以从 extension.json 导出清单对象： 
import manifest from "../extension.json";
import { InventoryExtension } from "./inventory";
import { InventoryPanel } from "./inventory-panel";

export { manifest, InventoryExtension, InventoryPanel };
Studio 会扫描 bundle 的导出，注册继承自 Extension 的模块。

​
构建命令

npm run build   # 单次生成 dist/index.js
npm run watch   # 监听源码并持续构建
react、react-dom 和 SDK 由宿主提供单实例，模板会配置好 Vite 和类型依赖。
不要手动修改 sdk/。需要更新 SDK 时，应通过 Studio 的扩展开发流程重新同步。