swain-keys

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

swain-keys

Per-project SSH key provisioning for git signing and authentication.

为Git签名与认证提供按项目划分的SSH密钥配置服务。

When invoked

调用方式

Locate and run the provisioning script at

skills/swain-keys/scripts/swain-keys.sh

bash

SCRIPT="$(find . .claude .agents -path '*/swain-keys/scripts/swain-keys.sh' -print -quit 2>/dev/null)"

If the path search fails, glob for

**/swain-keys/scripts/swain-keys.sh

定位并运行位于

skills/swain-keys/scripts/swain-keys.sh

的配置脚本：

bash

SCRIPT="$(find . .claude .agents -path '*/swain-keys/scripts/swain-keys.sh' -print -quit 2>/dev/null)"

如果路径搜索失败，使用通配符查找

**/swain-keys/scripts/swain-keys.sh

。

Workflows

工作流程

Default (no arguments or "set up keys")

默认流程（无参数或输入“set up keys”）

Run

--status

first to show current state:

bash

bash "$SCRIPT" --status

If keys are not fully provisioned, ask the user if they'd like to proceed with provisioning.

先运行

--status

查看当前状态：

bash

bash "$SCRIPT" --status

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

Provision ("provision keys", "configure signing", "set up SSH")

配置流程（输入“provision keys”、“configure signing”、“set up SSH”）

Run the full provisioning flow:

bash

bash "$SCRIPT" --provision

The script will:

Derive a project name from the git remote or directory
Generate
```
~/.ssh/<project>_signing
```
(ed25519, no passphrase) if not exists
Create
```
~/.ssh/allowed_signers_<project>
```
with the configured git email
Add the public key to GitHub via
```
gh ssh-key add
```
for both authentication and signing
Create
```
~/.ssh/config.d/<project>.conf
```
with a host alias that bypasses global SSH agents
Update the git remote URL to use the project-specific host alias
Set local git config for commit and tag signing
Verify SSH connectivity and signing capability

运行完整的配置流程：

bash

bash "$SCRIPT" --provision

脚本将执行以下操作：

从Git远程仓库或目录推导项目名称
若不存在则生成
```
~/.ssh/<project>_signing
```
（ed25519类型，无密码短语）
创建包含已配置Git邮箱的
```
~/.ssh/allowed_signers_<project>
```
文件
通过
```
gh ssh-key add
```
将公钥添加到GitHub，用于认证与签名
在
```
~/.ssh/config.d/<project>.conf
```
中创建绕过全局SSH代理的主机别名
更新Git远程仓库URL以使用项目专属的主机别名
设置本地Git配置以启用提交与标签签名
验证SSH连接与签名功能

Status ("key status", "check keys")

状态查询（输入“key status”、“check keys”）

bash

bash "$SCRIPT" --status

bash

bash "$SCRIPT" --status

Verify ("verify keys", "test signing")

验证流程（输入“verify keys”、“test signing”）

bash

bash "$SCRIPT" --verify

bash

bash "$SCRIPT" --verify

Handling scope refresh

权限范围刷新处理

gh ssh-key add

fails due to insufficient scopes, the script will print an action-needed message. When this happens:

Tell the user they need to authorize additional GitHub scopes

Show them the command:

gh auth refresh -s admin:public_key,admin:ssh_signing_key

This will open a browser for OAuth — it requires human interaction
After they confirm, re-run
```
--provision
```
(idempotent, will skip completed steps)

如果

gh ssh-key add

因权限范围不足失败，脚本会显示需要执行操作的提示信息。出现此情况时：

告知用户需要授权额外的GitHub权限范围

显示命令：

gh auth refresh -s admin:public_key,admin:ssh_signing_key

该命令会打开浏览器进行OAuth授权——需要人工交互
用户确认后，重新运行
```
--provision
```
（脚本具有幂等性，会跳过已完成的步骤）

Integration with swain-init

与swain-init的集成

When called from swain-init, run

--provision

directly without the status-first flow. swain-init handles the "would you like to?" prompt.

当从swain-init调用时，直接运行

--provision

，跳过先查看状态的流程。swain-init会处理“是否继续？”的提示。

Session bookmark

会话书签

After provisioning, update the bookmark:

bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "Provisioned SSH keys for {project}"

配置完成后，更新书签：

bash

bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "Provisioned SSH keys for {project}"

Error handling

错误处理

If not in a git repo: fail with clear message
If
```
gh
```
CLI unavailable: skip GitHub registration steps, warn user to add keys manually
If git email not configured: fail early with instructions
All steps are idempotent — safe to re-run after fixing issues

若不在Git仓库中：显示明确错误信息后退出
若
```
gh
```
CLI不可用：跳过GitHub注册步骤，提醒用户手动添加密钥
若Git邮箱未配置：提前退出并给出配置说明
所有步骤均具有幂等性——修复问题后可安全重新运行