miguelbalvin-dev/GAM

# GAM — Git Account Manager [](https://www.npmjs.com/package/@gamcli/gam) [](https://www.npmjs.com/package/@gamcli/gam) [](https://nodejs.org) [](LICENSE) ## 安装说明 ``` npm install -g @gamcli/gam ``` **仅限 Linux：** 安装 `libsecret` 以支持 keychain： ``` # Ubuntu / Debian sudo apt-get install libsecret-1-dev # Fedora / RHEL sudo dnf install libsecret-devel # Arch sudo pacman -S libsecret ``` ## 快速开始 ``` # 添加你的第一个 GitHub 账户 gam add # 添加第二个账户（例如工作账户） gam add # 在它们之间切换 gam use personal gam use work # 检查当前处于活动状态的账户 gam status ``` 就是这样。无需环境变量，无需 OAuth App 设置，无需 SSH 密钥管理。它可以直接运行。 ## 功能 - **OAuth Device Flow** — 通过 GitHub 的浏览器流程进行身份验证；无需密码或 PAT - **内置 OAuth Client ID** — 开箱即用，无需注册应用 - **安全的 token 存储** — token 存储在 OS keychain 中（macOS Keychain、Windows Credential Manager、Linux SecretService） - **本地别名** — 为每个账户指定一个易于记忆的名称（`work`、`personal`、`oss`），独立于 GitHub 用户名 - **Git credential helper** — `git push` 和 `git pull` 自动使用当前活动账户；无需重新身份验证 - **健康诊断** — `gam doctor` 检查您的整个设置，并准确告诉您需要修复什么 ## 示例工作流 ``` # 对两个账户进行身份验证 gam add # follow the browser flow → choose alias "personal" gam add # follow the browser flow → choose alias "work" # 列出你拥有的账户 gam list # ✓ personal MiguelCastrillon active # · work company-user # 在推送之前切换到你的工作账户 gam use work git push # uses work credentials automatically # 切换回来 gam use personal git push # uses personal credentials automatically # 运行健康检查 gam doctor ``` ## 命令 ### `gam add` 通过 OAuth Device Flow 对 GitHub 账户进行身份验证。 ``` gam add ``` 打开浏览器并跳转至 `github.com/login/device`。一旦您授权，系统将提示您为该账户选择一个本地别名。随后，GAM 会将其自身配置为 Git credential helper，以便 `git push` 能够立即使用。 ``` ◆ Add Account ────────────────────────────────────────────── Open in your browser: → https://github.com/login/device Enter this code: → ABCD-1234 ────────────────────────────────────────────── ✓ Account added ALIAS personal GITHUB MiguelCastrillon NAME Miguel Castrillon EMAIL miguel@example.com ``` ### `gam list` 列出所有已配置的账户。 ``` gam list ``` ``` ◆ Accounts · 3 configured ────────────────────────────────────────────── ● personal MiguelCastrillon active · work company-user · oss octocat ``` ### `gam use ` 切换活动账户，并更新 `git config --global user.name` 和 `git config --global user.email`。 ``` gam use work ``` ``` ✓ Switched to work ALIAS work GITHUB company-user NAME Ada Lovelace EMAIL ada@example.com GIT CONFIG user.name Ada Lovelace user.email ada@example.com ``` ### `gam status` 显示当前活动的账户，并验证 git config 是否同步。 ``` gam status ``` ``` ◆ Status ────────────────────────────────────────────── ACCOUNT ALIAS work GITHUB company-user NAME Ada Lovelace EMAIL ada@example.com AUTH ✓ Active GIT CONFIG USER.NAME Ada Lovelace USER.EMAIL ada@example.com IN SYNC ✓ Yes ``` ### `gam remove ` 移除账户并删除其存储的 token。 ``` gam remove work ``` 在移除之前，会显示账户详细信息并要求确认。 ### `gam doctor` 运行六项健康检查，并报告您整个设置的状态。 ``` gam doctor ``` ``` ◆ Health Check ────────────────────────────────────────────── ✓ Git installed git version 2.43.0 ✓ Accounts configured 2 accounts configured ✓ GitHub authentication Token stored for personal ✓ Token scope repo access enabled ✓ Git config in sync user.email matches personal ✓ Git credential helper Registered ────────────────────────────────────────────── ✓ Everything looks good. ``` 如果某项检查失败，修复方法会内联显示： ``` ✖ GitHub authentication No token found for work → Run gam add to re-authenticate ``` | 检查项 | 通过条件 | |---|---| | 已安装 Git | `git` 在 PATH 中可用 | | 已配置账户 | 至少添加了一个账户 | | GitHub 身份验证 | 活动账户在 keychain 中存在对应的 token | | Token 范围 | Token 包含 `repo` 权限范围 | | Git config 已同步 | `git config user.email` 与活动账户匹配 | | Git credential helper | `gam` 已注册为 Git credential helper | ### `gam config` 管理用于身份验证的 OAuth Client ID。 ``` # 设置自定义 Client ID gam config oauth # 显示当前配置 gam config show ``` GAM 内置了 OAuth Client ID 并可立即使用。只有在您想要使用自己的 GitHub OAuth App 时（例如，用于企业版 GitHub 或控制授权期间显示的应用名称），才需要用到此命令。 **创建您自己的 OAuth App：** 1. 前往 **GitHub → Settings → Developer settings → OAuth Apps → New OAuth App** 2. 将 **Authorization callback URL** 设置为 `http://localhost`（Device Flow 不使用此项） 3. 在应用设置中启用 **Device Flow** 4. 复制 **Client ID** 并运行 `gam config oauth` ## 架构 GAM 遵循严格的分层架构 —— 命令层很轻量，所有逻辑都存在于服务中。 ``` src/ commands/ Thin CLI handlers — one file per command services/ Business logic — no I/O, fully unit-tested github/ GitHub API and OAuth Device Flow (RFC 8628) git/ Git operations via execa storage/ Config persistence (conf) and token storage (keytar) ui/ Terminal Design System — theme, components, landing screen utils/ Shared error classes types/ TypeScript interfaces container.ts Composition root — all dependency wiring in one place cli.ts Commander.js program factory index.ts Entry point — intercepts git-credential before Commander ``` **端到端工作原理：** ``` gam add └─ AccountService.authenticate() ├─ DeviceFlow.requestDeviceCode() → POST /login/device/code ├─ DeviceFlow.pollForToken() → POST /login/oauth/access_token ├─ GitHubClient.getCurrentUser() → GET /user ├─ GitHubClient.getPrimaryEmail() → GET /user/emails ├─ ConfigStore.saveAccount() → ~/.config/gam/config.json └─ CredentialStore.setToken() → OS keychain git push └─ git asks: gam git-credential get └─ CredentialHelperService.getCredential() └─ CredentialStore.getToken() → OS keychain ``` **别名与 GitHub 用户名的对比：** | 字段 | 用途 | |---|---| | `alias` | 本地的、用户选择的名称，被所有 `gam` 命令使用 | | `username` | GitHub 登录名 —— 用于 git HTTP 身份验证 | ## 环境要求 - **Node.js** 18 或更高版本 - **Git**（用于 `gam use` 和 credential helper） - **OS keychain** — macOS 和 Windows 内置支持；Linux 上需要 `libsecret` ## 向后兼容性 在引入别名功能之前创建的账户会在读取时进行透明迁移：它们会自动获得 `alias = githubUsername`，且不会对已存储的数据进行任何更改。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：Git工具, MITM代理, OAuth, SOC Prime, 凭据管理, 开发工具, 自动化攻击, 账户管理