6.11 --include-partial-messages - 包含部分流事件
第 6 章 · CLI 标志说明 · 第2部分：命令参考
概述#
--include-partial-messages 标志允许您在流式响应中包含部分消息。这对于实时处理、调试和监控流式输出非常有用。
基本语法#
bash复制claude --include-partial-messages
工作原理#
当使用流式输出时，Claude 的响应会分块发送。默认情况下，只有完整的消息才会被处理。使用 --include-partial-messages 标志后，部分消息也会被包含在输出中。
使用场景#
1. 实时监控流式输出#
bash复制# 监控流式输出的每个部分claude --include-partial-messages -p "生成一个长篇技术文档" # 输出会显示每个部分消息，包括不完整的句子和段落
2. 调试流式响应#
bash复制# 调试流式响应的生成过程claude --include-partial-messages --verbose -p "解释复杂的概念"# 可以看到响应是如何逐步生成的
3. 实时处理流式数据#
bash复制# 实时处理流式输出claude --include-partial-messages -p "生成代码"|whileread line;doecho"收到: $line"# 实时处理每一行done
4. 网络延迟测试#
bash复制# 测试流式输出的网络延迟claude --include-partial-messages -p "生成大量文本"|pv -l > output.txt # pv 会显示每秒接收到的行数
高级用法#
1. 与其他标志组合#
bash复制# 包含部分消息 + 详细日志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 行代码"|whileIFS=read -r line;do# 计算进度PROGRESS=$(echo"$line"|grep -oE '[0-9]+'|head -1)if[ -n "$PROGRESS"];thenecho -ne "进度: $PROGRESS%\r"fidoneecho -e "\n完成"
3. 流式输出到文件#
bash复制# 将流式输出保存到文件claude --include-partial-messages -p "生成长文档"> output.txt # 同时显示和保存claude --include-partial-messages -p "生成文档"|tee output.txt
4. 实时过滤#
bash复制# 实时过滤流式输出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"|whileIFS=read -r line;do# 高亮显示函数定义ifecho"$line"|grep -q "def \|class \|async def ";thenecho -e "\033[32m$line\033[0m"# 绿色# 高亮显示注释elifecho"$line"|grep -q "#";thenecho -e "\033[36m$line\033[0m"# 青色elseecho"$line"fidone
示例 2: 流式日志记录#
bash复制#!/bin/bash# stream-logger.shLOG_FILE="stream-$(date +%Y%m%d-%H%M%S).log"echo"开始记录流式输出到 $LOG_FILE"claude --include-partial-messages -p "生成技术文档"|whileIFS=read -r line;do# 添加时间戳TIMESTAMP=$(date'+%Y-%m-%d %H:%M:%S')echo"[$TIMESTAMP] $line"|tee -a "$LOG_FILE"doneecho"记录完成"
示例 3: 实时字数统计#
bash复制#!/bin/bash# word-counter.sh TOTAL_WORDS=0 claude --include-partial-messages -p "写一篇关于 AI 的文章"|whileIFS=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.shecho"分析流式输出..."claude --include-partial-messages -p "生成代码"|{LINES=0FUNCTIONS=0CLASSES=0whileIFS=read -r line;doLINES=$((LINES +1))ifecho"$line"|grep -q "def ";thenFUNCTIONS=$((FUNCTIONS +1))fiifecho"$line"|grep -q "class ";thenCLASSES=$((CLASSES +1))fiecho"$line"doneecho -e "\n--- 分析结果 ---"echo"总行数: $LINES"echo"函数数: $FUNCTIONS"echo"类数: $CLASSES"}
性能考虑#
1. 网络延迟#
bash复制# 测试网络延迟对流式输出的影响time claude --include-partial-messages -p "生成 1000 行文本" # 比较包含和不包含部分消息的性能time claude -p "生成 1000 行文本"
2. 内存使用#
bash复制# 监控内存使用/usr/bin/time -v claude --include-partial-messages -p "生成大量文本"2>&1|grep"Maximum resident set size"
3. 输出缓冲#
bash复制# 禁用输出缓冲以获得更实时的输出stdbuf -o0 claude --include-partial-messages -p "生成文本"
调试技巧#
1. 查看流式事件#
bash复制# 查看所有流式事件claude --include-partial-messages --verbose -p "生成代码"# 输出会包含详细的事件信息
2. 分析部分消息#
bash复制# 分析部分消息的结构claude --include-partial-messages -p "生成文本"|cat -A # 显示所有特殊字符
3. 比较完整和部分消息#
bash复制# 保存完整输出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=""whileIFS=read -r line;doBUFFER="$BUFFER$line"# 检查是否是完整的句子ifecho"$BUFFER"|grep -q "\.$\|!\|?";thenecho"完整句子: $BUFFER"BUFFER=""fidone# 处理剩余的缓冲区if[ -n "$BUFFER"];thenecho"剩余部分: $BUFFER"fi}
3. 错误处理#
bash复制#!/bin/bash# 处理流式输出错误 claude --include-partial-messages -p "生成文本"|whileIFS=read -r line;do# 检查错误ifecho"$line"|grep -qi "error\|错误";thenecho"发现错误: $line">&2# 可以选择中断或继续fi echo"$line"done
4. 性能优化#
bash复制# 使用缓冲减少 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 集成#
bash复制# 实时过滤流式输出claude --include-partial-messages -p "生成代码"|grep"import "
2. 与 awk 集成#
bash复制# 实时处理流式输出claude --include-partial-messages -p "生成文本"|awk'{print NR": "$0}'
3. 与 sed 集成#
bash复制# 实时转换流式输出claude --include-partial-messages -p "生成文本"|sed's/foo/bar/g'
4. 与 jq 集成#
bash复制# 处理 JSON 流式输出claude --include-partial-messages --output-format json -p "生成数据"| jq '.'