## 权限声明不是权限授予

当前清单支持 `fs`、`ai`、`codemirror`、`workspace`、`state`、`ipc`。这些字段用于描述和校验能力需求，不是独立的完整安全沙箱，也不自动开放任意系统能力。

接口是否存在看 preload，操作是否允许看主进程的实际检查。开发时要同时理解这两个层次。

## 路径授权属于实际上下文

用户选择的材料、当前项目登记的文件和允许的输出位置各有用途。一个组件窗口的路径授权，不应被另一个窗口简单复制使用。

| 行为 | 正确处理 |
| --- | --- |
| 读取登记的项目材料 | 核对格式，按需要读取；处理失败返回 |
| 用户选择另存为位置 | 使用目标宿主真实支持的选择流程，再执行写入 |
| 修改只读输入原件 | 保存工作副本，不关闭只读检查 |
| 组件升级 | 保留用户项目、历史和允许迁移的数据 |
| 需要新系统能力 | 提出并实现主进程、preload 与组件的完整契约 |

渲染层传 `trusted: true` 不会取得授权。不要尝试修改宿主源码目录、安装包或其他组件内容来消除权限错误。

## 版本兼容怎么声明

组件清单有自己的 `version`、接口 `apiVersion` 以及宿主版本边界。上线前建立一份矩阵：

| 组合 | 必须确认 |
| --- | --- |
| 最低支持宿主 + 新组件 | 所需接口、资源、错误提示均可用 |
| 当前宿主 + 新组件 | 完整正常流程通过 |
| 旧宿主 + 不兼容组件 | 能明确拒绝，不停在空白窗口 |
| 旧项目 + 新组件 | 输入、成果和状态迁移可用 |
| 正式宿主 + 开发源码 | 不把开发便利当成生产导入能力 |

## 来源与类别的差别

开发源码扫描会按目录来源处理 builtin 和 thirdparty。第三方目录默认不启用，正式打包环境还会验证安装内容。不要通过改清单的 type 声明跨越来源约束。

`task` 与 `tool` 决定类别和对应发行格式。正式组件的签名描述还包含身份、内容摘要和范围，不能通过改扩展名改变其含义。

## 当前事件接口的清理约定

`onExtensionAlreadyOpen(callback)` 返回移除本次监听的函数。`onExtensionCloseRequest` 等旧接口可能替换原监听且不返回取消函数；不能套用一个未经核对的通用订阅封装。

组件只清理自己拥有的资源。为了修复重复事件去移除宿主全部监听，会引入其他功能失效。

## 什么时候必须更新宿主

已有接口之上的表单、模板、资源和业务流程可以作为组件更新。涉及原生模块、新 IPC、后台运行机制或新的窗口授权时，需要配套宿主版本，不能单发插件承诺旧宿主自动获得能力。

兼容说明应写给用户看：最低版本是什么，需要升级什么，哪些已有项目保持可用。不要把内部实现编号当作公开版本号。