内容
# termrender
终端截图，**完美复制您的真实终端** — 您的 shell、iTerm2 颜色和字体，以及程序的真实彩色输出。暗黑或亮色模式自动跟随您的系统。
```bash
termrender exec --theme auto --window-bar rings -o demo-basic.png -- echo "Hello, termrender!"
```
大多数终端到图像的工具都会渲染您提供的文本，使用通用主题且没有提示。termrender 相比之下，**在真实的 PTY 中运行命令**，并**请求您的 shell 渲染其提示**，因此截图看起来就像您在终端中实际看到的一样。上面的图像使用单个命令生成 — 您真实的 fish 提示、iTerm2 颜色和命令的输出，全部自动捕获。
基于 [termless](https://github.com/beorn/termless) 构建，用于无头终端模拟和 PNG 渲染。
## 安装
需要 [Bun](https://bun.sh)。
```bash
bun install
bun link # 注册全局 `termrender` 命令 (~/.bun/bin)
```
## 使用
### `exec` — 运行命令并截图（最高保真）
```bash
termrender exec --theme auto -o ls.png \
--window-bar rings -- eza -la
# 固定提示样式和工作目录
termrender exec --prompt fish --cwd ~/some/repo -o git.png -- git log --oneline -5
```
| 选项 | 默认值 | 描述 |
| --- | --- | --- |
| `--prompt <mode>` | `auto` | 提示源：`auto`、`fish`、`zsh`、`none`。`auto` 解析终端的真实 shell：iTerm2 配置文件命令 → 登录 shell (`dscl`) → `$SHELL` |
| `--cwd <dir>` | cwd | 命令和提示的路径/ git 分段的工作目录 |
| `--timeout <ms>` | 30000 | 命令退出的最大等待时间 |
| `--no-auto-rows` | — | 保持完整的终端高度，而不是修剪空行 |
| `--no-trailing-prompt` | — | 命令退出后不要重复提示 |
命令必须自行退出 — 对于服务器、监视模式和 TUI，记录一个 `.cast` 文件并使用 `render`。
### `render` — 渲染 `.cast` 文件或管道 ANSI 文本
```bash
termrender render recording.cast -o screenshot.png # cols/rows 来自 cast 文件头
echo -e "\e[32mgreen\e[0m" | termrender render -o out.png
```
### 常用选项
`-o/--output` (`.png`)、`--theme <path|auto>`、`--theme-type`、`--profile <name>`、`--cols/--rows`、`--font-family`、`--font-size`（单元格几何形状随之缩放）、`--padding`（默认 12）、`--border-radius`（默认 8）、`--window-bar none|rings|colorful`、`--margin`、`--margin-fill`。
## 主题源
| 源 | 您得到的内容 |
| --- | --- |
| *(默认值，无 `--theme`)* | **系统主题** — 暗黑或亮色模式自动跟随您的 macOS 外观 |
| `--theme auto` | 您的 **实时 iTerm2 配置文件**：16 色调色板、前景色/背景色/光标、配置文件字体 + 大小。直接读取偏好设置 plist 文件（macOS）— 无需导出步骤 |
| `.itermcolors` 文件 | 完整的导出 iTerm2 颜色方案 |
## 功能
### 🐟 Fish 语法高亮
termrender 使用 fish shell 的标记级算法来为命令、选项、管道和重定向着色，完全按照 fish 的方式：
| 标记 | 颜色 | 示例 |
|---|---|---|
| 命令 | 青色 | `git`、`echo` |
| 选项 | 青色 | `--oneline`、`-la` |
| 管道/运算符 | 洋红色 | `\|`、`&&` |
| 重定向 | 粗青色 | `>`、`>>` |
```bash
termrender exec --theme auto --window-bar rings -o demo-highlight.png -- git log --oneline -5
```
### 🎨 系统感知主题
如果没有 `--theme` 标志，termrender 会根据您的 macOS 系统外观自动选择暗黑或亮色主题。下面它显示了一个目录列表，使用的调色板来自您的实时 iTerm2 配置文件：
```bash
termrender exec --theme auto --window-bar rings -o demo-theme.png -- ls -la
```
### 🪟 窗口栏样式
选择 `rings`（macOS 交通灯）、`colorful`（实心点）或 `none`：
```bash
termrender exec --theme auto --window-bar colorful -o demo-windowbar.png -- echo "termrender"
```
### 🐚 提示样式
使用 `--prompt fish` 或 `--prompt zsh` 来匹配您的 shell 提示。termrender 调用实际的 shell 来渲染提示行 — 路径缩写、git 分支检测和颜色变量都像在您的真实终端中一样工作：
```bash
termrender exec --prompt zsh --theme auto --window-bar rings -o demo-omz.png -- git log --oneline -5
```
## MCP 服务器
`bin/termrender-mcp.ts` 通过两个 MCP 工具向代理公开 termrender — `render_command` 和 `render_text` — 渲染的 PNG 作为图像内容块内联返回，因此代理立即看到结果并可以在同一循环中自我纠正（错误的主题、列未对齐等）。
### 注册
**Claude 代码：**
```bash
claude mcp add --scope user --transport stdio termrender -- bun run /path/to/termrender/bin/termrender-mcp.ts
```
**Codex（OpenAI）：**
```bash
codex mcp add termrender -- bun run /path/to/termrender/bin/termrender-mcp.ts
```
或在 `~/.codex/config.toml` 中：
```toml
[mcp_servers.termrender]
enabled = true
transport = { type = "stdio", command = "bun", args = ["run", "/path/to/termrender/bin/termrender-mcp.ts"] }
```
**OpenCode：**
将以下内容添加到 `opencode.json`（项目根目录）或 `~/.config/opencode/opencode.json`：
```jsonc
{
"mcp": {
"termrender": {
"type": "local",
"command": ["bun", "run", "bin/termrender-mcp.ts"]
}
}
}
```
> **注意**：OpenCode 使用 `"type": "local"`（不是 `"stdio"`）和 `"command"` 作为 **字符串数组** — 这避免了 shell 注入。
## 工作原理
- **真实输出**：`exec` 在 PTY 中生成命令（termless `Terminal.spawn`，Bun 的原生终端支持），因此程序会发出与交互式相同的颜色。
- **真实提示**：提示由实际的 shell 渲染 — `fish -i -c fish_prompt`（需要交互式标志，否则 fish 会跳过其颜色变量），或 `zsh -ic 'print -rP "$PROMPT"'` — 带有正确的 `--cwd`，因此路径和 git 分段是实时的。
- **真实主题**：`--theme auto` 从 `com.googlecode.iterm2.plist` 中提取默认配置文件，逐个键值通过 `plutil -extract` 提取（plist 文件包含会破坏整个文件转换的二进制 blob）。支持 sRGB 和 Display P3 色域。
- **自动调整图像大小**：`exec` 在高屏幕上捕获，计算使用的行数，并将捕获的字节重新输入到内容大小的终端中。
- **系统主题**：`defaults read -g AppleInterfaceStyle` 告诉我们 macOS 是否处于暗黑或亮色模式；相应的内置主题被自动使用。
## 已知限制
- 配置文件字体通过 PostScript 名称匹配；如果光栅化器无法解析它，渲染会回落到捆绑的等宽栈（布局不受影响）。
- CJK 宽字符渲染单元格之间有可见的间隙。
- `--theme auto` 和提示检测以 macOS 为中心（iTerm2 plist、`dscl`）。
## 许可证
MIT
