# @gespenst/core 中文文档

规范地址：https://npmcn.com/package/%40gespenst/core/

版本：0\.2\.0
npm 元数据更新时间：2026-10-28T07:26:57.540Z
中文译文更新时间：2026-11-16T05:34:36.264Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gespenst/core
原文对照：https://npmcn.com/package/%40gespenst/core/?lang=original
项目主页：https://gespenst.dev/
源码仓库：https://github.com/tobilg/gespenst

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.6 MB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：0 个
- 首次发布：2026-08-26T10:53:40.144Z
- 最新版本发布：2026-10-28T07:26:57.127Z
- 近 30 天下载量：4715（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

TypeScript 和网络的快速 Ghostty 驱动终端模拟器

## 安装

```sh
npm install @gespenst/core
```

也可以使用：`pnpm add @gespenst/core`、`yarn add @gespenst/core`、`bun add @gespenst/core`

## README

# @ gespensst/ 调值

一个高性能浏览器终端和无头 VT运行时间 由官方夜间供电 [`ghostty-vt.wasm`](https://github.com/ghostty-org/ghostty/releases/download/tip/ghostty-vt.wasm)。 。 。 .

文档、指南和现场演示: **[(原始内容存档于2018-10-21). gespent.dev](https://gespenst.dev/)**

本地API面向字节并围绕Web Streams而建. 浏览器终端使用工人 当可用时, 选择 WebGPU、 WebGL2 或运行时的 Canvas 2D, 并保留应用程序政策 在制造器外面.

> 幽灵的 `tip` 艺术品是夜造的 每个已出版的软件包版本的针和检查和 an 确切的文物。 在部署前将这个软件包版本固定在生产和测试升级中.

## 安装

```sh
pnpm add @gespenst/core
```

## 浏览器终端

导入样式表并给主机一个清晰的高度 :

```html
<div id="terminal"></div>

<style>
  #terminal {
    width: 100%;
    height: 32rem;
  }
</style>
```

```ts
import { createTerminal } from '@gespenst/core';
import '@gespenst/core/style.css';

const terminal = await createTerminal({
  container: document.querySelector<HTMLElement>('#terminal')!,
  worker: 'dedicated',
  renderer: 'auto',
});

terminal.write('\x1b[1;32mGhostty is ready\x1b[0m\r\n');
terminal.focus();
```

默认工人政策选择一个专职工人,当 `Worker` 财务报告和审定财务报表 `OffscreenCanvas` 为: 可用,如果工人启动失败,则重试主线。 自动渲染器尝试 WebGPU, 然后WebGL2,然后Canvas 2D用于单元格背景,然后在加速时向下移动 后端无法在运行时恢复 。 浏览器 Canvas 2D 在每个渲染器路径上塑造文本 。 发布运行 chrimium 的完整浏览器套件,以及Firefox和WebKit中的重点API兼容性测试; 3; 硬件 WebGPU 可用性不需要,因为渲染器会自动倒回.

## 连接 PTY

核心接受双向字节流,而不强制服务器协议 :

```ts
const connection = terminal.connect({
  readable: ptyOutput, // ReadableStream<Uint8Array>
  writable: ptyInput, // WritableStream<Uint8Array>
});

terminal.on('resize', ({ cols, rows }) => {
  sendPtyResize({ cols, rows });
});

await connection.closed;
```

将 PTY 字节保留为 `Uint8Array` 从套接字到Ghostty的数据。 使用 `@gespenst/websocket` 用于现成的二进制 WebSocket 传输,并调整消息大小, 后压,以及可选的再连接行为.

## 布局和字体

终端填充主机,因此主机必须具有非零宽度和高度. A 类 `ResizeObserver` 将网格与容器变化相匹配。 打电话 `fit()` 显示隐藏标签中创建的终端后 或对话.

默认字体堆栈使用已安装的系统单空间字体. 自定义字体具有灵活性, 不使用 来源于预定义的列表 :

```ts
await terminal.loadFont({
  family: 'JetBrains Mono',
  source: 'url(/fonts/jetbrains-mono.woff2)',
  descriptors: { weight: '400 700' },
});

await terminal.setFont({
  family: 'JetBrains Mono, ui-monospace, monospace',
  sizePx: 14,
  lineHeight: 1.25,
});
```

`loadFont()` 在文档和渲染器中安装面相 重新测量.

## 主题

主题使用便携式 CSS 字符串或 RGB(A) 对象,并包括命名为 ANSI 的xterm相容性, 选择,以及光标的颜色。 安装 `@gespenst/themes` 用于审计的可动摇树的预设:

```ts
import { catppuccinMocha } from '@gespenst/themes/catppuccin-mocha';

await terminal.setTheme(catppuccinMocha); // replaces the current theme
await terminal.updateTheme({ cursor: '#ffffff' }); // patches it
```

启用 `allowTransparency` 当非选择的颜色使用α时创建。 设定 `minimumContrastRatio` 当需要自动文本对比时。 缺少扩展的 ANSI 颜色为 由Ghostty生成一次,而不是在单元格递归回路中计算出一次.

## 配置基线

```ts
const terminal = await createTerminal({
  container,
  worker: 'dedicated',
  renderer: 'auto',
  scrollbackLines: 10_000,
  accessibility: 'basic',
  minimumContrastRatio: 1,
});
```

-   使用 `worker: 'shared'` 当许多终端共享一个工作事件循环时.
-   使用 `worker: false` 用于确定主线行执行或不支持的环境.
-   使用 `accessibility: 'full'` 当产品需要现场取景口文本镜时.
-   读取 `terminal.renderer.backend` 以查看实际选择哪个渲染器.
-   许多并行终端或内存受限设备的下回滚.

## 应用政策

终端逃生序列可以请求剪贴板写作和桌面通知. 核心发射 类型 `clipboardWrite` 财务报告和审定财务报表 `notification` 事件但不执行这些浏览器动作 自动。 版本0.1.0 拒绝远程剪贴板写入; 使用 `clipboardWrite` 仅作为审计 记录。 在显示通知前验证会话信任、用户意图和浏览器权限 .

对于用户启动的文本和 MIME 粘贴, 安装 `@gespenst/clipboard`。它保持剪贴板支持 禁用到加载加载, 支持 Kitty 模式 5522 粘贴事件, 拒绝远程写入 , 在不安全的文本可以绕过正常的粘贴安全之前,需要应用确认钩. 见 [剪贴板指南](https://npmcn.com/package/docs/core/clipboard.md)。 。 。 .

每个 `on()` 调用返回一次性订阅。 通话 `terminal.dispose()` 关闭活动 连接、处理添加、删除听众和已装入的字体、释放渲染资源以及 终止所有工人.

## 缓冲和视图状态

使用页面缓冲 API 来进行滚动条、搜索、链接、记录视图和兼容层:

```ts
const visible = await terminal.readBuffer();
const history = await terminal.readBuffer({
  start: 0,
  end: visible.state.totalRows,
});

terminal.on('viewportChange', ({ state: { viewportY, totalRows, viewportLength } }) => {
  updateScrollbar({ viewportY, totalRows, viewportLength });
});
```

行直接从Ghostty的活性格读取; Gespenst 不运行第二个 VT 剖析器. 范围 半开并被夹住. `viewportY` 编辑 `scroll` 事件使用绝对零取自 最古老的保留行。 在热路径上只打印行需要的特性 .

## 无头运行时间

```ts
import { createCoreRuntime } from '@gespenst/core/headless';

const runtime = await createCoreRuntime();
const terminal = runtime.createTerminal({ cols: 100, rows: 30 });

terminal.write('\x1b[34mParsed by Ghostty VT\x1b[0m\r\n');
const text = terminal
  .viewport()
  .viewportRows.map((row) => row.text)
  .join('\n');

console.log(text);
runtime.dispose();
```

重用一个 `CoreRuntime` 对于多个终端,所以他们共享编译的Ghostty模块. 这个 无头运行时间工作没有DOM 并暴露解析细胞,脏行,光标状态,效果, 选择、快照和输入编码.

## 业绩做法

-   保持输出字节本地化并避免解码-编码周期.
-   使用 `writeAsync()` 当生产者需要解析和渲染边界时.
-   保存有意义的运输块,而不是一次写一个字节.
-   在输出热道上将回转并避免频繁取景或快照读取.
-   首页d `readBuffer()` 区域重建所有保留回滚.
-   量身定做和共享的工人 与真正的终端计数和输出程序.

工作空间基准旨在进行有控制的比较,而不是一项普遍的吞吐量主张:

```sh
pnpm bench:throughput
```

## 文档

-   [核心指南](https://github.com/tobilg/gespenst/blob/main/docs/core/index.md)
-   [工作空间和软件包概览](https://github.com/tobilg/gespenst)
-   [PTY 浏览器示例](https://github.com/tobilg/gespenst/tree/main/examples/pty)

核心指南涵盖PTY架构,每个配置组,字体和主题,事件政策, 性能测量,无头使用,xterm.js迁移,和故障排除.

## 许可证

麻省理工学院. 卖家Ghostty WASM持有麻省理工学院的执照 `THIRD_PARTY_NOTICES.md`。 。 。 .

## 常见问题

### @gespenst/core 是什么？

TypeScript 和网络的快速 Ghostty 驱动终端模拟器

### 如何安装 @gespenst/core？

在项目目录运行 npm install @gespenst/core，或使用 pnpm add / yarn add / bun add。

### @gespenst/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gespenst/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gespenst/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gespenst/core 可以商用吗？

@gespenst/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gespenst/core 的下载量有多少？

根据 npm 官方下载统计，@gespenst/core 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,715 次，日均约 157 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gespenst/core 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/28（18 天前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

