zyJson3.1.5

Imported from ZhuHuan521/SMTCLyrics (e/unpacked/zyJson3.1.5/AGENTS.md). Install upstream with npx skills add ZhuHuan521/SMTCLyrics --skill zyJson3.1.5. Copyright stays with the author.

# AGENTS.md

项目说明

当前目录是由 zyJson3.1.5.ec 解包得到的易语言目录工程。 外部编辑器应直接修改本目录内容，再通过 tool\\e-packager.exe 回包生成 zyJson3.1.5.ec.e 文件。

目录结构

• src/：源码目录。普通程序集、类、窗口程序集使用 .txt 保存；窗口界面定义使用同名 .xml 保存。
• src/.数据类型.txt：数据类型定义。
• src/.DLL声明.txt：DLL 声明。
• src/.常量.txt：常量定义。
• src/.全局变量.txt：全局变量定义。
• project/：封包所需元数据与原生快照，请勿随意删除。
• header/：自动生成的公开接口头文件，仅供查阅与分发，不参与回包。
• elib/：当前工程依赖支持库的公开接口导出文本，仅供查阅与 AI 理解，不参与回包。
• image/：图片资源 / 二进制资源及 list.json。
• audio/：音频资源 / 二进制资源及 list.json。
• tool/：当前目录自带的 e-packager.exe。
• info.json：记录本目录来源 .ec 的文件名、路径、类型、修改时间、尺寸、MD5。

易语言路径

• 当前易语言主程序路径通常从注册表读取：HKEY_CLASSES_ROOT\E.Document\Shell\Open\Command，以及兼容视图下的 HKEY_LOCAL_MACHINE\SOFTWARE\Classes\E.Document\Shell\Open\Command。
• 解析方式是读取默认值中的命令行，再提取其中的可执行文件路径并取目录。
• 当前机器探测到的易语言安装目录候选：
  • D:\eyuyan\eyy

易语言基础约定

• 以 # 开头的标识通常表示常量；图片、音频和其它二进制资源也按常量资源使用，例如 #启动画面。
• 以 & 开头通常表示对子程序取址，常用于回调或传递函数地址，例如 到整数 (&枚举窗口过程)；当某个 API、DLL 或外部接口要求传递“整数型函数地址”时，通常可写作 到整数 (&子程序名)。
• 以 . 开头的是易语言系统指令或关键字，例如：.版本、.程序集、.子程序、.参数、.局部变量、.程序集变量、.全局变量、.常量、.DLL声明、.数据类型、.成员、.如果、.如果真、.否则、.返回。修改源码时不要删掉前导的 .，也不要把这些关键字改写成 C/C++ / JavaScript 风格。
• 单引号 ' 开头表示注释。注释是一整行语句，不要把注释内容当成真正代码，也不要改成 // 或 /* */。
• 布尔值使用 真 / 假。
• 数组下标通常从 1 开始，访问第一个元素常写作 数组 [1]，不要按多数编程语言习惯改成从 0 开始推导。
• .变量循环首 (起始值, 终止值, 步长, 变量) 的循环范围由参数决定，不是固定从 1 开始；遍历数组时常见写法是 .变量循环首 (1, 取数组成员数 (数组), 1, i)，但其它起止范围也可能是合法的。
• .计次循环首 (次数, i) 的计次变量 i 通常从 1 递增到 次数；如果配合数组成员数使用，常见有效下标范围也是 1..取数组成员数 (数组)。
• 赋值常写作 变量 ＝ 值，不要误写成半角 =。
• 自增 / 自减通常写作 a ＝ a ＋ 1、a ＝ a － 1，不要写成 a++、--a。
• 返回常见写法为 返回 (...)。
• 普通程序集、窗口程序集中的子程序名按全局解析，没有命名空间可用于隔离同名函数；新增或重命名这类子程序时，必须确保它在整个工程范围内全局唯一，避免与其它程序集 / 窗口程序集中的现有子程序重名。
• 类中的成员子程序通常不能直接写成 &类内子程序名 作为普通回调传给 API 或 DLL；需要回调时，优先使用普通程序集子程序、窗口程序集子程序，或额外做桥接子程序。
• 代码中常见全角中文标点、全角运算符和中文引号，编辑时不要擅自替换成其它语言习惯写法。

源码文件规则

• 程序集、类、窗口程序集源码文件通常以 .版本 2 开头，随后出现 .程序集 ...、.程序集变量 ...、.子程序 ...、.参数 ...、.局部变量 ... 等定义。
• src 目录中以 . 开头的固定文件不是普通源码页，而是映射到易语言内部专用表的固定入口；它们应保留原文件名，不要改名成别的页面，也不要挪到子目录。
• src/.数据类型.txt：只放 .数据类型 / .成员 相关定义，用于自定义数据类型表。
• src/.DLL声明.txt：只放 DLL 声明相关内容，用于外部 DLL 命令 / 声明表，不要在这里写普通 .子程序。
• src/.常量.txt：只放常量定义，用于常量表；#常量名 之类引用通常来自这里或支持库。
• src/.全局变量.txt：只放全局变量定义，用于全局变量表。
• 这些固定文件中的定义会在封包时分别写回易语言内部对应的数据区；如果把它们并到普通程序集 .txt 中，或把普通源码写进这些固定文件，回包后很容易出现编译错误、名称链接错误或结构错位。
• 窗口界面定义放在 src/<窗口名>.xml，窗口事件实现代码放在对应窗口程序集 .txt 中；不要把窗口 XML 内容写回源码 .txt。
• 控件事件子程序依赖窗口界面定义和窗口程序集之间的名称绑定，必须保留在对应的窗口程序集源码页中，不能挪到普通程序集、其它窗口程序集或类里。像 _图片框_定位_鼠标左键被按下、_按钮_Clear_被单击 这类事件子程序，一旦脱离所属窗口程序集，回包后通常会出现事件失联或编译错误。
• 新增子程序时，必须写完整的 .子程序 头、必要的 .参数 / .局部变量，以及函数体；不要只写一段裸代码。
• 新增 DLL 声明、数据类型、常量、全局变量时，放到各自固定文件中，不要误加到程序集源码页里。

图片 / 音频 / 二进制资源

• image/list.json 和 audio/list.json 是资源索引，实际资源文件通常位于同目录下的 .bin 文件中；封包时按索引读取，不要只新增文件而不更新 list.json。
• 资源的使用方法和常量一致，在易语言代码中以 #资源名 引用；list.json 中的 logicalName 就是 # 后面的资源名。
• image/ 与 audio/ 只是资源类型分组，除图片和音频外，也可以存放程序需要携带的任意二进制数据。
• 新增图片资源：tool\\e-packager.exe update . --add-image 图片文件路径，默认使用文件名 stem 作为资源名，例如 logo.png 对应 #logo。
• 新增音频资源：tool\\e-packager.exe update . --add-audio 音频文件路径，默认使用文件名 stem 作为资源名。
• 显式指定资源名：tool\\e-packager.exe update . --add-image 资源名=文件路径 或 tool\\e-packager.exe update . --add-audio 资源名=文件路径；资源名不要包含路径分隔符或 Windows 文件名非法字符。

新增程序集 / 类 / 窗口操作

• 新增普通程序集：在 src/ 或其子目录中新建一个文件名不以 . 开头的 .txt 文件，例如 src/网络/下载工具.txt。该文件会在封包时自动识别为源码页。最小示例：

.版本 2

.程序集 下载工具

.子程序 示例, 整数型
返回 (0)

• 新增类：同样是在 src/ 或其子目录中新建普通 .txt 文件，但 .程序集 头中要写基类。自定义类通常写作 .程序集 类名, 对象；如果继承别的类，则把第二个字段写成基类名。最小示例：

.版本 2

.程序集 下载任务, 对象
.程序集变量 地址, 文本型

.子程序 开始
' TODO: 在此补充实现

• 新增窗口：至少需要同时新增两个文件。
  1. src/<窗口名>.xml：窗口界面定义。
  2. src/窗口程序集_<窗口名>.txt：窗口程序集源码，建议严格按这个名字来创建，便于封包时和窗口 XML 自动匹配。
• 新增窗口程序集时，推荐直接写成 .程序集 窗口程序集_<窗口名>，并把窗口 XML 根节点的 名称 属性保持为同一个窗口名。最小示例：

.版本 2

.程序集 窗口程序集_主窗口

.子程序 __启动窗口_创建完毕
' TODO: 在此补充窗口初始化代码

• 封包器会优先按这些规则匹配窗口和窗口程序集：同名、窗口程序集_<窗口名>，以及少量兼容写法。为了减少名称链接错误，新增窗口时优先使用 窗口程序集_<窗口名>.txt 这种命名。
• 新增源码页后，不需要手动编辑窗口列表页或其它目录索引；pack 时会自动扫描 src/**/*.txt（排除 src/.数据类型.txt、src/.DLL声明.txt、src/.常量.txt、src/.全局变量.txt 这些固定文件）以及 src/**/*.xml。
• 新增完成后，立即运行 tool\\e-packager.exe 或 tool\\e-packager.exe pack . .\\pack\\zyJson3.1.5.ec 做一次封包验证，尽早发现语法错误、窗口绑定错误或名称链接错误。

无头编译

• 前提：如果当前目录存在 lib/AutoLinker.fne，并且易语言已成功加载 AutoLinker，则可优先使用 AutoLinker 的无头编译链路验证回包结果。
• 当前目录暂未检测到 lib/AutoLinker.fne；如后续补入该文件，可直接使用下面的命令格式。
• 使用方法参考 D:\git\AutoLinker。

推荐使用启动器方式处理启动早期弹窗：

D:\git\AutoLinker\bin\fne_release\AutoLinkerTest.exe headless-compile `
  "<从注册表获取到的易语言主程序路径>" `
  "D:\demo\demo.e" `
  "D:\demo\build\demo.exe" `
  --target auto --static `
  --result "D:\demo\build\compile-result.json" `
  --timeout 120

也可以直接启动易语言主程序：

"<从注册表获取到的易语言主程序路径>" `
  "D:\demo\demo.e" `
  --autolinker-headless-compile `
  --autolinker-output "D:\demo\build\demo.exe" `
  --autolinker-target auto `
  --autolinker-result "D:\demo\build\compile-result.json"

优先使用 AutoLinkerTest headless-compile 处理启动早期弹窗；仅在需要时再用直接参数方式。

代码格式要求

• 保持一条逻辑语句一行，不要把多行代码压成一行。
• 保持原有缩进、空行和注释风格，尽量与现有源码一致。
• 如果只是修改某个子程序，不要重写整个页面，更不要重复输出 .版本 2。
• 不要修改任何以 . 开头的系统指令拼写，也不要擅自替换成其它语言关键字。
• 新增普通程序集 / 窗口程序集子程序前，先检查工程内是否已有同名子程序；没有命名空间可兜底，同名很容易在封包或编译时触发名称冲突。
• 如果修改的是窗口事件、类方法或程序集方法，要确保该子程序仍保留在原有所属页面中。
• 如果修改的是控件事件子程序，除了保留在原所属页面中，还要继续留在对应窗口的窗口程序集内，不要跨窗口移动，也不要改成普通工具子程序。

常见流程控制示例

.如果真 ()
    a ＝ 0
.如果真结束

.如果 (a ＝ 0)
    a ＝ 1
.否则
    b ＝ 1
.如果结束

.计次循环首 (count, i)
    a ＝ a ＋ 1
.计次循环尾 ()

.变量循环首 (1, 100, 1, i)
    输出调试文本 (i)
.变量循环尾 ()

.判断开始 (b ＝ 1)
    a ＝ 1
.判断 (b ＝ 2)
    a ＝ 2
.默认
    a ＝ 0
.判断结束

回包方法

在项目根目录执行以下任一方式：

• 默认方式：tool\\e-packager.exe 默认输出到 pack/ 目录，文件名优先使用 info.json 中记录的默认封包文件名。
• 显式方式：tool\\e-packager.exe pack . .\\pack\\zyJson3.1.5.ec.e

回包后的 zyJson3.1.5.ec.e 可直接在易语言 IDE 中打开并编译。

更新依赖和资源

当你新增模块、支持库、图片、音频或其它二进制资源，或希望刷新当前目录下的派生依赖文件时，可在项目根目录执行：

• 刷新当前 project/.module.json、ecom/ 以及可用时的 elib/：tool\\e-packager.exe update .
• 新增模块后顺带写入依赖并刷新：tool\\e-packager.exe update . --add-ecom 某模块.ec
• 新增支持库后顺带写入依赖并刷新：tool\\e-packager.exe update . --add-elib 某支持库.fne
• --add-elib 也可直接填写支持库名称，例如：tool\\e-packager.exe update . --add-elib spec
• 新增图片资源并写入 image/list.json：tool\\e-packager.exe update . --add-image logo.png
• 新增音频资源并写入 audio/list.json：tool\\e-packager.exe update . --add-audio notify.wav
• 自定义资源常量名：tool\\e-packager.exe update . --add-image 启动画面=splash.bin，代码中用 #启动画面 引用。

update 不会直接回包；它用于在继续编辑源码前，同步项目中模块 / 支持库的依赖描述、导出的辅助资料以及资源索引。

错误定位

如果回包时检测到语法错误，e-packager.exe 会输出类似以下信息：

• source_syntax_error: file=src/某页面.txt, line=行号, ...
• xml_syntax_error: file=src/某窗口.xml, line=行号, ...

请按报错中的文件与行号修正后再重新回包。

工具来源

本目录由 e-packager 解包生成。