Installation and Upgrade

安装与升级

系统要求

组件	要求
VS Code	1.98.0 或更高版本
Git	2.31.0 或更高版本；建议使用当前仍受维护的版本
工作区	本地或远程扩展宿主可访问的真实文件系统工作区
工作区信任	必须设为受信任
网络	能访问所连接平台的 Web/API 与 Git HTTPS 地址

TriForge 是 workspace 扩展。使用 Remote SSH、WSL 或 Dev Container 时，扩展和 Git 命令运行在远程扩展宿主一侧；Token 也保存在该环境对应的 VS Code SecretStorage 中。

为什么要求 Git 2.31+

TriForge 使用 Git 的 GIT_CONFIG_COUNT、GIT_CONFIG_KEY_n、GIT_CONFIG_VALUE_n 机制，把只对单个子进程有效的认证和安全设置传给 Git。这些能力从 Git 2.31 起才可依赖。旧版 Git 可能无法应用临时 Authorization Header、凭据交互禁用或 Hook 隔离，不应执行带 Token 的远程操作。

查看版本：

git --version

从 VSIX 安装

图形界面

1. 下载 triforge-git-0.5.1.vsix。
2. 在 VS Code 打开扩展视图。
3. 点击扩展视图右上角 …。
4. 选择“从 VSIX 安装…”。
5. 选中 VSIX，按提示重新加载窗口。

命令行

Windows PowerShell：

code --install-extension .\triforge-git-0.5.1.vsix

macOS/Linux：

code --install-extension ./triforge-git-0.5.1.vsix

安装后，在活动栏查找 TriForge 的分支/合并图标；命令面板中搜索 TriForge Git 可查看所有命令。

从源码运行

需要 Node.js 和 pnpm。仓库根目录执行：

pnpm install
pnpm run verify

然后用 VS Code 打开项目文件夹，按 F5 启动 Extension Development Host。

打包本地 VSIX：

pnpm run package

从旧发布者升级

0.4.0 起发布者改为 zhangxh-math，扩展 ID 为：

zhangxh-math.triforge-git

较早本地构建可能使用：

local-lab.triforge-git

VS Code 会把两个 ID 当成两个不同扩展，不能原位升级。先卸载旧 ID：

code --uninstall-extension local-lab.triforge-git

再安装新 VSIX。不要同时保留两个版本，否则它们可能贡献相同的命令和视图。

SecretStorage 按扩展 ID 隔离。新版无法读取旧 ID 的 Token，这是安全边界，不是迁移故障；安装后需重新连接平台。

普通版本升级

升级到同一个扩展 ID 的新版本时：

1. 完成或取消正在进行的 Merge/Revert 等 Git 操作。
2. 安装新 VSIX 或从 Marketplace 更新。
3. 重新加载 VS Code。
4. 打开 TriForge 并点击刷新。
5. 如果视图顺序仍是旧版布局，运行“View: Reset View Locations”。

正常升级不会主动删除连接或 Token。但如果扩展 ID、实例 URL 或账号发生变化，出于安全原因可能需要重新验证 Token。

卸载

code --uninstall-extension zhangxh-math.triforge-git

卸载扩展不会：

• 删除本地 Git 仓库；
• 删除 .git/config 中的 remote；
• 删除已经创建的 GitHub/GitLab/Gitea 仓库；
• 回滚已经完成的提交或推送。

若希望在卸载前移除 Token，可在“托管平台”区域逐个执行“删除连接”。这会删除该连接的 SecretStorage 凭据，但仍不会改变 Git remote。

工作区信任与虚拟工作区

TriForge 会运行本机 Git、读取仓库状态并访问远程服务，因此清单明确声明：

• 不支持未受信任工作区；
• 不支持虚拟工作区。

如果功能全部不可用，请先查看 VS Code 窗口是否处于 Restricted Mode，并确认打开的是磁盘上的文件夹，而不是只读虚拟文件系统。

安装后自检

1. 命令面板能找到“TriForge Git: 刷新”。
2. 活动栏出现 TriForge 图标。
3. 打开 Git 仓库时能看到当前分支。
4. 执行 git --version 确认为 2.31+。
5. 打开“输出”面板并选择“TriForge Git”，确认没有激活错误。

若图标、视图或按钮不见了，转到 故障排查。