打包与交付

两种交付形式

形式	产物	适用
源码交付	模块目录（含 `manifest.json`）	内部模块、开源模块、需要平台方审核源码的场景
加密交付	单个 `.jmod` 文件	商业分发、需要保护源码的场景

两种方式宿主都能直接加载，模块代码不需要为加密做任何改动。

生成 .jmod

bash

python tools/encrypt_module.py encrypt \
    --in modules/my_module \
    --out modules/my_module.jmod \
    --key-id dev-alice

--key-id 由平台方分配（密钥文件由平台方发放）。自用调试用 --key-id default。
打包后源码目录可以保留，不影响运行。

什么会被打进 .jmod

内容	是否打包
所有 `.py` 文件（含子目录）	✅
`ui/` 下的文件（含多页面 HTML）	✅
`assets/` 下的文件	✅
`manifest.json`	✅（作为元信息，不重复存）
`__pycache__`、`.pyc`、`.pyo`	❌
其他目录（`tests/`、`docs/`、临时文件）	❌

结论：模块要用的东西只能放在 .py、ui/、assets/ 里，放别处加密交付后会丢。

交付前自检

bash

python tools/encrypt_module.py inspect --in modules/my_module.jmod

只输出元信息（模块名、版本、权限、打包时间、完整性校验值、包体大小），不会还原源码。可以放心把输出贴给平台方当审核材料。建议每次交付前跑一次。

多文件模块

text

my_module/
├── manifest.json
├── main.py             # 入口（entry 指定）
├── core/
│   ├── __init__.py
│   ├── parser.py       # 可被 main.py 导入
│   └── client.py
├── ui/
│   ├── index.html
│   └── app.js
└── assets/
    └── icon.png

多个 .py 打成一个包后，模块内 import core.parser 照常工作，不用额外配置。交付后用户机器上不会留下源码文件。

第三方 Python 依赖

优先只用标准库；
确需第三方包，把纯 Python 的包源码放进模块目录（如 vendor/ 下的 .py）随包分发，入口文件里把该目录加进 sys.path 再导入；
含 C 扩展的包（.pyd/.so）无法保证在用户机器上可用，提前和平台方确认。

安装到宿主

把模块目录或 .jmod 文件放进宿主的 modules/ 目录，重启宿主即可。同名模块的源码目录与 .jmod 并存时，以 .jmod 为准。

版本升级

递增 manifest.json 的 version（x.y.z 语义化：修复补丁 z、新增功能 y、不兼容变更 x）；
重新打包；
替换宿主 modules/ 下的产物并重启；
升级不清除持久化数据。数据结构变了自己做迁移（见持久化存储）；
保留上一版 .jmod，出问题直接替换回去。

交付物清单

模块目录或 .jmod，外加一段说明：功能、所需权限及理由、所需配置、外部依赖（adb 这类外部可执行文件不算模块的一部分，需宿主环境提供或单独约定）。