Artheru：Initial bilingual draft (auto-published)

2026-05-16T14:00:13Z

Initial bilingual draft (auto-published)

新页面

<languages/>

== 概述 / Overview ==
本页是 Medulla `IOObject` 基类与其上 ''全部装饰属性''的速查表。属性定义在 `D:\src\M2\MedullaCore\Types\IO.cs:9-70`。

This page is the cheat sheet for the Medulla `IOObject` base class and ''all its decorating attributes''. Attribute definitions at `D:\src\M2\MedullaCore\Types\IO.cs:9-70`.

== IOObject 基类 / IOObject base ==
{| class="wikitable"
! 成员 / Member !! 类型 / Type !! 含义 / Meaning
|-
| `Name` || `string` || 实例名（由 startup.iocmd 加载时设置）/ instance name set by the script engine on load
|-
| `TimeoutThreshold` || `float = 500` || 预期更新间隔（ms）；框架不强制，插件自己用 / expected update interval, plugin-enforced
|-
| `Methods` || `string[]` || 反射回填的公共方法名 / reflection-backed; for UI auto-binding
|-
| `OpenUI(Terminal)` || virtual || 打开 UI 面板的钩子 / UI panel creation hook
|-
| `CloseUI()` || virtual || 关闭 UI / UI teardown
|-
| `SwitchTerminal(Terminal)` || virtual || 把 UI 迁移到新 Terminal / migrate UI to a new Terminal
|}

`MainIOObject` 类名是 Medulla 反射查找的硬约束（`MedullaIO.cs:299`）。
The class name `MainIOObject` is a hard-coded reflection lookup in `MedullaIO.cs:299`.

== 装饰属性 / Decorating attributes ==
=== [IOObjectMonitor] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 字段值导出到 CycleGUI 的属性栅格；如果 `VerboseLog = true`，每次变化记到 DLog。
Exports the field to CycleGUI's property grid; logs to DLog if `VerboseLog = true`.

<syntaxhighlight lang="csharp">
[IOObjectMonitor]
public float currentVelocity;

[IOObjectMonitor(desc = "电池剩余百分比 / Battery percentage")]
public int batteryPercent;
</syntaxhighlight>

=== [IOObjectUtility] ===
'''目标''' / Target: 方法（仅 ''零参数''）/ method (zero-arg only)

'''效果''' / Effect: 在 UI 的 "Actions" 组中显示为按钮。
Renders as a button in the UI's "Actions" group.

<syntaxhighlight lang="csharp">
[IOObjectUtility]
public void StartScan() { /* trigger device start */ }
</syntaxhighlight>

=== [IOObjectWebUtility] ===
'''目标''' / Target: 方法 / method

'''效果''' / Effect: 自动注册 HTTP 端点 `/<IOName>/<MethodName>`。
Auto-registers an HTTP endpoint `/<IOName>/<MethodName>`.

<syntaxhighlight lang="csharp">
[IOObjectWebUtility(type = WebUtilityType.API)]
public byte[] GetCurrentFrame() { /* return JSON or binary */ }

[IOObjectWebUtility(type = WebUtilityType.WebPage)]
public byte[] StatusPage() { /* return HTML */ }
</syntaxhighlight>

子类型 / Subtypes (`type` enum):
* `WebPage` — 返回 `byte[]`，作为完整页面 / returns `byte[]` as a full page
* `API` — JSON API
* `Utility` — 普通工具方法
* `DataChunk` — 大块二进制数据（流式 / chunked）

=== [IOObjectWatch] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 看门狗。当 JS 表达式 `jsWatcher` 在字段上为 true → 触发告警模板 `jsAlertTemplate`。
Watchdog. When the JS predicate `jsWatcher` on the field evaluates true → fires the alert template `jsAlertTemplate`.

<syntaxhighlight lang="csharp">
[IOObjectWatch(
watchVal = "value",
jsWatcher = "value < 10",
jsAlertTemplate = "Battery critically low: ${value}%",
jsAlertColorTemplate = "red",
holdIfAlert = true)]
public int batteryPercent;
</syntaxhighlight>

=== [IOObjectSerialize] ===
'''目标''' / Target: 类 / class

'''效果''' / Effect: 自定义序列化器。当前 build 未使用 / unused in current build.

<syntaxhighlight lang="csharp">
[IOObjectSerialize(Serializer = typeof(MyCustomSerializer))]
public class MyIO : IOObject { ... }
</syntaxhighlight>

== 与 CartDefinition 属性的区别 / vs CartDefinition attributes ==
注意 `[AsUpperIO] / [AsLowerIO] / [AsInitParam] / [UseLadderLogic]` 不是 `IOObject` 的属性 —— 它们属于 `CartDefinition`（位于 `CartActivator` 插件）。详见 [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]]。

The `[AsUpperIO]` / `[AsLowerIO]` / `[AsInitParam]` / `[UseLadderLogic]` attributes are NOT on `IOObject` — they live in the `CartActivator` plugin's `CartDefinition` family. See [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]].

== Web 端点路由 / Web endpoint routing ==
Medulla 启动 HTTP server（`Startup.cs:204-256`）后：
After Medulla starts its HTTP server:

* `GET /getIOs` — 列出所有加载的 IOObject + 它们的字段 + 方法 + 端点
* `GET/POST /<IOName>/<MethodName>` — 调用 `[IOObjectWebUtility]` 方法
* `GET /<IOName>/<FieldName>` — 读 `[IOObjectMonitor]` 字段（如果配置开放）

端口由 `MedullaIO.CPort` 控制（默认 8081 / `MedullaIO.cs:34`）。

Port controlled by `MedullaIO.CPort` (default 8081).

== 调试技巧 / Debug tips ==
* '''字段不出现在 dashboard''' → 检查 `[IOObjectMonitor]` 是否标在 ''public 字段''上。
* '''按钮不出现''' → `[IOObjectUtility]` 标在 ''public 零参数方法''上吗？
* '''Web 端点 404''' → IO 名是否正确？看 `/getIOs` 列表确认。
* '''告警不触发''' → `jsWatcher` 表达式语法错误是常见原因；用 `console.log(value)` 调试。

== 相关页面 / See also ==
* [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]]
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/Medulla|Medulla]] / [[Special:MyLanguage/Medulla-API|Medulla-API]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

IOObject属性参考 - 版本历史

Artheru：​Initial bilingual draft (auto-published)

Artheru：Initial bilingual draft (auto-published)