socket-pty
@ai-zen/socket-pty 是一个跨平台 PTY 传输层。它启动一个真实的终端进程（bash、vim、node -i 等），将其暴露为一个网络端点；任何能建立 socket 连接并遵循 JSON-RPC 2.0 的客户端，均可对该终端进行读写。
- 真实屏幕：以
@xterm/headless渲染终端当前真实画面（所见即所得），而非无限历史日志。 - 薄能力本体：主入口只暴露能力与协议，不掺入入口适配；MCP 适配作为独立子路径。
- 单一事实来源：本仓库
docs/是文档唯一来源，website 只做聚合呈现。
特性
- 跨平台：Unix domain socket（Linux/macOS）与 TCP loopback（Windows 首选）。
- 标准协议：socket 上每行一条 JSON-RPC 2.0 报文，以
\n分帧。 - 客户端与后端解耦：只依赖
IPtySession抽象，默认用node-pty，便于测试注入 mock。 - MCP 适配：可作为 MCP server（stdio）暴露终端操作工具。
入口
包提供两个入口：
| 入口 | 内容 | 用途 |
|---|---|---|
@ai-zen/socket-pty（主入口 .） | PtyServer / PtySession / createSocketPty / 协议与类型 | 以程序化方式启动/持有终端服务 |
@ai-zen/socket-pty/mcp（./mcp） | serveMCP / MCPManager / ConnectionPool | 作为 MCP server 暴露终端操作工具 |
核心概念
端点（endpoint）
端点是被托管终端所监听的网络位置，有 unix 与 tcp 两种形态：
- Unix domain socket：
{ type: "unix", path: "/path/to.sock" }，地址unix:/path/to.sock。 - TCP loopback：
{ type: "tcp", port: 5174, host: "127.0.0.1" }，地址tcp:127.0.0.1:5174。
端点地址由启动方显式指定（--socket / --port 二选一）。连接一个终端的前提是已知其地址；serve / createSocketPty 不自动分配地址。仅 MCP 的 spawn 作为特例会自分配本机临时端点并返回。
协议
socket 上每行一条 JSON-RPC 2.0 报文：
jsonc
请求: {"jsonrpc":"2.0","method":"pty/read","params":{},"id":7}
成功: {"jsonrpc":"2.0","result":{...},"id":7}
失败: {"jsonrpc":"2.0","error":{"code":-32601,"message":"..."},"id":7}- 请求必须含
id（string 或 number）；不支持通知（无id的请求被拒绝）。 - 每个请求对应一个响应，响应回显同一
id。 params必须是对象。
屏幕语义
- 屏幕由服务端（端点侧）用 xterm-headless 维护，是终端的当前真实画面。
pty/read返回当前整个屏幕（rows行），不是历史日志——滚动出屏外的内容不会出现。pty/read可截取当前屏的部分行（top/bottom或start+end）。- 客户端断开不影响终端继续运行；重新连接仍可读到当前画面。
会话生命周期
- 常驻：
serve/spawn启动的进程独立常驻，客户端断开重连不影响其存活与当前屏幕。 - 终止：
pty/kill终止会话并关闭端点；之后端点不可再连接。 - 清理：Unix socket 端点关闭时，对应 socket 文件被移除。