iTerm2 Shell Integration 新 Shell 接入全流程清单从脚本打包到自动注入的完整实现指南【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2导读本指南是 iTerm2 官方为开发者编写的一份 App 端操作清单讲解如何为一种全新 shell添加 shell integrationshell 集成支持。围绕这份清单本文从脚本打包、版本注册、枚举登记、自动注入、手动安装器 UI、测试与文档六个层面逐条展开其背后的源码实现与调用链读者可按此清单完整落地一次 添加新 shell 的改动。全文中shell表示小写 shell 名即ShellIntegrationVersion...;shellshell中出现的名字Xxx表示对应的首字母大写形式用于枚举 case 与类名。最完整的先例是 xonsh 接入时的两个提交1bf85d898Add xonsh as a supported shell for shell integration与1e4ee607bAdd xonsh shell integration下文各步骤不明确时均可对照它们。注意清单中的行号是近似值、会随版本漂移实际操作请以 grep 相邻符号为准。前提条件脚本仓库与两类 shell 形态动手之前需要先明确两件事脚本本体不在本仓库。shell integration 脚本位于iTerm2-shell-integration子模块独立仓库必须先在该子模块中合并新脚本并完成打包见下节打包脚本App 侧依赖它的步骤才能生效。决定脚本如何被自动加载。shell 分为两种形态dotfile 型bash / zsh / tcsh安装器在用户的 dotfile如~/.bashrc末尾追加一行source。autoload 型fish / xonsh 及类似 shellshell 会自动从某个目录加载脚本无需修改 dotfile。注入方式改为设置一个标记/配置环境变量——xonsh 用XONSHRC指向脚本另一些 shell 则是设置其 autoload 目录。动手前必须先确认你的 shell 使用哪个环境变量因为下面多个步骤都以它为中心。打包脚本让 App 认识这个文件tools/copy_shell_integration.sh是唯一的打包入口脚本会从子模块拷贝脚本、并自动生成版本表头。四个必做改动tools/copy_shell_integration.sh仿照现有五个脚本添加一行cp $SUBMODULE/shell_integration/shell Resources/shell_integration/iterm2_shell_integration.shell。当前打包出的脚本位于 Resources/shell_integrationiterm2_shell_integration.{bash,fish,tcsh,xonsh,zsh}五个文件。submodules/iTerm2-shell-integration把子模块指针 bump 到包含新脚本的提交。iTerm2.xcodeproj/project.pbxproj将iterm2_shell_integration.shell添加为文件引用并纳入各 target 的 Resources 构建阶段xonsh 当时新增了 1 个 PBXFileReference 3 个 in Resources 构建文件。必须使用tools/add_file_to_xcodeproj.rb禁止手改工程文件。sources/ShellIntegration/iTermLatestVersionByShell.h不要手工编辑。该文件首行就是// DO NOT MODIFY - Generated by tools/copy_shell_integration.sh由copy_shell_integration.sh通过 grep 每个打包脚本里的ShellIntegrationVersion自动再生成grep ShellIntegrationVersion ... | sed -n s/^.*ShellIntegrationVersion\([^;]*\).*shell\([a-z]*\).*$/ \2: \1,/p当前生成结果可见于 sources/ShellIntegration/iTermLatestVersionByShell.hbash 20、fish 22、tcsh 8、xonsh 2、zsh 17。生成后shell条目会自动出现其值以脚本实际声明为准——不要假定是 1例如 xonsh 初始提交写的是1但脚本后来 bump 到版本 2、表头重新推导后现在读的是2。脚本侧有一个硬性前置条件必须输出能被生成器正则匹配的 token即包含ShellIntegrationVersionN;shellshell且 shell 名为小写[a-z]*。xonsh 的脚本就以注释形式满足此条件见 Resources/shell_integration/iterm2_shell_integration.xonsh 的# ShellIntegrationVersion2;shellxonsh。若脚本省略该 token 或 shell 命名不一致表头条目会被静默丢弃、该 shell 退化为无版本跟踪——依赖表头前务必先验证打包后的脚本包含此 token。枚举与 shell 注册表App 侧用枚举表示每种 shell需在两处登记sources/ShellIntegrationInstaller/iTermShellIntegrationInstaller.h在iTermShellIntegrationShell枚举中加入iTermShellIntegrationShellXxx现有 case 可见iTermShellIntegrationShellXonsh。再次强调版本表头iTermLatestVersionByShell.h不在这里编辑它是生成文件。sources/ShellIntegrationInstaller/iTermShellIntegrationWindowController.m(a)iTermShellIntegrationShellString返回shell(b) shell 名到枚举的map约 610 行添加shell: (iTermShellIntegrationShellXxx)现有条目如xonsh: (iTermShellIntegrationShellXonsh)。shell 版本通知表terminalSetShellIntegrationVersion:解析脚本上报的版本字符串并据此弹升级提醒位于 sources/VT100Screen/VT100ScreenMutableStateTerminalDelegate.m。两点改动更新该方法中过时的 shell 名单注释约 2704 行以包含新 shell。不要把新 shell 加入硬编码的 critical-updates 字典——除非该 shell 存在即使在仅关键更新模式下也必须催促用户升级的版本。全新 shell 应保持缺席其最新版本已由生成表头在非关键路径上提供。源码中该字典目前仅含tcsh/bash/zsh/fish而 xonsh 不在其中正是这一原则的体现。自动注入登录 shell 与 SSH 两条链路ShellIntegrationInjection.swift资源列表、枚举与注入类文件 sources/ShellIntegration/ShellIntegrationInjection.swift 负责在启动进程时通过修改环境变量注入集成脚本三处改动(a) 在资源列表约 167 行加入local(iterm2_shell_integration.shell)当前列表含bash/zsh/fish/xonsh及bash-si-loader、.zshenv、fish 的vendor_conf.d加载器。(b) 在Shell枚举约 181 行加case xxx shell并在工厂 switch 中返回对应的注入类。(c) 新增XxxShellIntegrationInjection类设置该 shell 的标记/配置环境变量让 shell 自动加载脚本。xonsh 的实现在约 282-304 行把脚本路径追加到冒号分隔的XONSHRC列表头部\(shellIntegrationDir)/iterm2_shell_integration.xonsh:\(existing)而目录式 autoload 的 shell 则把 autoload-dir 环境变量指向包含脚本的目录——请确认该目录确实含有一个命名正确、shell 会去 source 的脚本。关键不变量computeModified(env:argv:)必须原样返回argv仅改环境与 xonsh 类的return (modifiedEnvironment(...), argv)完全一致。一旦它改动 argv下面 Conductor 的空 argv SSH 分支就不再适用集成会在 SSH 场景下静默失败。若你的 shell 确实需要改 argv如 bash 的--posix则必须在该代码中显式点名该 shell。Conductor.swiftSSH 场景两处编辑文件 sources/SSH/Conductor.swift 处理 SSH 会话中的注入两处改动alwaysSupported约 2080 行加入shell当前值为[fish, xonsh, zsh]使 SSH 注入对远端登录 shell 生效。注释列举仅环境注入的 shell约 2344 行写的是 (zsh/fish/xonsh add no argv)。若你的 shell 是纯环境式加入该列表。该注释解释了空 argv 分支约 2332-2344 行为何正确纯环境注入时保持modifiedCommandArgs为空让 framer 以交互模式exec 登录 shell 并继承注入的环境如 zsh 的ZDOTDIR若在此处点名 shellframer 会执行login_shell -c shell外层非交互 shell 会在内层交互 shell 启动前拆掉注入典型如 zsh 的.zshenv会 unsetZDOTDIR集成便永不加载。此分支的正确性恰恰依赖于上面argv 不变不变量。手动安装器 UI 流程手动安装菜单 iTerm2 Install Shell Integration由iTermShellIntegrationWindowController.m驱动dotfile 型 shell 大多可复用现有 switchautoload 型则需要 xonsh 式的 无 dotfile 特判。需覆盖以下要点行号取自该文件均已在 xonsh 提交中验证shellIntegrationPath脚本写入位置。dotfile 型为~/.iterm2_shell_integration.shellautoload 型为 autoload 路径如 xonsh 返回~/.config/xonsh/rc.d/iterm2.xsh见约 275 行。注意 macOS 与 Linux 配置目录的差异。utilitiesdotfile 型追加别名PATH 型改为追加 PATH 行xonsh 用$PATH.insert(...)并在别名构建器的case ...Xxx:返回nil见约 292 行注释。shell_and/引号 switch约 331 行在匹配该 shell拼接与引号行为的分支中加case ...Xxx:。autoload 特判mkdir -p autoload dir步骤xonsh 为mkdir -p ~/.config/xonsh/rc.d需要在字符串构建器约 413/417 行与reallySend路径约 516/521 行各加一次。launchBashString/exitBashString单 bash 特例仅当新 shell 需要 xonsh 那样的 prompt 设置 workaround用bash -c设置 PS1/PS2见约 462 行。modifyStartupScriptsAndProceedTo:early-return 空操作以及两处finishSendShellCommandsInstall快捷路径约 648、709、721 行autoload 型 shell 跳过 dotfile 步骤注释明确写着 For xonsh, no dotfile modification is needed (rc.d auto-loads)。配套的粘贴命令视图 iTermShellIntegrationPasteShellCommandsViewController.m 还需两处改动(a) 更新 not supported 提示文案把新 shell 列入支持名单现有文案为 Only bash, fish, tcsh, xonsh, and zsh work with shell integration约 68 行。(b) autoload 型需添加 auto-loads ... no dotfile update needed 步骤与isDone快捷判断xonsh约 111-138 行isDone (stage i) || (stage i self.shell iTermShellIntegrationShellXonsh)。其他 shell 名单触点全局一致性新增 shell 名会散落在多个功能入口必须同步更新以免出现某处支持、某处报不支持的不一致sources/API/iTermAPIScriptLauncher.m向knownShells约 818 行当前[ bash, tcsh, zsh, fish, xonsh ]添加shell使 Python API 脚本能以该登录 shell 运行。sources/Settings/ProfilesGeneralPreferencesViewController.m两个列表都要改xonsh 提交同时更新了它们shells数组约 793 行当前[ bash, fish, xonsh, zsh]启用自定义命令的 Load shell integration automatically 选项。SSH 命令类型的提示文案约 836 行当前为Requires bash, fish, tcsh, xonsh, or zsh.用户可见按字母序插入新 shell。若只改数组不改文案SSH 帮助文本会错误地宣称该 shell 不受支持。OtherResources/framer.pyget_env_var约 596-618 行通过os.environ.get(SHELL)检测 shell两处编辑向known_shells约 604 行含 bash/csh/dash/fish/ksh/sh/tcsh/xonsh/zsh添加shell。仿照 xonsh 的$SHELL覆盖约 601-602 行以XONSHRC为标记新增基于该 shell 标记环境变量的覆盖if os.environ.get(MARKER_ENV_VAR, ): user_shell shell这一步对任何非 POSIX / 非登录 shell 场景都是必须的而非可选项当 shell 以自定义 profile 命令启动、经 SSH 启动、或任何非登录 shell 路径运行时$SHELL仍指向用户的 POSIX 登录 shell如/bin/zshbasename($SHELL)会误判。xonsh 正因XONSHRC需要此覆盖。验证方式以非登录自定义命令启动该 shell确认 framer 日志报告shellshell。sources/AITerm/RemoteCommand.swift更新getShellType帮助文案中的示例列表外观性见约 678 行 Detects the shell in use (e.g., bash, fish, xonsh, zsh).。sources/Settings/Base.lproj/PreferencePanel.xib更新 Load shell integration automatically 复选框的 tooltip 中 shell 列表约 2448 行当前为 Available for bash, fish, tcsh, xonsh and zsh. ...同样为外观性改动。测试与文档让改动可验证ModernTests/ShellIntegrationLiveHarness.swift给SupportedShell枚举中每一个 switch添加该 shellxonsh 当年触及五个位置均可在文件约 93-133 行看到对应 case枚举case列表约 94 行含zsh, bash, fish, tcsh, xonsh。可执行候选约 103 行如 xonsh 为[/usr/local/bin/xonsh, /opt/homebrew/bin/xonsh, /usr/bin/xonsh]。arguments(for:)启动参数约 108/114 行xonsh 为[executable, --no-rc, -i]——务必为 shell 定向路由而不是落入为其他 shell 合并的臂。资源名约 124 行xonsh 为iterm2_shell_integration.xonsh。sourceCommand(integrationPath:)约 128-133 行该 switch 穷尽且无 default不添加新臂无法编译。使用该 shell 自身的 source 语法zsh/bash/fish/tcsh 用source pathxonsh 用execx(open(path).read())注意存在source要求解析期常量路径的 shell。若该 shell 的行编辑器在 source 前发送光标位置报告CSI 6n如 xonsh 的 prompt_toolkitharness 必须应答否则 shell 卡死xonsh 目前因此XCTSkip见文件约 80-88 行新 shell 大概率需要同样的 skip 或实现 CPR 应答器。docs/notes-3.7.txt追加一行 release note限 50 列xonsh 为 xonsh is now a supported shell.。不需要改动 / 仅需验证sources/Settings/Profiles/ITAddressBookMgr.m只有注释提到 shell 名——可选择性扩充注释无需代码改动。引号转义提交9aff539d4是为语法会破坏反斜杠转义的 shellxonsh准备的通用使能器检查为新手 shell 生成的任何安装器命令字符串是否需要同类处理。小结一次新增 shell 的完整改动地图将以上清单归纳为一张改动地图打包层copy_shell_integration.sh 子模块指针 pbxproj 生成表头→App 识别层iTermShellIntegrationInstaller.h枚举 iTermShellIntegrationWindowController.m字符串/映射 VT100ScreenMutableStateTerminalDelegate.m版本通知→自动注入层ShellIntegrationInjection.swift注入类 Conductor.swiftSSH 支持牢记argv 不变不变量→手动安装 UI 层window controller 各分支 paste 命令视图→全局名单层API launcher、Profile 偏好面板、framer.py、RemoteCommand 文案、PreferencePanel tooltip→测试与文档层ShellIntegrationLiveHarness.swift的穷尽 switch release notes。对照 xonsh 的两个先例提交逐条执行即可稳妥地为新 shell 打通 iTerm2 的全部集成能力。【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
企业数字化 ERP 产品动态
相关推荐
Gradle 依赖解析引擎（Dependency Resolution Engine）内部原理深度解析 构建工具开发工具 【免费下载链接】gradle Adaptable, fast automation for all 项目地址： https://gitcode.com/gh_mirrors/gr/gradle 点击查看 免费下载 Gradle 的依赖解析引擎负责把构建脚本中声明的依赖（如 com.google.guava:guava:31.1-jre&#x… · 2026/9/21 7:40:57
别被网页制作模板中文坑了，懂建站报价才不亏 别被网页制作模板中文坑了，懂建站报价才不亏 网站做好了没人访问，这钱白花得冤不冤？很多老板找外包，问完建站报价，对方甩给你一个“网页制作模板中文”链接，说这是高端定制。你一看，哦，是套壳的。更坑的是，有些模板连基础的SEO结构都没做好，上线三个月，百度搜不到你公司名字。… · 2026/9/21 8:31:34
2026最新微信小程序连接wordpress：解决域名服务器搞不懂的实战指南 2026最新微信小程序连接wordpress：解决域名服务器搞不懂的实战指南 域名解析指向不对，服务器端口没开放，SSL证书配置报错——这三座大山，劝退了一半想用微信小程序展示WordPress内容的开发者。别急，2026最新的连接方案早已绕开了传统Web服务器配置的深坑，核心逻辑是：… · 2026/9/21 8:17:36
企业网站做电脑营销多少钱？揭秘防黑挂马的底层逻辑 企业网站做电脑营销多少钱？揭秘防黑挂马的底层逻辑 网站突然被黑，首页挂满赌博广告，后台密码怎么改都没用，这种绝望感做过站的都懂。很多老板第一反应是问：“清理一次病毒多少钱？”或者“换个服务器多少钱？”但真相往往扎心：单纯清理病毒的费用可能只要几百块，但重建信任、修复SEO权重、补全安全漏洞的成本，往… · 2026/9/21 8:03:27
3步搞定做品管圈网站从零搭建到上线避坑指南 3步搞定做品管圈网站从零搭建到上线避坑指南 不会写代码，但想给团队搭个品管圈展示平台？别慌。 很多河南的创业老板都卡在这一步：手里有现成的QCC成果，想做个官网放上去，结果一搜全是“前端开发教程”，看得头大。 做品管圈网站 这事儿，真没你想的那么玄乎。只要路子对，零基础也能 从零搭建… · 2026/9/21 7:45:56
Voyager 資料夾管理指南：為 Gemini 與 AI Studio 的 AI 對話打造真正的「檔案系統」 AI 应用前端 【免费下载链接】voyager Enhancement suite for Gemini, AI Studio, Claude & ChatGPT — plus a prompt manager for any websites, DeepSeek Harness included. / 面向 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件；其中的提示词管理器可用… · 2026/9/21 7:41:58
Flutter for OpenHarmony游戏卡片渐变背景实战：从原理到性能优化 直接铺开项目本身吧。这几个月我一直在折腾一件事：用Flutter给OpenHarmony做一款游戏集合类的App，说白了就是把若干小游戏塞进一个壳里，用统一入口分发。这个方向本身不算新鲜，真正让我花了不少心思的，是首页那堆游戏卡… · 2026/9/21 0:02:39
Word表格编号全攻略：从列表编号到题注交叉引用 写Word文档，最让人头疼的往往是那些“看起来不起眼”的小问题。比如表格编号这事：今天在表后面多加了两个空白行，明天给客户交稿前发现整个章节的编号全部错位，光是挨个改序号就能耗掉大半个下午。我前阵子帮人整理一份上百页的技… · 2026/9/21 0:02:39
从第一个站到第二个站：独立开发者的静态网站选型与落地实践 1. 项目概述1.1 核心需求解析做独立开发者这几年，说实话，第一个网站上线的那天晚上我兴奋得没睡着。但等它跑了半年，流量惨淡、功能臃肿、代码自己都懒得看第二遍之后，我才慢慢琢磨明白一个道理：第一个网站是练手&… · 2026/9/20 0:00:41
agents-generator 决策矩阵全解析：从项目检测到 AGENTS.md 规则生成的 16 步判定流程 agents-generator 决策矩阵全解析：从项目检测到 AGENTS.md 规则生成的 16 步判定流程 【免费下载链接】agentic-awesome-skills AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and … · 2026/9/21 0:00:18
gin-vue-admin 前端工具函数全景指南：src/utils 复用规范与源码级解析 gin-vue-admin 前端工具函数全景指南：src/utils 复用规范与源码级解析 【免费下载链接】gin-vue-admin 🚀ViteVue3Gin拥有AI辅助的基础开发平台，企业级业务AI开发解决方案，内置mcp辅助服务，内置skills管理，… · 2026/9/21 0:00:18
