【AI智能体工程化实战03】智能体工程化开发环境

第3章 环境准备与"驾驶舱"初体验

本章你将学到：

• 配置Claude Code（最强也最贵）和Trae（当前免费）的开发环境
• 用Claude Code完成第一个AI辅助编程任务
• 用Trae可视化地完成同一个任务
• 初步感受两种工具的工作方式差异

本章你将产出：一个可正常运行的开发环境，以及第一次用AI工具生成代码的成功体验；根据你的情况选择其中一款即可。

---

3.1 硬件与软件要求

在开始之前，先确认你的电脑满足基本条件。

硬件要求

项目	最低配置	说明
内存	8GB	够用，16GB更舒适
操作系统	Windows 10+ / macOS 12+ / Linux	三个平台都支持
网络	稳定的互联网连接	需要调用云端API

不需要独立显卡，不需要大硬盘，不需要配置任何深度学习环境。你手上的普通笔记本电脑就足够了。

你需要提前安装的软件

• Python 3.10 或更高版本 ：如果你不确定是否已安装，打开终端（Windows用PowerShell，macOS用"终端"），输入 python --version。如果显示版本号且 ≥ 3.10，就准备好了。如果没装，去 python.org 下载安装包，安装时记得勾选"Add Python to PATH"。
• Git ：如果你还没装，去 git-scm.com 下载安装。安装时一路默认即可。装好后在终端输入 git --version 确认。
• 一个代码编辑器：VS Code、Cursor 或者直接用 Trae 都行。本章我们会同时接触Claude Code和Trae，你不需要额外安装VS Code，Trae本身就是一个完整的编辑器。

Python虚拟环境（必做）

在正式开始之前，养成一个好习惯：为每个项目创建独立的Python虚拟环境。这能避免不同项目的依赖互相冲突。

打开终端，进入你想存放项目的目录，执行：

# 创建项目文件夹
mkdir comment-analyzer
cd comment-analyzer

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

激活成功后，终端前面会出现 (venv) 标识。以后每次打开这个项目，都要先激活虚拟环境。

---

3.2 API密钥安全管理

在开始调用任何AI服务之前，有一件事必须提前讲清楚：API密钥的安全管理。

很多初学者的做法是：把密钥直接写在代码里，然后不小心传到GitHub上，几小时后发现账户被刷了几百美元。

绝不硬编码密钥。这是你在本书学到的第一个工业级开发习惯。

正确做法：用环境变量存储密钥。

第一步：创建 .env 文件

在项目根目录下新建一个文件，命名为 .env（注意：就是 .env，没有文件名前缀）。内容如下：

ANTHROPIC_API_KEY=你的Claude_API密钥

第二步：创建 .gitignore 文件

同样在项目根目录下新建 .gitignore，输入以下内容：

# 环境变量文件
.env

# Python虚拟环境
venv/

# Python缓存
__pycache__/
*.pyc

这样，Git就会自动忽略 .env 文件，你的密钥永远不会被提交到仓库里。

第三步：在代码中读取环境变量

安装 python-dotenv 库：

pip install python-dotenv

然后在Python脚本中这样读取密钥：

import os
from dotenv import load_dotenv

load_dotenv()  # 加载.env文件中的变量
api_key = os.getenv("ANTHROPIC_API_KEY")  # 读取密钥

这样，密钥只存在于你本地的 .env 文件中，代码里没有任何敏感信息。你的代码可以安全地分享给任何人，也可以安全地提交到GitHub。

---

3.3 Claude Code安装与配置

Claude Code是Anthropic官方推出的命令行AI编程工具。它运行在终端里，用自然语言对话的方式帮你写代码、改代码、解释代码。

安装步骤

macOS/Linux用户：

打开终端，执行：

npm install -g @anthropic-ai/claude-code

如果你没有安装Node.js和npm，先去 nodejs.org 下载LTS版本安装。

Windows用户：

建议使用Windows子系统WSL，或者直接从GitHub Release页面下载预编译的二进制文件。

配置API密钥

安装完成后，在你的终端配置文件（macOS/Linux是 ~/.zshrc 或 ~/.bashrc，Windows是系统环境变量）中添加：

export ANTHROPIC_API_KEY="你的密钥"

然后执行 source ~/.zshrc（或重新打开终端）使其生效。

验证安装

在终端输入：

claude

如果看到Claude Code的欢迎界面，说明安装成功。输入 /help 可以查看所有可用命令。

---

3.4 第一个指令：让Claude Code为你写个函数

环境搭好了，我们来动手做第一件事：让Claude Code帮我们写一个Python函数。

在终端中进入项目文件夹，启动Claude Code：

cd comment-analyzer
claude

然后输入以下指令（这是一条完整的Prompt，你可以直接复制使用）：

请帮我写一个Python函数 analyze_comment(comment_text: str) -> dict。
这个函数目前是骨架阶段，功能是：
1. 接收一段评论文本
2. 检查输入是否为空，如果是空字符串，返回 {"valid": false, "reason": "输入为空"}
3. 如果输入非空，暂时返回 {"valid": true, "reason": "暂未实现具体分析逻辑"}
4. 包含完整的类型注解和docstring（中文）
5. 将代码保存为 comment_agent.py

Claude Code会生成代码，并在你的项目目录下创建 comment_agent.py 文件。打开看看，代码应该类似这样：

def analyze_comment(comment_text: str) -> dict:
    """
    分析用户评论的有效性。

    参数:
        comment_text: 用户评论文本

    返回:
        包含分析结果的字典，格式为:
        {
            "valid": bool,  # 评论是否有效
            "reason": str   # 判定理由
        }

    示例:
        >>> analyze_comment("这家店的红烧肉很好吃")
        {"valid": true, "reason": "暂未实现具体分析逻辑"}
    """
    if not comment_text or not comment_text.strip():
        return {"valid": False, "reason": "输入为空"}

    return {"valid": True, "reason": "暂未实现具体分析逻辑"}

你可以直接在终端里测试一下这个函数：

python -c "from comment_agent import analyze_comment; print(analyze_comment('')); print(analyze_comment('试试看'))"

期望输出：

{'valid': False, 'reason': '输入为空'}
{'valid': True, 'reason': '暂未实现具体分析逻辑'}

你刚才经历了什么？

你没有手动敲这段代码，甚至不需要记得JSON的字段名。你说了一段自然语言描述需求，AI帮你生成了符合Python规范、有类型注解、有docstring的完整代码。

但这还只是"用AI写代码"，不是"造智能体"。从第4章开始，我们会用Claude Code做更复杂的事情：生成规范文档、生成测试数据集、生成智能体的核心Prompt。

---

3.5 Trae IDE安装与初探

Claude Code是命令行工具，控制力强，但界面纯文本。Trae是字节跳动推出的AI IDE，把AI辅助开发的能力集成到了可视化编辑器里。

安装步骤

1. 访问Trae官网 trae.ai，下载对应操作系统的安装包。
2. 安装并启动Trae。
3. 首次启动时，Trae会引导你选择内置模型。选择默认模型即可（Trae内置了模型服务，你暂时不需要额外配置API密钥）。
4. 用Trae打开我们在3.1节创建的 comment-analyzer 项目文件夹。

体验Trae的SOLO模式

Trae有一个独特的功能叫SOLO模式：你只需要描述你想做什么，它会自动完成"写代码→运行→调试→修复"的完整循环。

在Trae的AI对话面板中，输入以下指令：

在当前项目中创建一个 hello_agent.py 文件。
内容是一个Python函数 greet(name: str) -> str，
如果name为空返回"请输入名字"，否则返回"你好，{name}！欢迎学习AI Agent开发。"
写完后自动运行测试一下。

观察Trae的操作：

1. 它自动创建了文件。
2. 它写好了代码。
3. 它自己运行了测试。
4. 如果有错，它会自己修。

这就是一站式开发的感觉------你只需要说需求，工具帮你完成从代码到验证的全流程。

---

3.6 两种工具的对比与协同

现在你同时接触了两个工具。它们不是竞争关系，而是互补关系。

对比维度	Claude Code	Trae IDE
交互方式	终端命令行，纯文本对话	可视化IDE，图形界面+AI对话
优势场景	规范化文档生成、批量脚本编写、工程资产沉淀	可视化智能体编排、多文件项目管理、拖拽式配置
上手门槛	需要适应终端操作	更接近传统IDE使用习惯
可追溯性	对话记录即开发日志	项目文件即开发记录

在本书中，我们的教学策略是：先在Claude Code中学清楚每一步的底层逻辑，再用Trae享受可视化的便利。 如果你在学习过程中对某个工具有偏好，完全可以用一种工具走完全程------五步法是通用的，不绑定任何工具。

---

3.7 本章小结

• 我们配置了Python虚拟环境、Git、环境变量管理，建立了工业级的项目基础。
• 绝不硬编码API密钥------这是你从本章开始养成的第一个安全习惯。
• 分别用Claude Code和Trae完成了第一个AI辅助编程任务，初步感受了两种工作方式。
• Claude Code擅长命令行下的精准控制，Trae擅长可视化的一站式开发。

从第4章开始，我们将正式进入实战。你将用Claude Code走完Harness五步法的前两步：为"评论甄别智能体"设计评测规范，并构建一套带黄金标准的测试数据集。

---

课后练习

1. 确保你的开发环境完全就绪：Python虚拟环境可激活、Claude Code可正常对话、Trae可正常打开项目。
2. 检查你的 .gitignore 文件是否包含了 .env 和 venv/。如果还没有，现在就创建。
3. 在Claude Code中尝试修改 comment_agent.py 的代码，让它能处理"输入只有空格"的情况（当前版本只处理了空字符串，" " 这样的纯空格输入应该也被判定为空）。
4. （可选）在Trae中用SOLO模式创建一个新文件 test_comment_agent.py，写一个简单的测试脚本，测试 analyze_comment 函数在空输入和正常输入下的表现。

---