🤖 阶段七：用 Claude Code CLI 开发、调试、部署 AI 项目

全程终端操作 | 从零构建 AI Agent | CLI 工具调用实战

7.1 通过 CLI 从零创建 AI Agent 项目结构

阶段：项目设计

Step 1：用 CLI 初始化项目目录

# === 创建项目根目录 ===
mkdir ~/my-ai-agent && cd ~/my-ai-agent

# === 初始化 git 和 npm ===
git init
npm init -y

# === 用 Claude 查看当前状态 ===
claude -p "列出当前目录的文件，确认项目已初始化"

Step 2：让 Claude 设计项目结构

# 启动 Claude 交互模式
claude

# 在交互界面输入（一次性给出完整需求）：
"我要创建一个基于 Node.js 的 AI Agent 项目。
这个 Agent 需要具备以下能力：
1. 读取本地文件
2. 调用外部 API（天气、搜索）
3. 执行 shell 命令（受限）
4. 有记忆能力（对话历史存储）

请帮我设计完整的项目目录结构，并创建所有骨架文件。
使用 ES Module 语法。

目录结构要求：
my-ai-agent/
├── src/
│   ├── agent.js        # Agent 主入口/编排
│   ├── tools/           # 工具集
│   │   ├── index.js     # 工具注册中心
│   │   ├── fileReader.js
│   │   ├── apiCaller.js
│   │   └── shellExecutor.js
│   ├── memory/          # 记忆模块
│   │   └── memoryStore.js
│   ├── llm/             # LLM 调用封装
│   │   └── client.js
│   └── utils/           # 工具函数
│       └── logger.js
├── tests/
├── data/                # 运行时数据
├── .env.example
├── package.json
└── README.md

请先创建所有目录，再逐个创建文件，
每个文件包含完整的骨架代码和 JSDoc 注释。"

Step 3：安装依赖

# 让 Claude 确定并安装依赖
"分析 src/ 下的所有骨架代码，确定需要的 npm 依赖，
然后运行 npm install 安装它们。
可能的依赖：openai（或 @anthropic-ai/sdk）、dotenv、chalk、winston 等"

7.2 命令行编写 Agent 核心代码、逐行纠错

阶段：代码编写

Step 1：编写工具注册中心

# 在 Claude 交互界面中，逐个模块开发
"实现 src/tools/index.js — 工具注册中心：
1. 导入所有工具模块
2. 每个工具注册为 { name, description, parameters, execute }
3. 导出 getTools() 和 executeTool(name, args) 函数
4. 工具调用时记录日志
参考以下工具接口规范：
- name: 唯一标识
- description: 给 LLM 看的工具描述
- parameters: JSON Schema 格式的参数定义
- execute: async (args) => result"

Step 2：实现 LLM 客户端

# 继续在 Claude 中开发
"实现 src/llm/client.js — LLM 调用封装：

功能要求：
1. 封装 Anthropic API 调用（使用 @anthropic-ai/sdk）
2. 从环境变量读取 API 密钥
3. 支持工具定义传入（function calling）
4. 支持多轮对话（传入消息历史）
5. 实现重试机制（失败后最多重试 3 次）
6. 流式输出支持（可选）

特别注意：
- 使用 try-catch 处理 API 错误
- 区分网络错误和 API 错误
- 添加请求日志"

# 写完每个模块后，立即审查：
"逐行解释 src/llm/client.js 的逻辑，标注潜在问题"

# 如果有错误，直接告诉 Claude：
"第 45 行，messages 参数的格式不对，
Anthropic API 需要 { role, content } 格式，不是 { role, message }"

Step 3：实现 Agent 主入口

# Agent 编排逻辑
"实现 src/agent.js — Agent 主循环：

执行流程：
1. 初始化（加载配置、工具、记忆）
2. 接收用户输入
3. 构建 LLM 请求（系统提示 + 工具定义 + 对话历史 + 用户输入）
4. 调用 LLM
5. 如果 LLM 返回工具调用：
   a. 执行工具
   b. 将工具结果加入对话
   c. 回到步骤 4
6. 如果 LLM 返回文本回复：
   a. 输出回复
   b. 存入记忆
   c. 等待下一个用户输入

要求：
- 最大循环次数设为 10（防止死循环）
- 每次工具调用都打印到终端
- 支持 'exit' 命令退出"

Step 4：功能测试与逐行调试

# 在终端直接运行测试
node src/agent.js

# 将报错直接传给 Claude
node src/agent.js 2>&1 | claude -p "分析报错，修复 src/ 下的代码"

# 或在交互模式中让 Claude 调试
"运行 node src/agent.js，根据报错修复代码，
重复运行和修复直到程序能正常启动并响应输入"

7.3 利用 CLI 工具调用能力让 Agent 自测自修

阶段：调试与自愈

让 Claude Code CLI 模拟"Agent 的测试者"

Step 1：让 CLI 为 Agent 写测试

cd ~/my-ai-agent && claude

# 让 Claude 分析并生成测试
"分析 src/ 下所有模块，为每个模块生成 Jest 测试文件。
重点关注：
1. 工具注册中心的注册和调用逻辑
2. LLM 客户端的请求构建和错误处理
3. Agent 主循环的工具调用分支
4. 记忆模块的存储和检索

生成测试文件到 tests/ 目录，确保 npm test 能运行。"

Step 2：自动测试 → 报错 → 修复循环

# 在 Claude 交互界面中输入：
"运行 npm test，分析所有失败的测试。

对于每个失败：
1. 判断是测试写错了还是代码有 bug
2. 如果是测试问题，修正测试
3. 如果是代码 bug，修复代码
4. 重新运行该测试验证
5. 全部修复后运行完整测试套件确认

最多迭代 3 轮。3 轮后如果仍有失败，列出剩余问题。"

Step 3：边界测试与健壮性验证

# 让 Claude 设计边界测试
"为 src/tools/shellExecutor.js 设计边界测试：
1. 传入空命令
2. 传入危险命令（rm -rf /）
3. 传入超长命令（10000字符）
4. 传入特殊字符
5. 并发执行多个命令

生成测试代码并运行。如果 shellExecutor 没有正确处理这些情况，
修复它直到全部通过。"

7.4 命令行项目优化、精简、模块化重构

阶段：代码优化

Step 1：代码质量审查

cd ~/my-ai-agent && claude

"全面审查 src/ 下的代码，逐文件给出改进建议：
1. 代码重复：哪些逻辑可以提取为公共函数
2. 错误处理：哪些地方缺少 try-catch
3. 性能问题：哪些地方有 N+1 或同步阻塞
4. 可读性：哪些命名不够清晰
5. 安全性：shellExecutor 的命令注入防护

按优先级排列，先修复严重问题。"

Step 2：模块化重构

# 让 Claude 做重构
"重构 src/agent.js：
当前 agent.js 有 200+ 行，职责太多。

拆分为：
- agent.js（~60行）：只负责编排主循环
- src/orchestrator.js：处理 LLM 响应的决策逻辑
- src/contextBuilder.js：构建发送给 LLM 的上下文
- src/responseHandler.js：处理最终响应的格式化

保持外部行为完全不变。重构后运行测试确认。"

Step 3：配置外部化

# 硬编码 → 配置文件
"把 src/ 下所有硬编码的配置提取到 config.js：
1. LLM 模型名称
2. 最大工具调用循环次数
3. 工具超时时间
4. 日志级别
5. 记忆存储路径
6. API 重试次数

config.js 支持从环境变量覆盖默认值。
更新所有引用这些值的文件。"

7.5 终端直接完成轻量化部署与运行监控

阶段：部署与运维

Step 1：生成 Docker 配置

cd ~/my-ai-agent && claude

"为这个 Node.js AI Agent 项目生成：
1. Dockerfile（多阶段构建，最终镜像尽量小）
2. .dockerignore
3. docker-compose.yml（如果项目未来需要 Redis 做记忆存储）

Dockerfile 要求：
- 基于 node:20-alpine
- 只安装生产依赖
- 非 root 用户运行
- 健康检查端点"

Step 2：生成 systemd 服务配置（Linux 服务器部署）

# 让 Claude 生成 systemd 服务文件
"生成 systemd 服务配置，将我的 AI Agent 注册为系统服务：

服务名：my-ai-agent
工作目录：/home/$(whoami)/my-ai-agent
启动命令：node src/agent.js
用户：当前用户
自动重启：失败后 5 秒重启
日志：输出到 journald

同时生成安装脚本 install-service.sh"

Step 3：部署执行

# === 完整部署流程 ===

# 1. Claude 生成部署脚本
claude -p "生成完整部署脚本 deploy.sh：
- 安装依赖
- 运行测试
- 构建 Docker 镜像
- 如果使用 systemd：安装并启动服务
- 如果使用 Docker：启动容器
- 健康检查
- 输出部署报告" > deploy.sh
chmod +x deploy.sh

# 2. 审查部署脚本
cat deploy.sh
claude -p "审查 deploy.sh，检查安全问题"

# 3. 执行部署
./deploy.sh

Step 4：运行监控脚本

# 生成监控脚本
claude -p "生成 AI Agent 运行监控脚本 monitor.sh：
1. 检查进程是否存活（systemd 或 docker）
2. 检查内存和 CPU 使用
3. 检查日志中的错误率
4. 超过阈值时发送告警（打印红色警告）
5. 输出健康状态报告" > monitor.sh
chmod +x monitor.sh

# 定期执行监控
watch -n 30 ./monitor.sh

Step 5：生成运维文档

# 一键生成运维手册
claude -p "生成 OPS.md 运维手册：
1. 启动/停止/重启 方法
2. 日志查看方法
3. 配置修改方法
4. 常见故障排查（进程假死、内存泄漏、API 限流）
5. 备份和恢复
6. 升级步骤" > OPS.md

课后练习