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：
首次运行命令或修改文件时，工具可能请求授权。允许它读写当前扩展目录，并运行安装依赖和构建所需的命令即可。
Claude Code 在终端进入扩展目录后启动 Claude Code，再粘贴同一份提示词：
Cursor 或其他编辑器内置 AI 使用“打开文件夹”打开扩展源码目录，在 AI 聊天中粘贴提示词。确认聊天上下文对应的是整个扩展工程，而不只是当前打开的一个 .tsx 文件。
不需要为不同 AI 工具准备不同版本的需求。llms.txt 是普通文本，能读取网页或文件的 AI 编程助手都可以使用。
先看看扩展可以包含什么 扩展不一定只有一个页面。它可以同时为创作者、剧本和玩家提供不同能力，你只需根据需求选择需要的部分。
扩展中的部分 直观理解 常见例子 完整页面 玩家打开后占据主要画面 背包、任务列表、手机、图鉴、小游戏 常驻小界面或弹窗 叠在剧情画面上的小界面，也常被称为 HUD 日期、属性条、任务追踪、获得物品提示 配置面板 创作者在 Studio 中调整扩展 标题、颜色、位置、数量、功能开关 剧本指令 剧本执行到这里时让扩展做一件事 新增任务、获得物品、改变好感度 进度数据 记住玩家在游玩中产生的状态 背包物品、任务进度、已解锁图鉴 快捷键与按钮 玩家主动触发扩展功能 按 J 打开任务页、点击图标关闭面板 自动响应 游戏发生某件事时自动工作 变量变化时弹提示、进入对话时显示工具栏 可视化界面联动 Studio 负责排版，程序补充动态行为 按钮切页、刷新列表、修改文字和图片 替换系统界面 接管 Studio 原有的游戏页面 自定义标题、存读档、设置或对话框
你不需要记住这些功能对应的代码名称。只要把“谁使用、怎样触发、看到什么、是否保存”描述清楚，开发指导文件会告诉 AI 应该使用哪种扩展能力。
一个完整任务扩展会怎样工作 以任务扩展为例，各部分可以这样连在一起：
创作者在配置面板中填写页面标题和每页显示数量；
剧本运行“新增任务”指令；
任务进度自动跟随存档保存；
画面右侧 HUD 提醒玩家有新任务；
玩家按 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 dev。如果 AI 反复尝试这个命令，提醒它重新读取 package.json 和扩展开发指导。
在 Studio 中验收 构建成功后，根据扩展类型逐项检查：
剧本方法
在剧本中插入「调用扩展方法」Block。
确认能找到新方法，参数控件和默认值正确。
分别测试正常值、空数据和边界值。
程序 UI
在扩展程序预览中打开对应模块。
在主预览或调试画布中通过真实触发方式打开。
检查不同画面比例、空数据和内容较多时的布局。
反复关闭、打开和重启预览，确认没有重复监听或重复弹窗。
设置与存档
修改扩展设置，确认无需改代码即可生效。
保存游戏、改变数据后再读档，确认 slot 数据正确恢复。
换一个存档槽位，确认数据不会错误串联。
对 shared 数据确认它确实跨存档保留。
快捷键与系统界面
确认动作出现在输入按键设置中，并可以重新绑定。
测试键盘重复按下、界面已经打开和输入框聚焦等情况。
替换系统界面时，逐一检查标题、返回、存读档和设置入口。
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 没变化 检查以下内容：
AI 修改的是 Studio 当前关联的本地扩展目录；
extension.json.entry 指向实际生成的文件；扩展已经在当前项目启用；
Studio 已刷新项目发行物；
扩展日志中没有加载错误。
AI 是否可以直接制作可视化界面 可视化界面 JSON 主要由 Studio 编辑器维护。AI 更适合编写 TypeScript 控制器、React 程序 UI 和扩展逻辑。只需要排版界面时，先用可视化编辑器制作，再让 AI 通过 ctx.visualUI
下一步 第一次尝试可以从一个只有剧本方法和存档字段的小扩展开始。理解基本结果后，再增加 React UI、快捷键或系统插槽。
