数据插件开发

DataPlugin 用于向 IDE 贡献结构化数据。调用 start() 后，IDE 自动执行 on_contribute()，完成贡献后插件自动退出。它不渲染 UI，也不常驻运行。

基本结构

from pyrite_sdk.core.plugin import DataPlugin


class MyDataPlugin(DataPlugin):
    def on_contribute(self):
        # 在此注册数据贡献
        pass


plugin = MyDataPlugin()
plugin.run_once()

DataPlugin 的生命周期：start()（或 run_once()）→ on_contribute() → 所有挂起的请求完成后自动退出。不支持 on_pause()、on_resume()。

DataPlugin 可用 API：theme、i18n、stubs，以及 BasePlugin 公共 API（path、settings、message、dialog 等）。

主题贡献

通过 self.theme.contribute() 注册自定义主题。

API

方法	说明
`contribute(name, data, callback?)`	注册静态主题
`register_runtime(name, data, callback?)`	注册运行时主题（可动态更新）
`revoke(name, callback?)`	撤销已注册的主题
`get(name, callback?)`	查询已注册的主题数据
`list(callback?)`	列出所有已注册主题

主题数据结构

主题数据使用 color.primary / color.onPrimary 格式的键值对。dark. 前缀的键适用于深色模式。

from pyrite_sdk.core.plugin import DataPlugin


class NordTheme(DataPlugin):
    def on_contribute(self):
        self.theme.contribute("nord", {
            "color.primary": "#5E81AC",
            "color.onPrimary": "#ECEFF4",
            "color.surface": "#ECEFF4",
            "color.onSurface": "#2E3440",
            "dark.color.primary": "#88C0D0",
            "dark.color.onPrimary": "#2E3440",
            "dark.color.surface": "#2E3440",
            "dark.color.onSurface": "#ECEFF4",
        })


plugin = NordTheme()
plugin.run_once()

plugin.toml

manifest_version = 2
id = "nord-theme"
name = "Nord Theme"
version = "1.0.0"
type = "data"
protocol_version = 1
python_version = "3.14"
author = "Your name"
activation_events = ["onStartup"]
permissions = ["data.write"]
platforms = ["linux", "macos", "windows", "android"]

语言包贡献

通过 self.i18n.contribute() 注册语言包。使用 I18nKey 枚举确保键名与 IDE 一致。

API

方法	说明
`contribute(locale, messages, callback?)`	注册语言包
`register_runtime(locale, messages, callback?)`	注册运行时语言包
`revoke(locale, callback?)`	撤销已注册的语言包
`get(locale, callback?)`	查询已注册的语言包
`list(callback?)`	列出所有已注册语言包

使用 I18nKey

I18nKey 枚举包含 IDE 中所有可翻译的键，每个键有 .key 属性返回字符串键名。

from pyrite_sdk.api.data import I18nKey
from pyrite_sdk.core.plugin import DataPlugin


class EnglishLangPack(DataPlugin):
    def on_contribute(self):
        self.i18n.contribute("en", {
            I18nKey.NAV_FILES.key: "Files",
            I18nKey.NAV_DEVICES.key: "Devices",
            I18nKey.NAV_GIT.key: "Git",
            I18nKey.NAV_PLUGINS.key: "Plugins",
            I18nKey.NAV_SETTINGS.key: "Settings",
            I18nKey.GIT_COMMIT.key: "Commit",
        })


plugin = EnglishLangPack()
plugin.run_once()

类型存根贡献

通过 self.stubs.contribute() 注册 MicroPython 类型存根，为 IDE 的语言服务（pylsp）提供类型补全支持。

API

方法	说明
`contribute(provider_id, profiles, kind=..., version=..., aliases=..., metadata=..., callback?)`	注册存根
`register_runtime(provider_id, profiles, ...)`	注册运行时存根
`revoke(provider_id, callback?)`	撤销已注册的存根
`get(provider_id, callback?)`	查询已注册的存根
`list(callback?)`	列出所有已注册存根
`resolve_layers(layers, callback?)`	解析存根层级

完整示例

from pyrite_sdk.core.plugin import DataPlugin


class MicroPythonStubs(DataPlugin):
    def on_contribute(self):
        root = self.path.plugin() / "stubs"
        self.stubs.contribute(
            provider_id="micropython-stubs",
            kind="micropython",
            version="1.0.0",
            profiles=[
                {"id": "generic", "label": "MicroPython Generic", "path": str(root / "generic"), "priority": 10},
                {"id": "esp32", "label": "MicroPython ESP32", "path": str(root / "esp32"), "priority": 20},
            ],
            aliases=["micropython"],
        )

plugin.toml

manifest_version = 2
id = "micropython-stubs"
name = "MicroPython Stubs"
version = "1.0.0"
type = "data"
protocol_version = 1
python_version = "3.14"
author = "Your name"
activation_events = ["onStartup"]
permissions = ["data.write", "settings.read", "settings.write"]
platforms = ["linux", "macos", "windows", "android"]

混合贡献

一个 DataPlugin 可同时贡献多种数据：

class FullDataPlugin(DataPlugin):
    def on_contribute(self):
        self.theme.contribute("my-theme", {...})
        self.i18n.contribute("ja", {...})
        self.stubs.contribute("my-stubs", [...])

注意事项

DataPlugin 不支持 on_pause()、on_resume()。
贡献完成后插件自动退出，不要在 on_contribute() 中启动长期运行的任务。
如果需要在贡献后保持运行（如监听设置变化），使用 ServicePlugin 替代。
contribute() 是异步请求，Bridge 会等挂起请求完成后自动 stop_when_idle()。

On this page