6.11 --include-partial-messages - 包含部分流事件

概述

--include-partial-messages 标志允许您在流式响应中包含部分消息。这对于实时处理、调试和监控流式输出非常有用。

基本语法

claude --include-partial-messages

工作原理

当使用流式输出时，Claude 的响应会分块发送。默认情况下，只有完整的消息才会被处理。使用 --include-partial-messages 标志后，部分消息也会被包含在输出中。

使用场景

1. 实时监控流式输出

# 监控流式输出的每个部分
claude --include-partial-messages -p "生成一个长篇技术文档"

# 输出会显示每个部分消息，包括不完整的句子和段落

2. 调试流式响应

# 调试流式响应的生成过程
claude --include-partial-messages --verbose -p "解释复杂的概念"
# 可以看到响应是如何逐步生成的

3. 实时处理流式数据

# 实时处理流式输出
claude --include-partial-messages -p "生成代码" | while read line; do
    echo "收到: $line"
    # 实时处理每一行
done

4. 网络延迟测试

# 测试流式输出的网络延迟
claude --include-partial-messages -p "生成大量文本" | pv -l > output.txt
# pv 会显示每秒接收到的行数

高级用法

1. 与其他标志组合

# 包含部分消息 + 详细日志
claude --include-partial-messages --verbose -p "生成文档"

# 包含部分消息 + JSON 输出
claude --include-partial-messages --output-format json -p "分析数据"

# 包含部分消息 + 限制工具
claude --include-partial-messages --allowedTools "Read" "Grep" -p "搜索代码"

2. 实时进度显示

#!/bin/bash
# 显示实时进度
claude --include-partial-messages -p "生成 100 行代码" | while IFS= read -r line; do
# 计算进度
PROGRESS=$(echo "$line" | grep -oE '[0-9]+' | head -1)
if [ -n "$PROGRESS" ]; then
echo -ne "进度: $PROGRESS%\r"
fi
done
echo -e "\n完成"

3. 流式输出到文件

# 将流式输出保存到文件
claude --include-partial-messages -p "生成长文档" > output.txt

# 同时显示和保存
claude --include-partial-messages -p "生成文档" | tee output.txt

4. 实时过滤

# 实时过滤流式输出
claude --include-partial-messages -p "生成代码" | grep "def " | head -10
# 只显示函数定义

实际应用示例

示例 1: 实时代码生成监控

#!/bin/bash
# monitor-code-gen.sh

echo "开始生成代码..."
claude --include-partial-messages -p "生成一个完整的 REST API" | while IFS= read -r line; do
    # 高亮显示函数定义
    if echo "$line" | grep -q "def \|class \|async def "; then
        echo -e "\033[32m$line\033[0m"  # 绿色
    # 高亮显示注释
    elif echo "$line" | grep -q "#"; then
        echo -e "\033[36m$line\033[0m"  # 青色
    else
        echo "$line"
    fi
done

示例 2: 流式日志记录

#!/bin/bash
# stream-logger.sh
LOG_FILE="stream-$(date +%Y%m%d-%H%M%S).log"
echo "开始记录流式输出到 $LOG_FILE"
claude --include-partial-messages -p "生成技术文档" | while IFS= read -r line; do
# 添加时间戳
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
echo "[$TIMESTAMP] $line" | tee -a "$LOG_FILE"
done
echo "记录完成"

示例 3: 实时字数统计

#!/bin/bash
# word-counter.sh

TOTAL_WORDS=0

claude --include-partial-messages -p "写一篇关于 AI 的文章" | while IFS= read -r line; do
    # 统计当前行的字数
    WORDS=$(echo "$line" | wc -w)
    TOTAL_WORDS=$((TOTAL_WORDS + WORDS))

    # 显示累计字数
    echo -ne "已生成字数: $TOTAL_WORDS\r"

    # 输出内容
    echo "$line"
done

echo -e "\n总字数: $TOTAL_WORDS"

示例 4: 流式输出分析

#!/bin/bash
# analyze-stream.sh
echo "分析流式输出..."
claude --include-partial-messages -p "生成代码" | {
LINES=0
FUNCTIONS=0
CLASSES=0
while IFS= read -r line; do
LINES=$((LINES + 1))
if echo "$line" | grep -q "def "; then
FUNCTIONS=$((FUNCTIONS + 1))
fi
if echo "$line" | grep -q "class "; then
CLASSES=$((CLASSES + 1))
fi
echo "$line"
done
echo -e "\n--- 分析结果 ---"
echo "总行数: $LINES"
echo "函数数: $FUNCTIONS"
echo "类数: $CLASSES"
}

性能考虑

1. 网络延迟

# 测试网络延迟对流式输出的影响
time claude --include-partial-messages -p "生成 1000 行文本"

# 比较包含和不包含部分消息的性能
time claude -p "生成 1000 行文本"

2. 内存使用

# 监控内存使用
/usr/bin/time -v claude --include-partial-messages -p "生成大量文本" 2>&1 | grep "Maximum resident set size"

3. 输出缓冲

# 禁用输出缓冲以获得更实时的输出
stdbuf -o0 claude --include-partial-messages -p "生成文本"

调试技巧

1. 查看流式事件

# 查看所有流式事件
claude --include-partial-messages --verbose -p "生成代码"
# 输出会包含详细的事件信息

2. 分析部分消息

# 分析部分消息的结构
claude --include-partial-messages -p "生成文本" | cat -A

# 显示所有特殊字符

3. 比较完整和部分消息

# 保存完整输出
claude -p "生成文本" > full-output.txt
# 保存部分输出
claude --include-partial-messages -p "生成文本" > partial-output.txt
# 比较差异
diff full-output.txt partial-output.txt

最佳实践

1. 选择合适的场景

适合使用 --include-partial-messages 的场景：

  * 需要实时监控输出
  * 需要调试流式响应
  * 需要实时处理数据

不适合使用的场景：

  * 只需要最终结果
  * 网络连接不稳定
  * 输出量非常大

### 2\. 处理部分消息

```bash
#!/bin/bash
# 正确处理部分消息
claude --include-partial-messages -p "生成文本" | {
BUFFER=""
while IFS= read -r line; do
BUFFER="$BUFFER$line"
# 检查是否是完整的句子
if echo "$BUFFER" | grep -q "\.$\|!\|?"; then
echo "完整句子: $BUFFER"
BUFFER=""
fi
done
# 处理剩余的缓冲区
if [ -n "$BUFFER" ]; then
echo "剩余部分: $BUFFER"
fi
}

3. 错误处理

#!/bin/bash
# 处理流式输出错误

claude --include-partial-messages -p "生成文本" | while IFS= read -r line; do
    # 检查错误
    if echo "$line" | grep -qi "error\|错误"; then
        echo "发现错误: $line" >&2
        # 可以选择中断或继续
    fi

    echo "$line"
done

4. 性能优化

# 使用缓冲减少 I/O 操作
claude --include-partial-messages -p "生成文本" | stdbuf -oL grep "关键词"
# 只处理必要的部分
claude --include-partial-messages -p "生成文本" | head -100

常见问题

Q1: 什么时候应该使用 --include-partial-messages？

A: 当您需要实时监控、调试或处理流式输出时使用。如果只需要最终结果，不需要使用此标志。

Q2: 包含部分消息会影响性能吗？

A: 可能会有轻微的性能影响，因为需要处理更多的消息。但对于大多数应用场景来说，影响可以忽略不计。

Q3: 部分消息是完整的吗？

A: 不一定。部分消息可能是不完整的句子、段落或代码片段。

Q4: 如何区分完整和部分消息？

A: 部分消息通常不包含完整的句子或代码结构。可以通过检查句子结束符（如句号、问号、感叹号）来判断。

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

A: 可以。在交互模式中使用时，会实时显示部分响应。

与其他工具的集成

1. 与 grep 集成

# 实时过滤流式输出
claude --include-partial-messages -p "生成代码" | grep "import "

2. 与 awk 集成

# 实时处理流式输出
claude --include-partial-messages -p "生成文本" | awk '{print NR": "$0}'

3. 与 sed 集成

# 实时转换流式输出
claude --include-partial-messages -p "生成文本" | sed 's/foo/bar/g'

4. 与 jq 集成

# 处理 JSON 流式输出
claude --include-partial-messages --output-format json -p "生成数据" | jq '.'