权限与版本兼容
理解能力声明、路径授权与需要升级宿主的边界。
本页目录
权限声明不是权限授予#
当前清单支持 fs、ai、codemirror、workspace、state、ipc。这些字段用于描述和校验能力需求，不是独立的完整安全沙箱，也不自动开放任意系统能力。
接口是否存在看 preload，操作是否允许看主进程的实际检查。开发时要同时理解这两个层次。
路径授权属于实际上下文#
用户选择的材料、当前项目登记的文件和允许的输出位置各有用途。一个组件窗口的路径授权，不应被另一个窗口简单复制使用。
| 行为 | 正确处理 |
|---|---|
| 读取登记的项目材料 | 核对格式，按需要读取；处理失败返回 |
| 用户选择另存为位置 | 使用目标宿主真实支持的选择流程，再执行写入 |
| 修改只读输入原件 | 保存工作副本，不关闭只读检查 |
| 组件升级 | 保留用户项目、历史和允许迁移的数据 |
| 需要新系统能力 | 提出并实现主进程、preload 与组件的完整契约 |
渲染层传 trusted: true 不会取得授权。不要尝试修改宿主源码目录、安装包或其他组件内容来消除权限错误。
版本兼容怎么声明#
组件清单有自己的 version、接口 apiVersion 以及宿主版本边界。上线前建立一份矩阵：
| 组合 | 必须确认 |
|---|---|
| 最低支持宿主 + 新组件 | 所需接口、资源、错误提示均可用 |
| 当前宿主 + 新组件 | 完整正常流程通过 |
| 旧宿主 + 不兼容组件 | 能明确拒绝，不停在空白窗口 |
| 旧项目 + 新组件 | 输入、成果和状态迁移可用 |
| 正式宿主 + 开发源码 | 不把开发便利当成生产导入能力 |
来源与类别的差别#
开发源码扫描会按目录来源处理 builtin 和 thirdparty。第三方目录默认不启用，正式打包环境还会验证安装内容。不要通过改清单的 type 声明跨越来源约束。
task 与 tool 决定类别和对应发行格式。正式组件的签名描述还包含身份、内容摘要和范围，不能通过改扩展名改变其含义。
当前事件接口的清理约定#
onExtensionAlreadyOpen(callback) 返回移除本次监听的函数。onExtensionCloseRequest 等旧接口可能替换原监听且不返回取消函数；不能套用一个未经核对的通用订阅封装。
组件只清理自己拥有的资源。为了修复重复事件去移除宿主全部监听，会引入其他功能失效。
什么时候必须更新宿主#
已有接口之上的表单、模板、资源和业务流程可以作为组件更新。涉及原生模块、新 IPC、后台运行机制或新的窗口授权时，需要配套宿主版本，不能单发插件承诺旧宿主自动获得能力。
兼容说明应写给用户看：最低版本是什么，需要升级什么，哪些已有项目保持可用。不要把内部实现编号当作公开版本号。