---
title: "sidecar | Eidos Docs"
description: "sidecar 的 SDK 签名、权限和行为约定。"
source: "https://docs.eidos.space/zh-cn/plugins/api/sidecar/"
lang: "zh-CN"
---

# sidecar

在 manifest.sidecar 声明本机程序与默认参数。API 3.9 的 configurable: true 可启用需审阅的启动配置；API 3.12 的 maxOutputFrameBytes 可接收有明确大小上限的大响应。仅独立页面和文件 View 可获得此能力；原生程序保有 JavaScript 沙箱之外的系统权限。CLI Serve 和移动端不提供原生 sidecar。

使用指南: [native-processes](https://docs.eidos.space/zh-cn/plugins/native-processes/). [API 索引](https://docs.eidos.space/zh-cn/plugins/api/).

签名、参数及返回类型从 SDK 自动生成；可选成员不保证在每个宿主和上下文中存在。

## SidecarEvent

[源码](https://github.com/mayneyao/eidos/blob/dev/packages/plugin-sdk/src/index.ts#L241)

支持宿主: Lite

```ts
export type SidecarEvent = {
    type: "message";
    data: BackgroundMessage;
} | {
    type: "stderr";
    text: string;
} | {
    type: "exit";
    code: number | null;
    signal: string | null;
} | {
    type: "error";
    message: string;
};
```

关联类型: [BackgroundMessage](https://docs.eidos.space/zh-cn/plugins/api/types/#backgroundmessage).

## SidecarStatus

[源码](https://github.com/mayneyao/eidos/blob/dev/packages/plugin-sdk/src/index.ts#L246)

### SidecarStatus.available

支持宿主: Lite

```ts
available: boolean;
```

### SidecarStatus.running

支持宿主: Lite

```ts
running: boolean;
```

### SidecarStatus.command

支持宿主: Lite

```ts
command: string;
```

### SidecarStatus.launch

支持宿主: Lite

```ts
launch?: SidecarLaunch;
```

关联类型: [SidecarLaunch](https://docs.eidos.space/zh-cn/plugins/api/sidecar/#sidecarlaunch).

## SidecarLaunch

[源码](https://github.com/mayneyao/eidos/blob/dev/packages/plugin-sdk/src/index.ts#L253)

### SidecarLaunch.command

支持宿主: Lite

```ts
command: string;
```

### SidecarLaunch.args

支持宿主: Lite

```ts
args: string[];
```

## PluginSidecar

[源码](https://github.com/mayneyao/eidos/blob/dev/packages/plugin-sdk/src/index.ts#L258)

### PluginSidecar.status

支持宿主: Lite

仅查询：available 表示找到了程序，running 表示存在所属原生进程；均不保证协议就绪或程序版本兼容。不会执行、安装或弹出授权。

```ts
status(): Promise<SidecarStatus>;
```

返回值: `Promise<SidecarStatus>`.

### PluginSidecar.start

支持宿主: Lite

核对按 Space、包修订及含参数的精确程序身份保存的授权，缺失或变化时请求审阅。安装或启用可审阅具体默认启动；覆盖须声明 configurable: true。不同的已有进程须先停止。待启动确认最多五分钟，随发起 View 取消；已启动后关闭 View 仅断开连接。成功仅表示系统启动程序，不代表协议就绪。

```ts
start(launch?: SidecarLaunch): Promise<void>;
```

| 参数     | 类型            | 必填 |
| ------ | ------------- | -- |
| launch | SidecarLaunch | 否  |

返回值: `Promise<void>`.

### PluginSidecar.stop

支持宿主: Lite

停止共享的所属进程树并等待退出，影响所有已连接 View。Stop 保留授权，禁用或卸载撤销授权。更新插件、离开 Space、关闭所属窗口或退出 Lite 也会停止进程；不会撤销已产生的原生修改。

```ts
stop(): Promise<void>;
```

返回值: `Promise<void>`.

### PluginSidecar.send

支持宿主: Lite

写入一个 JSON 值并追加 LF。包含 LF 的单帧最多 1 MiB；含本次新帧的待写 stdin 最多 4 MiB。完成表示流写入完成，不表示收到原生协议回复。

```ts
send(data: BackgroundMessage): Promise<void>;
```

| 参数   | 类型                | 必填 |
| ---- | ----------------- | -- |
| data | BackgroundMessage | 是  |

返回值: `Promise<void>`.

### PluginSidecar.onEvent

支持宿主: Lite

订阅不会启动进程，返回可释放监听器，关闭 View 时取消订阅。stdout 以 LF 分隔 JSON（接受 CRLF），单条记录默认最多 1 MiB，不含 CRLF；API 3.12 可声明 manifest.sidecar.maxOutputFrameBytes，整数范围 1 至 16777216。stdout 每秒字节上限为 max(16 MiB, 单条记录上限的两倍)；stderr 每秒超出 1 MiB 的部分丢弃。非法或超限输出会先发出 error 再停止进程，exit 到达时应保留最初错误。Unicode 行分隔符仍是字符串内容。事件不重放，重新连接后应查询原生状态。

```ts
onEvent(listener: (event: SidecarEvent) => void): Promise<Disposable>;
```

| 参数       | 类型                            | 必填 |
| -------- | ----------------------------- | -- |
| listener | (event: SidecarEvent) => void | 是  |

返回值: `Promise<Disposable>`.

关联类型: [SidecarStatus](https://docs.eidos.space/zh-cn/plugins/api/sidecar/#sidecarstatus), [SidecarLaunch](https://docs.eidos.space/zh-cn/plugins/api/sidecar/#sidecarlaunch), [BackgroundMessage](https://docs.eidos.space/zh-cn/plugins/api/types/#backgroundmessage), [SidecarEvent](https://docs.eidos.space/zh-cn/plugins/api/sidecar/#sidecarevent), [Disposable](https://docs.eidos.space/zh-cn/plugins/api/types/#disposable).
