流星雨模块框架文档中心

快速上手

写一个能跑的模块，前后大概五分钟。完整要求见 manifest 清单 和 生命周期。

开始前的准备

项目要求
Python3.10+（与宿主运行环境一致即可）
系统宿主跑在 Windows 上；模块本身是纯 Python，在任意系统写都行
依赖模块尽量只用标准库。确需第三方包，随模块目录一起打包（见 打包与交付）
运行前提模块不能独立运行，必须由宿主加载。本地验证需要一份宿主运行环境（向平台方索取）

模块开发只需要做三件事：写一个 manifest.json，写一个继承 JadeModule 的入口文件，把目录交给宿主（或自行加密成 .jmod）。

所有跨模块行为、持久化、界面推送都走 ctx 这一个对象，宿主内部怎么实现的不用管。

1. 目录结构

text
modules/
└── my_module/                 # 目录名建议与模块名一致
    ├── manifest.json          # 必需：模块清单
    ├── main.py                # 必需：入口文件（文件名由 entry 指定，默认 main）
    └── ui/
        └── index.html         # 可选：模块自带 Web 页面

把 my_module/ 整个放进宿主的 modules/ 目录就能被扫描到。加密模块是单个文件 modules/my_module.jmod，与源码目录同在 modules/ 下时加密版本优先。

2. manifest.json

json
{
  "name": "my_module",
  "version": "1.0.0",
  "entry": "main",
  "author": "your_name",
  "description": "一句话说明这个模块做什么",
  "permissions": [],
  "config": {}
}

字段含义见 manifest 清单。

3. 入口文件 main.py

python
"""my_module — 我的第一个模块"""
from jade_framework import JadeModule


class MyModule(JadeModule):
    name = "my_module"       # 可省略，默认取 manifest.name
    version = "1.0.0"        # 可省略，默认取 manifest.version

    def setup(self, ctx):
        """加载后调用一次：注册处理器、订阅事件。"""
        ctx.register_handler("hello", self._hello)

    def on_enable(self):
        self.ctx.log.info("my_module 已启用")

    def on_disable(self):
        self.ctx.log.info("my_module 已停用")

    # ---- 业务方法 ----
    def _hello(self, who: str = "world") -> str:
        return f"Hello, {who}!"


MODULE = MyModule   # 推荐显式指定入口类

4. 怎么验证

模块由宿主加载，不能像普通脚本那样直接运行，它依赖宿主注入的 ctx。

  1. 把 my_module/ 整个放进宿主的 modules/ 目录；
  2. 按平台方提供的方式启动宿主；
  3. 在外壳左侧模块列表里找到你的模块，打开开关（启用）；
  4. 打开页面点一下，确认能拿到返回值；右侧日志栏能看到 ctx.log 的输出。

还没拿到宿主环境的时候，先把纯逻辑（解析、计算、格式化）写成不依赖 ctx 的函数，用普通 Python 脚本先测这部分。能提前挡掉大部分 bug。

5. 从别处调用它

python
# 其他模块中
ctx.call("my_module", "hello", "小明")
javascript
// 模块页面（前端）中
const text = await jade.call("my_module", "hello", "小明");

下一步