黑猫助手软件包开发文档

欢迎！本站将教你如何为 黑猫助手 编写软件包（Application / 软件包）。

软件包是黑猫助手的功能单元：它既可以是带界面、可启动的任务（例如「挂机打怪」）， 也可以是只提供函数、被其它软件包复用的函数库（例如「黑猫@基础库」）。 学会编写软件包，你就可以把自己的思路变成一个可安装、可分享的功能。

软件包长什么样？

一个软件包就是 apps/ 目录下的一个文件夹，用一份 .hm.json 清单描述自己：

apps/
└── 黑猫@我的任务/
    ├── .hm.json        # 清单：名称、类型、版本、依赖……
    ├── index.lua       # 任务入口：CheckTime / Check / Main
    └── ui/             # 界面（可选）
        ├── index.lua   # 注册表单
        └── main.lua    # 主表单

学习路径

建议按顺序阅读：

1. 什么是软件包 —— 理解软件包的类型与命名。
2. 目录结构 —— 每个文件/目录的作用。
3. 软件包清单 .hm.json —— 清单字段详解。
4. 运行机制 —— CheckTime、Check、Main 如何协作。
5. 编写第一个软件包 —— 手把手写出可运行的任务。

之后可以按需查阅：

• VM 全局函数 —— 运行时可用的内置函数。
• 黑猫@基础库 —— 角色、背包、珍兽、技能等常用能力。
• 游戏原生接口 —— 聊天 / 喊话等基础库未封装的原始调用。
• 运行环境与可用库 —— 三个运行环境、可用标准库与隔离规则。
• 界面（表单） —— 用声明式 schema 构建配置界面。
• 调试与常见问题 —— Main 不执行、配置不生效等排查。
• 发布与安装 —— 把软件包分享给其他人。
• 参考仓库 —— 一批真实运行的软件包仓库，照着写最快。

术语表

术语	含义
软件包 / 应用	apps/ 下的一个目录，可被安装、启动、依赖
全名（fullName）	作者@名称，例如 黑猫@基础库，在磁盘上就是目录名
清单	软件包根目录下的 .hm.json
任务	类型为 任务 的软件包，会出现在任务列表中，可以被启动
函数库	类型为 函数库 的软件包，被任务依赖，提供 require 模块与注入函数
注入（inject）	把函数库 inject/ 下的原生 Lua 脚本注入到游戏客户端中执行
UI 服务	每个任务独立的一份 Lua 运行环境，负责渲染表单、处理事件

准备好了吗？从 什么是软件包 开始吧。