钥匙

钥匙是 Skill 需要的 API Key、Token 等凭据。输出目录、模型选择等普通配置由 Skill 自己处理；SkillHub 不提供通用参数管理器。

确认 Skill 的需求

实际运行的 SKILL.md 中，metadata.skillhub.env 是唯一钥匙需求说明。明确写 env: [] 表示作者确认无需钥匙；没有声明表示尚未确认。自动检测、导入发现和运行报错只是建议，同名钥匙已在库中也不会因此注入。

作者确认变量名和用途后，可用 skillhub env declare "<local-skill-id>" --key "<KEY>" --description "<用途>" 补充需求并保存版本。旧 --required / --optional 参数继续兼容，缺值均不阻止启动；默认不写 required 字段。确认完全不需要时用 --empty。

无编辑权时，请作者补充；或到 APP 的 Skill 钥匙页，在建议行点击「另存为我的 Skill 并补充」并亲自确认。副本独立维护、不自动跟随原版更新，不继承钥匙选择或使用同意；CLI 不创建副本。已有需求时使用 --empty 还须加 --replace，明确全部移除。内容或来源版本需要重新核对时先处理提示，再明确继续运行。

全部钥匙与按团队

变量卡的名称右侧显示灰色「用于…」，用途和编辑输入框都在同一行，过长时省略。「全部钥匙」取声明该变量的 Skill 中第一个非空用途，不一致时悬停可查看其他说明。双击编辑后，会顺序更新所有可维护的本机 Skill；作者维护的项跳过并显示数量。部分失败会保留输入和错误，重试只处理失败项。没有本机 Skill 声明的变量以钥匙备注显示只读用途。

每把钥匙独立保存一个变量名和值，同名添加不会覆盖其他钥匙；备注用于区分不同账号。迁移后的别名、默认值、标签值和 Skill 覆盖均成为独立钥匙，之后分别更新。

钥匙按服务器、空间和账号隔离。账号钥匙由 Server 加密保存并同步到本机加密缓存，默认只有本人可用；Server 运营者持有解密材料。仅本机空间的钥匙只在这台电脑加密保存，不同步或共享。钥匙值不会随 Skill 包上传。共享后接收者可用于其有权运行且声明匹配的 Skill；撤权阻止后续获取，但无法收回已经取得的值。

已登录账号的旧本机钥匙在服务器支持统一钥匙时自动上传到当前服务器，不自动共享；不再询问首次启用或上传范围。旧 Server 保留本机数据，升级并恢复同步后继续上传。迁移后每把独立更新，保留原来的实际选择；商店或团队 Skill 仍需使用同意。

标题右侧切换「全部钥匙 / 按团队」、刷新和添加钥匙；下方搜索并按来源/团队筛选。「全部钥匙」的搜索框是「搜索 Skill」：只筛选右侧的 Skill，左侧钥匙不变，方便找到 Skill 后直接把值拖过去；搜索时悬停钥匙不会隐藏其他 Skill。「按团队」仍搜索变量名、备注或标签。连线后会立即显示新连线，保存和同步在后台完成；失败时连线会撤回并提示重试。点击一条连线可以选中它，按 Delete 即取消连接：这个变量会从该 Skill 的 SKILL.md 声明里移除，提示中可以撤销。团队或商店的 Skill 由作者维护，不能这样移除。

「全部钥匙」是两栏连线面板，直接放在页面上，没有外框和列标题，两栏一直延伸到窗口底部：左栏将所有可见值与本机 Skill 声明按变量名分卡，可滚动且隐藏滚动条；右栏均匀排列你本机的全部 Skill（还没声明钥匙的也在，标注「未声明钥匙」），放不下时可滚动。点击 Skill 名称打开其钥匙页签。一个值可连到多个 Skill；只要被一个 Skill 使用，胶囊和触点即为蓝色。每个 Skill 的每个变量各有一条线：使用中蓝色流动虚线，待允许静态蓝线，缺值从橙色输入行连橙线，Skill 卡也显示橙框。减少动态效果时不流动。筛掉的值不画线。

把值触点拖到声明了同变量的 Skill 上，即可改用；也可点击或键盘选中触点，再点击蓝框高亮的 Skill。拖到你自己的、还没声明这个变量的 Skill 上时，会先把变量写进它的 SKILL.md 声明，再改用这个值。团队或商店的 Skill 由作者维护，不能这样添加声明，会显示「由作者维护，无法添加钥匙声明」。选中时其他连线变淡，Esc 或再次点击原触点取消，不兼容的目标不接收。触点提示「拖到 Skill 上改用这个值」；需要使用同意时另行确认，「待允许」按钮可直接打开确认。变量右上角「+」添加行内值，页头「添加钥匙」和底部「添加新钥匙」直接在左栏追加行内新卡，自动居中并聚焦变量名；填写变量名、用途及密码值后在值行回车保存；已有值时添加的新值保存后再选择要连接的 Skill；橙色缺值行保存后，会逐个选给当前所有缺该变量且关系已就绪的 Skill，并逐个确认使用同意。个别失败可重试，不会重复创建已保存的值。键盘选中触点后，焦点移到第一个可接收的 Skill；切换成功或失败后返回原触点。点 Skill 名称会取消选中，并按其本机或团队来源打开钥匙页签。

悬停变量卡、把键盘焦点移入卡内、编辑或添加值，以及选中或拖动触点时，会高亮该变量：右栏只保留声明了它的 Skill 并重新居中，其他卡片和连线淡出；选中或拖动触点时右栏保留全部 Skill，方便连到还没声明的 Skill。移出卡片后有短暂宽限，可跨到右栏继续选择；编辑、草稿、选中或拖动时会持续保留。卡片移动时连线跟随，减少动态效果时直接切换。

系统 Skill、声明无效及其他账号或空间的 Skill 不参与面板。真实读取失败仅在对应 Skill 卡片显示「钥匙关系读取失败」，可单击重试，不以整页警告代替。「按团队」若有关系读取失败，会显示一条可重试的非阻塞提示，提醒使用关系可能不完整。

「按团队」保持每个团队独立网格，显示备注、来源和自定义标签；团队钥匙显示团队与提供者。「用在」为可横向滚动的 Skill 小卡片，支持方向键和「›」翻页，点击打开 Skill。原右键或操作菜单保留。两个连线面板的「+ 标签」就地新增，点击已有标签就地编辑；回车保存、空值回车删除、Esc 或失焦取消。团队页菜单保留原对话框。标签最多三个且不重复，各不超过六个 Unicode 字符，只在本账号的这台电脑显示，不同步、不共享、不影响匹配。只有所有者能更新、共享、删除；删除须先确认并列出受影响的 Skill，每把同名钥匙仍是独立对象。

Skill 的钥匙页签分为两栏：左侧变量卡片可上下滚动，右侧 Skill 卡片居中。每行最右侧有触点，点击可改用这个值；也可以从当前使用的触点拖到同变量的另一触点，松在其他地方不改变选择。需要使用同意时另行确认。使用中为蓝色流动虚线，待允许为静态蓝线，缺值为静态橙线；减少动态效果时不流动。缺值变量直接显示输入框，Skill 卡片也会变为橙色边框。

值仅显示固定 16 个字符单元的遮挡预览，按 Unicode 字符计数：至少 24 个字符时显示首尾各 4 位和中间 8 个圆点；16–23 个字符时显示 12 个圆点和末 4 位；更短或尚不可读时只显示 16 个圆点。预览只在本机生成，不上传。单击本人值可输入新值，回车保存；未保存时，Esc、点击行外或焦点移到应用内其他行时放弃输入并保留旧值。切到密码管理器等其他应用时保留输入，保存进行中也不会取消；修订冲突保留输入，核对新修订后再保存。他人团队共享值带蓝色内圈及团队、提供者，直接共享显示提供者，均保持只读。本人值可加标签，通过旁边的图标共享或删除；尚未同步的值显示「仅本机」或上传失败提示。

点击「待允许」即可打开使用同意对话框。点击已经使用的触点不会重复选择；待允许时会直接打开同意对话框。双击「用于…」可编辑用途，回车或离开输入框保存，Esc 取消；失败保留输入，重新读取声明期间暂不可编辑，作者维护的声明只读。变量右上角「+」添加行内新值；它和橙色缺值输入都可在回车、点击行外或焦点移到应用内其他元素时保存，切到密码管理器等其他应用或输入法选字期间不会保存。非空值按原规则创建并选择或分配，需要同意时另行确认；失败保留草稿和输入，显示一行错误，可继续重试。空「+」草稿离开时移除，空缺值输入保留；Esc 仍可取消草稿，再点「+」会聚焦已有输入。左栏底部「添加新钥匙」完成后，新卡片会居中滚入视野；减少动态效果时直接跳转。

Skill 钥匙页签底部有两个入口：「添加新钥匙 ｜ 选择已有钥匙」。「选择已有钥匙」会弹出下拉菜单，列出你已有值、但这个 Skill 还没声明的变量名，顶部可搜索。选中后会把变量写进 SKILL.md 声明；这个变量只有一个值时自动连上，有多个值时请在卡片里点选要用的那个。团队或商店的 Skill 由作者维护，不能这样添加。

Skill 底部「添加新钥匙」直接追加行内卡片。图标、变量名和「用于」用途输入排在同一行；名称下方可点击检测到或待确认的变量预填，自己输入用途后不再被建议覆盖。填写变量名、用途和密码值后，在值行回车或点击卡片外保存，焦点移到应用内其他元素也会保存；切到密码管理器等其他应用时保留输入。名称尚未声明时先补声明，已声明时只创建并选择，保留原用途。只有未声明且无编辑权时，才须点击卡内「创建个人副本并保存」明确确认；直接回车会提示该入口，离开不会创建副本，原版不变。空卡离开或 Esc 移除；部分填写离开时保留草稿，只标记缺失或无效字段的边框，回车才显示中文校验气泡。已有填写时 Esc 仅失焦，草稿保留且不保存。保存失败在输入下方显示一行错误并保留输入，重试不重复创建已保存的钥匙；钥匙页需要同步时会尝试同步后再重试。中文输入法选字的回车不会保存；标签完成输入后才检查长度。钥匙页新卡只创建钥匙并把用途保存为备注，不自动选择 Skill。仅本机空间本地保存，账号空间在服务器支持时直接保存到该服务器。

团队钥匙

账号钥匙归创建者所有，团队是共享对象。只有所有者能修改值、管理共享或删除；接收者不会获得所有权。共享名单决定谁能获取，Skill 的实际声明与使用同意仍须满足。

所有者退出或被移出团队后，其钥匙对该团队的共享失效，所有权保留。接收者仍有直接共享或其他团队授权时可保留访问；否则需要替代钥匙。团队继续使用前，请让留在团队的同事创建并共享替代钥匙。

尚未迁移的旧团队钥匙保留原运行范围；按名称创建或更新的旧接口不能安全保留对象身份时，APP 会提示升级服务器，不会用本机改值冒充云端更新。

在团队分组点击「添加并共享给此团队」，会新建本人拥有的独立钥匙并共享，不会覆盖同名对象。owner 可以「管理共享」选择用户或团队，并明确「取消共享」某项；「删除钥匙」删除整把及全部共享，不替接收者换另一把。接收者没有更新、共享、删除或使用记录入口。别名、默认值、变体和「仅此 Skill」不再提供，各把独立保存和更新。

主动退团前会列出本人将停止向该团队共享的钥匙。团队仍需使用时，请让留在团队的同事先创建并共享替代钥匙，不建议多人共用登录账号。被移出或失去最后路径时，通知中心提示受影响变量；打开后可定位仍可访问的钥匙，或返回受影响 Skill 的钥匙页重新选择。离线通知可能延后，仍有其他路径的接收者可以继续使用。

在「按团队」视图的卡片操作菜单中，owner 可打开「使用记录」：默认最近 30 天，可选 1–90 天并分页查看用户、可见 Skill、次数与最近时间。不可查看的 Skill 不可点击。记录只覆盖服务端成功运行授权，不代表程序或供应商实际执行成功；未走服务端复验的本人运行（包括在线本地运行）与平台外使用不统计。

本机恢复与重置

迁移和旧值更新的恢复副本位于当前空间的 env-import-backups，值、元数据、选择、同意与迁移标记均加密保存。数据密钥是当前空间 keys/<账号>/unified/data-key.bin 中的 32 随机字节，后续代在 key-material/<代号>/data-key.bin；目录 0700、文件 0600，Windows 使用私有 ACL。请连同密钥文件安全备份；同时取得文件与密文的人能够解密，系统钥匙串不再保护它。仅复制密文不能恢复丢失的密钥。

VAULT_KEY_MISSING 表示原数据密钥文件不可用。旧测试版使用系统钥匙串的库也按密钥丢失处理，程序不会调用系统钥匙串或自动替换密钥。值备份使用同一数据密钥加密，不能单靠值备份恢复；有此前导出的口令加密数据密钥文件时，可用它恢复。

macOS 上本人文件的权限被放宽时，APP 会自动收紧为 0600 后继续。属主不符、存在额外硬链接或 Windows 私有 ACL 无效时返回 VAULT_KEY_INSECURE；应恢复当前用户所有权、移除额外硬链接并恢复私有权限后重试，不要重置密钥。只有文件缺失或长度不符才返回 VAULT_KEY_MISSING。

需要取回迁移前的文件时，可明确运行：

skillhub keys restore --backup "<当前空间 env-import-backups 内的备份路径>" --confirm --json

此命令只解密到新的私有 key-recovery 目录，恢复值、策略与标记；不会覆盖运行中的库。请妥善保管恢复目录，导入需要的数据后删除其中的明文。

遇到 KEY_INSTANCE_CHANGED 或 KEY_REVISION_ROLLBACK，先核对实例与服务器恢复情况，再明确运行：

skillhub keys reset-cloud --confirm --json

它只清理已同步的云端记录、实例绑定、游标及失效的待上传操作，保留 pending_upload、local_only、数据密钥和原备份，再重新同步。原选择不会悄悄改为另一把。自部署的实例信任变更仍需通过连接服务器流程确认。

确实无法取回原数据密钥时，可明确运行 skillhub keys rotate-data-key --confirm --json 启用新一代密钥。旧密钥材料和加密资料不会删除，旧缓存归档在 env-import-backups/key-generation-<新代号>/；旧未同步值在原密钥恢复前暂不可读。结果会给出新代号与云端同步错误（如有），网络恢复后可用 skillhub sync 重试。列出可选代号使用 skillhub keys generations --json；初始代为 legacy。

建议在原密钥仍可读取时，额外导出口令加密的数据密钥文件。口令至少 12 个字符，只通过密码框或无回显输入的 stdin 管道提供，不能放在命令参数里；直接终端输入会被拒绝。下面在 Bash 中运行：

IFS= read -r -s -p '恢复口令：' vault_passphrase
printf '%s' "$vault_passphrase" | skillhub keys export-data-key --destination "/绝对路径/data-key-export.json" --generation legacy --passphrase-stdin --json
unset vault_passphrase

导出文件不覆盖已有文件；请在安全位置保管它和口令。丢失原密钥之后再导出不能补回它。使用导出文件恢复某次备份时，同样无回显读取口令，替换上面的管道右侧为：

skillhub keys restore --backup "<某次备份目录或文件>" --generation legacy --key-file "/绝对路径/data-key-export.json" --passphrase-stdin --confirm --json

原数据密钥文件仍在时可以不传 --key-file、--passphrase-stdin；代号默认取自备份，也可明确选 --generation。换代归档目录也可作为恢复输入，按原代号解密本人拥有的钥匙。恢复不会覆盖运行中的库，返回 privateRecoveryDirectory 完整路径。该目录含明文，取回需要的数据后请明确删除：

skillhub keys recovery-delete --path "<privateRecoveryDirectory 完整路径>" --confirm --json

上传失败会保留本机记录并标记原因、暂停该项，不会阻断其他钥匙的同步和撤权。已收到的 Server keyId 用于精确恢复；若请求结果丢失且没有可证明的 Server 身份，不会按同名猜测合并，可能暂时保留本机与云端两条记录，需核对后处理。

迁移完成后降级到旧 APP 将无法读取本机钥匙；需要原数据密钥和上述备份恢复，不能直接安装旧版继续使用。

运行时如何选择

迁移保留原来实际生效的选择；个人覆盖值变成普通钥匙并保留对应绑定，不再作为额外覆盖层。本人、直接共享、团队共享和未切换的旧团队来源平等参与选择；变量名必须完全相同，同一把钥匙经多条途径共享仍只算一把。

已有选择仍有效就继续使用，新增同名钥匙不会打断。首次没有选择时，账号空间先取得本次完整授权清单；唯一候选的值就绪后才可采用，多把需要选择。查看状态不保存选择或使用同意，真正运行或亲自确认才保存；状态查询若确认失权，仍会清理对应缓存。原选择删除、失权或改名后需要明确处理，即使只剩一把也不会自动更换。

非自有 Skill 必须获准使用具体钥匙。「自动允许使用本人拥有的钥匙」继续对本人拥有的钥匙生效，包括迁移前的全局允许；它不会放行共享钥匙。明确拒绝仍会阻止使用，「仅这次」会替换该 Skill 对这把钥匙原有的持续允许，成功运行后需要再次确认。「仅这次」与持续使用同意都只保存在本机，第二台设备会再次询问；具有正式身份的选择可以同步。显式选用的旧团队钥匙保留原有允许，新匹配的旧团队来源仍需确认。仅本机空间与游客的完整本机库可离线首次匹配。

尚未迁移的旧团队钥匙仍可选用，在钥匙页单独列为「尚未切换的旧团队凭据」，只读；对它的选择不会跨设备同步；团队把它重新创建为新钥匙后，需要重新选择一次。第三方或团队 Skill 如果还没有同步到本机的运行版本，请先同步该 Skill，再确认钥匙。

已选择的本人钥匙可离线使用最后成功缓存的版本，不为统计强制联网。共享钥匙启动前需要联网复验权限和修订，值变化先刷新再读取；失败时不注入该变量，其他变量与子进程继续，不清空全库、不改用另一把。使用记录只表示服务器成功授权，不证明程序或供应商调用成功；本人离线和仅本机运行不伪造云端记录。

skillhub env status --skill-id "<local-skill-id>" --json
skillhub run "<local-skill-id>" -- python scripts/main.py

第二条仅在该 Skill 确有相应脚本且当前目录正确时使用。只注入已声明、已授权的变量，不输出值；已声明但跳过的变量也不会从父进程环境继承同名值。被运行程序可以读取其环境，只运行可信程序。

状态 JSON 为每个变量提供 state、reasonCode、下一步和 APP 定位。MISSING_KEY 表示缺值，KEY_NEEDS_CHOICE 表示多候选，KEY_SELECTION_INVALID 表示原选择失效，NEEDS_CONSENT 表示需在 APP 允许，KEY_NEEDS_ONLINE 表示需登录或联网确认，KEY_SYNCING 表示授权清单或值尚未就绪。服务器需升级时提供 SERVER_UPGRADE_REQUIRED 原因。CLI 提供从标准输入保存的 env set，不提供取回明文或绕过使用同意的命令，也不自行挑第一把。详见 CLI 使用。

从标准输入添加钥匙

skillhub env set "<local-skill-id>" --key "<KEY>" [--note "<备注>"] --json 只从标准输入读取值，去掉末尾换行，拒绝空值及 --value 参数。直接在终端运行时会关闭输入回显。创建本人独立钥匙并选给指定 Skill；尚未声明且可编辑时同时补声明，不可编辑时返回 NEEDS_AUTHOR_OR_PERSONAL_COPY 和 APP 定位。

缺值、多候选未选、待同意或共享权限无法确认时，变量不注入，程序仍启动；stderr 脱敏提示「变量名 未配置，未注入」，多候选提示去 APP 连线，不影响其他已配置变量。不再区分必需/可选，也不会自动换来源或重试任务。

通常请用户在 APP 该 Skill 的钥匙页添加。只有用户在对话中明确提供值并同意保存时，Manager 才可经 printf '%s' '<值>' | skillhub env set ... 代存；不回显、不写文件、不读回，完成后不再提及值。