6.13 --max-turns - 限制非互動模式中的代理輪數

概述

--max-turns 標誌允許您限制非互動模式中代理的輪數（對話輪次）。這對於控制執行時間、資源使用和防止無限迴圈非常有用。

基本语法

bash


claude --max-turns <数字>

参数说明

引數	型別	預設值	說明

<数字>| 整數| 無限制| 代理的最大輪數

## 使用场景

### 1\. 限制执行时间

    bash


    # 限制代理最多执行 5 轮
    claude --max-turns 5 -p "分析项目中的所有文件"
    # 代理会在 5 轮后停止，即使任务未完成

### 2\. 控制资源使用

    bash


    # 限制轮数以控制 API 调用次数
    claude --max-turns 10 -p "生成完整的测试套件"
    # 避免过多的 API 调用和资源消耗

### 3\. 防止无限循环

    bash


    # 防止代理陷入无限循环
    claude --max-turns 3 -p "递归处理所有子目录"
    # 即使代理尝试继续，也会在 3 轮后停止

### 4\. 快速原型开发

    bash


    # 快速获取初步结果
    claude --max-turns 2 -p "设计系统架构"
    # 获取初步想法，不进行深入分析

## 高级用法

### 1\. 与其他标志组合

    bash


    # 限制轮数 + 指定模型
    claude --max-turns 5 --model opus -p "生成代码"

    # 限制轮数 + 限制工具
    claude --max-turns 3 --allowedTools "Read" "Grep" -p "搜索代码"

    # 限制轮数 + JSON 输出
    claude --max-turns 10 --output-format json -p "分析数据"

### 2\. 渐进式执行

    bash


    #!/bin/bash
    # progressive-execution.sh
    # 第一轮：快速分析
    echo "第一轮：快速分析"
    claude --max-turns 1 -p "分析项目结构" > analysis-round1.txt
    # 第二轮：深入分析
    echo "第二轮：深入分析"
    claude --max-turns 2 -p "基于初步分析，深入分析代码" > analysis-round2.txt
    # 第三轮：生成建议
    echo "第三轮：生成建议"
    claude --max-turns 3 -p "基于分析结果，生成改进建议" > suggestions.txt
    echo "渐进式执行完成"

### 3\. 动态调整轮数

    bash


    #!/bin/bash
    # dynamic-turns.sh

    # 根据任务复杂度动态调整轮数
    TASK=$1

    case "$TASK" in
        "simple")
            MAX_TURNS=2
            ;;
        "medium")
            MAX_TURNS=5
            ;;
        "complex")
            MAX_TURNS=10
            ;;
        *)
            MAX_TURNS=3
            ;;
    esac

    echo "执行任务: $TASK (最大轮数: $MAX_TURNS)"
    claude --max-turns "$MAX_TURNS" -p "完成这个任务"

### 4\. 超时控制

    bash


    #!/bin/bash
    # timeout-control.sh
    MAX_TURNS=5
    TIMEOUT=60
    # 使用 timeout 命令限制总时间
    timeout "$TIMEOUT" claude --max-turns "$MAX_TURNS" -p "生成代码"
    if [ $? -eq 124 ]; then
    echo "任务超时"
    else
    echo "任务完成"
    fi

## 实际应用示例

### 示例 1: 代码审查

    bash


    #!/bin/bash
    # code-review.sh

    FILE=$1

    # 第一轮：快速审查
    echo "快速审查..."
    claude --max-turns 2 -p "快速审查 $FILE 的代码质量" > quick-review.txt

    # 第二轮：详细审查
    echo "详细审查..."
    claude --max-turns 5 -p "详细审查 $FILE，包括安全性、性能和可维护性" > detailed-review.txt

    # 第三轮：生成修复建议
    echo "生成修复建议..."
    claude --max-turns 3 -p "基于审查结果，生成具体的修复建议" > fixes.txt

    echo "代码审查完成"

### 示例 2: 文档生成

    bash


    #!/bin/bash
    # generate-docs.sh
    # 第一轮：生成大纲
    echo "生成大纲..."
    claude --max-turns 2 -p "为项目生成文档大纲" > outline.md
    # 第二轮：生成内容
    echo "生成内容..."
    claude --max-turns 10 -p "基于大纲，生成完整的文档内容" > docs.md
    # 第三轮：完善文档
    echo "完善文档..."
    claude --max-turns 3 -p "完善文档，添加示例和说明" > final-docs.md
    echo "文档生成完成"

### 示例 3: 测试生成

    bash


    #!/bin/bash
    # generate-tests.sh

    # 第一轮：分析代码
    echo "分析代码..."
    claude --max-turns 3 -p "分析 src/ 目录下的代码结构" > analysis.txt

    # 第二轮：生成测试用例
    echo "生成测试用例..."
    claude --max-turns 5 -p "基于分析结果，生成测试用例" > test-cases.txt

    # 第三轮：生成测试代码
    echo "生成测试代码..."
    claude --max-turns 10 -p "将测试用例转换为 pytest 代码" > tests.py

    echo "测试生成完成"

### 示例 4: 重构代码

    bash


    #!/bin/bash
    # refactor-code.sh
    FILE=$1
    # 第一轮：分析问题
    echo "分析问题..."
    claude --max-turns 2 -p "分析 $FILE 中的代码问题" > problems.txt
    # 第二轮：设计重构方案
    echo "设计重构方案..."
    claude --max-turns 3 -p "设计重构方案" > refactor-plan.txt
    # 第三轮：执行重构
    echo "执行重构..."
    claude --max-turns 10 -p "执行重构，生成重构后的代码" > refactored-code.py
    echo "重构完成"

## 轮数选择建议

### 1\. 简单任务：1-2 轮

    bash


    # 简单查询
    claude --max-turns 1 -p "解释什么是递归"

    # 快速检查
    claude --max-turns 2 -p "检查代码语法"

### 2\. 中等任务：3-5 轮

    bash


    # 代码审查
    claude --max-turns 3 -p "审查代码质量"
    # 文档生成
    claude --max-turns 5 -p "生成 API 文档"

### 3\. 复杂任务：6-10 轮

    bash


    # 完整功能开发
    claude --max-turns 10 -p "开发一个 REST API"

    # 系统设计
    claude --max-turns 8 -p "设计微服务架构"

### 4\. 非常复杂的任务：10+ 轮

    bash


    # 大型项目重构
    claude --max-turns 15 -p "重构整个项目"
    # 完整测试套件生成
    claude --max-turns 20 -p "为整个项目生成测试"

## 最佳实践

### 1\. 从小轮数开始

    bash


    # 先用小轮数测试
    claude --max-turns 2 -p "生成代码"

    # 如果需要，增加轮数
    claude --max-turns 5 -p "生成代码"

### 2\. 监控执行进度

    bash


    #!/bin/bash
    # monitor-progress.sh
    MAX_TURNS=5
    for i in $(seq 1 $MAX_TURNS); do
    echo "轮次 $i/$MAX_TURNS"
    claude --max-turns 1 -p "继续任务" > "turn-$i.txt"
    # 检查是否完成
    if grep -q "完成" "turn-$i.txt"; then
    echo "任务已完成"
    break
    fi
    done

### 3\. 保存中间结果

    bash


    #!/bin/bash
    # save-intermediate.sh

    MAX_TURNS=5

    for i in $(seq 1 $MAX_TURNS); do
        claude --max-turns 1 -p "继续任务" > "intermediate-$i.txt"

        # 检查是否需要继续
        if [ $? -ne 0 ]; then
            echo "任务失败"
            break
        fi
    done

### 4\. 错误处理

    bash


    #!/bin/bash
    # error-handling.sh
    MAX_TURNS=5
    claude --max-turns "$MAX_TURNS" -p "生成代码" 2>&1 | tee output.txt
    # 检查是否达到最大轮数
    if grep -q "max turns" output.txt; then
    echo "警告：达到最大轮数，任务可能未完成"
    fi

## 常见问题

### Q1: 如何选择合适的轮数？

A: 根据任务复杂度选择。简单任务 1-2 轮，中等任务 3-5 轮，复杂任务 6-10 轮。

### Q2: 达到最大轮数后会发生什么？

A: 代理会停止执行，即使任务未完成。建议检查输出并决定是否增加轮数。

### Q3: 可以在交互模式中使用吗？

A: 不可以。`--max-turns` 只适用于非交互模式（使用 `-p` 标志）。

### Q4: 如何知道任务是否完成？

A: 检查输出中是否包含完成指示，或者根据输出内容判断。

### Q5: 轮数限制会影响结果质量吗？

A: 可能会。如果轮数太少，任务可能无法完成。建议根据任务复杂度选择合适的轮数。

## 与其他标志的组合示例

### 与其他标志的组合示例

### 1\. 完整的开发流程

    bash


    #!/bin/bash
    # full-development.sh

    # 分析阶段
    claude --max-turns 3 -p "分析需求" > analysis.txt

    # 设计阶段
    claude --max-turns 5 -p "设计系统架构" > design.txt

    # 实现阶段
    claude --max-turns 10 -p "实现功能" > implementation.txt

    # 测试阶段
    claude --max-turns 5 -p "生成测试" > tests.txt

    echo "开发流程完成"

### 2\. 迭代优化

    bash


    #!/bin/bash
    # iterative-optimization.sh
    for i in 1 2 3; do
    echo "迭代 $i"
    claude --max-turns 3 -p "优化代码" > "optimization-$i.txt"
    # 检查是否需要继续
    if grep -q "无需优化" "optimization-$i.txt"; then
    echo "优化完成"
    break
    fi
    done

### 3\. 分阶段执行

    bash


    #!/bin/bash
    # staged-execution.sh

    # 阶段 1：快速原型
    claude --max-turns 2 -p "创建快速原型" > prototype.txt

    # 阶段 2：完善功能
    claude --max-turns 5 -p "完善原型功能" > refined.txt

    # 阶段 3：最终实现
    claude --max-turns 10 -p "实现最终版本" > final.txt

    echo "分阶段执行完成"

## 总结

--max-turns 標誌提供了一種控制非互動模式中代理執行輪數的方式。透過使用此標誌，您可以：

• 限制執行時間和資源使用
• 防止無限迴圈
• 實現漸進式執行
• 控制成本和效率

合理使用 --max-turns 可以幫助您更好地控制代理行為，特別是在需要限制執行時間或資源的場景中。