跳转到内容

使用已安装的本机程序

Lite Plugin API 3.8.0 允许独立的页面或文件 View 通过 ctx.capabilities.sidecar 与已安装程序通信。插件声明程序名和固定参数,Lite 负责发现程序、启动确认、消息传输及进程清理。CLI Serve 和移动端不提供该能力。 打包前应使用匹配的 SDK/tools 检查目标宿主。

原生程序以当前用户的操作系统权限运行,不受 JavaScript 文件和网络声明限制。 程序的只读工具设置不是系统沙箱;应分别审查原生程序的工具策略与插件 JavaScript 权限。

下面的 example-agent 是占位程序名,代表已安装、通过 LF 分隔 JSON 通信的程序。 参数应与所选程序实际支持的参数一致:

{
"apiVersion": 1,
"id": "local.agent",
"name": "Local agent",
"version": "0.1.0",
"requires": { "pluginApi": "3.8.0" },
"sidecar": { "command": "example-agent", "args": [] },
"views": [
{ "id": "chat", "title": "Agent", "kind": "page", "entry": "./main.ts" }
],
"placements": [{ "location": "navigation", "view": "chat" }]
}

command 必须是可执行文件名,不能是路径或 shell 命令。最多 64 个参数固定在 manifest 中。接口不允许调用方传入工作目录、环境变量或动态参数,也不安装、下载 程序。Lite 使用规范化的 Space 根目录作为工作目录,搜索绝对 PATH 目录及标准用户、 系统程序位置,排除当前 Space 及解析到 Space 内的链接。Space 外正常安装程序的 符号链接可以使用。

启动时不会通过 shell 解释参数,因此 Windows .cmd 和 .bat 包装脚本不可用。 应在每个声称支持的系统上验证程序发现和进程清理。

先检查 ctx.capabilities.sidecar 是否存在。status() 仅发现程序,不执行程序或 弹出确认;available 不代表程序版本兼容。用户新建任务或发送消息时调用 start(), Lite 会展示程序、固定参数、工作目录及系统权限并请求原生确认。取消或超时后应允许重试。

start() 复用现有的所属进程;每次启动新进程都必须重新确认,确认最多等待五分钟。 启动成功仅表示系统接受了程序,协议就绪和版本兼容性仍由插件判断。

在 View 中先订阅,再发送程序协议命令:

const native = ctx.capabilities.sidecar
if (!native) throw new Error("当前宿主不支持本机程序")
ctx.subscriptions.add(
await native.onEvent((event) => {
// 将事件数据作为文本渲染,处理协议错误,并丢弃过期结果。
console.log(event)
})
)
// 在用户新建任务或发送消息的处理器中:
await native.start()
// 使用程序实际支持的协议,并自行关联请求 ID。
await native.send({ type: "get_state", id: "state-1" })

send() 写入一个 JSON 值和 LF,不等待协议回复。包含 LF 的输入帧最多 1 MiB, 包含新帧的待写 stdin 最多 4 MiB。stdout 必须使用 LF 分隔 JSON,也接受 CRLF; U+2028/U+2029 仍是字符串内容。事件包括 message、stderr、error 和 exit。 输出非法或超限会终止进程。速率限制与签名见 API 参考。

如果程序通过单条响应返回较长历史,可声明 sidecar.maxOutputFrameBytes,并设置 requires.pluginApi: "3.12.0"。值为 1 至 16777216 的整数,默认仍为 1048576 字节。 上限按不含 CRLF 的 UTF-8 JSON 记录字节数计算,不改变 stdin 限制。stdout 每秒速率上限 为 16 MiB 和单条记录上限两倍中的较大值。例如 "maxOutputFrameBytes": 16777216 允许最多 16 MiB 的单条记录和每秒 32 MiB 输出。此能力对应 sidecar.outputFrameLimit, 仅 Lite 提供;打包前须使用匹配的 SDK/tools,并确认实际宿主支持。 exit 紧随 error 到达时,应保留最初的具体错误,不应替换成泛化的断连提示,也不应 静默丢弃历史来适应传输限制。

每个所属窗口、Space、插件及包版本共享一个进程。关闭 View 只取消监听,不停止进程。 事件不会重放,返回页面时应查询原生状态与消息历史。会话侧栏可以使用现有 Explorer 贡献点,通过 ui.navigate("chat", route) 在主区域打开对话。可选的插件私有存储或 JavaScript 后台用于协调选择和草稿;该后台 不能启动原生进程。

应展示进度、可恢复的启动错误,并通过程序协议提供停止生成的操作。 sidecar.stop() 会结束共享进程。禁用或更新插件、离开 Space、关闭所属窗口、退出 Lite 也会结束进程,再次运行需重新确认。停止不会撤销原生副作用,也不会删除程序自己 保存的会话文件。