# 插件开发与排错

插件安装、授权、运行状态和日志都在 **插件面板** 中操作。

## 创建项目

在 NyaTerm 仓库根目录执行：

```sh
# 纯界面插件：查看选中终端的会话信息
pnpm plugin:create example.session temp/plugins/my-session --template ui
pnpm plugin:pack temp/plugins/my-session temp/plugins/my-session.nyap

# Rust 插件：界面调用后台，也提供原生命令
pnpm plugin:create example.hello temp/plugins/my-hello --template rust
node temp/plugins/my-hello/build.mjs
pnpm plugin:pack temp/plugins/my-hello temp/plugins/my-hello.nyap
```

创建器拒绝覆盖已有目录。项目包含 manifest、可用入口、SDK 和 README；
Rust 模板还包含编译脚本，编译后自动填入当前平台的可执行文件路径。
需要 Node 和 Rust 1.94 或更新版本。Rust SDK 使用本地路径依赖，移动项目时
应一起提供 SDK 或调整 Cargo.toml 中的路径。

将生成的 `.nyap` 安装到插件面板，检查权限并启用。UI 模板需先选中已连接终端；
Rust 模板可以打开界面点击运行，也可以直接执行插件卡片上的原生命令。

## 页面字体

宿主会将应用的界面字体栈通过 `NyaTerm.context.theme` 中的 `--font-sans`、
`--font-display` 同步到插件页面；修改设置时，已打开的页面也会收到更新，无需重载。
`--font-mono` 提供宿主的默认等宽字体栈。SDK 默认使用界面字体，表单控件继承字体；
插件自定义 CSS 应使用 `font-family: var(--font-sans, system-ui, sans-serif)`，
代码区域可使用 `var(--font-mono, monospace)`，避免写死 `system-ui`。

iframe 可以使用系统安装的字体，但不会继承主界面的 `@font-face`。
若使用未安装到系统的内置字体或其他 Web 字体，需要在插件包内提供字体文件并声明
`@font-face`。已有插件若写死字体，需要修改 CSS 并重新打包安装。

## 编写 Rust 后台

入口实现 `Plugin`，由 `Server::from_env()` 启动服务。SDK 负责握手、传输、
并发、作用域、超时和取消，无需手写 JSON-RPC：

```rust
#[async_trait]
impl Plugin for MyPlugin {
    async fn call(&self, context: Context, method: &str, input: Value) -> Result<Value> {
        match method {
            "ui/session" => {
                let session = context.host().session().await?;
                context.log("info", "Session inspected").await?;
                Ok(session)
            }
            _ => Err(RpcError::method_not_found(method)),
        }
    }
}
```

以上会话读取需在 manifest 中声明并获授 `session.read`；原生执行需 `native`。
UI 调用 `NyaTerm.backend("ui/session")`，contributions.commands 中的原生命令
则使用 manifest 声明的方法。不要向 stdout 打印日志，它专用于协议；使用
`Context::log` 或 stderr。不要记录口令、令牌、终端输入输出等敏感内容。

默认采用 JSONL。将 `backend.transport` 改为 `stdio-framed` 后，SDK 根据宿主
环境自动切换协议，支持二进制帧；界面流式订阅尚未提供。完整 API 和取消约定
见 [Rust SDK](../plugins/sdk/rust/nyaterm-plugin-sdk/README.md)。

## 固定远端 Probe 和共享 Monitor

Manifest v1 可选声明 `contributions.probes` 和 `contributions.monitors`，旧包不必增加字段。
以 GPU 为例：

```json
{
  "contributions": {
    "panels": [{ "id": "overview", "title": "GPU", "entry": "ui/index.html" }],
    "probes": [
      {
        "id": "gpu-overview",
        "title": "GPU probe",
        "entry": "assets/probes/gpu.sh",
        "timeoutMs": 15000
      }
    ],
    "monitors": [
      {
        "id": "gpu",
        "title": "GPU",
        "schema": "gpu.v1",
        "method": "monitor/collect",
        "panel": "overview"
      }
    ]
  },
  "permissions": ["native", "remote.probe"]
}
```

每类最多 16 项，ID 不可与其他贡献重复。脚本必须位于包内 `assets/probes/*.sh`，为非空 UTF-8、无 NUL、最多 64 KiB；
超时范围 1–30 秒。Monitor 必须引用已声明面板，声明 `monitor/*` 方法、原生后台和 Probe；当前只支持 `gpu.v1`。
自动授权绑定审核版本；启用对话框展示脚本全文，更新/切换版本移除 `remote.probe` 授权。
宿主不保证第三方脚本只读，不允许两个有效插件同时提供同一种 Monitor schema。

后台每次 `monitor/collect` 调用 `context.host().remote_probe("gpu-overview").await?`，解析结果并返回 GPU JSON。
对应 RPC `host/remote/probe` **只接受** `{ "probeId": "gpu-overview" }`，返回 `{ stdout, stderr, exitStatus }`。
不能提供命令、参数、stdin 或其他会话 ID；宿主从当前包解析脚本，在所属 SSH 连接的新 exec 通道执行 `sh -s`。
stdout/stderr 合计限 1 MiB，超时或取消关闭该通道，不向交互终端输入命令、不关闭 SSH 连接。
执行前后检查版本、授权、窗口、会话及锁屏；网络设备和禁止远程探测的会话不可执行。

UI 只订阅结果，不直接启动后台采集循环：

```js
await NyaTerm.ready;
const monitor = await NyaTerm.monitoring.subscribe("gpu", (snapshot) => {
  // revision, sessionId, overview, error, refreshing, paused
  render(snapshot);
});
await monitor.refresh();
await monitor.unsubscribe();
```

宿主以插件/版本/窗口/会话/Monitor 为键共享任务，订阅返回初始快照，再推送递增 revision。
Bridge 仅向对应 iframe 发送所属订阅；未开放通用原生事件透传或 UI 调用 `monitor/*`。
宿主消费者使用 typed `pluginApi.subscribeMonitor/refreshMonitor/unsubscribeMonitor`；
`subscribePluginMonitor` 负责先监听再订阅、初始快照竞态、revision 去重及释放。
每个 iframe 最多 16 个订阅；宿主最多 256 订阅和 128 共享任务。

SDK Context 提供 `language`、主题变量和 `monitorIntervalSeconds`。使用 `onContextChange` 同步语言/主题，
仅间隔变化时重新订阅。主窗口订阅 25 分钟续期；iframe 作用域按现有机制重建。
闲置任务不持有请求租约；后台每次只处理一次采集，不保存已经结束请求的 Context。

`gpu.v1` 结构与 `RemoteGpuOverview` 相同，宿主拒绝未知字段并限制设备/进程数量和文本长度。
资产回填只能来自当前会话的 GPU 数据，没有任意连接修改接口。
完整示例与构建命令见 [GPU 插件](../plugins/examples/gpu-monitor/README.md)。

## 查看状态和日志

原生后台按需启动并复用进程。卡片显示未启动、启动中、运行中、已停止或运行异常；
禁用插件和仅界面插件有独立标识。RPC 方法返回错误时，只记录调用失败，后台仍可
继续运行；进程退出、握手或协议失败则显示运行异常。

点击 **查看日志** 可刷新、复制和清空。日志包括时间、版本、级别、来源和消息。
日志弹窗每秒刷新，卡片状态每 2.5 秒刷新；关闭插件管理面板后停止轮询。
每个插件最多保留 100 条、64 KiB 消息与来源/版本文本，单条消息最多 2 KiB。
stderr 每次启动最多采集约 64 KiB，超过后继续排空而不保留。
日志只在内存中保留，退出应用即清除，不进入备份或云同步。
宿主会遮蔽常见凭据和作用域令牌，但插件作者仍需自行避免写入敏感内容。

**停止后台** 保留启用状态和权限。普通调用可启动新进程，进程内计数等状态会重置；
监控任务会同时暂停，定时器不会自行重新启动后台，手动刷新或重新启用可恢复。
插件有进行中的请求时会提示忙碌；先结束或关闭该操作，再停止后台。
禁用、更新、切换版本、锁屏和退出应用也会停止后台。旧进程的延迟消息不会覆盖
新启动进程的状态。更新插件必须提升版本号，同版本不同内容不能重新安装。

## 本地验证

```sh
node --test scripts/create-plugin.node-test.mjs
cargo test --manifest-path plugins/sdk/rust/nyaterm-plugin-sdk/Cargo.toml
cargo test --manifest-path src-tauri/crates/nyaterm-plugin-runtime/Cargo.toml --features sdk-fixture
pnpm exec vitest run src/components/plugins/PluginDiagnostics.test.tsx --maxWorkers=4
```

`native-counter` 示例已使用 SDK，并升到 1.0.1：执行两次可看到计数递增和日志；
停止后台后再执行，计数从 1 开始。新版安装包为 `temp/plugins/native-counter.nyap`。
模板编译和打包已在 Windows 验证；其他平台需构建对应二进制并填写 executables。