RFC: 多 Runtime 支持（ClipHandler + Go SDK）

[yan5xu]

动机

当前只有 Bun/TS Runtime。非 TS 开发者（Go/Rust）想写 Clip 只能走 Edge Clip 模式——自己实现完整 Provider 协议（Connect-RPC + protobuf + 心跳 + 重连 + 进程管理），业务代码只占 30%。

支持多 Runtime 后，Go 开发者可以用 Go SDK 写 Clip，享受和 TS 一样的托管体验：

clip := pinix.NewClip()
clip.Handle("list", func(input JSON) (JSON, error) {
    return listTodos(), nil
})
clip.Run() // stdin/stdout NDJSON，SDK 全包了

pinix add 一键安装，pinixd 托管进程生命周期。

Edge Clip vs SDK Clip 定位

	SDK Clip（Runtime 托管）	Edge Clip（自管理）
本质	应用/服务	设备驱动
特征	纯软件，任何机器能跑	绑定特定硬件/环境
安装	pinix add 一键	手动部署到目标机器
进程管理	Runtime 托管（crash recovery）	自己管
协议复杂度	IPC NDJSON（SDK 封装）	Provider Connect-RPC（自己实现）
适合	应用开发者	基础设施/硬件开发者
例子	clip-todo, agent-clip	bb-browserd, iphone-clip, homekit-clip

四种 Runtime 类型

类型	安装	启动	IPC
bun	npm/registry → bun install	bun run index.ts --ipc	stdin/stdout NDJSON
binary	下载平台 binary	直接执行	stdin/stdout NDJSON
docker	docker pull	docker run -i	stdin/stdout NDJSON
wasm	下载 .wasm	内嵌加载 (wazero)	函数调用适配

binary 和 bun 的 IPC 协议完全一致（都是 stdin/stdout NDJSON），差别只在安装和启动命令。

pinixd 内部架构

pinixd
├── ProviderStream → Hub
├── RuntimeStream → Hub
└── ClipManager
    ├── BunHandler    implements ClipHandler
    ├── BinaryHandler implements ClipHandler
    ├── DockerHandler implements ClipHandler
    └── WasmHandler   implements ClipHandler

ClipHandler 接口

type ClipHandler interface {
    Install(manifest ClipManifest) error
    Remove(clipId string) error
    Start(clipId string, config ClipConfig) (ClipConn, error)
    Stop(clipId string) error
}

type ClipConn interface {
    Send(msg Message) error
    Recv() (Message, error)
    Close() error
}

ClipManager 的核心逻辑（crash recovery、invoke 路由、心跳）不需要知道具体 Runtime 类型。

pinix.json runtime 字段

{ "runtime": "bun", "entry": "index.ts" }
{ "runtime": "binary", "entry": "clip-monitor", "artifacts": {"darwin-arm64": "https://..."} }
{ "runtime": "docker", "image": "ghcr.io/epiral/clip-sandbox:latest" }
{ "runtime": "wasm", "entry": "clip-compute.wasm" }

SDK 分层

消息协议规范 (NDJSON schema) ← 唯一真相源
    ├── @pinixai/core (TypeScript) — 已有
    ├── pinixai-go-sdk (Go) — binary Clip 用
    └── pinixai-rust-sdk (Rust) — 按需

所有 SDK 实现同一套 NDJSON 消息协议。

实现路线

阶段	做什么	理由
Phase 1	重构 pinixd：Bun 代码抽成 BunHandler + ClipHandler 接口	纯重构，不加功能
Phase 2	BinaryHandler + Go SDK (pinixai-go-sdk)	Go 开发者享受托管体验
Phase 3	DockerHandler / WasmHandler	按需求

不做的

• 不为每种语言搞一种 Runtime（其他语言编译成 binary 或 wasm）
• runtime 字段不无限扩展，四种足够
• WASM 不需要独立 SDK，用任何语言编译到 WASM target 即可
• Remote 不是 Runtime 类型，走 Provider 协议

前置

依赖 #30（Runtime 与 Provider 协议分离）