技能使用指南

fnox-providers（Fnox提供者配置）Skill 是什么？能做什么？

想给 Fnox 配置 age 加密、AWS Secrets Manager、Azure Key Vault、GCP 或 1Password？fnox-providers 技能可生成可直接使用的 fnox.toml 提供者配置，内置最佳实践与反模式提醒，帮你避开私钥泄露与硬编码凭证。立即了解安装与使用步骤，让秘密管理配置一次成型。

Fnox提供者配置Skillfnox-providers
8 个章节 约 16 分钟阅读 AI 智能生成

Fnox提供者配置Skill：一次配置，统一管理本地加密与多云秘密存储

  • 覆盖三类提供者：本地加密（age、AWS KMS、Azure、GCP）、云存储（AWS Secrets Manager、Azure Key Vault、GCP Secret Manager、Vault）、密码管理器（1Password、Bitwarden、Infisical、pass），一个技能讲透配置写法。
  • 开箱即用的配置模板：直接给出 fnox.toml 与 fnox.local.toml 的标准写法，公钥提交、私钥外置，避免把密钥写进仓库。
  • 附带最佳实践与反模式：明确告诉你"不要硬编码凭证"“不要共享私钥”“不要过度混合提供者”，少踩坑。
  • 可验证、可运维：提供 fnox provider test、fnox provider list、fnox provider add/remove 等命令，配置完立刻验证是否生效。
  • 适合团队协作与多环境：同一份配置里可以让开发用 age、团队共享用 1Password、生产用 AWS Secrets Manager。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：Fnox提供者配置Skill 技能英文名：fnox-providers 技能ID：14019

这个技能解决的问题非常具体：在 Fnox 中如何为不同的秘密源正确配置"提供者"（provider）。Fnox 是一个用于管理密钥与秘密的工具，而"提供者"决定了秘密到底存在哪里、用什么方式加密——是本地 age 密钥、是 AWS Secrets Manager、是 Azure Key Vault、还是 1Password 这类密码管理器。配置文件 fnox.toml 里写错一个字段、把私钥误提交进 Git、或者在生产环境用了开发用的本地加密，都会带来安全风险。这个技能把这些配置知识结构化地喂给 AI，让 AI 直接帮你生成正确的提供者配置片段，而不是靠翻文档试错。

从技能定义可以看到，它被授权使用的工具是 Read、Write、Edit、Bash、Grep、Glob——这意味着 AI 不仅能"告诉你怎么写"，还可以直接读取你项目里的 fnox.toml、编辑配置文件、执行 fnox provider test 之类的命令做验证，形成一个"读配置 → 改配置 → 跑命令验证"的闭环。

一键安装的思路与步骤（通用流程，具体命令与入口以官方说明为准）：

  1. 确认前提：本地已具备 AI 客户端的技能（Skill）加载能力，并且项目中已经在使用 Fnox（即存在或计划创建 fnox.toml）。如果还没装 Fnox，请先按官方说明完成安装。
  2. 获取技能：在技能市场或技能仓库中按技能ID 14019 或英文名 fnox-providers 检索并添加该技能。
  3. 放入技能目录：按客户端约定把技能放入技能目录（常见做法是放置在个人或项目级技能文件夹中），重启或刷新会话，使技能被加载。
  4. 验证是否生效：在新会话中直接提问"帮我用 age 配置一个 fnox 提供者，公钥放 fnox.toml，私钥放 fnox.local.toml"，如果 AI 能输出带 [providers.age] 段落的 TOML 片段并说明理由（而不是泛泛而谈），说明技能已生效。
  5. 做一次真实校验：让 AI 执行 fnox provider list 查看已配置提供者，或 fnox provider test age 测试连通性，通过即代表整条链路可用。

2. 该技能的主要功能和特点

  • 三类提供者的完整配置口径：把加密类（age、AWS KMS、Azure、GCP）、云存储类（AWS Secrets Manager、Azure Key Vault、GCP Secret Manager、HashiCorp Vault）、密码管理器类（1Password、Bitwarden 等）的 type 字段与必填参数一一说明，避免"类型写错、字段名记混"。
  • 推荐路径明确：详情中把 age 加密标注为推荐方案，并给出密钥对生成、公钥提取、fnox.toml 与 fnox.local.toml 分离提交的完整链路。
  • 多人 / 多接收者支持：age 提供者支持 public_keys 数组，可以同时把团队成员与 CI/CD 系统列为接收者，实现"一份密文、多人可解"。
  • 云厂商凭证的正确姿势：明确指出不要写 access_key_id / secret_access_key，而是走 AWS 凭证链（~/.aws/credentials 或环境变量）；Azure 通过 Azure CLI 或环境变量认证，GCP 通过 gcloud 或服务账户认证。
  • 秘密映射写法规范：给出 [secrets] 中 provider + value + description 的标准结构，让"秘密名 → 远端路径"的映射清晰可读。
  • 运维命令配套：fnox provider list、fnox provider test <name>、fnox provider add、fnox provider remove，让配置不是一次性写完就完事。
  • 最佳实践与反模式成对出现：开发用 age、生产用云秘密管理器、团队协作走 1Password/Bitwarden；同时列出硬编码凭证、共享私钥、无意义混合提供者三类反模式。
  • 进阶场景覆盖：AWS 跨账户访问（role_arn）、Vault 命名空间（namespace）、多区域部署（us-secrets / eu-secrets 别名）、从开发到生产的迁移路径。

和"搜索引擎 + 官方文档"相比，它的强项在于上下文感知：AI 会结合你已有的 fnox.toml 结构给出增量修改，而不是甩给你一段需要自己适配的通用示例。

3. 如何使用该技能？

以下按典型工作流给出分步指南，示例可直接参考改写。

第 1 步：生成 age 密钥对（本地加密路线）

age-keygen -o ~/.config/fnox/keys/identity.txt
cat ~/.config/fnox/keys/identity.txt | grep "public key"

输出类似 age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p 的公钥，这就是要写进配置的值。

第 2 步：把公钥写进可提交的 fnox.toml

[providers.age]
type = "age"
public_keys = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]

第 3 步：把私钥路径写进被 Git 忽略的 fnox.local.toml

[providers.age]
identity = "~/.config/fnox/keys/identity.txt"

这一步是关键：私钥永远不进入版本库。

第 4 步：写入一个加密秘密

fnox set DATABASE_PASSWORD
# 按提示输入值，使用 age 公钥加密

echo "secret-value" | fnox set API_KEY --provider age

第 5 步：切换到云端提供者（示例为 AWS Secrets Manager）

[providers.aws-sm]
type = "aws-sm"
region = "us-east-1"

[secrets]
DATABASE_URL = {
  provider = "aws-sm",
  value = "prod/database-url",
  description = "生产数据库连接字符串"
}

注意这里 value 填的是远端秘密名称，而不是秘密本身的值。

第 6 步：验证配置是否真的可用

fnox provider list          # 列出已配置的提供者
fnox provider test age      # 测试 age 提供者
fnox provider test aws-sm   # 测试 AWS Secrets Manager 提供者
fnox provider add           # 交互式添加提供者
fnox provider remove age    # 移除提供者

输入 / 输出说明：你对 AI 的输入通常是"我有一份 fnox.toml，想把生产秘密迁到 GCP Secret Manager"这类自然语言描述；输出应当是一段可直接粘贴的 TOML 配置、需要执行的命令，以及"哪些字段要放进 local 文件、哪些凭证走环境变量"的提示。如果输出里出现明文私钥或硬编码 access_key_id，一定要打回去重写。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
Fnox提供者配置Skill（本技能） AI 辅助的 Fnox 提供者配置专家 生成 age / 云存储 / 密码管理器三类提供者配置，附带最佳实践与反模式提示 需先具备 Fnox 环境与技能加载能力，门槛低，自然语言即可 已在用 Fnox、需要快速接入多种秘密源的团队 优势：配置片段可直接用，能读取并修改现有 fnox.toml；不足：仅覆盖 Fnox 生态，非通用密钥管理方案
手写 fnox.toml（纯人工） 原生手动配置 完全自由地编写提供者与秘密映射 需要熟读文档、记住各提供者字段 一次性少量配置、老手维护 优势：无额外依赖；不足：字段易错、私钥易误提交、跨云配置学习成本高
SOPS + age 文件级加密方案 对 YAML/JSON 等配置文件整体加解密 需自行安装 sops 与 age 并管理规则 配置文件整体加密、GitOps 流程 优势：生态成熟、与 Git 集成好；不足：不直接对接云秘密管理器与 1Password 等，多环境分层需自己设计
HashiCorp Vault（原生使用） 企业级秘密管理平台 动态凭证、租约、审计、命名空间 部署与运维成本高，需要专门维护集群 中大型企业统一密钥治理 优势：功能最全、审计能力强；不足：重，个人与小团队上手成本高

可以看出，本技能并不是要替代 Vault 或 SOPS，而是降低 Fnox 这一层的配置摩擦：Fnox 本身可以对接 Vault、AWS、Azure、GCP、1Password 等多种后端，而"怎么把后端正确接进来"正是这个技能负责的部分。

5. 该技能的典型应用场景与实际体验情况

场景一：个人开发者的本地密钥管理 角色是独立开发者，痛点是"本地 .env 到处放，怕误提交"。使用方式是让 AI 生成 age 提供者配置，公钥进 fnox.toml、私钥路径进 fnox.local.toml，然后用 fnox set 写入数据库密码。实际体验：这是全篇门槛最低的路径，AI 输出的配置基本可一次成型，唯一需要注意的是 ~/.config/fnox/keys/ 目录要先建好。

场景二：小团队的共享秘密 角色是团队 Tech Lead，痛点是"CI 和三个成员都要能解密，但不能共享私钥"。使用方式是把多个 public_keys 写进 age 提供者，成员与 CI 各持一份私钥。实际体验：多接收者数组的写法很直观，AI 会自动提醒"私钥不要提交"，这一点比单纯查文档更省心。

场景三：多环境与多云并存的成熟项目 角色是平台工程师，痛点是开发用本地加密、生产用 AWS、共享 Webhook 放 1Password，配置文件越写越乱。使用方式是让 AI 按"开发 / 团队 / 生产"三段式组织提供者，并给提供者起 ages、team、prod 这类语义化别名。实际体验：别名 + 分环境的写法显著提升可读性，AI 也会提示"不要为简单项目堆叠过多提供者"这一反模式。

场景四：从开发环境迁移到生产 角色是后端工程师，痛点是把本地 age 加密的秘密平滑切到 AWS Secrets Manager。使用方式是让 AI 生成 fnox.production.toml，把 DATABASE_URL 的 provider 从 age 改为 aws-sm。实际体验：迁移的核心不是写配置，而是确认云端秘密已提前创建、凭证链可访问，建议改完后立刻跑 fnox provider test aws-sm。

上手难度与注意事项：整体属于"低门槛、高上限"——age 路线几分钟可跑通；云端路线真正的成本在云账号侧的权限与凭证配置。务必牢记三点：不硬编码凭证、不提交私钥、不无意义地混合多种提供者。

6. 该技能能为用户带来的价值

  • 把"查文档 + 试错"压缩成"一次对话"：原本需要在多个云厂商文档与 Fnox 文档之间来回切换的配置工作，变成一次自然语言描述即可产出可用片段，配置时间从"半天"量级降到"几分钟"量级。
  • 显著降低安全出错概率：私钥外置、凭证走环境变量、不硬编码 access key——这些规则被内置在技能的推荐输出里，相当于给每次配置都配了一位代码审查者，避免了最容易发生的密钥泄露事故。
  • 降低多云门槛：AWS、Azure、GCP、Vault、1Password、Bitwarden 的配置差异被统一到同一套 [providers.x] 结构下，团队不必为每家云单独培养"配置专家"。
  • 提升配置可维护性：语义化别名、按环境拆分配置文件、[secrets] 中带 description 的写法，让半年后回来看配置的人依然能读懂，长期维护成本明显下降。
  • 可验证的交付：配套的 provider list / provider test 命令让"配置完成"有客观标准，而不是靠感觉。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？ A：安装方式取决于你使用的 AI 客户端，通常是在技能市场按技能ID 14019 或英文名 fnox-providers 检索后添加，并放入客户端的技能目录中加载。具体安装入口、是否需要付费与授权方式，以官方说明为准。技能本身不包含任何独立的收费信息，请不要轻信非官方渠道的"激活码"说法。

Q2：我不会 age，也不懂云厂商的密钥服务，能直接用吗？ A：可以。技能里已经把最推荐的 age 路线拆成"生成密钥对 → 公钥写 fnox.toml → 私钥路径写 fnox.local.toml → fnox set 写入秘密"四步，照着执行即可。云端路线也可以先用 fnox provider test 验证，再逐步替换。

Q3：为什么我的私钥不能直接写在 fnox.toml 里？ A：因为 fnox.toml 是要提交到版本库的，而私钥一旦提交就等于泄露。技能中明确把 [providers.age] 的 identity 字段放到被 Git 忽略的 fnox.local.toml，并在反模式章节强调"永远不要提交私钥"。如果你的仓库曾经提交过私钥，应当立即轮换密钥。

Q4：这个技能和 SOPS、HashiCorp Vault 该怎么选？ A：三者定位不同。SOPS 偏向"把配置文件整体加密"，Vault 偏向"企业级统一密钥治理平台"，而本技能解决的是在 Fnox 中正确配置各种后端提供者。如果你已经在用 Fnox，或者希望用一套配置同时对接 age、云秘密管理器和 1Password，选它；如果需要动态凭证与强审计，则应优先考虑 Vault。

Q5：一个项目里配置多个提供者会不会很乱？ A：可以多配，但要克制。技能给出的建议是"简单项目选一个合适的提供者"，多提供者只在确有分层需求时使用（如开发用 age、团队共享用 1Password、生产用 AWS），并通过 prod-secrets、staging-secrets 这类别名让语义清晰。过度混合正是技能列出的反模式之一。