UniPty

面向 Node、Bun、Deno 的运行时无关 PTY —— 一套公共契约，可由开发者显式选择的 Backend。

English | 简体中文

Node、Bun、Deno 各自暴露了不同的 PTY 底层实现——安装模型、I/O 表示、生命周期语义、原生部署约束都不同。UniPty 把这些收敛为一套小而诚实的契约：应用显式选择 Backend，所有底层差异都留在 Core 私有的接缝之后。没有隐式 shell 执行，不会静默回退到管道，也不做运行时替换。

安装

Core 加上一个你选定的 Backend——装哪个包，就得到哪个引擎：

不知道选哪个引擎？下方「选型」一节的能力差异矩阵会告诉你每个引擎到底给你什么。

快速上手

import { UniPty } from "unipty";
import { createNodePtyBackend } from "@unipty/backend-node-pty";

const backend = await createNodePtyBackend(); // 一次性就绪
const unipty = new UniPty({ backend });

const pty = unipty.spawn(["/bin/sh", "-i"], {
  cwd: process.cwd(),
  terminal: { cols: 120, rows: 40 },
});

for await (const text of pty.stream({ encoding: "utf8" })) {
  process.stdout.write(text);
}
pty.write("echo hello\n"); // 布尔写入就绪——语义见契约速览
pty.resize(80, 24); // 仅字符单元格
pty.terminate(); // 终止请求，绝不级联 close
pty.close(); // 传输关闭，绝不杀死子进程
const { exitCode, signal } = await pty.exited; // 独立观察

换引擎只是一行改动——上面所有代码在每条路由上完全一致： createZigptyBackend()（zigpty）、createBunBackend() （bun）或 createDenoSigmaPtyFfiBackend() （deno）。引擎专属行为（选项、权限、 能力差异）见各包 README。

契约速览

你能调用的一切，以及它的确切承诺：

四个最常被设计出来「防坑」的行为：

• 结构化启动 —— Bun 风格 spawn(argv, options)，argv 为非空参数向量。没有字符串命令重载、没有隐式 shell；元字符只是普通数据。
• 表示选择的流 —— pty.stream({ encoding: "utf8" | "bytes" })。UTF-8 视图优先使用原生文本，否则增量解码字节；字节视图只产出原生字节——重新编码的文本绝不冒充原始输出。
• 布尔写入就绪 —— write() 返回 false 的含义是「暂停并等待 drain()」，绝不是「重试」；饱和时以类型化的 backpressure 失败拒绝整个值。绝不部分接受、绝不静默丢弃。
• 非级联生命周期 —— close() 绝不杀子进程，terminate() 绝不关传输，exited 在两者之后依然有效。unipty.dispose() 立即阻止新 spawn，等待所有存活 PTY 关闭后恰好一次释放 Backend。

选型

官方路由

Node 路由适配的是第三方库——不是 Node 运行时原生 API，文档绝不如此宣称。Deno 只是最后一条路由的运行时元数据，不是其实现身份。

引擎能力差异（各底座实际给到什么）

每条路由的公共契约完全一致——结构化 argv、几何尺寸与 resize、写就绪 + drain + 饱和整值拒绝、非级联 close/terminate、bootstrap 缓冲、公共错误码。但底层引擎并不相同。选路由前请先看这张如实差异表：✓ 开箱即用，⚠ 需要选项或带有已声明的限制，✗ 不提供。

所有路由上 exec 失败都是退出观察（绝不是 spawn 异常）；各适配器的细节见各自包的 README。

获取 Backend

手动导入是一等路径——Core 永远不需要获取层：

const backend = await createBunBackend(); // 或任意官方工厂
const unipty = new UniPty({ backend });

需要确定性发现时，@unipty/backend 将工作分段：纯解析（不导入）、仅元数据检查（不初始化）、然后是选定候选的初始化——其失败是终止性的且结构化的：

import { autoResolveUniPtyBackend } from "@unipty/backend";

const backend = await autoResolveUniPtyBackend({
  candidates: ["@unipty/backend-node-pty"], // 有序偏好
  from: import.meta.url, // 调用方为根的基址
});

打包部署场景改为提供显式不可变 manifest（defineUniPtyBackendManifest()）， 由 unipty-helper-backend manifest --candidate <pkg> --out backend-manifest.ts 生成。完整分段契约见获取层 README。

架构（60 秒版）

application code
   │  public contract (spawn / stream / write / resize / lifecycle / exited)
   ▼
UniPty Core ──── owns every observable behaviour: views, conversion,
   │             bootstrap buffering, backpressure, errors, lifecycle state
   ▼
Ready Backend ── one injected, already-ready object per UniPty instance
   │             (native loading / connection / negotiation finished first)
   ▼
real PTY on node-pty / zigpty / Bun.Terminal / @sigma/pty-ffi

读代码前值得知道的设计原则：

• 底座诚实。 每个适配器都如实记录底层的真实行为（kill-and-close 原语、无界内部缓冲、信号不透明），而不是粉饰；支持声明证据门控——一个元组只有针对已安装制品跑完整公共契约全过才算 verified，发布目录是唯一事实源。
• 无隐藏策略。 没有隐式 shell、没有静默管道回退、没有第二套插件注册表、没有能力/资产协议。扩展点都是显式的：Backend wrapper 与不透明能力 token（pty.capability(token)，按对象身份匹配）。

完整设计叙事见架构设计.md。

包一览

一致性与兼容性证据

每一条支持声明都经过同一接缝：公共一致性套件针对已安装的包制品运行（pack、安装进隔离消费者、只经公共导出驱动）。原生全量通过产出一条正向 Verification Evidence 记录；确定性聚合器校验身份/元组/提交唯一性并产出发布目录，文档站点原样消费它。失败只是 CI 诊断——绝不会变成永久的「不支持」声明。当前发布的逐元组事实见兼容性目录。

本地运行：

pnpm --filter @unipty/conformance run conformance --backend node-pty --emit-evidence

文档地图

按意图找去处：

路线说明：v1 聚焦 PTY；持久化、重连、远程主机属于可替换 Backend 与 wrapper，而不是第二套插件生命周期。

开发

corepack pnpm install
pnpm build && pnpm typecheck && pnpm test
pnpm --filter @unipty/backend-zigpty test   # zigpty 套件（真实 PTY）
pnpm --filter @unipty/backend-bun test      # Bun 套件（需要 Bun）
cd packages/backend-deno-sigma__pty-ffi && deno test -A test/   # Deno 套件
pnpm check:arch                             # 包图所有权规则

许可证

MIT