forktty

<div align="center"> <img src="packaging/linux/icons/forktty.png" alt="ForkTTY" width="80" /> # ForkTTY **Linux 原生多代理终端，具备可编程本地套接字 API、一流的 Git 工作树和感知提示的通知。** ForkTTY 在隔离的工作空间中运行编码代理，暴露用户本地的 Unix 套接字用于自动化，并可以将长期运行的任务放置在专用的 Git 工作树中，而不将 UI 与一个代理供应商绑定。 [](LICENSE) [](https://github.com/Lucenx9/forktty/actions) [](https://github.com/Lucenx9/forktty/releases/tag/v0.2.0-alpha.14) [](https://rustup.rs/) [](docs/native-gtk-ghostty.md) [网站](https://forktty.dev/) · [文档](https://forktty.dev/docs) · [代理上下文](https://forktty.dev/llms.txt) · [下载 v0.2.0-alpha.14 AppImage](https://github.com/Lucenx9/forktty/releases/download/v0.2.0-alpha.14/forktty-0.2.0-alpha.14-x86_64.AppImage) </div> > **状态**: 早期 alpha 版本（v0.2.0-alpha.14）。ForkTTY 仅支持 Linux，GTK/Ghostty 运行时现在是主要实现。AppImage 是此 alpha 版本的主要 Linux 下载；Debian 软件包仍然可用于 Debian/Ubuntu 用户。 完整的用户指南，请阅读 [forktty.dev/docs](https://forktty.dev/docs)。 对于面向代理的检索，请从 [llms.txt](https://forktty.dev/llms.txt) 或单个文件 [llms-full.txt](https://forktty.dev/llms-full.txt) 开始。本 README 主要关注项目概述、安装路径、快速入门和贡献者命令。 <p align="center"> <img src="docs/assets/forktty-alpha14.png" alt="ForkTTY with embedded Ghostty panes, workspace sidebar, split terminals, and agent status indicators" width="960" /> </p> ## 为什么选择 ForkTTY - **代理无关的自动化**：相同的套接字 API 和 CLI 流适用于 Codex、Claude Code、Antigravity CLI、OpenCode、旧版 Gemini CLI、shell 脚本和自定义工具。 - **一流的工作树工作流**：通过本地 `git2` 操作和可选的 `.forktty/setup` / `.forktty/teardown` 钩子，创建、附加、删除和合并隔离的工作树工作空间。 - **原生 Linux 终端栈**：GTK4/libadwaita shell，带有嵌入的 Ghostty 支持的终端、分割窗格、会话恢复、通知、命令调色板、设置和 quake 模式。 - **本地优先的姿态**：无崩溃报告或产品事件跟踪，一个匿名的每日使用情况探测，可以禁用，owner-only Unix 套接字权限，有界请求/会话/配置文件和 argv-based 命令执行。可选的更新检查每天最多命中 GitHub Releases 一次，也可以禁用。 ## 安装 最快的路径是从 [v0.2.0-alpha.14 版本](https://github.com/Lucenx9/forktty/releases/tag/v0.2.0-alpha.14) 获取预构建的产物。 每个版本都包含： - `forktty-0.2.0-alpha.14-x86_64.AppImage` — 推荐的便携式 Linux 软件包。 - `forktty-0.2.0-alpha.14-x86_64.AppImage.zsync` — AppImage delta-update 元数据，供外部 AppImage 管理器使用。 - `forktty_0.2.0.alpha.14_amd64.deb` — Debian/Ubuntu 软件包。 - `SHA256SUMS` — 发布产物的校验和。 下载后，验证校验和： ```bash sha256sum -c SHA256SUMS ``` ### AppImage ```bash chmod +x forktty-0.2.0-alpha.14-x86_64.AppImage ./forktty-0.2.0-alpha.14-x86_64.AppImage ``` AppImage 始终包含 vendored libghostty-vt 库，并优先使用主机的 GUI 栈：当主机提供 GTK4 时，ForkTTY 运行在系统的 GTK4/libadwaita 上，以获取原生光标主题、fontconfig 和 portal 集成，并且仅在没有 GTK4 的主机上使用捆绑的 GTK 副本作为后备。它依赖于主机系统获取 glibc、GSettings/GIO 数据树、Wayland/X11 会话服务、fontconfig、OpenGL/Vulkan/Mesa 驱动栈和桌面通知服务。 它是 alpha 版本的主要可下载产物，适用于大多数现代发行版，但仍应在目标发行版/桌面环境上进行测试后再依赖。 ForkTTY 默认情况下每天最多检查 GitHub Releases 更新一次。AppImage 安装可以在确认后就地更新：ForkTTY 下载新的 AppImage 和 `SHA256SUMS`，验证 SHA256，然后原子替换当前文件。非 AppImage 安装打开发布页面而不是更新。像 Gear Lever 这样的 AppImage 管理器继续有效，当它们从稳定的可写 AppImage 路径启动 ForkTTY 时；如果 ForkTTY 看到提取的、只读的或不安全的路径，它会回退到发布页面并让管理器控制。 ForkTTY 默认使用 OpenGL GTK 渲染器（`GSK_RENDERER=ngl`）。如果 AppImage 启动但 GTK 界面渲染不正确，可以使用终端覆盖它： ```bash GSK_RENDERER=gl ./forktty-0.2.0-alpha.14-x86_64.AppImage ``` 仅在万不得已时使用 `GSK_RENDERER=cairo`：软件渲染器较慢，在重度终端重绘下保留更多内存。 ### Debian / Ubuntu (.deb) `.deb` 针对 Debian 13/Trixie 或更新版本和 Ubuntu 24.04 LTS 或更新版本。 Debian 12/Bookworm 版本低于软件包基准线，因为它不提供 libadwaita 1.4+。 ```bash sudo apt install ./forktty_0.2.0.alpha.14_amd64.deb # 或，如果 apt 无法直接读取文件路径： sudo dpkg -i forktty_0.2.0.alpha.14_amd64.deb sudo apt -f install ``` 软件包安装 `forktty` 二进制文件、桌面条目和图标。删除它 (`sudo apt remove forktty`) 会清理 `/usr/bin/forktty` 和桌面集成。 ### 从源代码构建 需求： - Linux - [Rust 1.96+](https://rustup.rs/) - GTK4 和 libadwaita 开发文件 - `git`，Zig 和完整的 Ghostty 源代码子模块，用于 vendored Ghostty 终端库 - 不需要系统 Ghostty 软件包；源代码和打包构建使用固定的 vendored Ghostty 库 开发者仓库检查还期望完整的 Ghostty 源代码子模块： ```bash git submodule update --init vendor/ghostty ``` Debian / Ubuntu： ```bash sudo apt install build-essential libssl-dev libgtk-4-dev libadwaita-1-dev git zig desktop-file-utils ``` Fedora： ```bash sudo dnf install gcc gcc-c++ openssl-devel gtk4-devel libadwaita-devel git zig desktop-file-utils ``` Arch / CachyOS： ```bash sudo pacman -S base-devel openssl gtk4 libadwaita git zig desktop-file-utils ``` 源代码构建需要 libadwaita 1.4+，匹配 Debian 13/Trixie、Ubuntu 24.04 LTS 和更新的发行版软件包。发布 AppImages 捆绑 GTK4、libadwaita 和 gtk4-layer-shell，因此终端窗格不依赖于这些主机软件包。 克隆并运行： ```bash git clone https://github.com/Lucenx9/forktty.git cd forktty git submodule update --init vendor/ghostty scripts/ghostty-gtk-lib-probe.sh --ensure --print-path cargo run -p forktty-ui-gtk ``` 打包构建仅限于 GTK/Ghostty。实验性的 WebKitGTK 浏览器窗格在源代码中保留，但需选择加入 `browser` 功能；它不包含在 AppImage 或 `.deb` 中。 对于显式终端构建，仅使用 `gtk-ghostty` 功能： ```bash cargo run -p forktty-ui-gtk --no-default-features --features gtk-ghostty ``` 对于源代码独有的浏览器实验，安装 WebKitGTK 6 开发文件并选择加入： ```bash cargo run -p forktty-ui-gtk --no-default-features --features browser ``` 在本地构建 Debian 软件包： ```bash bash scripts/build-deb.sh sudo dpkg -i target/packaging/deb/forktty_*.deb ``` `scripts/build-deb.sh` 和 `scripts/build-appimage.sh` 调用 `scripts/ghostty-gtk-lib-probe.sh --ensure --print-path`，并在无法构建、定位或验证 `ghostty-gtk-embed.so` 时失败。验证后的库安装到 `usr/lib` 旁边 `forktty` 二进制文件，因此安装的终端窗格可以通过二进制文件的 RUNPATH 加载它，而无需 `FORKTTY_GHOSTTY_GTK_LIB`。 在本地构建 AppImage（需要 `appimagetool` 在 `PATH` 上，或 `APPIMAGETOOL=/path/to/appimagetool`）： ```bash bash scripts/build-appimage.sh ./target/packaging/appimage/forktty-*-x86_64.AppImage ``` 设置 `APPIMAGE_UPDATE_INFO=1` 时，使用嵌入式更新元数据构建发布样式的 AppImages；这需要 `zsyncmake` 在 `PATH` 上，并发出匹配的 `.zsync` 文件。 AppImage 包含与 `usr/share/doc/forktty/` 内的 ForkTTY 相同的版权/许可信息和第三方通知。 ## 首次运行 ### 检查环境 安装后，确认运行时看起来健康： ```bash forktty --version forktty doctor ``` `forktty doctor` 是一个仅限本地的检查工具。它报告解析的配置、会话、套接字、钩子配置路径和已知的恢复行为，如果环境干净，则退出 0，否则退出 2 并显示明确的警告。 ### 默认工作空间和快捷键 ForkTTY 打开当前目录作为 `main` 工作空间。使用命令调色板进行大多数导航和窗格操作： - `Ctrl+Shift+P`：命令调色板 - `Ctrl+Shift+N`：新建工作空间 - `Ctrl+Shift+O`：打开工作空间 - `Ctrl+Shift+H`：向右分割窗格 - `Ctrl+Shift+E`：向下分割窗格 - `Ctrl+Shift+T`：在聚焦的窗格中新建标签页 - `Ctrl+Shift+W`：关闭窗格 - `Ctrl++`/`Ctrl+=`，`Ctrl+-`，`Ctrl+0`：缩放终端窗格 - `Ctrl+B` 或 `F9`：切换工作空间侧边栏 - 代理：标题栏按钮或命令调色板 - `Ctrl+Shift+M`：通知 - `F1`：键盘快捷键 - `Ctrl+,`：设置 ## 套接字 CLI 相同的 `forktty` 二进制文件会讲本地套接字 API。诊断命令即使在 GTK 应用程序运行时也有效： ```bash forktty --help forktty --version forktty doctor # 本地诊断，不需要套接字 forktty ping # 检查正在运行的守护进程 ``` 工作空间、表面、工作树、通知和元数据命令与实时套接字通信： ```bash forktty list forktty focus "Workspace 2" forktty ssh user@example.com forktty surfaces --workspace-name main forktty agents --workspace-name main forktty agent-health --workspace-name main forktty resume-agent --surface-id <surface-id> forktty agent-reclaim-plan --workspace-name main --min-idle-ms 600000 forktty read-screen --surface-id <surface-id> forktty capture-tail --surface-id <surface-id> --lines 80 forktty tree --workspace-name main forktty top --workspace-name main forktty split-surface --axis vertical forktty new-tab forktty send-text "cargo test\n" forktty worktree-status forktty notify --title "Input needed" --kind prompt "Blocked on test fixture" forktty set-status --key agent:codex --label Codex --value Running --color blue forktty set-progress --key build --label Build --value 42 --total 100 forktty statusline forktty log --level warn "Waiting for reviewer input" forktty notifications forktty capabilities forktty events ``` 标题栏代理 HUD 显示在工作空间上持久化的代理会话，突出显示需要输入的会话，可以聚焦或恢复跟踪的代理。`forktty agents`、`forktty agent-health` 和 `forktty statusline` 包括钩子派生的代理生命周期（`running`、`idle`、`needs_input`、`ended` 或 `unknown`），当提供程序会话 ID 已持久化时。`forktty agents` 和 `forktty agent-health` 还公开钩子派生的 `resume_cwd` 和 `last_activity_ms`。对于 Antigravity CLI，`resume_cwd` 来自钩子有效载体的 `workspacePaths`，因为 `agy` 从 `~/.gemini/config` 执行生成的包装脚本，而不是从项目目录。 在 ForkTTY 重启后，带有支持的持久化代理会话的恢复终端窗格通过提供程序的 argv-only 恢复命令重新生成，例如 `codex resume -C <resume_cwd> <session-id>` 当 Codex 钩子元数据记录会话工作目录时。没有 cwd 标志的提供程序（如 Claude Code）以 `resume_cwd` 为子进程目录启动。如果旧的 ForkTTY 会话没有持久化 `resume_cwd`，Codex 恢复仍然可以从 Codex 的本地 `session_meta` JSONL 推断它，当该项目目录仍然存在时。 当提供程序钩子记录确切的 `bypassPermissions` 模式时，ForkTTY 在 `agent-health`、显式恢复和恢复时间自动恢复时保留该提升模式，通过发出记录的 Codex 和 Claude Code 绕过标志；其他权限模式保留为元数据，从不成为 argv。 `forktty agent-reclaim-plan` 是只读的：它标识旧的空闲会话，这些会话是本地可恢复的，并解释为什么其他会话受到保护，但它不暂停或关闭窗格。 仅限源代码构建的 `browser` 功能公开基于套接字的浏览器窗格自动化： ```bash forktty browser open --profile Default https://example.com forktty browser navigate <surface-id> https://www.rust-lang.org forktty browser snapshot <surface-id> forktty browser click <surface-id> <ref> forktty browser fill <surface-id> <ref> "value" forktty browser eval <surface-id> "document.title" forktty browser profile list forktty browser profile create Work forktty browser history list forktty browser bookmark add https://www.rust-lang.org forktty browser import discover ``` 套接字 CLI 和代理钩子桥接器是 `forktty` 二进制文件中的原生 Rust 代码，因此源代码检出和打包构建不需要 Node.js。 ### MCP 服务器 ForkTTY 还可以通过代理支持 stdio MCP 服务器公开相同的本地自动化表面： ```bash forktty mcp # 在 stdio 上运行 MCP 服务器 forktty mcp setup # 注册 Codex、Claude、Antigravity forktty mcp setup codex claude --dry-run forktty mcp setup gemini # 旧版 Gemini CLI 加入 forktty mcp remove gemini ``` MCP 服务器仅限本地：它不打开网络监听器，并将验证的工具调用桥 * `forktty mcp setup codex claude --dry-run` forktty mcp setup gemini # 旧版 Gemini CLI 加入 forktty mcp remove gemini ``` MCP 服务器仅限本地：它不打开网络监听器，并将验证的工具调用桥接到所有者专属的 ForkTTY Unix 套接字。它公开工作空间/表面检查、拓扑树、终端读取/捕获、持久化代理会话检查和显式恢复到新标签页、紧凑状态摘要、窗格分割/聚焦/发送文本、工作树创建/附加/删除/合并、通知和 `status_set`。 `FORKTTY_SOCKET_PATH`、`FORKTTY_WORKSPACE_ID` 和 `FORKTTY_SURFACE_ID` 作为默认值被遵守，当 MCP 主机从 ForkTTY 窗格启动时。 生成的 shell 接收： - `TERM=xterm-256color` - `COLORTERM=truecolor` - `TERM_PROGRAM=ForkTTY` - `TERM_PROGRAM_VERSION` - `FORKTTY_WORKSPACE_ID` - `FORKTTY_SURFACE_ID` - `FORKTTY_SOCKET_PATH` 这让钩子和脚本可以针对当前工作空间，而无需额外的标志。 手动套接字覆盖必须是绝对路径；空白或相对 `FORKTTY_SOCKET_PATH` 值被忽略，因此应用程序和 CLI 回退到默认套接字位置。 ## 代理钩子 安装 Codex、Claude Code、Antigravity CLI 和 OpenCode 的钩子模板： ```bash forktty hooks setup # 安装默认代理 forktty hooks setup codex # 只安装一个 forktty hooks setup gemini # 旧版 Gemini CLI 加入 forktty hooks setup codex claude --dry-run forktty hooks setup --full claude # 包括 Claude 每个工具钩子 forktty hooks remove opencode # 删除 ForkTTY 管理的钩子/插件 ``` `--dry-run` 打印将要执行的更改而不修改磁盘。Claude Code 安装默认情况下使用生命周期配置文件，避免每个工具调用的阻塞钩子；传递 `--full` 包括 `PreToolUse`、`PostToolUse`、`PostToolUseFailure` 和 `PostToolBatch`。重新运行安装会将 Claude 迁移到生命周期配置文件，除非传递 `--full`。`hooks remove` 只删除 ForkTTY 管理的条目/插件，并保留无关的代理钩子。 Gemini CLI 仍然作为现有安装的旧显式目标支持，但默认安装跳过它并更喜欢 Antigravity。 安装程序将命令合并到代理自己的配置文件中： | 代理 | 目的地 | | ----------- | ----------------------------------------------------------------- | | Codex | `$CODEX_HOME/hooks.json` 或 `~/.codex/hooks.json` | | Claude Code | `$CLAUDE_CONFIG_DIR/settings.json` 或 `~/.claude/settings.json` | | Antigravity CLI | `~/.gemini/config/hooks.json` 加上 `~/.gemini/config/forktty-hooks.generated/` 中的包装脚本 | | OpenCode | `$OPENCODE_CONFIG_DIR/plugins/forktty.generated.js` 或 `~/.config/opencode/plugins/forktty.generated.js` | | Gemini CLI | `~/.gemini/settings.json`（旧版加入：`forktty hooks setup gemini`） | 当 `HOME` 被覆盖时，`~` 默认值在该主目录下解析。现有配置被原子写入（tmp + rename），当内容更改时，会创建时间戳 `.bak-*` 备份。 在应用程序启动时，如果没有安装 ForkTTY 管理的代理钩子，或者安装的钩子指向一个过时的启动器，ForkTTY 将显示一个提醒通知。 诊断和测试已安装的钩子： ```bash forktty hooks doctor codex # 检查套接字、启动器、环境、钩子配置 forktty hooks test codex # 通过套接字将状态更新循环测试 ``` 每个代理的钩子命令都遵守一个代理特定的禁用变量： - `FORKTTY_CODEX_HOOKS_DISABLED=1` - `FORKTTY_CLAUDE_HOOKS_DISABLED=1` - `FORKTTY_GEMINI_HOOKS_DISABLED=1` - `FORKTTY_ANTIGRAVITY_HOOKS_DISABLED=1` - `FORKTTY_OPENCODE_HOOKS_DISABLED=1` 钩子通过相同的本地套接字管道报告状态、进度、日志和提示通知。手动钩子事件命令可以传递 `--socket <path>`，当它们在 ForkTTY 启动的 shell 之外运行时。 ## 功能特点 - 原生 GTK4/libadwaita 桌面 shell，内嵌 Ghostty-backed 终端。 - 递归分割窗格，窗格聚焦/关闭，命令调色板，设置对话框，通知面板和工作区侧边栏。 - 通过配置和 F12 进入 Quake/下拉模式，支持全局快捷键。 - 直接 Unix 套接字 JSON-RPC 服务器，用于工作区（包括 SSH 远程工作区），表面，终端读取/捕获，拓扑树/顶部健康检查，窗格选项卡，通知，工作树，元数据，持久化代理会话库存/恢复，紧凑状态摘要，事件流和功能。 - GTK 标题栏中的代理 HUD，用于生命周期，最后活动，注意，聚焦和跨工作区的恢复。 - Git 工作树创建/附加/删除/合并/状态，具有脏状态保护和在验证的工作树内执行的钩子。设置钩子是建议性的；拆除钩子失败或创建的脏状态阻止删除。 - 工作区顺序，活动工作区，窗格树，聚焦表面，cwd，分支和工作树元数据的会话恢复。 - 来自 ForkTTY 钩子和终端事件的提示感知通知，有界可见提示回退，Ghostty 铃声和钩子/套接字事件。 - 源代码独有的实验性 WebKitGTK6 浏览器窗格（在 `browser` 功能后面），具有可脚本化的快照/点击/填充/评估动词，每个配置文件持久的 WebKit 会话，配置文件 CRUD，历史/书签套接字加 CLI 访问，和来自本地 Firefox/Chromium 系列配置文件的历史/书签导入。 - 有界配置/会话/套接字处理和仅限本地的隐私默认设置。 ## 配置 配置文件：`~/.config/forktty/config.toml`。所有字段都是可选的。设置对话框故意不编辑 `general.shell`；通过编辑此文件或您的登录 shell 环境来更改 shell。 ```toml [general] theme_source = "dark" shell = "/bin/bash" worktree_layout = "nested" # "nested", "sibling", or "outer-nested" enable_pr_lookup = false notification_command = "" [appearance] persistent_scrollback_lines = 0 sidebar_position = "left" # "left" or "right" sidebar_visible = true window_mode = "normal" # "normal" or "quake" [notifications] desktop = true sound = true blocked_terminal_apps = [] blocked_terminal_types = [] [updates] auto_check = true [telemetry] anonymous_ping = true ``` `notification_command` 使用 `shell_words` 分割；ForkTTY 不使用 `sh -c`。第一个令牌必须是绝对可执行路径。通知标题/正文通过 `FORKTTY_NOTIFICATION_TITLE` 和 `FORKTTY_NOTIFICATION_BODY` 传递；OSC 99 `f`/`t` 元数据作为 `FORKTTY_NOTIFICATION_TERMINAL_APP` 和 `FORKTTY_NOTIFICATION_TERMINAL_TYPES_JSON` 暴露。`blocked_terminal_apps` 和 `blocked_terminal_types` 抑制终端源 OSC 99 通知，其确切的 `f` 应用程序或 `t` 类型与列出的字符串之一匹配。 `persistent_scrollback_lines` 默认关闭；当设置为 `0` 以上时，ForkTTY 在 `session-v2.json` 中为每个表面存储有界的纯文本尾部，并在新的 shell 启动前恢复它。实时嵌入式窗格遵循 Ghostty 的 `scrollback-limit` 预算（默认为 10 MB）和 `scrollbar = system|never` 偏好，因此鼠标滚轮回滚和垂直滚动条来自 Ghostty 配置，而旧的 ForkTTY `scrollback_lines` 被视为兼容性密钥，不包含在新的保存中。终端字体，颜色，光标/淡入不透明度，铃声行为，鼠标滚动乘数，单元格大小调整和不活动分割变暗来自 Ghostty 配置（`~/.config/ghostty/config.ghostty` 或旧的 `~/.config/ghostty/config`），当存在时，包括 `config-file`，`theme`，命名颜色，16 色调色板条目，`cursor-opacity`，`faint-opacity`，`bell-features`，`mouse-scroll-multiplier`，`adjust-cell-width`，`adjust-cell-height`，`unfocused-split-opacity` 和 `unfocused-split-fill`；不需要系统 Ghostty 安装。旧的 ForkTTY 字体/主题/回滚/铃声/渲染器密钥仅用于配置兼容性，不包含在新的保存中。终端窗格需要嵌入的 Ghostty GTK 小部件；如果 `ghostty-gtk-embed.so` 丢失或加载失败，窗格将报告生成失败，而不是使用旧渲染器打开。 `updates.auto_check = true` 检查 GitHub Releases 不超过 24 小时一次。时间戳写在成功和失败上，因此离线机器不会在每次启动时被探测。 `telemetry.anonymous_ping = true` 每天最多发送一个 GTK 启动 ping 到 `https://forktty.dev/api/telemetry/ping`。JSON 正文仅限于 `schema`，`kind`，`app`，`version` 和 `date`；它不包含安装 ID，用户名，主机名，cwd，存储库路径，分支，shell，代理元数据，终端缓冲区，套接字有效载荷或崩溃数据。将其设置为 `false` 以禁用 ping。 参见 [SPEC.md](SPEC.md#config) 以获取完整的验证字段列表及其边界。 ## 会话恢复 GTK/Ghostty 会话存储为： ```text ~/.local/state/forktty/session-v2.json ``` ForkTTY 导入旧的 `session.json`（如果存在），但保存原生运行时为 v2。恢复不会保留正在运行的 PTY 进程；为恢复的窗格生成新的 Ghostty 支持的终端。回滚恢复仅限于由 `persistent_scrollback_lines` 控制的选入纯文本尾部。损坏或结构无效的会话文件被隔离。 ## 安全摘要 - 本地 Linux 桌面威胁模型；同一用户进程仍然是本地信任边界的一部分。 - Unix 套接字默认为 `$XDG_RUNTIME_DIR/forktty.sock`，并带有 `/tmp/forktty-<uid>/forktty.sock` 备用路径和仅所有者权限。 - 套接字请求行，配置文件和会话文件大小有界。 - shell 路径，钩子和自定义通知命令使用验证的 argv 执行，而不是 shell 管道。 - 工作树名称，套接字提供的存储库路径和钩子位置在变异或执行前被验证。 - ForkTTY 不进行崩溃报告或产品事件跟踪网络调用。启用 `telemetry.anonymous_ping = true` 时，GTK 应用程序每天发送一个匿名的使用情况 ping；将其设置为 `false` 以禁用它。启用 `updates.auto_check = true` 时，GTK 应用程序最多每天检查一次 GitHub Releases；浏览器窗格和 PR 查找仍然是可选的用户导向网络路径。已发货的 AppImage 和 `.deb` 不嵌入浏览器运行时。 参见 [SECURITY.md](SECURITY.md) 和 [PRIVACY.md](PRIVACY.md)。 ## 已知限制 - 仅限 Linux。没有支持的 macOS 或 Windows 版本。 - 原生终端集成需要 libadwaita 1.4+。 - AppImage 捆绑了 GTK4/libadwaita/Ghostty 以及 gtk4-layer-shell，但仍然依赖于主机的 glibc，fontconfig，OpenGL/Vulkan/Mesa 驱动程序栈，显示服务器库和桌面会话服务。在目标发行版/桌面环境中测试它；在包管理器集成重要的情况下，Debian/Ubuntu 上首选 `.deb`。 - PTY 在重启后不会持续；恢复的会话会启动新的 shell。回滚持久性是可选的，仅限纯文本，并且有界。 - OSC 9 和基本的 OSC 99 终端通知从 Ghostty 持有的 PTY 流中解析，并按表面速率限制；OSC 99 标题/正文 base64 有效载荷和相同 ID 标题/正文块被解码，并带有独立的 multipart 标题/正文，相同 ID 更新/关闭控制影响 ForkTTY 的通知模型，并且应用内打开/关闭/全部清除以及基本的相同 ID 按钮可以发送 OSC 99 报告。图标名称，应用程序名称图标备用，应用程序/类型过滤元数据，场合过滤，紧急程度，过期和声音元数据提供通知处理，积极的 `w` 过期值会关闭应用内通知，并且可以通过 `g` 缓存的 `p=icon` 数据；更广泛的块生命周期行为仍然部分。 - Quake 全局快捷键和 layer-shell 放置依赖于桌面/合成器支持。 - 代理休眠/挂起 UI，提供者侧会话存在检查，完整主题自定义，多窗口和浏览器历史/书签 GTK 地址栏集成是待办事项。 - 浏览器窗格在此 alpha 版本中是源代码独有的和实验性的；仅在故意测试该路径时使用 `--features browser`。 ## 故障排除 - `forktty doctor` 是第一步：它在启动失败之前解释配置，会话，套接字和钩子配置问题。 - 如果终端窗格在源代码树中报告 `ghostty-gtk-embed.so` 丢失，请运行 `git submodule update --init vendor/ghostty` 和 `scripts/ghostty-gtk-lib-probe.sh --ensure --print-path`。对于打包的构建，请使用 `bash scripts/build-deb.sh` 或 `bash scripts/build-appimage.sh` 重新构建或重新安装；打包者将验证库安装到 `usr/lib`。 - 如果 GTK 应用程序拒绝启动，请从终端运行它以查看 GLib/GTK 错误输出，然后重新运行 `forktty doctor`。 - 本地套接字位于 `$XDG_RUNTIME_DIR/forktty.sock`（或 `/tmp/forktty-<uid>/forktty.sock`）。在启动时拒绝陈旧或外部套接字；仅在确认没有其他 ForkTTY 实例拥有它们后手动删除它们。 - 损坏的 `~/.config/forktty/config.toml` 或 `~/.local/state/forktty/session-v2.json` 被重命名为 `*.bad-<timestamp>`，因此应用程序可以启动时使用默认值；重命名原因记录到 stderr。 - 本地日志位于 `~/.local/share/forktty/logs/` 下。 ## 支持 有关使用问题和错误报告，请从 [SUPPORT.md](SUPPORT.md) 开始，并附上 `forktty doctor` 的输出，您的发行版/桌面环境，安装方法和导致失败的确切命令或工作流程。安全报告应遵循 [SECURITY.md](SECURITY.md)。 ## 贡献 有用命令： ```bash cargo fmt --all --check git submodule update --init vendor/ghostty cargo run -p xtask -- check scripts/ghostty-gtk-lib-probe.sh --ensure --print-path cargo test --workspace --all-targets --no-default-features --features gtk-ghostty cargo clippy --workspace --all-targets --no-default-features --features gtk-ghostty -- -D warnings cargo build -p forktty-ui-gtk --no-default-features --features gtk-ghostty scripts/gtk-ghostty-smoke.sh cargo test -p forktty-ui-gtk --all-targets --no-default-features --features browser desktop-file-validate packaging/linux/dev.forktty.forktty.desktop bash scripts/build-deb.sh bash scripts/build-appimage.sh ``` 参见 [SPEC.md](SPEC.md)，[ROADMAP.md](ROADMAP.md) 和 [docs/native-gtk-ghostty.md](docs/native-gtk-ghostty.md)。在标记 alpha 版本之前使用 [docs/release-qa.md](docs/release-qa.md)。 ## 灵感 从零开始为 Linux 构建，灵感来自 [cmux](https://github.com/manaflow-ai/cmux) 和其他多代理终端工作流。 ## 许可证 [GNU Affero General Public License v3.0](LICENSE) (`AGPL-3.0-only`)