Claude Code 教程

简体中文

繁體中文
English

简体中文

繁體中文
English

主题

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

概述 ​

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

基本语法 ​

bash
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. 实时进度显示 ​

bash
#!/bin/bash

显示实时进度 ​

claude --include-partial-messages -p "生成 100 行代码" | while IFS= read -r line; do

计算进度 ​

PROGRESS=$(echo "$line" | grep -oE '[0-9]+' | head -1)

bash
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: 实时代码生成监控 ​

bash
#!/bin/bash

monitor-code-gen.sh ​

echo "开始生成代码..." claude --include-partial-messages -p "生成一个完整的 REST API" | while IFS= read -r line; do # 高亮显示函数定义

python
    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: 流式日志记录 ​

bash
#!/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: 实时字数统计 ​

bash
#!/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: 流式输出分析 ​

bash
#!/bin/bash

analyze-stream.sh ​

echo "分析流式输出..." claude --include-partial-messages -p "生成代码" | { LINES=0 FUNCTIONS=0 CLASSES=0

bash
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=""

bash
while IFS= read -r line; do
BUFFER="$BUFFER$line"

检查是否是完整的句子 ​

bash
if echo "$BUFFER" | grep -q "\.$\|!\|?"; then
echo "完整句子: $BUFFER"
BUFFER=""
fi
done

处理剩余的缓冲区 ​

bash
if [ -n "$BUFFER" ]; then
echo "剩余部分: $BUFFER"
fi
}

3. 错误处理 ​

bash
#!/bin/bash

处理流式输出错误 ​

claude --include-partial-messages -p "生成文本" | while IFS= read -r line; do # 检查错误

bash
    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 '.'

基于 MIT 许可发布

Copyright © 2024-present