mini-term: Instructions file for Claude Code

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, etc.) when working with code in this repository.

Project Overview

mini-term — GPUI 原生桌面终端管理器，支持多项目、多标签、分屏布局，并能感知 AI 进程（Claude/Codex/Grok 等）状态；带移动端中转镜像与 SSH 远程项目能力。

• UI/渲染: gpui-pre 0.3.5（Zed 快照，crates.io 版；根 Cargo.toml 里以 gpui 为别名引用，窗口/文字后端在 gpui-pre-platform）+ gpui-component 0.6.2（Resizable/Modal/Input/Tree 等）
• 终端: alacritty_terminal（VT 状态机，进程内直喂，无 IPC）+ portable-pty
• 发布形态: Windows x64 NSIS 安装包（scripts/windows-installer.nsi，包内平铺 exe + 三个 sidecar + portable-conpty，全部「与 exe 同目录」；调试符号 mini_term.pdb 另作单独的 zip 资产，不进安装包；卸载时摘掉四家 AI 工具里的 hook 注册，升级不摘）+ macOS dmg + Linux deb/tar.gz
• 历史: 项目最初是 Tauri v2 + React 实现，v1.0.0-beta 后整体删除切换到 GPUI 原生版；找旧实现看 git 历史（合并点 236d5c1）

开发命令

# 首次/换版本后：构建三个 sidecar 并连同便携 ConPTY 就位到 target/debug/
node scripts/stage-sidecars.mjs

# 启动开发实例（⚠️ 与装机版并跑时必须隔离数据目录）
MT_APP_DATA_DIR="$LOCALAPPDATA/mini-term-gpui-dev" cargo run -p mt-app

# 全工作区测试（2026-09 实数：33 个目标 / 2076 例 —— 目标数 = Running + Doc-tests 行数，
# 例数 = 各 `test result:` 行 passed 之和；数字只是快照，随代码增长）
cargo test --workspace

# 量化每帧 CPU / 帧时间 p50·p99 / 一帧合并了几次 invalidation（dev-only 度量工具，
# 默认不编译；档位与读数解释见 crates/mt-app/src/frame_profiler.rs 的模块注释）
cargo build -p mt-app --features frame-profiler
MT_FRAME_OVERLAY=1 MT_APP_DATA_DIR="$LOCALAPPDATA/mini-term-gpui-dev" ./target/debug/mini-term

# 中转服务端协议边界测试 / sidecar 工作区
cd relay-server && cargo test
cargo build --manifest-path sidecars/Cargo.toml

# 移动端 PWA
cd mobile && npm run build

# 改文案后重新生成 i18n 字典
node crates/mt-i18n/tools/gen_from_ts.mjs

# 改 oh-my-pi / pi 扩展模板后离线验证（Bun 运行时，omp / pi 本身不必安装）
bun run tools/omp-ext-check.ts
bun run tools/pi-ext-check.ts
# pi 模板再在本机装的真 pi 运行时里跑一遍（SDK + faux 假模型，不联网不花 token）
node tools/pi-ext-realrun.mjs

# 重做 README 顶部宣传片（Linux + Xvfb + lavapipe 实拍真实应用 → 逐帧合成，产物写到 docs/promo/；
# 依赖与参数见 tools/promo/README.md）
tools/promo/build.sh

• 便携 ConPTY（Windows）：main() 在建 gpui 平台层之前调 mt_pty::conpty::initialize_default()，从 exe 同目录的 portable-conpty\ 预载 Windows Terminal 1.24 的 conpty.dll，PTY 宿主于是是 portable-conpty\x64\OpenConsole.exe 而不是系统 conhost.exe。dev 实例的这个目录由上面的 stage-sidecars.mjs 就位到 target/debug/；没就位就回落系统 ConPTY——看日志里的 [conpty-bootstrap] backend=portable|system 一行。⚠️ 该脚本不认 CARGO_TARGET_DIR：给构建另设了 target 目录时，要把 target/debug/portable-conpty/（连同三个 sidecar）复制到那个目录的 debug/ 下，否则 dev 实例跑的是系统 conhost。MT_DISABLE_PORTABLE_CONPTY=1 跳过预载，用于开 / 关对比与排障
• 工具链由根目录 rust-toolchain.toml 钉死（channel + clippy/rustfmt），CI 按同一文件安装，本地 clippy 与 CI 同版本。新机器 / 新 checkout 先跑一次无参 rustup toolchain install（新版 rustup 已弃用「缺工具链时自动安装」）；升级工具链只改该文件的 channel 一处。
• ⚠️ 禁跑 cargo fmt：本仓 HEAD 非 rustfmt-clean，全仓 fmt 会重排几十个文件淹没 diff。
• ⚠️ GPUI dev 实例运行中时，cargo build -p mt-app / cargo run -p mt-app 会卡在「无法替换 target/debug/mini-term.exe」——先关实例，或给这次构建另设 CARGO_TARGET_DIR。cargo test（含 -p mt-app 与 --workspace）不受影响：mt-app 没有集成测试，只编单测 harness（target/debug/deps/mini_term-<hash>.exe），不产出也不替换 mini-term.exe。
• ⚠️ 别给 mt-app 加 tests/ 目录：包里只要有集成测试，cargo test 就会先把该包的 bin 编出来（给测试提供 CARGO_BIN_EXE_*），上面那条文件锁就又回来了。不需要 GPUI 的端到端测试放进对应的下层 crate（PTY → VT → grid 冒烟在 crates/mt-terminal/tests/terminal_smoke.rs）。