# 插件开发概览
> 理解 Astravia 插件的运行方式、能力出口和信任边界。
Canonical page: /plugins/overview
插件跑在桌面渲染进程里，不是沙箱 iframe
权限要经过声明、安装授权和运行时校验
先确认它真的需要做成插件
Astravia 插件用于扩展桌面客户端的界面、文件浏览器、对话和 Agent 能力。插件通过 `@astravia-org/plugin-sdk` 获取宿主提供的策展能力出口。
插件可以把领域工具和可交互产物放进 Astravia 工作区，但必须经过清单声明和宿主授权。
## 运行模型 [#运行模型]
插件使用 React、TypeScript 和 Vite 开发。
生产产物通过 Module Federation 加载，清单不提供其它加载方式。
React、React DOM 和插件 SDK 由宿主以共享单例提供，可选再共享宿主设计系统组件。
插件在桌面渲染进程内运行，不是 iframe 或 Worker 沙箱。
需要文件、网络、命令或模型时，调用经由主进程的能力总线，逐次校验授权并约束到本插件命名空间。
## 信任与权限 [#信任与权限]
插件面向官方或合作方策展的扩展，不应被视为可直接运行的任意不可信代码。需要权限的能力必须同时满足：
### 在清单中声明 [#在清单中声明]
在 `plugin.json` 中声明权限。
### 安装时授权 [#安装时授权]
用户或管理员在安装流程中确认授权。
### 运行时校验 [#运行时校验]
宿主在调用对应 API 时再次校验权限。
## 先选正确的扩展形态 [#先选正确的扩展形态]
并非所有扩展都需要做成插件：
给 Agent 增加一组指令与工作流时优先使用技能。
只连接外部工具或数据源时优先使用 MCP。
需要桌面 UI、宿主 API 或完整生命周期时再创建插件。
需要一致的外观、组件替换或主题页面时使用主题系统。
## 可扩展范围 [#可扩展范围]
插件的扩展面分成四类：
十余个界面槽位，涵盖全局浮层、工作区整页视图、文件预览、活动面板 Tab、输入栏动作、新会话上下文区、消息卡片、工具调用行内渲染、Turn 卡、快捷键，以及文件浏览器的右键菜单、工具栏与装饰。
注册工具与生命周期 Hook、干预系统提示词、决定是否自动续跑；清单侧还可以贡献技能、内聚 MCP Server、工具策略、智能体与团队。
反过来给宿主补齐能力：模型服务商、媒体生成、OCR、CLI Provider 和受管本地服务。
在获得授权后访问文件、网络、浏览器自动化、插件私有存储、加密密钥、离屏截图，以及用户已配置的 AI 模型。
宿主已不再提供设置页配置槽，插件的配置界面由插件自己渲染、自己持久化。