运行环境与安全红线
宿主 Python 版本、预置库、私有依赖怎么带、绝对不能做什么。
运行环境
| 项 | 事实 |
|---|---|
| Python | 宿主 3.11 – 3.12 |
| 宿主预置核心库 | numpy、PySide6（含 QtWebSockets 等全套）、torch、transformers、sounddevice、requests、httpx |
| 沙箱 | 无 —— 插件与主程序同权限 |
| 运行时 pip | 严禁 |
私有依赖：libs/ 与 vendor/
如果依赖宿主未包含的轻量 Python 库（opencc、deepl、openai、jieba…）， 严禁在运行时调用 pip。标准做法：
在插件源码根目录创建
libs/或vendor/：bashpip install <package_name> -t ./libs依赖目录随 MOD 打包发布。
宿主
PluginRegistry加载插件时自动探测并把插件目录/libs与插件目录/vendor注入sys.path，插件内部及其子线程可直接import。插件卸载时宿主自动从
sys.path移除这些路径，保持全局环境纯净。
禁止事项
| 禁止 | 原因 |
|---|---|
os.system("pip install …") / subprocess 装包 | 污染用户环境、静默失败、无版本控制 |
| 私自上传麦克风 / 字幕 / 历史数据 | 隐私红线 |
| 修改主程序全局配置 / 其它插件配置 | 越权；只读写 plugins_config/<本插件 id> 与 plugin_data/<本插件 id> |
| 木马 / 挖矿 / 未授权的后台行为 | 直接封禁 |
改主程序核心词库（src/transbox/ui/locales/*.json） | 用插件自带 locales/ 增量覆盖 |
把二进制/权重放进 data/models/ | 那是纯权重目录，用户点「清除缓存」会误伤 |
把几十 MB 二进制打进 .tbmod | 上传通道 20 MB 上限 |
网络
- 只访问自己声明的 API / 模型源。
- 建议在
permissions里声明用到的能力：
json
"permissions": ["net", "clipboard", "hotkey", "window"]| 值 | 含义 |
|---|---|
net | 访问网络 |
clipboard | 读写剪贴板 |
hotkey | 注册全局热键 |
window | 创建窗口 / 修改窗口属性 |
permissions 目前用于工坊展示与审计（未来可能做门禁）——声明了不代表自动放行， 但不声明会被视为隐瞒。
凭据处理
- 让用户在
config_schema里填（"type": "password", "is_secret": true）， 不要硬编码私钥、个人路径、开发者机器的绝对路径。 - Key 存进插件配置即可（宿主按插件隔离）；不要把 Key 写进日志或
emit_event的 payload。
数据存放
| 内容 | 位置 |
|---|---|
| 配置 | plugins_config/<plugin_id>（宿主管理） |
| 小状态 | host.get_plugin_kv() |
| 缓存 / 文件 / 参考音频 | self.get_data_dir() → <安装目录>/data/plugins/<plugin_id>/ |
| 模型权重 | 由宿主管理（model_artifacts） |
见 配置与私有数据。
安全等级说明
数据类插件（theme / glossary / i18n）相对更安全；脚本类插件（Python）请用户自担风险。 平台对 script 类做人工审核，对 data 类与信任作者可自动上架。
核心团队保留规范演进与上下架的权利。
相关
- 打包与体积上限
- 发布渠道
- 配置与私有数据
- 目录结构与 mod.json —
permissions字段