secrets-management

密钥管理技能

激活时机

在以下情况下激活此技能：

• 设置 API 密钥或凭据
• 创建 secrets.json 文件
• 实现密钥加载模式
• 使用 .env 文件
• 集成需要身份验证的外部 API
• 确保凭据不会提交到 git

核心原则

安全基础

• 绝不在源代码中硬编码 API 密钥
• 务必立即将 secrets.json 添加到 .gitignore
• 务必提供 secrets_template.json 作为设置参考
• 使用环境变量回退机制以兼容 CI/CD

标准文件结构

project/
├── secrets.json          # Actual secrets (NEVER commit)
├── secrets_template.json # Template with placeholder values (commit this)
├── .gitignore           # Must include secrets.json
└── .env                 # Alternative for env vars (also gitignored)

实现模式

secrets.json 格式

{
  "anthropic_api_key": "sk-ant-api03-...",
  "openrouter_api_key": "sk-or-v1-...",
  "openai_api_key": "sk-...",
  "database_url": "postgresql://user:pass@localhost/db",
  "comment": "Add your API keys here. Keep this file private."
}

Python 加载模式

import os
import json
from pathlib import Path

def load_secrets():
    """Load secrets from secrets.json with env var fallback."""
    secrets_path = Path(__file__).parent / "secrets.json"
    try:
        with open(secrets_path, 'r') as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return {}

SECRETS = load_secrets()

# Use with environment variable fallback
API_KEY = SECRETS.get("anthropic_api_key", os.getenv("ANTHROPIC_API_KEY", ""))

设置清单

1. 创建包含占位值的 secrets_template.json
2. 复制为 secrets.json 并添加真实凭据
3. 将 secrets.json 添加到 .gitignore
4. 在应用中实现密钥加载
5. 确认 git status 显示 secrets.json 为未跟踪文件

安全最佳实践

应该 ✅

• 将密钥存储在 secrets.json 中
• 立即将其添加到 .gitignore
• 提供用于设置的模板文件
• 使用环境变量回退机制
• 团队成员变更后轮换密钥

不应该 ❌

• 硬编码 API 密钥
• 提交真实凭据
• 记录完整的 API 密钥
• 通过电子邮件或聊天分享密钥

密钥格式参考

提供商	格式
Anthropic	sk-ant-api03-...
OpenRouter	sk-or-v1-...
OpenAI	sk-...
AWS Access	AKIA...

相关资源

请参阅 AgentUsage/secrets_management.md，了解完整文档，包括：

• 带验证的高级加载模式
• .env 文件集成
• 自动化测试模式
• 紧急密钥轮换流程
• 生产环境部署策略