运行时模型

JokyMouse 的 Lua 运行时遵循一个很明确的原则：脚本可以自动化输入、读取自身设置、并在关键节点与用户沟通，但平台不会把整套桌面 UI 控制权无限制地开放给脚本。

模块边界

安全边界与开发模式

运行时会移除 Lua 标准库中不适合市场脚本直接使用的入口，例如 io、os.execute、os.remove、os.rename、os.getenv、loadfile 和 dofile 相关能力不会作为推荐路径开放。脚本需要文件能力时，应使用 jokymouse.fs API。

开发模式只用于本地调试：

• jokymouse.fs 在普通模式下只能访问脚本私有的 data://、cache://、temp:// 空间。
• 开发模式下额外允许 file:// 真实文件路径。
• jokymouse.http 在普通模式下走白名单；开发模式下可绕过白名单。
• 开发模式脚本不能发布到市场。

脚本可用 jm.is_dev_mode() 判断当前是否处于开发模式，但不能在 Lua 中自行开启开发模式。

中断与正常退出

运行中的脚本可能因为用户手动停止、平台要求终止，或者脚本自身调用 jm.exit() 而结束。这三种路径的含义不同：

• 用户或平台主动停止时，运行时会抛出中断错误，脚本应当尽快结束。
• 调用 jm.exit() 时，整体会被视作正常完成，同时会停止其他 fork 出来的任务。
• 调用 jm.panic(errmsg) 或 Lua 原生 error(errmsg) 时，脚本会以错误方式结束。
• 长循环或等待逻辑应该使用 jm.sleep(...) 或 jm.ensure_running()，这样才能及时响应停止信号。

settings 的角色

脚本的 settings 是发布链路中的正式配置，不只是本地表单。运行时通过 jm.settings() 读取完整配置，平台会把这些值串进创作页、安装页和运行时。

fork 任务模型

jm.fork(fn, ...) 会创建一个异步任务并返回 task_id。随后可以用 jm.wait_task(task_id, timeout_ms?) 轮询结果，或者在不再需要时调用 jm.cancel_task(task_id)。

这种模型适合把主流程和辅助流程拆开，例如：

• 主任务负责切账号。
• 子任务负责定时检查某个 UI 是否出现。
• 任一方决定脚本正常结束时，由 jm.exit() 统一收口；需要报告失败时使用 jm.panic(errmsg)。

为什么 dialog 是单独模块

提示框与自动化输入是两类职责。把这类交互留在 jokymouse.dialog 里，可以明确告诉脚本作者：

• 这是和用户沟通的正式接口。
• 这是平台愿意持续维护的交互边界。
• 这不等价于任意自定义窗口系统。

接下来可以按需查看 jokymouse API、jokymouse.system API、jokymouse.dialog API、jokymouse.log API、jokymouse.ocr API、jokymouse.screen API、jokymouse.http API、jokymouse.fs API、jokymouse.json API 和 jokymouse.storage API 的详细签名。