jterm4

jterm4 是一个面向开发工作流的原生 GTK4 终端。它默认使用 Block 后端，把命令、输出、退出状态和工作目录组织成可搜索的结构化块；需要传统终端语义时也可切换到 VTE 后端。

能力概览

默认 Block、可选 VTE 的双终端后端
标签页、混合后端分屏、方向导航、缩放、前台进程关闭确认与多窗口独立会话恢复
跨命令块搜索、失败/慢命令筛选、只记录元数据的 JSONL 命令历史
统一模糊面板：动作、历史、YAML/TOML workflow 和自然语言命令入口
可执行 .jtnb.md Notebook，逐 cell 运行/停止并分离 stdout 与 stderr
基于现代 GTK4 列表模型的异步文件树、Git 分支/脏状态条、长命令桌面通知
SSH 主机选择、连接复用与自动重连
可选多 provider AI、可搜索和归档的多会话 Chats 库，以及绑定当前 Block pane 的原生 Shell Agent；每条候选命令均可编辑且需单独批准
配置热重载、可覆盖快捷键、8 套内置主题
CJK 输入法和 Unicode 安全的搜索/通知显示

分屏会继承当前 pane 的后端：Block 创建 Block sibling，VTE 创建 VTE sibling，并可继续嵌套。每个可见 pane 都独立拥有并清理其进程，关闭 pane、标签或窗口前会统一检查前台任务。

构建与运行

推荐使用仓库提供的 Nix 开发环境：

nix develop
cargo run

也可以在安装 GTK4、libadwaita、VTE GTK4、PCRE2 与 pkg-config 开发包后直接使用 Cargo。

GTK4 栈必须足够新（glib >= 2.80、pango >= 1.52、gtk4 >= 4.14、libadwaita >= 1.5，以及 GTK4 版 VTE vte-2.91-gtk4 >= 0.76）。Ubuntu 22.04 等稳定发行版自带的这些库过旧，或根本没有 vte-2.91-gtk4，会导致 cargo install --path . 在 *-sys 构建脚本处失败。运行 ./scripts/bootstrap_deps.sh 一键准备依赖：

./scripts/bootstrap_deps.sh            # 配好推荐工具链（Nix）
./scripts/bootstrap_deps.sh --check    # 只检测缺什么，不安装
./scripts/bootstrap_deps.sh --backend system --install   # 改用发行版系统包

脚本默认使用 Nix（精确固定匹配的库版本、不污染系统包），也可用 --backend system 改装发行版 -dev 包。

完整质量门禁：

cargo fmt --all -- --check
cargo test --all-features --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features --locked
cargo build --release --all-features --locked

安装脚本默认优先使用 Nix；没有 Nix 时自动退回 Cargo，并且不会覆盖已有配置：

./scripts/install.sh
./scripts/install.sh --backend cargo
./scripts/install.sh --prefix /opt/jterm4 --no-config
./scripts/install.sh --dry-run

默认安装到 ~/.local/bin/jterm4，同时安装 jterm4-support-bundle，并把 shell 集成、内置 workflow 和欢迎 Notebook 安装到 ~/.local/share/jterm4/。配置使用 0600。脚本支持 DESTDIR、XDG_CONFIG_HOME 和 CARGO_TARGET_DIR；使用非默认 prefix 时可通过 JTERM4_ASSET_DIR / JTERM4_WORKFLOW_DIR 指向对应的 share/jterm4 目录。卸载默认保留用户配置、状态与历史：

./scripts/uninstall.sh
./scripts/uninstall.sh --purge-config   # 明确删除全部配置和状态

桌面集成（应用列表里的图标）

./scripts/install.sh 默认一并安装桌面集成，无需额外步骤，安装后 jterm4 就会出现在 GNOME/KDE 的应用列表里，可以搜索、点击启动、固定到 dock：

安装内容	位置（默认 prefix）
启动器条目	`~/.local/share/applications/io.github.beamiter.jterm4.desktop`
应用图标	`~/.local/share/icons/hicolor/{scalable,128x128,256x256}/apps/io.github.beamiter.jterm4.*`
AppStream 元数据	`~/.local/share/metainfo/io.github.beamiter.jterm4.metainfo.xml`

安装时脚本会把 Exec= / TryExec= 改写成二进制的绝对路径（系统 prefix 如 /usr 除外），因为桌面会话的 PATH 在登录时就固定了：若 ~/.local/bin 不在其中，TryExec=jterm4 会失败并让条目整个从应用列表中消失——这是"装好了却找不到图标"最常见的原因。随后脚本会校验条目并刷新 update-desktop-database 与 gtk-update-icon-cache（陈旧的图标缓存会盖住刚装进去的图标）；DESTDIR 打包场景下跳过刷新，交由包管理器处理。 --no-desktop 可只装二进制。

自检与手动刷新：

desktop-file-validate ~/.local/share/applications/io.github.beamiter.jterm4.desktop
gtk-launch io.github.beamiter.jterm4          # 按启动器条目实际启动一次

图标若一时没刷新，注销重登（或 X11 下 Alt+F2 → r 重启 GNOME Shell）即可。 Wayland 下窗口按 app_id 与条目关联，X11 下则依赖 StartupWMClass=jterm4——GTK4 的 X11 WM_CLASS 取自程序名而非 application ID，写成 application ID 会导致 dock 里出现一个没有图标的重复条目。

nix build / nix run 分别构建和启动 flake 中的默认 package/app， nix flake check 验证同一 package。也可为已有 release binary 生成确定性、带 SHA-256 的本地安装归档：

cargo build --release --all-features --locked
./scripts/package-release.sh target/release/jterm4
(cd target/dist && sha256sum --check *.sha256)

该归档可换目录后安装，但仍动态依赖兼容的 GTK4、libadwaita、VTE GTK4 和 PCRE2 系统运行库，并非静态或自包含的 portable 应用。

Flatpak 与桌面集成

项目使用稳定应用 ID io.github.beamiter.jterm4，提供 desktop、AppStream、 SVG/PNG 图标以及可复现 Flatpak 清单。Flatpak 中的 Shell、SSH、Git、curl 和通知命令通过 flatpak-spawn --host 运行，因此终端操作的是宿主环境而不是一次性沙箱；原生安装路径保持直接执行。内置 shell 集成、workflow 和欢迎 Notebook 一并安装在 /app/share/jterm4/。

flatpak-builder --user --install-deps-from=flathub --force-clean \
  --disable-rofiles-fuse --repo=flatpak-repo flatpak-build \
  packaging/flatpak/io.github.beamiter.jterm4.yml
flatpak build-bundle flatpak-repo io.github.beamiter.jterm4.flatpak \
  io.github.beamiter.jterm4

权限模型、宿主桥接、安全边界、安装命令与已知限制见 Flatpak 指南。

启动与配置

默认配置路径为 ~/.config/jterm4/config.toml。从完整示例开始：

jterm4 --init-config
jterm4 --check-config

也可使用独立配置：

jterm4 --config ~/my-jterm4.toml
jterm4 --check-config ~/my-jterm4.toml

常用启动覆盖不会修改配置：

jterm4 ~/project
jterm4 --mode block --no-restore
jterm4 -d /tmp --execute bash -lc 'printf "hello\\n"'
jterm4 --safe-mode

--safe-mode 不读取指定或默认配置，也不采用 JTERM4_* 外观/行为覆盖；它使用内置 VTE 主题与默认快捷键，并禁用配置重载、恢复、持久化、远程主机、历史、仓库探测、AI/Agent 与 Notebook 执行，适合排查损坏配置或启动环境。

诊断命令均可在没有图形显示的 SSH/CI 环境运行：

jterm4 --help
jterm4 --doctor --json       # 同时报告 ready / active 会话快照数量
jterm4 --check-config --json
jterm4 --config-path
jterm4 --restore-config-backup
jterm4 --print-default-config
jterm4 --shell-integration bash
jterm4 --generate-completion zsh
jterm4-support-bundle ~/Desktop

--doctor 除配置语义和运行时依赖外，还检查配置权限、有效轮换备份、写锁、AI provider/密钥存在性、workflow 搜索位置、欢迎 Notebook、历史和 SSH 就绪度；不会发起网络请求。support bundle 使用额外的脱敏诊断模式，只收集权限/大小、计数、非敏感系统特征和选定环境变量的“存在/不存在”，不包含配置、命令/输出、会话内容、密钥、主机名或本地路径。分享前仍应逐项检查归档内容。

配置文件保存后会自动热重载；Ctrl+Shift+R 可手动重载。应用内保存会先验证 TOML 与语义、获取进程锁并检查磁盘 revision，再以 0600 临时文件同步、原子替换并轮换两份有效备份；冲突、锁超时、无效内容或 I/O 错误会显示原生提示，且不会覆盖磁盘。--restore-config-backup 可恢复最近的有效备份。

日志支持普通级别和标准 target 指令，并输出进程内相对时间、级别与模块名：

JTERM4_LOG=debug jterm4
RUST_LOG='warn,jterm4=debug,jterm4::state=trace' jterm4

JTERM4_LOG 优先于 RUST_LOG；未知指令会被忽略，默认级别保持 warn。

CLI 补全可按需加载，支持 bash、zsh、fish 和 PowerShell，不需要额外运行时依赖：

# bash
source <(jterm4 --generate-completion bash)

# zsh
source <(jterm4 --generate-completion zsh)

# fish
jterm4 --generate-completion fish | source

# PowerShell
jterm4 --generate-completion pwsh | Out-String | Invoke-Expression

Block 模式可通过 finished_block_viewport_rows 调整长块出现顶部/底部导航控件的行数阈值；block_compact = true 可启用更接近 jterm1/Warp 的紧凑块间距。两项配置均保持 GTK4 原生实现，不增加运行时依赖。

安装与更新 jsh

jterm4 优先使用配套 shell jsh，找不到时才退回 bash。命令面板中的 Install or update jsh 会在一个独立标签页里运行安装脚本：标签页本身就是进度界面，可以 Ctrl+C 中断，脚本结束后等待 Enter 再关闭，失败原因不会一闪而过。

安装脚本来自 jsh 仓库并内嵌在二进制里，因此一台从未装过 jsh 的机器也能引导；校验和验证、 rename(2) 原子替换（运行中的 shell 不受影响，新标签页才使用新版本）、旧二进制回滚副本，以及 PATH 上的 jsh 其实是同名的其他程序时的提示，全部由脚本统一处理。

缺少 jsh 或有新版本时，顶栏下方出现一条可忽略的提示条。检查在后台线程进行，从不自动安装：

jsh_update_check = "daily"    # "startup" 每次启动联网；"daily" 复用缓存；"never" 关闭

daily 复用安装脚本自己的缓存（~/.cache/jsh/update-check.json），同机同时开着多个 jterm 也只产生一次网络请求。检查失败（离线等）时提示条保持隐藏，只写日志。

核心快捷键

功能	快捷键
新建 / 关闭	`Ctrl+Shift+T` / `Ctrl+Shift+W`
下一个 / 上一个标签	`Ctrl+Tab` / `Ctrl+Shift+Tab`
标签 1–8 / 最后一个	`Ctrl+1`…`Ctrl+8` / `Ctrl+9`
搜索 / 命令面板	`Ctrl+Shift+F` / `Ctrl+Shift+P`
左右 / 上下分屏	`Ctrl+Shift+E` / `Ctrl+Shift+D`
聚焦 / 调整 Pane	`Ctrl+Alt+方向键` / `Ctrl+Alt+Shift+方向键`
复制 / 粘贴	`Ctrl+Shift+C` / `Ctrl+Shift+V`
配置 / 重载	`Ctrl+Shift+O` / `Ctrl+Shift+R`
SSH 主机选择	`Ctrl+Shift+S`
Block 历史 / 跨块搜索	`Ctrl+Shift+H` / `Ctrl+Shift+G`
workflow / 失败块 / 最早块	`Ctrl+Shift+M` / `Ctrl+Shift+X` / `Ctrl+Shift+N`
全选 / 回填 / 清空 Block	`Ctrl+Shift+A` / `Ctrl+Shift+I` / `Ctrl+Shift+K`
Block 过滤 / 书签 / 标签栏位置	`Alt+Shift+F` / `Ctrl+Shift+B` / `Ctrl+Alt+B`
AI 面板 / 询问选中块	`Ctrl+Alt+Shift+A` / `Ctrl+Shift+Q`
Shell Agent（Block）	`Ctrl+Alt+G`
字号增 / 减 / 复位	`Ctrl+=` / `Ctrl+-` / `Ctrl+0`

全部命令和当前绑定可在 Ctrl+Shift+P 中搜索。快捷键可在 [keybindings] 中覆盖，设为 false 可解除绑定。Ctrl+R 与 Ctrl+P 保留给 shell/readline；Block 历史统一使用 Ctrl+Shift+H。

AI provider、model、endpoint 和 API key 均可在 Settings 的 AI & Agent 分组配置；面板输入的 key 会原子保存到独立的 owner-only 文件，绝不会写入 config.toml，环境变量仍具有最高优先级。AI 面板的分隔条宽度会随配置持久化。New chat 会创建并选中一个新会话，旧会话继续保留在可搜索的 Chats 会话库中；会话自动取标题，也可 Rename、Archive/Unarchive，Delete 前会要求确认。输入框使用 Enter 或 Ctrl+Enter 发送，Shift+Enter 换行，并保留输入法候选确认语义。请求期间可 Stop，失败或停止后可按原 chat/context Retry；选中 Block 会显示可清除的 context chip，输出被截断时 chip 会明确提示。空会话也提供只填充、不自动发送的快捷提示。

当前选择、每个 chat 的草稿和实际发送的选中 Block 上下文会跟随各自窗口快照恢复；快速关窗会先强制刷新草稿，发送失败或中途退出的问题也会作为可重试 draft 恢复，Ask selected Block 不会覆盖正在编辑的文字，关窗时其内存重试也会转成可恢复 draft/context。集合最多保存 50 条 chat metadata、每个 chat 最多 100 个 turn，紧凑 JSON 总预算仍为 8 MiB；超出总预算时只裁剪最旧的完整问答对，不会删除在途问题，并在对应会话显示 truncated。出站请求另保留最近至多 40 个 turn/256 KiB，单条输入、Block 输出和模型文本分别有 64 KiB、64 KiB、256 KiB 硬上限，可见 AI/Agent activity 各限制为 1 MiB，同时最多运行 4 个 provider 请求。窗口状态另为完整 chat metadata 预留 64 KiB，Pane/Tab 数据挤压空间时也不会静默删除整个 Chats 库。旧版单会话 schema v1 会自动迁移。后台回复始终绑定发起请求的 chat，切换不会串话，已经 Delete 的 chat 收到迟到回复时会直接丢弃。默认脱敏覆盖 active、non-active、archived chat 及其 draft/context；--safe-mode 与 --no-restore 的隔离和恢复语义保持不变。

命令面板使用模糊匹配；输入 > 只看动作、@ 只看 JSONL 历史、: 只看 workflow、? 提交自然语言命令请求。历史和 workflow 只写入当前编辑行；? 请求会绑定当前 Block pane，在块流中显示可 Stop/Retry/Regenerate 的审阅卡，并携带可见的 selected Block 不可信上下文。它与命令纠正、Shell Agent proposal 共用可编辑、复制、动态风险提示的审阅逻辑，主操作只会 Insert for review，不会执行。所有审阅式插入都拒绝 CR、LF、Tab、NUL 和终端控制字符，避免多行条目越过“不提交”边界。Ctrl+Alt+G 或顶部栏的 Agent 开关会打开绑定当前 Block pane 的 Shell Agent；若打开时已选中 finished Block，它会作为可见、可移除的不可信上下文附加。Agent 显示目标、provider/model、shell、回合进度、activity 与实时 prompt readiness，可单独 Stop/Retry 当前模型请求，并可切换持久化的 typo-like 命令纠正。严格 JSON proposal 可复制、编辑、Reject、Insert only 或逐条 Approve & Run；Insert only 只回填普通 shell 编辑行并在 Agent 上下文记录“未执行”，危险命令执行仍需第二次确认。完成块的退出码和截断输出随后回灌到下一轮；done 后可用 Follow up 保留上下文追问，回合耗尽后可用 New task 在同一 pane 重置 Agent transcript 与预算。

若希望 Block 准确记录命令边界、退出码和 cwd，可加载内置 shell 集成：

source <(jterm4 --shell-integration bash)

也可从已安装的 share/jterm4/shell-integration/ 加载 bash、zsh、fish 或 PowerShell 脚本。

Block 模式与 jterm1 保持相同的选择语义：Ctrl+Up 从最新块进入选择，Shift+Up/Down 扩展范围，普通 Up/Down 移动 active edge，Enter 按终端顺序把所有选中命令回填为可编辑文本而不执行，Escape 取消选择。右键多选区域可批量复制命令、输出或完整块；长 Block 提供顶部/底部跳转与 sticky header，后台异步输出使用独立 Block 样式。

后台输出只会在提示符空闲且用户尚未开始编辑时归入独立 Block；一旦输入开始，后续输出保持在当前终端中，避免把 shell 回显、补全或交互输出错误拆块。

许可证

jterm4 以 MIT OR Apache-2.0 双许可证发布，使用者可任选其一；完整文本见 LICENSE-MIT 与 LICENSE-APACHE。向本仓库提交贡献即表示贡献者同意按相同的双许可证条款授权该贡献。仓库许可与 crates.io 发布是两个独立决定，因此 Cargo 包目前仍保留 publish = false。

安全默认值

新安装不会写入任何远程主机、用户名、IP 或个人路径。
OSC 52 远程剪贴板写入默认关闭。
AI 会话库默认对常见云密钥、PAT、JWT 和私钥进行脱敏，覆盖 active、non-active、archived chat 以及草稿和 Block 上下文。
Agent 只支持显式选中的 Block pane；prompt 忙或已有输入时拒绝提交，危险模式会醒目标注，但最终批准仍由用户负责。
可执行 Notebook 在独立进程组运行，关闭或停止 cell 会终止其进程组；安全模式完全禁用 Notebook 执行。
命令历史只保存 command、cwd、exit code 和完成时间，不保存输出，并限制单条/总文件大小。
每个窗口使用独立的原子会话快照；并发窗口互不覆盖，崩溃遗留快照会在下次启动回收。
配置、会话快照、JSONL 命令历史和 Block 历史使用 owner-only 权限；关键替换路径使用同步写入与原子 rename，降低信息泄露和断电损坏风险。
jterm4-support-bundle 不读取或打包上述内容，只报告脱敏诊断与文件元数据，并以 0600 创建归档。
项目采用 MIT OR Apache-2.0 双许可证；Cargo 包仍有意保留 publish = false，不将仓库许可自动等同于 crates.io 发布。依赖继续由每周 RustSec 审计与 Dependabot 检查。

进一步说明见用户指南、架构说明、Block 模式验收清单、AI / Agent / Chat 验收矩阵、性能指南、发布流程和 Tailscale/SSH 配置。参与开发前请阅读贡献指南、安全策略与变更日志。

Name		Name	Last commit message	Last commit date
Latest commit History 446 Commits
.github		.github
data		data
docs		docs
packaging		packaging
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
config.toml.example		config.toml.example
deny.toml		deny.toml
flake.lock		flake.lock
flake.nix		flake.nix
rust-toolchain.toml		rust-toolchain.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

jterm4

能力概览

构建与运行

桌面集成（应用列表里的图标）

Flatpak 与桌面集成

启动与配置

安装与更新 jsh

核心快捷键

许可证

安全默认值

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

jterm4

能力概览

构建与运行

桌面集成（应用列表里的图标）

Flatpak 与桌面集成

启动与配置

安装与更新 jsh

核心快捷键

许可证

安全默认值

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages