🔧 模块2：环境搭建篇 — Claude Code 开发环境配置

获取 API 密钥

访问 Anthropic Console → 注册/登录 → Settings → API Keys → Create Key → 复制密钥（以 sk-ant- 开头）。

配置环境变量

# 在项目目录下创建 .env 文件
cd ~/ai-agent-study
touch .env

# 编辑 .env 文件，写入以下内容：
# ANTHROPIC_API_KEY=sk-ant-your-actual-api-key-here

# 使用命令行直接写入（替换为你的真实密钥）
echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' > .env

# 创建 .gitignore（防止密钥被提交到 Git）
echo '.env' >> .gitignore
echo 'venv/' >> .gitignore
echo '__pycache__/' >> .gitignore

创建配置文件

# 创建 config.py，统一管理配置
cat > config.py << 'PYEOF'
"""AI Agent 全局配置文件"""
import os
from dotenv import load_dotenv

# 加载 .env 文件中的环境变量
load_dotenv()

# API 配置
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
if not ANTHROPIC_API_KEY:
    raise ValueError("❌ 未找到 ANTHROPIC_API_KEY！请在 .env 文件中配置。")

# 模型配置
DEFAULT_MODEL = "claude-sonnet-4-6"  # 性价比最优，适合入门

# 项目路径
PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
PYEOF

echo "✅ config.py 创建完成"

测试 API 连接

# 创建测试脚本 test_api.py
cat > test_api.py << 'PYEOF'
"""测试 Anthropic API 连接"""
from config import ANTHROPIC_API_KEY
from anthropic import Anthropic

def test_connection():
    """发送一个简单请求，验证 API 是否可用"""
    print("🔄 正在测试 API 连接...")
    try:
        client = Anthropic(api_key=ANTHROPIC_API_KEY)
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=100,
            messages=[{"role": "user", "content": "回复'连接成功！'"}]
        )
        print(f"✅ API 连接成功！响应: {response.content[0].text}")
        return True
    except Exception as e:
        print(f"❌ API 连接失败: {e}")
        print("常见原因：1) API密钥错误 2) 网络问题 3) 账户余额不足")
        return False

if __name__ == "__main__":
    test_connection()
PYEOF

# 运行测试
python3 test_api.py

获取 DeepSeek API Key

访问 DeepSeek 开放平台 → 注册/登录 → API Keys → 创建 API Key → 复制密钥（以 sk- 开头）。

配置环境变量（Linux/macOS）

# 在终端中执行（或写入 ~/.bashrc / ~/.zshrc 永久生效）
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-your-deepseek-api-key"
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_EFFORT_LEVEL="max"

# 然后正常启动 Claude Code
claude

Windows PowerShell 配置

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="sk-your-deepseek-api-key"
$env:ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"

claude

安装依赖（与方案A完全相同）

# 使用 Anthropic Python SDK + DeepSeek 端点
pip install anthropic python-dotenv requests rich

配置 .env 文件（支持双 API Key）

# 编辑 .env 文件，支持同时配置多个 API
cat > .env << 'EOF'
# ===== Claude API（海外用户首选）=====
ANTHROPIC_API_KEY=sk-ant-your-claude-key-here

# ===== DeepSeek API（国内用户推荐）=====
DEEPSEEK_API_KEY=sk-your-deepseek-key-here

# ===== 当前使用的 API 提供商：claude 或 deepseek =====
API_PROVIDER=deepseek
EOF

创建兼容双 API 的配置文件

# 更新 config.py，支持 Claude / DeepSeek 双提供商
cat > config.py << 'PYEOF'
"""AI Agent 全局配置文件 — 支持 Claude + DeepSeek 双 API"""
import os
from dotenv import load_dotenv

load_dotenv()

# --- API 提供商选择 ---
API_PROVIDER = os.getenv("API_PROVIDER", "claude")  # "claude" 或 "deepseek"

# --- 模型配置 ---
if API_PROVIDER == "deepseek":
    # DeepSeek 配置（国内推荐）
    API_KEY = os.getenv("DEEPSEEK_API_KEY")
    BASE_URL = "https://api.deepseek.com/anthropic"
    DEFAULT_MODEL = "deepseek-v4-pro"
    LARGE_CONTEXT_MODEL = "deepseek-v4-pro[1m]"  # 1M 上下文
    FAST_MODEL = "deepseek-v4-flash"
    if not API_KEY:
        raise ValueError(
            "❌ 未找到 DEEPSEEK_API_KEY！\n"
            "  请在 .env 文件中配置，或设置 API_PROVIDER=claude"
        )
else:
    # Claude API 配置（默认）
    API_KEY = os.getenv("ANTHROPIC_API_KEY")
    BASE_URL = "https://api.anthropic.com"
    DEFAULT_MODEL = "claude-sonnet-4-6"
    LARGE_CONTEXT_MODEL = "claude-opus-4-8"
    FAST_MODEL = "claude-haiku-4-5"
    if not API_KEY:
        raise ValueError(
            "❌ 未找到 ANTHROPIC_API_KEY！\n"
            "  请在 .env 文件中配置，或设置 API_PROVIDER=deepseek"
        )

# --- 项目路径 ---
PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))

# --- 打印当前配置 ---
print(f"🔧 API 提供商: {API_PROVIDER.upper()}")
print(f"📦 默认模型: {DEFAULT_MODEL}")
print(f"🌐 API 端点: {BASE_URL}")
PYEOF

echo "✅ config.py 更新完成（支持 Claude + DeepSeek 双 API）"

创建兼容双 API 的 Agent 基类

# 创建 agent_base.py — 所有 Agent 项目的通用基类
cat > agent_base.py << 'PYEOF'
"""Agent 基类 — 自动适配 Claude / DeepSeek API"""
from anthropic import Anthropic
from config import API_KEY, BASE_URL, DEFAULT_MODEL

def create_agent_client(model: str = None) -> Anthropic:
    """
    创建统一的 Agent API 客户端
    自动根据 config.py 中的 API_PROVIDER 选择正确的端点和密钥
    """
    return Anthropic(
        api_key=API_KEY,
        base_url=BASE_URL,
        # 注意：DeepSeek 端点不需要设置 default_headers
    )

# 快捷调用函数（本教程所有 Agent 项目可直接使用）
def call_model(
    system: str = "",
    user_message: str = "",
    model: str = None,
    max_tokens: int = 1024,
    temperature: float = 0.3,
) -> str:
    """
    统一的模型调用接口
    使用方式: reply = call_model(system="你是助手", user_message="你好")
    """
    client = create_agent_client()
    model = model or DEFAULT_MODEL

    response = client.messages.create(
        model=model,
        max_tokens=max_tokens,
        system=system,
        messages=[{"role": "user", "content": user_message}],
        temperature=temperature,
    )
    return response.content[0].text.strip()


# --- 测试 ---
if __name__ == "__main__":
    print("🧪 测试 API 连接...")
    try:
        result = call_model(
            system="用中文回复，简洁明了。",
            user_message="回复'API连接成功！当前用的是哪个模型？'",
            max_tokens=100,
        )
        print(f"✅ {result}")
    except Exception as e:
        print(f"❌ 连接失败: {e}")
        print("常见原因：1) API Key 错误 2) 网络不通 3) 账户余额不足")
PYEOF

# 运行测试
python3 agent_base.py

DeepSeek Python SDK 进阶参数

# DeepSeek 特有功能示例（仅在 API_PROVIDER=deepseek 时可用）
def deepseek_advanced_example():
    """展示 DeepSeek 特有的高级参数"""
    from anthropic import Anthropic

    client = Anthropic(
        api_key=API_KEY,
        base_url=BASE_URL,
    )

    # DeepSeek V4-Pro 支持思考模式（类似 Claude 的 extended thinking）
    # 注意：需要通过 extra_headers 传递 DeepSeek 特有参数
    response = client.messages.create(
        model="deepseek-v4-pro",
        max_tokens=2000,
        system="你是一个逻辑严密的推理助手。对复杂问题请展示你的思考过程。",
        messages=[{
            "role": "user",
            "content": "一个水池有3个进水管，A管单独注满需要2小时..."
        }],
        temperature=0.6,    # DeepSeek 推荐使用较低 temperature
        # 注意：在 Anthropic 兼容端点下，大部分 Claude 参数都适用
    )
    return response.content[0].text

# 如果你使用 OpenAI 兼容端点（备选方案），可以用 OpenAI SDK：
def deepseek_openai_sdk_example():
    """使用 OpenAI SDK 调用 DeepSeek（备选方案）"""
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-your-deepseek-key",
        base_url="https://api.deepseek.com",
    )

    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
    )
    return response.choices[0].message.content