LetsGal Studio 提供了一份专门给 AI 编程助手阅读的扩展开发指导文件。把它和你的需求一起交给 Codex、Claude Code、Cursor 或 GitHub Copilot，AI 就能了解扩展目录、SDK 查找方式、构建命令和不可破坏的约束。 你不需要先把所有扩展 API 背下来。更重要的是准备好扩展工程，并把想实现的玩家体验描述清楚。

打开 AI 扩展开发指导

查看或复制提供给 AI 编程助手的完整上下文

​
开始前准备

AI 需要在扩展的源码根目录中工作。按照下面四步准备即可。

​
1. 新建扩展并记住安装位置

进入 个性化 → 项目设置，在扩展树顶部点击「新建扩展」。创建窗口底部会显示最终安装位置，例如： 
macOS
/Users/xiaoming/Documents/AVG-Extensions/affection-toast-a1b2c3

Windows
C:\Users\Xiaoming\Documents\AVG-Extensions\affection-toast-a1b2c3
最后一段目录名由扩展名称和随机字符组成，每个人看到的都可能不同，这是正常的。创建后不要为了“看起来整齐”手动修改目录名或 extension.json 中的 id。

​
2. 初始化程序

在扩展树中展开刚创建的扩展，选中「程序」，点击「初始化程序」。完成后，源码根目录里应该直接出现： 
affection-toast-a1b2c3/
├── extension.json
├── package.json
├── src/
├── sdk/
├── ui/
└── vite.config.ts
如果只想制作标题页、菜单或 HUD，并且可视化界面编辑器已经能完成需求，可以不初始化程序，直接在 Studio 中制作界面。

​
3. 确认没有选错目录

点击「在终端中打开」或「在文件管理器中打开」。最简单的判断方法是：打开的这一层必须直接包含 extension.json、package.json、src/ 和 sdk/。
选择的目录是否正确原因
.../AVG-Extensions/affection-toast-a1b2c3/正确这是单个扩展的源码根目录
.../AVG-Extensions/太上层里面可能有多个扩展，AI 容易改错
.../affection-toast-a1b2c3/src/太下层看不到清单、构建配置和本地 SDK
.../我的游戏/extensions/.../错误这是游戏项目中的运行快照，不是完整源码

​
4. 用 AI 工具打开源码根目录

在 Codex、Cursor 等工具中选择“打开文件夹”，选中上面确认过的扩展目录。使用终端工具时，先进入同一个目录： 不会使用终端也没关系，直接使用“打开文件夹”即可。下面的命令只提供给习惯终端的用户。 
# macOS
cd "/Users/xiaoming/Documents/AVG-Extensions/affection-toast-a1b2c3"

# Windows PowerShell
cd "C:\Users\Xiaoming\Documents\AVG-Extensions\affection-toast-a1b2c3"
进入后再启动 AI 工具并粘贴本文提供的提示词。
不要让 AI 在项目内的扩展发行物快照上开发。发行物只用于预览和构建游戏，不包含完整源码，后续刷新扩展时还可能被覆盖。

​
第一次使用的推荐提示词

把下面内容复制到 AI 编程助手，再把中间的功能需求替换成自己的内容： 
请阅读 https://docs.avg-engine.com/extensions/llms.txt，
在当前扩展源码目录制作一个任务管理扩展：

- 写一个玩家任务面板，显示任务名称、状态、空状态和关闭按钮
- 扩展设置可以修改面板标题和每页数量
- 让剧本可以调用“新增任务”和“完成任务”
- 任务数据跟随当前存档保存

请直接修改代码并完成构建，不要修改扩展 id、sdk/ 或 dist/。
最后告诉我改了什么，以及如何在 Studio 中验证。
这段提示词由三部分组成：
  • 指导地址：告诉 AI 去哪里获取 LetsGal 专用上下文；
  • 需求：描述要做什么；
  • 完成要求：让 AI 构建代码并给出 Studio 验证方法。
这个例子把扩展的三部分连在了一起：剧本通过扩展方法改变任务数据，创作者通过配置面板调整显示方式，玩家在扩展页面中查看结果。

​
在不同工具中使用

​
Codex

用 Codex 打开扩展源码文件夹，在新任务中粘贴上面的提示词。Codex 会自动读取当前目录中的文件，可以修改源码并运行构建命令。 如果使用终端版 Codex，先进入扩展目录，再启动 Codex： 
cd "/你的扩展目录"
codex
首次运行命令或修改文件时，工具可能请求授权。允许它读写当前扩展目录，并运行安装依赖和构建所需的命令即可。

​
Claude Code

在终端进入扩展目录后启动 Claude Code，再粘贴同一份提示词： 
cd "/你的扩展目录"
claude

​
Cursor 或其他编辑器内置 AI

使用“打开文件夹”打开扩展源码目录，在 AI 聊天中粘贴提示词。确认聊天上下文对应的是整个扩展工程，而不只是当前打开的一个 .tsx 文件。
不需要为不同 AI 工具准备不同版本的需求。llms.txt 是普通文本，能读取网页或文件的 AI 编程助手都可以使用。

​
先看看扩展可以包含什么

扩展不一定只有一个页面。它可以同时为创作者、剧本和玩家提供不同能力，你只需根据需求选择需要的部分。
扩展中的部分直观理解常见例子
完整页面玩家打开后占据主要画面背包、任务列表、手机、图鉴、小游戏
常驻小界面或弹窗叠在剧情画面上的小界面，也常被称为 HUD日期、属性条、任务追踪、获得物品提示
配置面板创作者在 Studio 中调整扩展标题、颜色、位置、数量、功能开关
剧本指令剧本执行到这里时让扩展做一件事新增任务、获得物品、改变好感度
进度数据记住玩家在游玩中产生的状态背包物品、任务进度、已解锁图鉴
快捷键与按钮玩家主动触发扩展功能按 J 打开任务页、点击图标关闭面板
自动响应游戏发生某件事时自动工作变量变化时弹提示、进入对话时显示工具栏
可视化界面联动Studio 负责排版，程序补充动态行为按钮切页、刷新列表、修改文字和图片
替换系统界面接管 Studio 原有的游戏页面自定义标题、存读档、设置或对话框
你不需要记住这些功能对应的代码名称。只要把“谁使用、怎样触发、看到什么、是否保存”描述清楚，开发指导文件会告诉 AI 应该使用哪种扩展能力。

​
一个完整任务扩展会怎样工作

以任务扩展为例，各部分可以这样连在一起：
  1. 创作者在配置面板中填写页面标题和每页显示数量；
  2. 剧本运行“新增任务”指令；
  3. 任务进度自动跟随存档保存；
  4. 画面右侧 HUD 提醒玩家有新任务；
  5. 玩家按 J 打开完整任务页面查看详情。
第一次制作时不必全部实现。可以先让 AI 做出页面和一条“新增任务”指令，确认能运行后再增加设置、存档和快捷键。

​
按方向继续指导 AI

第一版能运行后，可以用下面这些短提示词逐步完善，不必每次重新描述整个扩展。

​
制作扩展的配置面板

配置面板是给项目创作者使用的。告诉 AI 每个选项的名称、默认值和用途即可。 
给当前任务扩展增加配置面板：

- 面板标题：文本，默认“任务”
- 每页数量：数字，默认 6，范围 2～12
- 显示已完成任务：开关，默认开启

这些选项要显示在 Studio 的扩展设置中，并实时影响任务页面。
不要做成玩家游戏中的设置页面。完成后构建并告诉我在哪里验证。
如果配置项之间存在关系，也要说清楚，例如“关闭任务分页后，隐藏每页数量设置”。

​
增加剧本可以调用的指令

Studio 把这类指令称为“扩展方法”。你不需要理解它的代码写法，只要说明指令名称、需要填写什么，以及执行后会发生什么。 
给当前任务扩展增加两个剧本指令：

1. 新增任务：填写任务 id、标题和可选说明；相同 id 不重复创建
2. 完成任务：选择任务 id；找不到任务时不要中断剧情

方法要出现在 Studio 的“调用扩展方法”选择器中，
任务数据跟随当前存档保存。完成后构建并给出剧本测试步骤。
还可以继续说明哪些内容必填、默认填什么，以及希望 Studio 提供文字框、数字框、角色选择还是下拉候选。

​
编写玩家看到的扩展页面

页面需求要同时说明内容、布局、交互和空状态，不需要先决定使用什么技术。 
给当前任务扩展制作一个玩家任务页面：

- 居中显示，包含标题、未完成/已完成切换和关闭按钮
- 每条任务显示标题、说明和完成状态
- 没有任务时显示“当前没有任务”
- 页面读取扩展设置和存档中的任务数据

请保持代码结构清晰。完成后构建，
并告诉我怎样通过“显示界面”Block 打开它。
想控制视觉方向时，继续补充颜色、尺寸、间距和动画即可。例如：“深色半透明卡片、宽 960 像素、完成任务降低透明度，不使用外部字体和 CDN。” 主要是静态排版时，可以先在 Studio 的可视化界面编辑器中制作，再告诉 AI：“保留现有排版，用程序让任务列表和按钮动态工作。”

​
其他常见方向怎么说

下面这些要求可以直接追加到你的提示词中：
想增加的能力可以这样告诉 AI
HUD 提示“新增任务时在画面右上角显示三秒提示，不要遮挡对话框。”
快捷键“玩家按 J 打开或关闭任务页，并允许在输入按键设置中重新绑定。”
自动响应“任务状态变化后立即刷新页面；重复打开预览不能产生多个提示。”
当前存档数据“任务只属于当前存档槽位，读档后恢复到保存时的状态。”
跨存档解锁“已解锁的图鉴在所有存档之间共享。”
联动可视化界面“我已经做好 main-panel 界面，请保留排版，让程序更新任务文字和按钮状态。”
替换系统页面“把这个页面作为自定义标题画面，同时保留开始游戏、设置和退出入口。”
系统界面替换会影响游戏的基础入口，第一次开发建议先从普通页面、HUD 或弹窗开始。

​
让 AI 修改已有扩展

修改已有功能时，告诉 AI 保留什么、改变什么： 
请阅读 https://docs.avg-engine.com/extensions/llms.txt，
然后修改当前扩展。

现在好感度变化提示固定出现在右上角。
请增加一个扩展设置，让创作者可以选择四个屏幕角落。

保持已有剧本方法、存档字段和默认行为不变。
旧项目没有这个设置时仍默认使用右上角。

完成后运行构建，并列出 Studio 验证步骤。
“保持已有存档兼容”“不要改变剧本方法参数”“旧项目使用原默认值”这类约束应当明确写出，尤其适合已经发布或已经被剧本使用的扩展。

​
可以授权 AI 做什么

一般扩展开发只需要允许 AI 编程助手：
  • 读取当前扩展目录；
  • 修改 src/、必要的配置和 extension.json 中非稳定字段；
  • 按锁文件安装依赖；
  • 运行 package.json 中已有的构建和测试命令。
下面这些操作不属于普通开发步骤，除非你确实需要，否则不要授权：
  • 修改 extension.json.id；
  • 手动修改 sdk/ 或 dist/；
  • 删除整个扩展目录；
  • 读取密钥或其他项目中的隐私文件；
  • 发布到扩展工坊；
  • 上传文件或调用外部服务；
  • 创建 Git tag 或执行发布流程。
AI 生成的代码仍然需要你确认行为。特别是存档、读档、快捷键、系统界面替换和外部网络请求，不应只看构建成功。

​
构建 AI 的修改

AI 编程助手通常会在终端执行项目自己的构建命令。默认程序扩展使用： 
npm install
npm run build
你也可以回到 Studio，在扩展树中右键扩展并选择「构建扩展（自动装依赖）」。Studio 会同步依赖、执行构建并刷新程序预览。 如果希望一边修改一边查看预览，可以在扩展目录运行： 
npm run watch
默认脚手架没有 npm run dev。如果 AI 反复尝试这个命令，提醒它重新读取 package.json 和扩展开发指导。

​
在 Studio 中验收

构建成功后，根据扩展类型逐项检查：

​
剧本方法

  1. 在剧本中插入「调用扩展方法」Block。
  2. 确认能找到新方法，参数控件和默认值正确。
  3. 分别测试正常值、空数据和边界值。

​
程序 UI

  1. 在扩展程序预览中打开对应模块。
  2. 在主预览或调试画布中通过真实触发方式打开。
  3. 检查不同画面比例、空数据和内容较多时的布局。
  4. 反复关闭、打开和重启预览，确认没有重复监听或重复弹窗。

​
设置与存档

  1. 修改扩展设置，确认无需改代码即可生效。
  2. 保存游戏、改变数据后再读档，确认 slot 数据正确恢复。
  3. 换一个存档槽位，确认数据不会错误串联。
  4. 对 shared 数据确认它确实跨存档保留。

​
快捷键与系统界面

  1. 确认动作出现在输入按键设置中，并可以重新绑定。
  2. 测试键盘重复按下、界面已经打开和输入框聚焦等情况。
  3. 替换系统界面时，逐一检查标题、返回、存读档和设置入口。

​
AI 完成后应该告诉你什么

一份合格的完成回复应该包含：
  • 修改了哪些文件；
  • 实现了哪些行为；
  • 执行了哪些构建或测试；
  • 构建是否成功；
  • 哪些效果无法在终端确认；
  • 你需要在 Studio 中怎样验证。
如果 AI 只贴出一段代码、没有真正修改文件，可以继续告诉它： 
请直接在当前扩展目录完成实现，不要只提供示例。
完成后运行 package.json 中的构建命令并修复错误。
如果 AI 声称“已经验证界面”，但没有实际运行 Studio 或浏览器预览，应以它提供的人工验收步骤为准，不要把构建成功等同于运行效果正确。

​
常见问题

​
AI 找不到扩展 API

让它先检查扩展目录中的 sdk/index.ts 和 sdk/sdk-context.ts。本地 SDK 是当前扩展最可靠的类型来源。 如果目录中没有 sdk/、package.json 或 src/，通常说明还没有在 Studio 中初始化程序，或者打开的是项目发行物而不是扩展源码。

​
AI 修改了 dist/index.js

让它把修改移回 src/，再执行构建。dist/ 会被下一次构建覆盖，不是源码。

​
构建成功但 Studio 没变化

检查以下内容：
  1. AI 修改的是 Studio 当前关联的本地扩展目录；
  2. extension.json.entry 指向实际生成的文件；
  3. 扩展已经在当前项目启用；
  4. Studio 已刷新项目发行物；
  5. 扩展日志中没有加载错误。

​
AI 是否可以直接制作可视化界面

可视化界面 JSON 主要由 Studio 编辑器维护。AI 更适合编写 TypeScript 控制器、React 程序 UI 和扩展逻辑。只需要排版界面时，先用可视化编辑器制作，再让 AI 通过 ctx.visualUI 增加动态行为。

​
下一步

第一次尝试可以从一个只有剧本方法和存档字段的小扩展开始。理解基本结果后，再增加 React UI、快捷键或系统插槽。

阅读 Hello World

看一个同时包含方法、设置、存档和 UI 的完整例子

查找运行时 API

按功能选择 ExtensionContext 命名空间