Manifest v2

插件包根目录的 plugin.toml 使用 Manifest v2 描述插件元数据、激活条件、权限与对 IDE 的贡献。Manifest 在安装与打包时都会被严格校验，未知字段（extra="forbid"）会导致拒绝。

顶层字段

manifest_version = 2
id = "my-plugin"
name = "My Plugin"
version = "1.0.0"
type = "ui"                # ui | service | data
protocol_version = 1
python_version = "3.14"
author = "Your name"
description = "A sample plugin."
activation_events = ["onStartup"]
permissions = ["ui.view", "file.read"]
platforms = ["windows", "linux", "macos", "android"]

[icons]
full = "assets/icon.png"
monochrome = "assets/icon-mono.png"

字段	类型	说明
`manifest_version`	int	固定为 `2`
`id`	string	全局唯一插件 ID，只能使用小写字母、数字、`-`、`_`
`name`	string	显示名称
`version`	string	语义化版本
`type`	string	`ui` / `service` / `data`
`protocol_version`	int	协议版本，当前为 `1`
`python_version`	string	目标 Python 版本（如 `"3.14"`）
`author`	string	作者
`description`	string	描述
`icons`	table	`full` / `monochrome` 图标
`activation_events`	list	激活事件（见下）
`permissions`	list	权限列表（见下）
`platforms`	list	支持的平台
`contributes`	tables	贡献点（见下）

激活事件

插件按激活事件延迟启动：只有事件命中才创建插件会话。未命中时保持未激活。

事件	语义
`onStartup`	IDE 启动时自动激活（`auto_start`）
`onView:<view_id>`	用户打开该贡献视图时激活
`onCommand:<command_id>`	执行该贡献命令时激活
`onLanguage:<language_id>`	打开对应语言文档时激活

激活事件的目标（<view_id> / <command_id>）必须指向本插件贡献的 ID，否则校验失败。

权限

权限默认拒绝，未声明的资源访问会被 IDE 拒绝（错误码 permission_denied）。

权限	资源
`ui.view` / `ui.navigate` / `ui.notify`	视图渲染 / 路由导航 / 消息通知
`file.read` / `file.write`	本地文件读写
`board.read` / `board.write`	设备文件读写
`editor.read` / `editor.write`	编辑器读写
`persistence.read` / `persistence.write`	持久化存储
`settings.read` / `settings.write`	IDE 设置
`serial.read` / `serial.write`	串口读写
`data.read` / `data.write`	数据贡献（主题 / 语言包 / 存根）
`dialog.show`	系统对话框
`runtime.inspect`	运行时检查（变量视图等）
`tab.create` / `tab.manage`	创建 / 管理标签页

贡献点（contributes）

navigation_containers

声明侧边导航容器（桌面 NavigationRail 与移动端 Drawer 共用同一注册表）：

[[contributes.navigation_containers]]
id = "my-plugin"
title = "My Plugin"
location = "primary"            # primary | secondary
order = 10
icon = { material = "extension_outlined" }

views

声明原生渲染视图。container 指向本插件声明的导航容器：

[[contributes.views]]
id = "my-plugin.main"
container = "my-plugin"
title = "My Plugin"
renderer = "native.form"        # 见原生视图目录
order = 0
when = "device.connected == true"

校验约束：

贡献 ID 必须使用 插件ID. 前缀，且全局唯一。
Ui 插件必须至少声明一个 navigation_containers。
renderer 仅支持 native.*；rfw / rfw.* 会被拒绝（错误码 rfwRendererUnsupported）。

commands

[[contributes.commands]]
id = "my-plugin.hello"
title = "Say Hello"
icon = { material = "waving_hand_outlined" }

命令处理器在 Python 中通过 self.commands.register() 注册。

menus

[[contributes.menus]]
location = "view/title"          # view/title | view/context | navigation/context | commandPalette
command = "my-plugin.hello"
view = "my-plugin.main"
group = "actions"
order = 0

configuration

声明本插件自己的配置项（类型 string / integer / number / boolean / array）：

[[contributes.configuration]]
id = "my-plugin.autoRefresh"
title = "Auto Refresh"
type = "boolean"
default = false
description = "自动刷新数据。"

运行时经 self.configuration.get/set/on_changed 访问。

条件表达式（when）

when 使用简单的布尔表达式控制可见性，可用上下文键包括：

editor.language、editor.hasDocument、runtime.language、runtime.state、device.connected、workspace.opened、plugin.enabled、view.active。

完整示例（逐字段注释）

# ================= 顶层字段 =================
manifest_version = 2                  # 固定值
id = "device-console"                 # 全局唯一；所有贡献 ID 用 "device-console." 前缀
name = "设备控制台"                    # 显示名称
version = "1.0.0"                     # 语义化版本
type = "ui"                           # ui | service | data
protocol_version = 1                  # 协议版本，当前为 1
python_version = "3.14"               # 目标 Python 版本
author = "You"
description = "展示工作区信息与文件的示例插件。"

# 激活事件：只有事件命中才启动插件（延迟启动），见 lifecycle 页
activation_events = [
  "onView:device-console.status",     # 打开该视图时激活
  "onCommand:device-console.hello",   # 执行该命令时激活
]

# 权限默认拒绝：列出插件实际要访问的资源
permissions = ["ui.view", "file.read", "data.read"]

platforms = ["windows", "linux", "macos", "android"]

# 图标二选一（material / asset 互斥）
[icons]
full = "assets/icon.png"
monochrome = "assets/icon-mono.png"

# ================= 贡献点 =================
# 侧边导航容器：Ui 插件必须至少声明一个
[[contributes.navigation_containers]]
id = "device-console"                 # 容器 ID
title = "设备控制台"
location = "primary"                  # primary | secondary
order = 10
icon = { material = "monitor_heart_outlined" }

# 视图：指向本插件声明的容器
[[contributes.views]]
id = "device-console.status"          # 贡献 ID，必须用 插件ID. 前缀
container = "device-console"          # 所属导航容器
title = "状态"
renderer = "native.form"              # 仅 native.*（列表见 sdk/ui-plugins）
order = 0
when = "workspace.opened == true"     # 条件表达式控制可见性（可选）

[[contributes.views]]
id = "device-console.files"
container = "device-console"
title = "项目文件"
renderer = "native.tree"
order = 1

# 命令：处理器在 Python 里用 self.commands.register() 注册
[[contributes.commands]]
id = "device-console.hello"
title = "打个招呼"
icon = { material = "waving_hand_outlined" }

# 菜单：把命令挂到标题栏 / 右键 / 导航上下文 / 命令面板
[[contributes.menus]]
location = "view/title"               # view/title | view/context | navigation/context | commandPalette
command = "device-console.hello"
view = "device-console.status"        # 作用于哪个视图（context 菜单需要）
group = "actions"
order = 0

# 配置项：Python 里用 self.configuration.get/set/on_changed 访问
[[contributes.configuration]]
id = "device-console.autoRefresh"     # 配置项 ID
title = "自动刷新"
type = "boolean"                      # string | integer | number | boolean | array
default = false
description = "文档内容变化时自动刷新状态视图。"

运行时读取示例：

def on_start(self):
    self.configuration.get(
        "device-console.autoRefresh",
        callback=lambda **cb: print("autoRefresh =", cb.get("value")),
    )
    self.configuration.on_changed(
        lambda event: print("changed:", event.get("value")),
        configuration_id="device-console.autoRefresh",
    )

On this page