manifest 清单

manifest.json 是模块的身份证，宿主靠它识别模块、管理依赖和权限。字段校验不通过时整个模块被跳过，并在宿主日志里记录原因。

字段表

字段	类型	必填	默认值	说明
`name`	string	✅	—	模块唯一标识，须匹配 `^[a-z][a-z0-9_]{1,63}$`（小写字母开头，2–64 字符）
`display_name`	string	❌	取 `name`	中文显示名，外壳界面展示用。仅作显示，依赖声明与路由仍用 `name`
`version`	string	✅	—	语义化版本 `x.y.z`，如 `1.0.0`
`entry`	string	❌	`"main"`	入口文件名（不含 `.py`），须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`
`author`	string	❌	`""`	作者
`description`	string	❌	`""`	一句话描述（显示在外壳卡片与模块列表）
`ui`	string	❌	`""`	模块默认页面相对路径，如 `"ui/index.html"`。`ui/` 目录下其余 HTML 也会自动注册为可打开页面（见界面开发）
`dependencies`	string[]	❌	`[]`	依赖的其他模块名；启用前会被自动启用
`permissions`	string[]	❌	`[]`	权限声明：`fs` / `net` / `process` / `native` / `eval`
`config`	object	❌	`{}`	模块默认配置，平台方可覆盖
`homepage`	string	❌	`""`	主页
`license`	string	❌	`""`	许可证

关于 display_name

name 有格式限制，写不了中文。想在外壳界面显示中文名，加 display_name：

json

{
  "name": "adb_monitor",
  "display_name": "手机状态监测",
  "version": "1.0.0"
}

外壳左侧栏、卡片区会优先显示 display_name，没写就回退到 name。目录名可以随显示名走（比如 modules/手机状态监测/），不影响加载——宿主认的是 manifest 里的 name。

校验规则

违反任何一条，模块被跳过并在宿主日志里记录错误：

未知字段直接拒绝。只允许上表中的字段，多一个就报 manifest 含未知字段。
模块名必须匹配 ^[a-z][a-z0-9_]{1,63}$；版本号必须是 x.y.z。
dependencies 与 permissions 必须是字符串数组，config 必须是对象。
不能依赖自身（name 不允许出现在 dependencies 中）。
依赖成环时，模块加载阶段报 KernelError: 模块依赖存在循环。

完整示例

json

{
  "name": "adb_monitor",
  "display_name": "手机状态监测",
  "version": "1.0.0",
  "entry": "main",
  "author": "your_name",
  "description": "ADB/Fastboot 手机状态实时监测",
  "permissions": ["process", "fs"],
  "ui": "ui/index.html",
  "config": {
    "interval": 2.0,
    "adb_path": "platform-tools/adb.exe"
  }
}

config 里的值通过 ctx.config 读取；平台方可以覆盖同名配置项，模块代码不用改。

权限怎么填

用到才声明，五种权限的覆盖范围见权限与审核。上面的例子调 adb 外部命令所以要 process，读本地文件所以要 fs。宿主运行在严格安全模式下时 fs 基本是必需的（Python 导入模块本身就要读文件，没声明会被拦下，报 未声明权限 'fs'，已拦截 open）。