一个支持对 Minecraft(基岩版)的命令进行补全与辅助输入的 App。本仓库为 App 的核心代码,业务逻辑用 Kotlin/JS 编写,打包成单文件 JavaScript 后由 Android 上的 Rhino 引擎执行。
App 工程参见 命令助手Android版。
- 支持命令的智能补全与纠错
- 支持命令在线帮助
- 加入了已汉化的 ID 表
- 一键粘贴命令
- 支持历史命令与命令收藏夹
- 支持外加命令库来加入支持更多的功能或命令补全
- 内置一组默认命令库,无需手动导入
- 支持通过远程清单更新命令库
- 支持更换主题样式
- 宣传片:BV1nx411V7jB
- 正式版下载链接
modules/— 宿主入口与启动段:main.cjs由 Loader AST 拼装,bootstrap/提供钩子、MapScript、Loader 与加载顺序src/— Kotlin/JS 业务源码,按core / ui / android / network / ca / json等分类data/— 从代码里剥出来的公共数据:内置命令库(idlibs/)、提示语、主题配色(theme.json)等 (每个数据文件都有对应说明,见docs/data-notes/)data/intl/— 界面文案(zh_CN/en_US)cabuildtools/— 构建工具(git subtree),AST 加载器、签名打包、壳子任务都在这里config/— 构建配置(版本号、渠道、发布方式等,见下一节)caclib/— 作者的 clib 源码(git subtree,保持原样不要手改):在线拓展包源的工程, 由clibspawn打包发布,不参与 App 构建caaccel/— Java 加速库源码(配合 Kotlin/JSAccel.kt)docs/— 开发文档:索引见docs/README.md,包含分支约定、构建配置、 数据外置与加速方案、data/各文件说明、风味构建、去重/LOADER 清理记录、 跨语言迁移候选、Kotlin/JS 迁移路线、QuickJS 计划等community-clib/— 社区拓展包源:src/放原始包,build.mjs解包重签后生成info.json/ 索引 /packs/*.lib/verify.key,GitHub 上直接对外提供(见该目录 README)build/— 构建产物(不入版本库)
-
安装依赖:
npm install需要 Node^22.18.0或>=24.11.0。构建工具用了 Babel 8(纯 ESM), 靠 Node 22+ 的require(esm)直接在 CommonJS 里加载;Node 太老会报模块找不到。 -
配置(一般不用改)。
config/shell.json与config/import.json里只写和机器无关的默认值, 构建时会自动探测本机路径:要找到的东西 探测顺序 cadroid 项目 环境变量 CA_CADROID→ CA 旁边的cadroid/或ca/Android SDK ANDROID_HOME/ANDROID_SDK_ROOT→ cadroid 的local.properties(sdk.dir)→ 常见安装位置Build Tools 优先 config/shell.json的buildToolVersion(默认 34.0.0),否则取已安装的最高版本JDK JAVA_HOME→~/.jdks(优先 17)→ Android Studio 自带的 JBR →/usr/lib/jvmandroid.jar SDK 里最新的 platform 解析结果会写到
build/generated/shellConfig.json(generateImport则写importConfig.json), 排查问题时直接看这份就知道用了哪个 SDK / JDK / cadroid。要固定某个路径,改config/shell.json里对应字段即可(填了就不再探测)。配置一览(都在
config/下,全部是 JSON;字段说明见 config/README.md):文件 内容 build.json版本号、versionCode、日期、许可更新日期、更新说明(会写进核心的 BuildConfig 与 update.json) update-sources.json客户端检查更新用的源地址(可按渠道配置、可清空关闭),以及发布端的下载地址表、更新站点根目录 publish.json发布方式( local复制到目录 /sftp上传)、目标路径与 SSH 参数shell.json壳子打包相关路径(一般不用改,自动探测) import.jsongenerateImport用的 android.jar(自动探测)caclib/里还有 clib 自己的元数据:config.json(发布源设置)、config/publish.json(发布方式)、src/*/library.json(每个命令库的 id/名称/版本/entry)。caclib/是作者的 git subtree;本仓库把它的元数据从@key txt统一转成了 JSON,cabuildtools/lib/clibspawn.mjs读取 JSON(兼容旧的.js回退)。注意:
caclib/signature/(clib 签名私钥)和caclib/outputs/不入库,所以clibspawn在全新检出的仓库里跑不起来,需要自己准备私钥后才会生成产物。
npm run help # 简版任务列表
npm run help -- buildRelease # 查看某个任务的详细参数
npm run build # 正式版
npm run snapshot # 快照版
# 渠道参数要放在 -- 后面(npm 会把 -- 之后的参数传给脚本)
npm run build -- -beta # 测试渠道
npm run build -- -dev # 开发渠道
npm run build -- -canary # 前沿渠道
# 等价于直接调用构建脚本
node ./cabuildtools/main.mjs buildRelease
node ./cabuildtools/main.mjs buildSnapshot
产物导出至 build/outputs/release/main.js 与 build/outputs/snapshot/main.js。
构建命令可以附加渠道参数,产物名会带上渠道名,一眼能看出是什么构建物:
node ./cabuildtools/main.mjs buildRelease # 命令助手(2026-10-15) stable.js + 命令助手stable<日期>.lib
node ./cabuildtools/main.mjs buildRelease -beta # 命令助手(2026-10-15) beta.js + 命令助手beta<日期>.lib
node ./cabuildtools/main.mjs buildSnapshot # build/outputs/snapshot/snapshot.js + 命令助手snapshot<日期>.lib
node ./cabuildtools/main.mjs buildSnapshot -dev # dev.js + 命令助手dev<日期>.lib
node ./cabuildtools/main.mjs buildSnapshot -canary # canary.js + 命令助手canary<日期>.lib
渠道名和构建形态是分开的两个概念:
- 形态(
BuildConfig.variants)决定核心行为:buildRelease->release,buildSnapshot->snapshot(快照形态:不写update.json,核心按非正式版处理) - 渠道(产物名 +
.lib的 uuid)默认都是 stable,加-beta/-dev/-canary才换成对应渠道
stable 只是对外的名字,内部仍然是 release/snapshot,所以核心代码里 variants == "release"
这类判断不受影响。
.lib 是安装器:装进 App 后把该渠道的脚本设为调试源并建快捷方式。每个渠道固定一个 uuid,
版本号取构建时刻 [年, 月, 日, 时, 分, 秒],同一天重新构建的包也会被识别为更新。快照形态沿用作者原来的
f6cf1729-... uuid(唯一特例,保证老的快照包还能被覆盖更新);同版本号下渠道优先级
canary > dev > beta > stable,低优先级不会覆盖高优先级。
在渠道参数之外还可以叠一个风味,只改脚本内容(默认主题、初始欢迎语、启动文字)和产物名,
不改构建形态/渠道;不会写更新清单。风味参数可选,不写时使用 data/flavors/default 基线数据。
npm run build -- -huangyxHUTAO # 南鸢晨星社区版风味:粉色主题 + 社区版欢迎语
node ./cabuildtools/main.mjs shellBuildDebug -huangyxHUTAO
风味定义在 data/flavors/<名字>/flavor.json:theme(默认主题)/ startupText /
welcome 等;主题配色本身是公共数据 data/theme.json,选择页顺序默认也按
data/theme.json 的键顺序。
data/flavors/default 是基线,其它风味在它上面合并,完整说明见
docs/flavor-build.md。
npm run gradlew # 正式版 APK
npm run gradlew -- -debug # 调试版 APK
# 等价于
node ./cabuildtools/main.mjs shellBuildRelease
node ./cabuildtools/main.mjs shellBuildDebug
正式版产物在 build/dist/,调试版在 build/outputs/debugApk/app-debug.apk。
壳子的 Gradle 任务由 shellGradle 内部调用,不需要手动执行。
调试包也开启了 R8(
minifyEnabled true)。Rhino 1.9 的SlotMapOwner$ThreadedAccess用了MethodHandle.invoke,D8 在 minSdk 21 下不会做兼容转换,不开 R8 会直接报Error while dexing;release 一直是开着的,所以只有 debug 会撞上。
npm test
# 等价于
node ./cabuildtools/tests/async-transform.test.mjs
node ./cabuildtools/tests/loader-ast.test.mjs
npm run update # 检查:有可更新的依赖就返回码 1(适合 CI)
npm run update -- --json # 机器可读输出
npm run update -- --no-error # 只看报告,不靠返回码卡流程
npm run upgrade # 升「范围内」的版本(npm update),然后跑 npm test
npm run upgrade -- --latest # 连大版本一起升(只动直接依赖的声明)
npm run upgrade -- --verify # 更新后再跑一次 npm run build
npm run upgrade -- --dry-run # 只打印会做什么,不改文件
npm run update -- ../other-repo # 目录(标准写法)
标准写法是 npm run <脚本> -- <参数>:-- 后的内容原样传给脚本,跨 npm 版本 /
yarn / pnpm / CI 都可移植。本仓库的 deps.js 额外支持省略 --(读取 npm 导出的
npm_config_xxx 环境变量),但那是便利支持,脚本/CI 请优先用标准写法。
目录也走标准写法:npm run update -- ../other-repo。
依赖检查靠 npm outdated,workspace 里的包也能识别;大版本默认不升,
因为跨大版本可能有 ESM/API 变化(比如 Babel 7 → 8),需要自己确认后
再 --latest。更新完会自动跑测试,加 --verify 还会再构建一次。
内置命令库只有一套来源:data/idlibs/*.json。由 src/core/BuiltinData.kt 用
Loader.fromFile 直接内联成 CA.Library.inner["default"] 等对象,用户无需手动导入。
默认启用/禁用的清单在 data/builtinLibs.json(default 字段:enabled 默认启用、
disabled 默认禁用但可在设置里开启);新增内置包的步骤见
docs/data-notes/builtinLibs.md。
caclib/ 不参与 App 构建——它是作者 在线拓展包源(clib)的工程仓库,通过
git subtree 同步进来,由 cabuildtools/lib/clibspawn.mjs 打包成 SIGNLIB01 发布到源站
(对应 pages/clib/ 的那套结构)。两者不要混:
把 caclib 的库内嵌成内置包会导致同一份内容在列表里出现两次。
data/idlibs 里除了命令库,还有 schema_v1.json(库格式的 JSON Schema)和
JSONSchema.json(内置的 rawtext schema,供 jsonPro 参数补全)。
cabuildtools/cli/libtool.mjs 提供三条命令,js / json 与 .lib 之间互转:
# json 或 js → .lib(默认 LIBRARY 锁定包)
npm run pack -- 我的库.json # 生成 我的库.lib
npm run pack -- 插件.js -o 输出.lib
# 打成分发格式(SIGNLIB01),需要私钥
npm run pack -- 我的库.json --sign signatures/keys/testkey_private.pem
# 输入已经是 .lib 也行:解出内容再按目标格式重打(可用来补签名)
npm run pack -- 旧包.lib --sign 私钥.pem -o 新包.lib
# .lib → js / json(自动识别 LIBRARY / SIGNLIB01 / LIBSIGN01)
npm run unpack -- 我的库.lib # JSON 内容输出 .json(格式化),否则 .js
npm run unpack -- 已签名.lib --key 公钥.pem # 顺带验签,失败退出码 2
# 只看容器信息
npm run info -- 我的库.lib内容会先做合法性检查:JSON 必须能解析,JS 必须能作为表达式求值。
pack 输入本身就是 .lib 时会先解出内容再按目标格式重打(可用来补签名);
不带 -o 时输出与输入同名,会覆盖原文件(会有提示)。
info 会打印容器格式、时间戳、库名/uuid/版本/作者;unpack --key 对签名容器
验签,失败退出码 2;对没有签名的 LIBRARY 容器会提示"跳过验签"。
pack/unpack 一个命令同时支持单文件、纯文件名和工作区批量:
| 目标写法 | 行为 |
|---|---|
| 不给目标 | 批量:工作区 src/ → build/libwork/pack/,lib/ → build/libwork/unpack/(批量模式不参与密钥) |
| 纯文件名(无路径) | 只在工作区对应目录找(pack→src/,unpack/info→lib/);可省略后缀,会自动匹配并提示选中的文件 |
| 带路径的文件 | 对指定文件操作;可省略后缀(提示后处理) |
| 带路径的文件夹 | 只处理里面的 .json/.js(pack)或 .lib(unpack) |
密钥规则:
| 写法 | pack(--sign) |
unpack / info(--key) |
|---|---|---|
| 不给 | 不加密(LIBRARY) | 遍历工作区 keys/ 尝试匹配签名 |
| 纯文件名 | 只在工作区 keys/ 里找,需要完整文件名(含后缀) |
同左 |
| 带路径文件 | 用指定密钥文件 | 用指定密钥文件(验签失败退出码 2) |
| 带路径文件夹 | 不支持 | 先遍历工作区 keys/,再遍历该目录 |
info 只接受单个文件:非签名包直接输出基础信息;签名包按上面的密钥规则验签。
# 工作区批量
npm run pack # libwork/src → build/libwork/pack
npm run pack -- /path/to/folder --sign testkey_private.pem
npm run unpack # libwork/lib → build/libwork/unpack
npm run unpack -- /path/to/folder --key /path/to/keys
# 工作区文件名(可省略后缀)
npm run pack -- foo
npm run unpack -- foo.lib
npm run info -- foo.lib
# 指定文件 / 路径(可省略后缀)
npm run pack -- libwork/src/foo.json --sign /abs/testkey_private.pem
npm run unpack -- build/libwork/pack/foo.lib -o build/libwork/unpack目录约定见 libwork/README.md。目录模式下批量失败会继续处理
其他文件并汇总退出码:一般失败 1,验签失败 2。
命令库有三种容器,01 是格式版本号:
| 魔数 | 生成工具 | 用途 |
|---|---|---|
LIBRARY |
js2lib.js |
锁定包(社区俗称「加密包」),安装器 lib 也用这个格式 |
SIGNLIB01 |
js2signlib.js |
分发(源站/商店下载),9 字节魔数 + 256 字节 RSA 签名 + 8 字节时间戳 + gzip 载荷 |
LIBSIGN01 |
App 下载时 / js2localib.js |
本地已验签库,9 字节魔数 + int32 sourceId 长度 + sourceId + SIGNLIB01 的 [9..] |
术语:社区里把
LIBRARY格式的包统称「锁定包」(后来又叫「加密包」)。 它并不加密,只是 App 用LIBRARY前缀识别、并把它标成「锁定」;列表里[锁定]那行小字是包作者自己写的说明,不是 App 生成的结论,别把它当成安全背书。
# 分发格式
node ./cabuildtools/lib/js2signlib.mjs <源码.js> <私钥.pem> <输出.lib>
# 本地格式(源站 uuid + App 公钥,公钥在 cadroid 的 Secret.HOTFIX_PUBLIC_KEY)
node ./cabuildtools/cli/js2localib.mjs <输入.lib> <源站uuid> <输出.lib> [app公钥]
签名私钥必须是 RSA 2048 位(App 里验签段长度写死 256 字节)。LIBSIGN01 旁边的 .hash
是 SHA1(appVerifyKey || SHA1(payload)),用 App 内置的公钥算——所以只有 App(或掌握其公钥的
本地流程)能产出合法 .hash。SIGNLIB01 只在下载路径里验签;直接拷贝进手机的 SIGNLIB01
会被当成未知格式,需要先转成 LIBSIGN01。
拓展包的「检测更新」和「在线拓展包」都支持多个源。入口:设置 → 智能补全 → 拓展包源, 打开独立的「管理拓展包源」页面(左上角标题、右上角 ▼)。
- 命令助手官方拓展包源默认存在,列表里带
[官方]前缀,不能禁用或删除; 给它加备注后,备注会当标题显示,原名以小字「原名:命令助手官方拓展包源」放在下面 - 添加源:右上角 ▼ →「添加拓展包源」,填源站根目录(或它的
info.json地址)。 读info.json是网络请求,走后台线程;失败会把输入回填到输入框 - 源显示名:
info.json的name→maintainer→details→ 地址。name是可选字段(官方源没有),源端声明了就用它;早期添加的源在下次 读取info.json时会自动同步过来 - 点按源:备注 / 禁用 / 删除(官方源只有备注)
- 源不再出现在「管理拓展包」列表里——源不是拓展包
- 配置存在
CA.settings.librarySources,源对象为{url, name, enabled, note, builtin}, 增删改都会立刻CA.trySave()(否则进程被系统杀掉后新加的源会丢失)
检查更新时(requestUpdateUrlFromDefSrc)按顺序遍历启用中的源,第一个给出该 uuid 更新地址的源
胜出;源内部仍然校验 sourceId、SHA-1 与 RSA 签名。
「在线拓展包」会汇总所有启用中的源,同一个 uuid 只显示版本最高的那个,下载时用该条目 所属的源验签。
签名包按验签用的公钥分两级,显示在「管理拓展包」列表里:
| 标记 | 判定方式 |
|---|---|
[官方] |
用官方源(builtin: true 的那个源)的公钥验签通过 |
[社区] |
用第三方源自己的公钥验签通过;下载时会在包旁边写一个 .community 标记 |
[内置] |
builtin:// 内置库 |
[锁定] |
LIBRARY 前缀格式,即锁定包(社区叫加密包) |
安全级别共五档(0–4),决定什么类型的包能被加载:
| 值 | 名称 | 允许加载 | 拒绝 |
|---|---|---|---|
| 0 | 禁用 | 全部:内置 / 官方签名 / 社区签名 / 锁定包 / 未打包的 .js/.json |
—(没有任何检查) |
| 1 | 低 | 签名包 + 锁定包(LIBRARY,没有签名也加载,会提示一次) |
未打包的 .js/.json |
| 2 | 中(默认,推荐) | 只加载签名包(官方 + 社区) | 锁定包、未打包的 .js/.json |
| 3 | 高 | 只加载官方签名 | 社区签名、锁定包、未打包的 .js/.json |
| 4 | 严格 | 只加载内置库 | 所有外部拓展包 |
切换时的确认框只在放宽级别(数字变小)时弹出——从低往高收紧是安全操作, 直接生效;从高往低放宽会提示会额外接受哪类包。
编辑 / 锁定 / 创建副本 / 新建拓展包这些开发操作只有「禁用」级别(值 0)才可见,而且编辑器只能处理 JSON 格式的包(JSON.parse 失败会直接提示)。
已移除原先"从 GitHub 自动下载远程拓展包"的机制(
modules/RemoteLibrary.js与libraries.json)。
本项目在开发过程中使用或参考了以下开源项目,感谢作者与贡献者:
- MyAgent — WebSocket Agent 服务端实现,以 git subtree 方式集成
- PEWS-API — Minecraft WebSocket 协议 SDK,WSServer 协议层参考上游实现
- Java-WebSocket — cadroid 侧的 WebSocket 传输层
- Rhino — Android 脚本引擎
- quickjs-kt — Android QuickJS 绑定,侧载加速 worker(Apache-2.0)