runtime — 设备运行时

检查设备运行时状态（如 MicroPython）的会话、作用域与变量。

self.runtime 提供对设备运行时（例如 MicroPython）的只读检查能力，包括枚举运行时会话、读取状态与作用域、分页遍历变量与对象信息，以及订阅程序生命周期事件。

使用 self.runtime 需要在插件权限中声明 runtime.inspect。运行时检查只读取状态，不会中断正在运行的程序。

方法

方法	说明
`sessions`	列出当前运行时会话
`state`	获取会话状态
`scopes`	获取会话的作用域列表
`variables`	分页获取作用域中的变量
`children`	惰性分页获取对象的子项
`object_info`	获取单个对象的详细信息

异常

异常	错误码	说明
`StaleReferenceError`	`stale_reference`	对象引用属于前一代运行时；后端重启（硬件复位 / 重连）会使先前创建的所有引用失效
`RuntimeUnavailableError`	`unavailable`	后端无法安全地检查运行时（能力不可用）

检查操作绝不会中断正在运行的程序。当后端没有安全读取状态的途径时，它会以 unavailable 拒绝，而不是发送中断。

数据类

数据类	字段
`RuntimeSession`	`session_id`、`generation`、`capability`（默认 `"available"`）、`program_state`（默认 `"idle"`）
`Scope`	`id`、`name`、`raw`
`Variable`	`name`、`type`、`repr`、`reference`、`has_children`、`named_variables`、`indexed_variables`
`ObjectInfo`	`reference`、`type`、`repr`、`attributes`（`Variable` 列表）、`raw`
`Page`	`items`、`total`、`start`

variables 与 children 返回 Page，其中 items 为 Variable 列表。start 为本次起始偏移，total 为该项总数（可能为空）。

查询

sessions(callback?)

列出当前可用的运行时会话。

def _on_sessions(**cb):
    for session in cb.get("sessions", []):
        print(session.session_id, session.generation, session.program_state)

self.runtime.sessions(callback=_on_sessions)

回调数据： callback(sessions=[...])

state(session_id?, callback?)

获取指定会话（省略时使用默认会话）的状态。

self.runtime.state(
    session_id="abc123",
    callback=lambda **cb: print(cb.get("session")),
)

回调数据： callback(session=RuntimeSession)

scopes(session_id, callback?)

获取会话中的作用域列表（如全局作用域、局部作用域）。

self.runtime.scopes(
    "abc123",
    callback=lambda **cb: print(cb.get("scopes", [])),
)

回调数据： callback(scopes=[...])

variables(session_id, scope_id, start?, count?, callback?)

分页读取作用域中的变量。

self.runtime.variables(
    session_id="abc123",
    scope_id="0",
    start=0,
    count=100,
    callback=lambda **cb: print(cb.get("page")),
)

参数：

session_id (str) — 会话 ID
scope_id (str) — 作用域 ID
start (int) — 起始偏移，默认 0
count (int) — 每页数量，默认 0

回调数据： callback(page=Page)

children(reference, start?, count?, callback?)

惰性分页获取某个对象引用的子项，避免一次性返回整个大容器。

self.runtime.children(
    reference="obj-ref-1",
    start=0,
    count=50,
    callback=lambda **cb: print(cb.get("page")),
)

参数：

reference (str) — 对象引用
start (int) — 起始偏移，默认 0
count (int) — 每页数量，默认 0

回调数据： callback(page=Page)

object_info(reference, callback?)

获取单个对象的类型、表示及属性信息。

self.runtime.object_info(
    reference="obj-ref-1",
    callback=lambda **cb: print(cb.get("info")),
)

回调数据： callback(info=ObjectInfo)

方法	事件主题
`on_session_created`	`runtime.session.created`
`on_session_ended`	`runtime.session.ended`
`on_session_state_changed`	`runtime.session.state.changed`
`on_program_started`	`runtime.program.started`
`on_program_paused`	`runtime.program.paused`
`on_program_resumed`	`runtime.program.resumed`
`on_program_finished`	`runtime.program.finished`
`on_backend_restarted`	`runtime.backend.restarted`
`on_variables_changed`	`runtime.variables.changed`

self.runtime.on_program_finished(
    lambda **cb: print("程序运行结束", cb)
)

使用示例

class RuntimeInspector(ServicePlugin):
    def inspect(self):
        self.runtime.sessions(callback=self._on_sessions)

    def _on_sessions(self, **cb):
        sessions = cb.get("sessions", [])
        if not sessions:
            print("无可用会话")
            return
        self.runtime.scopes(
            sessions[0].session_id,
            callback=lambda **cb: self._on_scopes(cb, sessions[0].session_id),
        )

    def _on_scopes(self, cb, session_id):
        scopes = cb.get("scopes", [])
        if not scopes:
            return
        # 分页读取第一个作用域的变量
        self.runtime.variables(
            session_id=session_id,
            scope_id=scopes[0].id,
            start=0,
            count=100,
            callback=lambda **cb: self._on_page(cb),
        )

    def _on_page(self, cb):
        page = cb.get("page")
        if page is None:
            return
        for var in page.items:
            print(var.name, var.type, var.repr)
        print("共", page.total, "项，当前页起始", page.start)

    def on_dispose(self):
        pass

对象引用只在当前运行时代内有效。硬件复位或重新连接会使引用失效并抛出 StaleReferenceError，请捕获该异常并重新枚举会话。

runtime — 设备运行时

On this page