模块 API 参考

全部签名的速查页。用法详解见各指南页。

生命周期钩子

python

def setup(self, ctx): ...      # 加载后一次：注册处理器、订阅事件
def on_enable(self): ...       # 每次启用：启动线程、开始推送
def on_disable(self): ...      # 每次停用：停线程、清推送
def on_unload(self): ...       # 卸载/替换前：最终清理

ctx

python

# 属性
ctx.name          # str，模块名
ctx.manifest      # 清单对象
ctx.log           # 日志器：debug / info / warning / error
ctx.config        # dict，只读，manifest.config 与平台方覆盖合并
ctx.store         # 存储门面，见下

# RPC
ctx.register_handler(method: str, fn: Callable)
ctx.handler(method: str)                                  # 装饰器写法
ctx.call(target: str, method: str, *args,
         timeout: float = 10.0, **kwargs) -> Any          # 同步，超时抛异常

# 事件
ctx.publish(topic: str, payload=None)                     # 异步广播
ctx.subscribe(topic: str, fn) -> Callable                 # fn(payload, source)，返回退订函数

# 外壳推送（整覆盖语义）
ctx.set_card(payload)             # dict / list / 标量；None 清除
ctx.push_fields(fields: dict)     # {} 清除
ctx.push_titlebar(items: dict)    # 普通字段 + 保留键 _buttons；{} 清除

_buttons 项格式：

python

{"label": "同步", "rpc": {"module": "m", "method": "sync",
                          "args": [], "kwargs": {}}}

ctx.store

python

# KV
store.get(key, default=None) -> Any
store.set(key, value)
store.set_many(mapping: dict)
store.get_many(prefix="") -> dict
store.delete(key) -> bool
store.keys(prefix="") -> list
store.size() -> int
store.exists() -> bool

# SQL
store.query(sql, params=()) -> list[dict]     # 只读：SELECT / PRAGMA / EXPLAIN
store.execute(sql, params=()) -> int          # 写，自动提交，返回受影响行数
with store.transaction(): ...                 # 块内多次写合并一次落盘，异常回滚

store.wipe()          # 清空全部数据，不可恢复
store.close()         # 宿主在卸载/退出时调用，一般不手动调

前端 jade（模块页面内）

javascript

await jade.call(module, method, ...args);   // Promise，失败 reject，固定 10s 超时
const off = jade.on(topic, (payload, source) => { ... });
off();                                       // 取消订阅

引入方式：

html

<script src="/jade-bridge.js"></script>

宿主注入的原生能力（如 jade.dialog）不会被 SDK 覆盖。

异常速查

异常	含义	处理
`ModuleNotCallable`	目标模块未启用/不存在	启用目标模块或声明依赖
`MethodNotFound`	目标模块没注册这个方法	检查方法名与注册位置（setup 里）
`PermissionError`	权限不足（未声明依赖或权限）	补 `dependencies` / `permissions`
`ManifestError`	manifest 字段非法	按 manifest 校验规则修正
`ModuleLoadError`	找不到/多个入口类、缺文件	检查入口文件与 `MODULE` 声明
`KernelError`	依赖成环等内核级错误	检查模块间依赖关系
存储类异常	语句类型不匹配、数据异常	检查 `query`/`execute` 用法与 SQL

manifest 速查

json

{
  "name": "my_module",            // 必填 ^[a-z][a-z0-9_]{1,63}$
  "display_name": "显示名",        // 可选，外壳展示用，可含中文
  "version": "1.0.0",             // 必填 x.y.z
  "entry": "main",                // 入口文件名（不含 .py）
  "author": "",
  "description": "",
  "ui": "ui/index.html",          // 默认页面；ui/ 下其余 HTML 自动注册
  "dependencies": [],
  "permissions": [],              // fs / net / process / native / eval
  "config": {},
  "homepage": "",
  "license": ""
}