用途:在 TrueFoundry 上管理密钥组(secret group)与单条密钥(key-value)。密钥组用于组织密钥,单条密钥保存键值对。适用于部署前的密钥准备以及密钥值轮换,也支持列出、创建、更新、删除操作。
主要能力:列出全部密钥组或指定组及其中密钥、按 ID 查看单条密钥、创建密钥组、更新组内密钥(修改值会生成新版本,数组中省略的密钥会被删除,至少需保留一条)、删除密钥组或单条密钥。创建、更新、删除均需人工审批(HITL)。
必要用法:使用直连 API 时先把 TFY_API_SH 设为该技能 scripts/tfy-api.sh 的完整路径,例如:TFY_API_SH=~/.claude/skills/truefoundry-secrets/scripts/tfy-api.sh。列出组:$TFY_API_SH GET /api/svc/v1/secret-groups;查看组:GET /api/svc/v1/secret-groups/GROUP_ID;列组内密钥:POST /api/svc/v1/secrets '{"secretGroupId":"GROUP_ID","limit":100,"offset":0}';查看单条:GET /api/svc/v1/secrets/SECRET_ID;删除组:DELETE /api/svc/v1/secret-groups/GROUP_ID;删除单条:DELETE /api/svc/v1/secrets/SECRET_ID。创建组前需先查密钥存储集成 ID:bash $TFY_API_SH GET '/api/svc/v1/provider-accounts?type=secret-store',按云厂商选择对应 integration 的 id 作为 integrationId。部署中通过 tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY> 引用密钥,随后执行 tfy apply -f manifest.yaml。
限制与安全:代理不得接受、存储、记录、回显或展示原始密钥值;须让用户在运行命令前将密钥值设为环境变量。若用户直接提供明文密钥,应警告并拒绝使用,改为环境变量方式;展示时只显示“(set)”或前 4 个字符加“***”。创建密钥组的命令中不得硬编码密钥值,应从环境变量或文件读取。Azure Key Vault 密钥名不支持下划线,可用连字符;软删除状态需在 Azure 门户或 CLI 清理(az keyvault secret purge --vault-name <vault> --name <secret-name>),平台 API 无法清除。常见错误还包括密钥组不存在、权限不足、名称已存在、密钥组为空、工作区未配置密钥存储、缺少 key 或 value 字段。