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. 處理部分消息

#!/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 '.'