# Mint Manifest 编写指南
## 概述
Manifest 是 Mint 运行时环境的配置文件，用于定义应用程序的元数据、权限和安全策略。本指南将帮助您正确编写 manifest 文件。
## 文件位置
Manifest 文件通常位于应用包的根目录下，命名为 `manifest.ron`。
根据项目代码中的 `Dandelion::autofill()` 函数 (src/config.rs:89-100),manifest 的路径为：
```
{pkg_path}/manifest.ron
```
## 文件结构
Manifest 使用 RON (Rusty Object Notation) 格式，主要包含两个部分：**只读配置 (entity_ro)** 和 **用户自定义配置 (entity_usr)**。
### 1. 只读配置 (entity_ro)
这是应用程序的核心配置，由应用开发者预先定义：
```ron
(
nickname: "应用名称", // 进程显示名称，用于标识服务
entire_id: "auto.swe.timekeeper", // 完整应用 ID，示例：auto.swe.timekeeper，测试运行可以留空
// 基础权限控制
basic_authority: { // SAuthBasicCtrl 类型
// 权限配置见下文"权限配置详解"
},
runtime_permission: Default, // 运行权限：Default 或 Su，测试运行可以留空
thinker_script: "/path/to/script.lua", // 主脚本路径（绝对路径）
executor_script_or_compiled: "/path/to/", // 执行器脚本或编译后的字节码，文件名只能为executor.wing
// 模块访问配置
native_access_no_suffix: [ // Lua dll/so模块（无后缀）
"module1",
"module2",
],
lua_access_no_suffix: [ // Lua .lua模块（无后缀）
"custom_lib1",
"custom_lib2",
],
pkg_path: "/path/to/package", // 无需手动填写
// 详细访问控制 - 命令白名单
command_allow: { // SDetailedAccessAllow 类型
"execute": ["cmd1", "cmd2"],
"popen": ["command1", "command2"],
},
// 详细访问控制 - 文件访问白名单，所有涉及文件访问的io api
file_access_allow: { // SDetailedAccessAllow 类型
"open": ["/allowed/path1", "/allowed/path2"],
"read": ["/readable/path"],
"write": ["/writable/path"],
},
)
```
### 2. 用户自定义配置 (entity_usr)
这是运行时由启动器或用户提供的配置：
```ron
(
flags: ["arg1", "arg2"], // 传递给 Lua 环境的命令行参数
customize_authority: { // 自定义权限覆盖
// 可覆盖 basic_authority 中的设置
},
command_allow_extra: { // 额外命令白名单
"execute": ["extra_cmd"],
},
file_access_allow_extra: { // 额外文件访问白名单
"open": ["/extra/path"],
},
)
```
## 权限配置详解
### Permission 枚举类型
Mint 定义了详细的权限类型来控制 Lua API 的访问 (src/security/mod.rs:36-83):
#### 致命风险 (Critical) - 默认禁用
**Global 模块:**
- `Dofile` - 执行任意 Lua 文件
- `Load` - 将字符串加载为函数
- `Loadfile` - 从文件加载函数
- `Require` - 加载任意模块
**OS 模块:**
- `OsExecute` - 执行系统命令
- `OsExit` - 终止进程
- `OsGetenv` - 获取环境变量
- `OsRemove` - 删除文件
- `OsRename` - 重命名文件
- `OsSetenv` - 设置环境变量
**IO 模块:**
- `IoOpen` - 打开任意文件
- `IoRead` - 读取文件内容
- `IoWrite` - 写入文件内容
- `IoPopen` - 打开系统进程
**Debug 模块:**
- `DebugGetinfo` - 获取函数信息
- `DebugGetlocal` - 获取局部变量
- `DebugGetmetatable` - 获取元表
- `DebugGetregistry` - 获取注册表
- `DebugGetupvalue` - 获取闭包上值
- `DebugGetuservalue` - 获取用户值
- `DebugSethook` - 设置钩子
- `DebugSetlocal` - 设置局部变量
- `DebugSetupvalue` - 设置闭包上值
- `DebugSetuservalue` - 设置用户值
**Package 模块:**
- `PackageLoadlib` - 加载动态库
#### 高风险 (High) - 默认禁用
- `PackagePath` - 模块路径
- `PackageLoaded` - 已加载模块
- `PackagePreload` - 预加载模块
- `PackageSearchpath` - 搜索模块路径
#### 中等风险 (Medium) - 默认启用但受限
- `MathRandom` - 随机数生成
- `MathRandomseed` - 随机数种子
- `StringDump` - 生成字节码
### 权限配置示例
```ron
basic_authority: {
// 致命风险 - 明确禁用
Dofile: false,
Load: false,
Loadfile: false,
Require: false,
OsExecute: false,
OsExit: false,
IoOpen: false,
// 根据需要启用的权限
MathRandom: true,
MathRandomseed: true,
}
```
## 完整示例
### 示例 1: 简单的沙箱应用
```ron
// manifest.ron
(
nickname: "SandboxApp",
entire_id: "com.example.sandbox",
basic_authority: {
MathRandom: true,
MathRandomseed: true,
// 其他所有危险权限默认禁用
},
runtime_permission: Default,
thinker_script: "C:/apps/sandbox/main.lua",
executor_script_or_compiled: "C:/apps/sandbox/executor.wing",
native_access_no_suffix: [],
lua_access_no_suffix: ["utils", "helpers"],
pkg_path: "C:/apps/sandbox",
command_allow: {},
file_access_allow: {},
)
```
### 示例 2: 需要文件访问的应用
```ron
// manifest.ron
(
nickname: "FileProcessor",
entire_id: "com.example.fileproc",
basic_authority: {
MathRandom: true,
IoOpen: true, // 需要文件访问
IoRead: true,
IoWrite: true,
},
runtime_permission: Default,
thinker_script: "C:/apps/fileproc/process.lua",
executor_script_or_compiled: "C:/apps/fileproc/executor.wing",
native_access_no_suffix: ["io", "os"],
lua_access_no_suffix: ["file_utils"],
pkg_path: "C:/apps/fileproc",
command_allow: {
"execute": ["dir", "copy"],
},
file_access_allow: {
"open": ["C:/apps/fileproc/data/"],
"read": ["C:/apps/fileproc/input/"],
"write": ["C:/apps/fileproc/output/"],
},
)
```
### 示例 3: 用户自定义配置
```ron
// 启动时传入的用户配置
(
flags: ["--verbose", "--output=result.txt"],
customize_authority: {
// 临时启用某个权限
OsExecute: true,
},
command_allow_extra: {
"execute": ["custom_command"],
},
file_access_allow_extra: {
"write": ["C:/temp/"],
},
)
```
## 安全注意事项
1. **最小权限原则**: 只授予应用所需的最小权限集
2. **路径限制**: 文件访问应限制在特定目录内
3. **命令白名单**: 系统命令执行必须明确指定允许的命令
4. **日志记录**: 所有权限使用都会被记录到日志中
## 验证 Manifest
在运行应用前，请确保：
1. ✅ 所有路径都是绝对路径且存在
2. ✅ 权限配置符合安全要求
3. ✅ 模块列表中的模块确实存在
4. ✅ RON 语法正确（可使用 RON 验证工具）
## 相关源代码
- 配置结构定义：`src/config.rs` (34-67 行)
- 权限类型定义：`src/security/mod.rs` (36-283 行)
- 默认安全配置：`src/security/mod.rs` (300-346 行)
- 蒲公英路径生成：`src/config.rs` (89-100 行)
## 常见问题
### Q: 如何调试 manifest 问题？
A: 启动时会输出详细的错误信息，包括：
- 参数解析失败
- 路径不存在
- 权限配置错误
### Q: 可以动态修改权限吗？
A: 不可以。权限在启动时确定，运行时不可更改。这是为了确保安全性。
### Q: 如何添加自定义模块？
A: 在 `lua_access_no_suffix` 中添加模块名，并确保模块文件位于 `pkg_path/lext/` 目录下。
---
**许可证**: MPL-2.0 (非商业用途) / Commercial License (商业用途)
**作者**: SASWE
**最后更新**: 2026-03-24
---
## 授权说明
本项目采用双授权模式：
- **非商业用途**：遵循 MPL-2.0 许可证
- **商业用途**：需要单独的商业授权许可，请联系作者 SALflake@aliyun.com