Terax 完全指南：7MB 级终端优先的 AI 原生开发工作区（Tauri 2 + Rust + React 19）-创锋一号

Terax 完全指南：7MB 级终端优先的 AI 原生开发工作区（Tauri 2 + Rust + React 19）

【免费下载链接】terax-aiLightweight (7MB) Terminal-first AI-native dev workspace项目地址: https://gitcode.com/GitHub_Trending/te/terax-ai

Terax 是一款开源、轻量级的终端优先 AI 原生开发环境（ADE），以"终端是第一公民、AI 原生嵌入、极致轻量"为核心设计理念，整体仅约 7–8 MB，无遥测、无需注册账号。本文基于项目官方德语说明文档（docs/readme/README.de.md），结合仓库源码与配置，系统讲解其功能矩阵、安装方式、AI 配置流程与源码构建方法，帮助你快速上手这套"以原生 PTY + GPU 终端 + 自带密钥的智能体侧边栏"为核心的开发工作区。

项目定位与整体架构

Terax 建立在 Tauri 2 + Rust 与 React 19 之上：Rust 侧通过portable-pty提供原生 PTY 后端，前端以 WebGL 渲染器呈现终端画面，并内置了可对接自有 API 密钥或完全本地模型的智能体（agentic）AI 侧边栏。除终端外，它还集成了代码编辑器、文件资源管理器、带 Git 图（commit graph）的源码管理面板以及 Web 预览窗格。

从仓库的依赖清单（package.json）可以确认技术底座：React 19、TypeScript、Vite、CodeMirror 6、xterm.js、Vercel AI SDK（ai@^6）、Tailwind v4、shadcn/ui 与 Zustand；Rust 侧（src-tauri/Cargo.toml）则声明了tauri = "2"、portable-pty = "0.9"、keyring = "3.6"等核心依赖，当前版本号为0.9.0-beta，采用 Apache-2.0 许可证。

其内部遵循"双进程模型"：Rust 进程独占全部操作系统能力（文件系统、进程、shell、密钥链），WebView 前端从不直接触碰 FS 或 shell，一切通过invoke()调用注册在 src-tauri/src/lib.rs 的 Tauri 命令完成。这一架构正是"轻量 + 安全 + 可测试"的基石。

核心功能矩阵

终端：xterm.js + WebGL，GPU 加速的块级命令输入

终端是 Terax 的立身之本，能力清单如下（见 docs/readme/README.de.md）：

xterm.js 搭配 WebGL 渲染器，支持多标签页与后台流式输出；
GPU 加速的块级（block-based）终端，带编辑器风格命令输入区；
通过portable-pty提供原生 PTY 后端，支持 zsh、bash、pwsh、fish、cmd；
水平与垂直分屏（split panes）；
内联搜索、链接识别与 True Color；
可将资源管理器或桌面中的文件拖入终端，自动生成 shell 安全引用的路径；
Windows 下支持按标签页切换工作环境（本机或任意已安装的 WSL 发行版）；
Spaces 可在重启后恢复标签页、工作目录与分屏布局。

仓库中的终端实现位于 src/modules/terminal，其渲染管线（详见 docs/architecture/ghostty-webgl-renderer.md）为：

portable-pty bytes -> libghostty-vt WASM model -> borrowed typed render views and row damage -> Terax renderer lease -> Terax-owned, xterm-inspired WebGL renderer

其中 WebGPU 是默认渲染器，WebGL 作为运行时与能力回退路径；若两条 GPU 路径均失败，面板会保留模型与 PTY 并提供 Retry 显示。渲染器采用池化管理：WebGL 渲染器属于窗口级池，仅在面板可见时租赁；隐藏标签页的模型继续解析 PTY 字节但立即释放渲染租赁，实现了"零闲置开销"。PTY 侧通过注入的初始化脚本（src-tauri/src/modules/pty/scripts 下的 zsh/bash/fish/ps1 脚本）发出 OSC 7（cwd）与 OSC 133 A/B/C/D（提示符边界 + 退出码）序列，使宿主无需重解析提示符即可跟踪工作目录与命令边界——这套机制在 docs/architecture/pty-shell-integration.md 中有详细说明。

代码编辑器：CodeMirror 6 + 内联 AI 补全

基于 CodeMirror 6，覆盖 TS/JS、Rust、Python、Go、C/C++、Java、HTML/CSS、JSON、Markdown 等主流语言（语言包在 package.json 中可逐一核对）；
内联 AI 补全，且支持本地模型；
AI 编辑差异（edit diffs）面板，可按 hunk 逐块接受或拒绝；
可选的语言服务器（LSP）支持：诊断、导航、补全、格式化，并可自定义服务器；相关实现见 src/modules/lsp，会话管理采用按（服务器, 工作区根目录）键控、3 分钟空闲回收与崩溃退避策略；
渲染 Markdown，并可查看图片、视频、音频与 PDF；
Vim 模式（依赖@replit/codemirror-vim）；
内置编辑器主题：Kanagawa、Catppuccin、Rosé Pine、Everforest、Dracula、Solarized、Nord、Tokyo Night、GitHub、Xcode 等，且编辑器主题独立于应用主题。

编辑器实现位于 src/modules/editor，其中lib/extensions.ts配置语言模式，lib/eol.ts通过多数投票检测并还原原始换行符，lib/indent.ts按文件探测缩进单位；格式化器注册表见lib/externalFormat.ts（biome、prettier、ruff、rustfmt、gofmt、clang-format、shfmt、zig fmt 等）。超过 10 MB 的文件会提示 "Open anyway"（硬上限 50 MB），超过 4 MB 则关闭语法高亮与 LSP——这些都是"轻量优先"原则的具体落地。

源码管理：hunk 级暂存 + 真实提交图

按 hunk 暂存 / 取消暂存，提交（Cmd+Enter / Ctrl+Enter），带 upstream 感知的推送；
分支显示，含 detached HEAD 状态；
Git 历史面板带真实提交图（为 merge 与 branch 绘制泳道）；
提交搜索与过滤，可跳转远端提交页面。

前端面板位于 src/modules/source-control 与 src/modules/git-history，Rust 侧完整命令面（git_status、git_diff、git_stage、git_commit、git_push、git_log、git_show_commit等）在 src-tauri/src/modules/git 中实现，且全部经过工作区授权注册表（workspace authorization registry）门控。

文件资源管理器：模糊搜索 + 实时同步

Catppuccin 图标主题；
模糊搜索、键盘导航、内联重命名、右键上下文操作；
磁盘文件变化实时刷新（基于notifycrate）；
可直接将文件与选区附加到 AI 侧边栏。

Web 预览与主题定制

自动探测本地开发服务器并以预览标签页打开；也可通过原生子 WebView 预览外部 URL（src/modules/preview）；
在应用内创建自定义主题，可在内置预设与自建主题间切换，支持分享与从社区导入；
背景图可调不透明度与模糊；
编辑器主题与应用主题互相独立（editorTheme偏好为"auto" | EditorThemeId，默认"auto"，由 src/modules/editor/lib/useEditorThemeExt.ts 在渲染期解析）。

AI 子系统：BYOK 云模型 + 完全本地推理

Terax 的 AI 侧边栏采用 BYOK（Bring Your Own Key）模式，提供商注册表定义在 src/modules/ai/config.ts（PROVIDERS常量）：

自带密钥的云端提供商：OpenAI、Anthropic、Google (Gemini)、Groq、xAI (Grok)、Cerebras、OpenRouter、DeepSeek、Mistral，以及任意 OpenAI 兼容端点；
本地 / 离线提供商：LM Studio、MLX、Ollama（此类提供商密钥可选，模型 ID 运行时填写）；
所有提供商由 Vercel AI SDK v6 的@ai-sdk/*适配器驱动。

智能体工作流能力包括：多步计划（Plan mode，执行前先生成计划并确认）、子代理（sub-agents）、项目记忆（通过工作区根目录的TERAX.md）、文件读/写/编辑/多文件编辑/grep/glob，以及带审批门控的 Bash 与后台进程。工具清单见 src/modules/ai/tools/tools.ts：read_file、list_directory、fs_search、fs_grep自动执行；write_file、create_directory、rename、delete、run_command、shell_session_run、shell_bg_spawn则设置needsApproval: true，在界面内弹出确认卡片后才执行——这是安全模型（docs/architecture/security-model.md）的一部分。

此外还有：

Coding-agent 编排：可在终端中启动 Claude Code，检查其输出，并通过需审批的工具下发后续任务；
Composer：#handle提示词片段、@path文件引用、语音输入，以及从资源管理器或选区附加；
自定义智能体：可配置独立的系统提示词与工具子集；
模型注册表：MODELS常量内置了各提供商的模型目录与能力评分（智能/速度/成本），并附MODEL_CONTEXT_LIMITS上下文窗口估算与estimateCost成本估算函数；DEFAULT_MODEL_ID为gpt-5.4-mini，同时为各提供商配置了默认补全模型（DEFAULT_AUTOCOMPLETE_MODEL）。

值得注意的安全设计：系统提示词（src/modules/ai/config.ts 中的SYSTEM_PROMPT）明确要求智能体"直接执行而非复述"、工具调用前先列计划、敏感路径读取拒绝后不得重试；而 src/modules/ai/lib/security.ts 维护了一份拒绝清单（.env*、.ssh/、凭据与 keychain 目录），读写两侧均强制执行。

安装指南

最新安装包请前往项目 Releases 页面获取，Terax 会从这里自动更新。

Windows 注意事项

默认 shell 探测顺序：pwsh.exe（PowerShell 7+）→powershell.exe（Windows PowerShell 5.1）→cmd.exe；
WSL 是完整的一等工作环境，而非被包裹的子进程；Windows 下通过 ConPTY + Job Object 管理子进程树（JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE，见 src-tauri/src/modules/pty/job.rs），确保 shell 关闭时其后代进程（如从 pwsh 里启动的npm run dev）一并终止。

Linux 注意事项

Arch / AUR：yay -S terax-bin（或paru等），跟随最新版本；
NixOS / Nix：使用官方 flake——非 NixOS 环境执行nix profile install github:crynta/terax-ai；NixOS 下导入 flake 并将inputs.terax.packages.${pkgs.system}.terax加入environment.systemPackages，也可直接使用更简单的nixosModules.terax。仓库内 nix/package.nix 即官方打包实现，覆盖 x86_64-linux、x86_64-darwin 与 aarch64-darwin，Linux 构建依赖 webkitgtk_4_1 并显式配置 GStreamer 插件路径；
AppImage：需要 FUSE；无 FUSE 时执行./Terax_*.AppImage --appimage-extract-and-run。Wayland 下出现渲染问题时，可尝试WEBKIT_DISABLE_DMABUF_RENDERER=1。相对而言，.deb/.rpm包会链接系统 GTK 栈，通常运行更流畅（deb/rpm 依赖声明见 src-tauri/tauri.conf.json：libwebkit2gtk-4.1-0与libgtk-3-0）。

配置 AI：三步完成

打开设置 -> AI（Settings -> AI）；
选择一个提供商并粘贴 API 密钥；若使用本地推理，则将 Terax 指向你的 LM Studio / MLX / Ollama 端点（默认端点 URL 在 src/modules/ai/config.ts 中定义，如 LM Studiohttp://localhost:1234/v1、Ollamahttp://localhost:11434/v1）；
密钥通过keyring写入操作系统密钥链，绝不会写入磁盘或 localStorage。

密钥存储的后端实现（src-tauri/src/modules/secrets.rs）按平台区分：macOS 使用 Keychain，Windows 使用 Credential Manager（均由keyringcrate 驱动）；Linux 因无法假定存在 gnome-keyring/kwallet 守护进程，采用应用本地数据目录中的secrets.json文件回退方案，以 0600 权限（仅属主可读写）写入，并通过"先写临时文件再原子重命名"保证一致性——这一行为由仓库内的单元测试（write_uses_mode_0600、write_overwrites_existing_atomically等）锁定。前端通过secrets_get/secrets_set/secrets_delete/secrets_get_all命令访问，无平台分支代码。

从源码构建

前置条件

Rust（stable），https://rustup.rs
Node 20+ 与 pnpm（仓库engines字段要求 Node >= 22，且仅使用 pnpm 包管理器）
对应平台的 Tauri 前置依赖，https://tauri.app/start/prerequisites/

运行

pnpm install pnpm tauri dev # 开发模式 pnpm tauri build # 生产打包

质量检查

pnpm lint pnpm check-types pnpm test cd src-tauri && cargo clippy --all-targets --locked -- -D warnings # Rust lint（与 CI 一致） cd src-tauri && cargo nextest run --locked # 或：cargo test --locked

前端测试基于 Vitest（pnpm test即vitest run），linter 为 Biome；终端渲染还额外提供pnpm bench:ghostty、pnpm profile:ghostty与pnpm soak:ghostty等专用脚本（见 package.json），用于在不启动应用的情况下对真实 WASM 终端模型做基准、剖析与浸泡验证。

技术栈一览

Tauri 2、Rust、portable-pty、React 19、TypeScript、Vite、xterm.js、CodeMirror 6、Vercel AI SDK v6、Tailwind v4、shadcn/ui、Zustand。

其中值得注意的是终端内核已从 xterm.js 完整迁移到 libghostty-vt WASM 模型（WebGPU 为默认渲染器、Terax WebGL 为兼容回退），xterm 及其附加组件已从代码库移除；这一迁移的发布门禁与资源效率证据分别记录在 docs/architecture/ghostty-release-readiness.md 与 docs/architecture/ghostty-resource-efficiency.md。

贡献、签名与许可证

欢迎提交 issue 与 PR：报告问题、提议功能或提交合并请求均可。更多信息见 CONTRIBUTING.md 与 docs/README.md（架构文档索引；若与TERAX.md冲突，以根目录 TERAX.md 为准，它同时是智能体读取的项目记忆文件）。Windows 构建使用 SignPath.io 提供的免费代码签名证书签名。Terax 基于 Apache-2.0 许可证发布，详见 LICENSE。

【免费下载链接】terax-aiLightweight (7MB) Terminal-first AI-native dev workspace项目地址: https://gitcode.com/GitHub_Trending/te/terax-ai

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析