用途
本技能用于在采用特定布局的仓库中处理密钥或密钥配置：仓库将密钥以 sops 加密的 dotenv 文件提交到 git，每个部署环境一个文件，例如 secrets/dev.env、secrets/prod.env。这些文件使用 age 身份解密。仓库中没有 .env、没有密钥服务、也没有需要登录的会话。每次检出、工作树和云沙箱在克隆时都带有加密文件；任何地方唯一的输入是一个 age 私钥。
主要能力
- 通过 pnpm secrets（tools/secrets.ts）这一唯一接口管理密钥。在带有该封装的仓库中，不要直接调用 sops。
- 支持的身份与作用域：
- agent：用户级，私钥位于每台代理运行机器上的 ~/.config/sops/age/keys.txt，云沙箱中为 SOPS_AGE_KEY，可解密 dev.env。
- personal：用户级，私钥位于用户的密码管理器，可解密列出其公钥的文件。
- prod：按项目，私钥位于该项目的生产平台和文档化的密码管理器条目，可解密 prod.env。
- .sops.yaml 按公钥列出接收者。加密不需要私钥；解密或编辑需要某个接收者的私钥。agent 和 personal 是本地开发密钥，由所有项目共享；prod 按项目铸造，因此一个泄露的部署变量只暴露一个项目。这些是约定，并非保证的接收者。现有仓库可能只使用共享的 dev 和 prod 密钥。在选择密钥前，请阅读仓库的密钥指南和 .sops.yaml；加密文件的接收者元数据决定哪些身份可以解密它。
使用方式
代理工作流：开发密钥可自行管理，无需询问：
pnpm secrets show dev # everything, decrypted
pnpm secrets get dev STRIPE_KEY
pnpm secrets set dev STRIPE_KEY sk_test_1
pnpm secrets unset dev STRIPE_KEY
pnpm secrets exec dev -- node apps/worker/src/main.ts
exec 将解密后的值放入子进程环境（覆盖 shell 的），从中移除 SOPS_AGE_KEY*，转发信号，并以子进程状态退出。
当授权任务需要生产密钥时，自行执行提权。不要要求用户运行命令或重新确认已授权的任务。
用 pnpm secrets exec prod -- true 检查访问权限，它不打印任何密钥值。仅存在 .age/elevated 文件并不能证明其密钥可以解密 prod。
如果访问失败，阅读仓库的密钥指南和接收者配置。使用文档化的账户、保险库、条目和字段来匹配密钥。不要假设 Personal 保险库、age-personal 接收者或 CLI 的默认账户。
自行运行文档化的读取，将密钥直接管道传入封装：
op read 'op://VAULT/ITEM/FIELD' --account ACCOUNT | pnpm secrets elevate.
用发现的标识符替换占位符；绝不打印密钥。
用 pnpm secrets exec prod -- true 确认解密，然后继续任务。
当文档化的 1Password 位置缺失时，使用 op account list --format json 和 op vault list --account ACCOUNT --format json 来识别正确的账户和保险库。在该保险库中用 op item list --account ACCOUNT --vault VAULT --format json 搜索文档化的密钥名称的条目元数据；只检查匹配的条目。在后续读取中传入 --account。Private、Personal 和 Shared 是不同的名称，不是可互换的别名。如果找到密钥但无法解密，将其公钥与文件的接收者比较，而不是反复尝试保险库名称。将私钥排除在工具输出之外。
仅在进展需要用户交互时询问用户，例如解锁 1Password 或授予不可用的访问权限。说明实际的阻塞原因。提权是按检出进行的，持续到 .age/elevated 被删除；不要将其复制到另一个工作树。
添加变量时，将其添加到 env schema 以及你能解密的每个 secrets/<env>.env。如果你无法解密 prod，请在 PR 中说明：类型化 env 检查会使 prod 启动失败，直到该值被设置，这是预期的信号。
绝不将 AGE-SECRET-KEY-... 写入受跟踪的文件、日志或提交。绝不将 personal 或 prod 放入云环境。
适用场景
适用于使用 .sops.yaml、加密环境文件或 pnpm secrets 脚本的仓库中的密钥或密钥配置。
限制
人类设置：对于一次性步骤（生成密钥、安装 sops 和 age、将代理密钥接入代理工具和云沙箱、配置 prod 平台以及轮换密钥），请阅读 references/setup.md。当用户要求提醒步骤时，按顺序引导他们阅读该文件。
对于设计所依赖的 sops 和 age 行为（身份联合、updatekeys、exec-env 限制、dotenv 怪癖），请阅读 references/sops-notes.md。