mcpField
S
swain-keys

swain-keys

github.com/cristoslc安全2103 次安装25 周前更新
代码仓库

关于 swain-keys

swain-keys 是为 Git 项目配置提交签名与身份验证密钥的技能，适用于需要按项目管理密钥的开发者。它会识别 GitHub 或 Forgejo，并采用相应的签名方式，还可检查和验证配置状态。

主要功能

  1. 01自动识别 GitHub 或 Forgejo
  2. 02为 GitHub 配置 SSH 签名
  3. 03为 Forgejo 配置 GPG 签名
  4. 04查看密钥和平台注册状态
  5. 05验证签名能力与密钥注册

适用场景

  1. 01为 GitHub 项目配置提交签名
  2. 02为 Forgejo 项目上传 GPG 公钥
  3. 03检查或验证现有密钥配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cristoslc/swain --skill swain-keys

安装后在 Claude Code 中输入/swain-keys确认已加载。

附带文件scripts/swain-keys.shtests/test-swain-keys.sh

详细介绍

swain-keys

为每个项目配置用于 Git 签名和身份验证的密钥。

支持两种代码托管平台，并为每种平台使用合适的签名模式：

  • GitHub — 通过 gh ssh-key add 使用 SSH 签名。
  • Forgejo — 通过 fj user gpg upload 使用 GPG 签名。

自动从 origin 远程仓库 URL 检测代码托管平台。设置 SWAIN_FORGE 可覆盖自动检测结果。

调用时

定位并运行配置脚本 scripts/swain-keys.sh（相对于此技能目录）：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SCRIPT="$REPO_ROOT/.agents/bin/swain-keys.sh"

如果路径搜索失败，请使用 glob 搜索 **/swain-keys/scripts/swain-keys.sh。

工作流

默认（无参数或“set up keys”）

先运行 --status 以显示当前状态：

bash "$SCRIPT" --status

如果密钥尚未全部配置完成，请询问用户是否要继续配置。

配置（“provision keys”、“configure signing”、“set up SSH”）

运行完整的配置流程：

bash "$SCRIPT" --provision

在 GitHub 上，脚本将：

  1. 根据 Git 远程仓库或目录推导项目名称。
  2. 如果 ~/.ssh/<project>_signing 不存在，则生成该文件（ed25519，无密码短语）。
  3. 使用已配置的 Git 邮箱地址创建 ~/.ssh/allowed_signers_<project>。
  4. 通过 gh ssh-key add 将公钥添加到 GitHub，用于身份验证和签名。
  5. 创建 ~/.ssh/config.d/<project>.conf，其中包含一个主机别名，该别名会绕过全局 SSH Agent，并通过 ssh.github.com:443 连接 GitHub SSH。
  6. 更新 Git 远程仓库 URL，使其使用此项目专属的主机别名。
  7. 在本地 Git 配置中设置 SSH 提交和标签签名。
  8. 验证 SSH 连接和签名能力。

在 Forgejo 上，脚本将：

  1. 根据 Git 远程仓库或目录推导项目名称。
  2. 如果尚不存在，则通过 gpg --batch --generate-key 生成 OpenPGP ed25519 密钥（以无人值守模式运行，使用 %no-protection）。
  3. 通过 fj user gpg upload 将 GPG 公钥上传到 Forgejo。
  4. 在本地配置 Git，以使用 OpenPGP 签名（gpg.format=openpgp），覆盖任何全局 SSH 签名配置。
  5. 保持远程仓库 URL 不变（Forgejo SSH 身份验证由用户现有的 SSH 配置处理）。
  6. 验证签名能力和 Forgejo GPG 密钥状态。
状态（“key status”、“check keys”）
bash "$SCRIPT" --status

显示代码托管平台类型、密钥状态、Git 配置和平台上的注册状态。适用时会报告“GPG key registered on Forgejo as signing key (Verified: true)”。

验证（“verify keys”、“test signing”）
bash "$SCRIPT" --verify

测试签名能力和平台上的密钥注册状态。对于 Forgejo，会验证 GPG 密钥在平台上是否显示 Can Sign: true。

环境变量

  • SWAIN_FORGE — 设置为 github 或 forgejo，以覆盖自动检测结果。
  • SWAIN_FORGEJO_HOST — 设置 Forgejo 实例 URL（例如，https://codeberg.org）。当 origin 包含 localhost 时，默认值为 http://localhost:3000。

处理权限范围刷新

GitHub

如果 gh ssh-key add 因权限范围不足而失败，脚本会打印一条需要执行操作的提示。出现这种情况时：

  1. 告知用户需要授权额外的 GitHub 权限范围。
  2. 向用户提供以下命令：gh auth refresh -s admin:public_key,admin:ssh_signing_key。
  3. 该命令会打开浏览器进行 OAuth 授权，需要人工操作。
  4. 用户确认后，重新运行 --provision（该操作具有幂等性，会跳过已完成的步骤）。
Forgejo

如果 fj user gpg upload 失败，请检查 fj 是否已通过身份验证：

fj auth login

然后重新运行 --provision。

与 swain-init 集成

从 swain-init 调用时，直接运行 --provision，不要先运行状态检查。是否继续的提示由 swain-init 处理。

会话书签

完成配置后，更新书签：bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" "Provisioned keys for {project}"

错误处理

  • 如果不在 git 仓库中：以清晰的消息提示失败。
  • 如果 gh CLI 不可用（GitHub）：跳过 GitHub 注册步骤，并提醒用户手动添加密钥。
  • 如果 fj CLI 不可用（Forgejo）：跳过 Forgejo 注册，并提醒用户手动上传 GPG 密钥。
  • 如果未安装 gpg（Forgejo）：失败并提供安装说明。
  • 如果未配置 git 邮箱：尽早失败并提供操作说明。
  • 所有步骤均支持幂等操作，可在修复问题后安全地重新运行。

评论

支持 Markdown