gPTY

gPTY - 一个基于 Rust 和 Godot 构建的桌面工作区。它提供平铺网格来放置窗格（终端、代码查看器、文件树、Wiki、媒体等）、概念捕获引擎，以及 JSON-RPC/MCP 控制接口，让 AI Agent 和自动化工具能够创建窗格、注入文本并查看终端输出，而无需抓取 TUI。每个窗格都可以通过 Shell、脚本或 Agent 使用同一个公开 API 控制。

概览

功能

窗格

• 平铺网格 - 拆分、调整大小并重新排列独立的 Shell 会话；保存并重新加载命名布局、工作区（标签页组）和配置文件。
• 仿真 - 使用 alacritty_terminal 网格，支持 16/256/true color、带正则表达式搜索的回滚缓冲区，以及自动换行文本选择。
• 记忆 - 重启后恢复回滚缓冲区、设置和工作区，并可对每个窗格的历史记录进行全文搜索。
• 文件树 - 原生 Godot OS 文件树浏览器。
• 代码查看器 - 渲染文本和 Markdown。
• Wiki - 一个纯 Markdown 笔记库，支持全文搜索、实时预览编辑器、[[wikilinks]]、反向链接和链接图，并会在你上次离开的位置重新打开。随附的 知识库 配置文件会在发布版本中打开内置 Wiki。观看窗格导览。
• 媒体 - 通过固定版本的精简 FFmpeg 后端（v0.7），在窗格中播放本地音频和视频。
• cli_view - 将任意命令的输出流式传输到窗格，让插件无需 Godot SDK 即可添加 UI。

Agent 与自动化

• 一个 API，三种入口 - 相同操作可通过 JSON-RPC 套接字、gpty CLI 和 MCP 服务使用：创建窗格、注入输入、读取输出、运行命令并等待特定模式，以及向带标签的窗格广播。该服务已以 io.github.godot-pty/gpty 的名称列入 MCP 官方注册表。
• Agent 状态徽章 - Agent 可在自己的窗格中声明 working 或 needs attention，并显示在标签页上。仅供显示。
• 可观测性窗格 - Reasoning 被动显示有文档记录的 Agent 生命周期事件（目前为 OMP，词汇不依赖适配器）；Inspector 是私有的、无工具的问答会话。gPTY 从不编排 Agent 状态。
• 概念 - 终端输出中的正则表达式触发器会捕获回复，并将其路由到相邻窗格。你可以在设置中手动编写，也可以使用可视化图编辑器创建。概念仅供显示；它们不会向 Shell 输入内容。

可扩展，但有限制

• 插件 - 基于清单，安装前需在 GUI 中审核，并设有公开的注册表。
• 书面威胁模型 - 请参阅 SECURITY.md。发布版本附带 SHA256SUMS 和构建来源证明；控制套接字仅供所有者访问。

状态

gPTY 是一个正在积极开发中的业余项目。本代码库绝大部分内容，包括大部分 Godot UI 布局和 Rust（gpty-core）GDExtension 桥接层，都是在人工审核下使用大模型生成的；因此，底层代码可能包含不符合惯例的写法和／或 bug。路线图和文档：https://gpty.dev/

组件	选择	原因
PTY 库	portable-pty	跨平台（Linux /dev/ptmx + Windows ConPTY），且使用统一 API
ANSI 解析	vte crate	快速的 Rust ANSI 状态机
异步运行时	tokio	每个终端对应一个任务；由通道驱动的捕获状态机
I/O 线程	每个 PTY 使用专用的 std::thread	阻塞读取行为可预测；通过 mpsc 桥接到 tokio
概念捕获	使用 Rust regex 匹配已解析的 LineParser 输出	线性时间匹配（可防止 ReDoS）；捕获缓冲区会存储原始字节，以便忠实还原网格
网格渲染	alacritty_terminal	完整的 DEC STD 070 网格状态机；将数组传给 Godot _draw()
Godot 桥接	gdext 0.5	适用于 Godot 4.7+ 的原生 GDExtension
Rust 版本	2024	需要 Rust >= 1.85

---

安装与使用

Linux、macOS 和 Windows 的独立二进制文件（无需安装 Godot）已发布在 GitHub Releases。

平台	软件包
Linux	gpty-v<version>-linux-x86_64.tar.gz - 解压；运行 ./gpty-gui.sh 启动 GUI，./gpty 是命令行工具
macOS	gpty-v<version>-macos.zip - 解压，右键点击 .app → 打开；旁边的 gpty 是命令行工具
Windows	gpty-v<version>-windows-x86_64.zip - 解压；运行 gpty-gui.exe 启动 GUI，gpty.exe 是命令行工具

每个版本也都附带 gPTY 知识库；侧边栏中的 知识库 配置会从用户数据中打开随附的 wiki。

在文件名中，<version> 是你下载的版本标签（例如 v0.7.0）。

每个版本都会发布一个 SHA256SUMS 文件，列出所有资源。运行下载的文件前，请先检查：

sha256sum -c SHA256SUMS            # Linux
shasum -a 256 -c SHA256SUMS        # macOS
certutil -hashfile <asset> SHA256  # Windows

校验和可以检测下载过程中是否发生文件损坏或篡改。每项资源还附带构建来源证明，将其与构建它的工作流运行关联起来：

gh attestation verify <asset> --repo godot-pty/gpty

这些二进制文件未经代码签名（参见 SECURITY.md）。

命令行工具

gpty 二进制文件通过 JSON-RPC IPC 控制正在运行的 GUI，每个发布包都会将它与 GUI 一同打包。它也发布在 crates.io 上；运行 cargo install gpty 会将同一二进制文件安装到 PATH（需要 Rust 工具链和 C 编译器，因为其中打包了 SQLite），MCP 客户端启动 gpty mcp 时使用的就是该副本。对于新工作区能够满足的命令，命令行工具只会按需启动一个实例——new-pane 和 layout load；而 gpty daemon start 会显式启动一个实例，--no-daemon 则绝不会启动实例。其他所有命令都需要已有工作区，因此会报错 no gpty GUI is running (start one with \gpty daemon start`)，而不会打开无法使用的窗口。只有在开发命令行工具本身时才需要从源码构建（cargo build -p gpty或cargo build --workspace）；如果你通过这种方式安装，**版本升级后请重新安装**（cargo install --path crates/gpty-cli --force）。如果较旧的 gpty在PATH` 中排在前面，就会遮蔽发布包中的命令行工具，并导致不明原因的失败（它不支持的子命令会在任何 IPC 发生前由 clap 直接终止）。因此，当命令行工具发现正在运行的 GUI 版本或 IPC 协议与自身不同时，会在标准错误输出中警告一次，指出双方的版本或协议；但解决办法是重新安装。

GUI 正在运行后（通过 Godot 或发布版二进制文件启动），命令行工具会通过 Unix 套接字连接（Linux 上为 $XDG_RUNTIME_DIR/gpty.sock，或使用 GPTY_SOCKET 环境变量）：

# Check if the GUI is running (exit 1 when it is not)
gpty daemon status

# Print the bundled agent skill (for coding agents running inside a pane)
gpty --skill

# Declare this pane's agent state, from inside the pane (display only)
gpty state working

# Spawn a new terminal pane
gpty new-pane --pane-type terminal

# List all active panes
gpty list-panes

# Send text to a pane (by label, e.g. T1)
gpty inject T1 --text "echo hello"

# Read a pane's screen and scrollback; run a command in a new pane and wait for its output
gpty pane-read T1 --lines 200
gpty pane-run --command "cargo test"
gpty pane-wait T1 --pattern "tests passed" --timeout-ms 30000

# Search and read a wiki vault
gpty vault search <vault> <pattern>
gpty vault read <vault> <path>

# Close a pane
gpty kill-pane T1

# Save and load named layouts
gpty layout save my-setup
gpty layout load my-setup
gpty layout list

# Install a plugin (reviewed in the GUI - its actions run as you)
gpty plugin install godot-pty/gpty-omp
gpty plugin list

# Manage the GUI daemon
gpty daemon start
gpty daemon status
gpty daemon stop

# Generate AI tool manifests (no GUI needed)
gpty schema
gpty schema --format mcp

# Run as MCP server over stdio (no GUI needed)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | gpty mcp

运行 gpty --help 查看所有子命令和标志。

MCP 集成

gpty 附带 MCP（Model Context Protocol）服务，供 AI Agent 和编码工具链控制工作区。仓库根目录中的 mcp.json 会声明该服务，以便自动发现：

{"mcpServers": {"gpty": {"command": "gpty", "args": ["mcp"]}}}

• 直接运行：通过标准输入/输出运行 gpty mcp，为每个 CLI 子命令提供一个工具（new-pane、list-panes、kill-pane、focus-pane、inject、pane-read、pane-status、pane-run、pane-wait、broadcast、vault-search、vault-read、vault-weight、layout-*、daemon-*、concept-*、version）。
• 清单：gpty schema --format mcp 会输出 MCP 工具清单（JSON Schema，无需运行中的 GUI），可交由 Agent 配置使用。

工具的 Schema 与 CLI 一样，均由 clap 定义生成（crates/gpty-cli/src/commands/schema.rs），因此不会与 gpty --help 不一致。

---

路线图

请参阅 ROADMAP.md，了解已发布、进行中和计划中的内容，每个发布系列各有一页。

---

安全

请参阅 SECURITY.md，了解威胁模型、报告流程，以及 gpty 不防范的风险。实施规则——包括 Concept Engine 对 ReDoS 的处理原则、PTY 环境清理、IPC 加固和 OSC 52 限制——见安全规则。

---

贡献

请参阅 CONTRIBUTING.md，了解设置说明、构建命令、测试、代码风格和拉取请求流程。

---

更新日志

请参阅 CHANGELOG.md，了解完整的版本变更和历史记录。

---

许可证

gPTY 是自由软件，依据 GNU 通用公共许可证第 3 版或更高版本授权——完整条款请见 LICENSE。

LICENSE-EXCEPTIONS.md 根据该许可证第 7 节增加了两项许可，使生态系统部分保持宽松：

• 插件、扩展和适配器无需采用 GPLv3。 任何通过 gPTY 的 CLI、JSON-RPC、MCP 或事件接口（包括原生窗格类型）与其协作的内容，都可以采用 Apache-2.0、MIT 或你选择的任何其他条款授权，并可与 gPTY 一同分发，无需承担额外义务。
• 配置和数据文件不受著佐权约束。 配置档案、工作区、布局、概念和设置的许可方式由你决定；gPTY 随附的默认 *.json 文件采用 Apache-2.0 授权。

版权所有 (C) 2026 Neil Pathare。

发行 gPTY 希望它能有所帮助，但不提供任何担保，也不对终端用户的任何使用承担责任；甚至不提供适销性或特定用途适用性的默示担保。详情请参阅 GNU 通用公共许可证。