Paper Summarize Pdf To Feishu
📚 知識管理
免費
📖 技能介紹
paper-summarize-pdf-to-feishu
本技能採用多 Agent 協作模式。作為主控 Agent，你的核心職責是：
- ✅ 排程流程
- ✅ 執行系統指令碼
- ✅ 向子 Agent 分配具體任務並傳遞上下文
- ✅ 與使用者溝通確認
❌ 請不要試圖自己在單次對話中完成所有長文本閱讀和細節比對。
🚨 執行前必讀（30 秒）
收到 PDF 後，第一步必須做：
- ✅ 完整閱讀本 SKILL.md（不要跳過！）
- ✅ 檢查前置依賴（
which pdftotext pdfinfo ...） - ✅ 建立日誌目錄（階段零）
❌ 禁止直接開始處理！
📌 核心原則（違反=任務失敗）
| 原則 | 說明 |
|---|---|
| 不要自己讀長文本 | 必須派生 Reader 子 Agent |
| 不要自己上傳圖片 | 必須派生 Vision 子 Agent |
| 不要自我稽核 | 必須派生 Reviewer + 真實資料注入 |
| 必須等使用者確認 | 階段四必須掛起 |
| 必須用佔位符 | Reader 必須插入 【FIGURE_X】 |
前置依賴檢查 (主控 Agent 執行)
確保以下工具可用：pdftotext, pdfinfo, pdfimages, pdftoppm, tesseract, jq。
如果缺失，通過以下命令安裝：
# PDF 處理工具
sudo apt-get install -y poppler-utils
# OCR 工具
sudo apt-get install -y tesseract-ocr tesseract-ocr-eng tesseract-ocr-chi-sim
# JSON 處理工具（指令碼中大量使用）
sudo apt-get install -y jq快速檢查：
which pdftotext pdfinfo pdfimages pdftoppm tesseract jq
# 所有命令都應該返回路徑日誌管理規範（重要！）
日誌目錄結構
在階段零開始時，主控 Agent 必須建立以下目錄結構：
mkdir -p "$PAPER_DIR/logs/scripts"
mkdir -p "$PAPER_DIR/progress"
mkdir -p "$PAPER_DIR/errors"| 目錄說明： | 目錄 | 用途 | 內容 |
|---|---|---|---|
$PAPER_DIR/logs/ |
統一日誌目錄 | 所有 Agent 和指令碼的日誌 | |
$PAPER_DIR/logs/scripts/ |
指令碼日誌 | extract_metadata.log, locate_figures.log 等 |
|
$PAPER_DIR/progress/ |
進度報告 | Markdown 格式的子 Agent 完成報告 | |
$PAPER_DIR/errors/ |
錯誤報告 | 錯誤日誌和堆疊跟蹤 |
優點：
- ✅ 每篇論文獨立，不會覆蓋
- ✅ 多人使用不會衝突
- ✅ 清理論文時一起清理
- ✅ 符合"工作目錄"的概念
完整工作流程（六階段）
階段零：去重檢查 (主控 Agent 排程)
日誌目錄建立：
mkdir -p "$PAPER_DIR/logs/scripts"
mkdir -p "$PAPER_DIR/progress"
mkdir -p "$PAPER_DIR/errors"
log_master "✅ 日誌目錄已建立"目標：檢查論文是否已處理，避免重複工作。
-
提取後設資料：
scripts/extract_metadata.sh <input.pdf> "$PAPER_DIR/metadata.json" "$PAPER_DIR" -
檢查去重：
scripts/check_duplicate.sh "$PAPER_DIR/metadata.json" "$PAPERS_DIR" result=$? # 儲存退出碼 # 檢查指令碼輸出中的 RESULT 變數 if echo "$output" | grep -q "RESULT=duplicate"; then echo "❌ 完全重複：該論文已處理過" echo "📋 飛書文件：$(cat $PAPER_DIR/feishu_doc_token.txt)" exit 1 # 停止任務 elif echo "$output" | grep -q "RESULT=possible_duplicate"; then echo "⚠️ 可能重複：已存在飛書文件，但 PDF 檔案未找到" echo "📋 請使用者確認是否繼續" # 等待使用者確認 fi # 檢查退出碼 if [[ $result -eq 1 ]]; then echo "❌ 去重檢查失敗，停止任務" exit 1 fi -
根據返回結果判斷：
- 退出碼 0 + RESULT=new：新論文，建立
$PAPER_DIR，複製 PDF，進入階段一 - 退出碼 1 + RESULT=duplicate：❌ 完全重複，立即停止任務，告知使用者已處理過
- 退出碼 0 + RESULT=possible_duplicate：⚠️ 可能重複，等待使用者確認
- 退出碼 2 + RESULT=supplement：補充材料，執行合併流程
- 退出碼 0 + RESULT=new：新論文，建立
⚠️ 重要：主控 Agent 必須檢查指令碼的退出碼和 RESULT 變數，如果檢測到重複（RESULT=duplicate 或退出碼 1），必須立即停止任務，不得繼續執行後續階段！
階段一：提取與初稿生成 (Sub-agent: Reader)
日誌要求：
- 所有日誌輸出到 $PAPER_DIR/progress/reader.log
- 使用標準格式：[YYYY-MM-DD HH:MM:SS] [級別] 訊息
- 關鍵步驟必須記錄（開始、完成、錯誤）
- 完成後生成進度報告到 $PAPER_DIR/progress/reader_report.md
目標：提取 PDF 文本並生成結構化總結初稿。
-
提取文本（主控 Agent 執行）：
scripts/extract_pdf_text.sh "$PAPER_DIR/paper.pdf" "$PAPER_DIR/paper.txt" "$PAPER_DIR" -
派生閱讀子 Agent（主控 Agent 呼叫
sessions_spawn）：sessions_spawn task="你是一個專業的學術閱讀助手 (Reader)。 **任務**： 1. 分段讀取 $PAPER_DIR/paper.txt 的完整內容（不要跳過任何部分）。 2. 嚴格按照 summary_template.md 的結構要求，提取以下內容： - 研究背景與動機 - 研究設計 - 方法/系統架構 - 核心結果（包含所有關鍵資料：百分比、p 值、置信區間、樣本量） - 討論與侷限性 - 結論 3. 必須將最終生成的 Markdown 文本儲存到 $PAPER_DIR/summary.md 中。 **資料精度要求**： - 百分比：28.7%（不要四捨五入） - P 值：P < 0.001 或 P = 0.005 - 樣本量：n=691 或 2,069 人 **圖片佔位符要求**（重要！）： - 在**相關章節內容後**插入佔位符標記：`【FIGURE_X】` - 佔位符單獨一行，不要與正文混排 - **必須用中文方括號** `【】`，因為飛書會過濾 HTML 註釋 `<!-- -->` - **新增預期描述**（幫助 Vision Agent 匹配圖片）： ```markdown ## 研究設計 本研究採用隨機對照試驗設計... 【FIGURE_1】 <!-- 預期：流程圖/試驗設計，展示參與者分組和隨訪流程 --> ## 核心結果 LLM 單獨表現優異... 【FIGURE_2】 <!-- 預期：柱狀圖/資料對比，展示主要結局指標 -->- 佔位符放置原則 ⭐：
- Figure 應該放在與其內容相關的章節後，而不是按編號順序
- 例如：研究設計流程圖 → 放在"研究設計"章節後，而不是"研究背景"後
- 從 paper.txt 中提取 Figure 標題，根據內容判斷應該放在哪個章節
- 佔位符數量 ⭐：
- 佔位符數量 ≠ PDF 中 Figure 總數
- 只插入重要的、原文有描述的 Figure（通常 3-5 個）
- 判斷標準：正文中明確提到"如圖 X 所示"或有大段圖片描述的
進度日誌（必須寫入）：
- 開始任務時，立即寫入 $PAPER_DIR/progress/reader.log：
[YYYY-MM-DD HH:MM:SS] Reader 子 Agent 啟動 [YYYY-MM-DD HH:MM:SS] 開始讀取 paper.txt (共 XXX 行) - 每完成一個章節，追加進度：
[YYYY-MM-DD HH:MM:SS] ✅ 完成：研究背景與動機 [YYYY-MM-DD HH:MM:SS] ✅ 完成：研究設計 ... - 完成後寫入最終報告：
[YYYY-MM-DD HH:MM:SS] ✅ Reader 任務完成 [YYYY-MM-DD HH:MM:SS] 輸出檔案：$PAPER_DIR/summary.md (XXX KB) [YYYY-MM-DD HH:MM:SS] 總耗時：X 分鐘
完成後彙報（向我報告）：
## Reader 子 Agent 完成報告 **開始時間**: YYYY-MM-DD HH:MM **完成時間**: YYYY-MM-DD HH:MM **耗時**: X 分鐘 ### 執行結果 - ✅ 成功生成 summary.md ### 輸出檔案 - `$PAPER_DIR/summary.md` (XXX KB, XXX 行) - `$PAPER_DIR/progress/reader.log` (進度日誌) ### 論文關鍵資訊 - **研究型別**: <如 RCT、佇列研究等> - **樣本量**: <如 2,069 人> - **主要結局**: <如 問診時長減少 28.7%> ### 問題與備註 <如有問題，在此說明；如無問題，填寫"無">確認後向我（主控 Agent）報告。"
- 佔位符放置原則 ⭐：
-
等待子 Agent 完成並確認
$PAPER_DIR/summary.md已生成。
階段二：文件建立與限流配圖 (Sub-agent: Vision)
目標：建立飛書文件並插入圖表。
-
建立飛書文件（主控 Agent 執行）：
feishu_doc action=create title="總結：<論文標題>"獲取
doc_token並儲存到$PAPER_DIR/feishu_doc_token.txt。 -
寫入初稿（主控 Agent 執行）：
# ⚠️ 注意：必須使用 Reader 生成的完整 summary.md，不要手動修改或精簡 feishu_doc action=write doc_token="<token>" content="$(cat $PAPER_DIR/summary.md)" -
定位圖表（主控 Agent 執行）：
scripts/locate_figures.sh "$PAPER_DIR/paper.pdf" "$PAPER_DIR/paper.txt" "$PAPER_DIR/images"輸出說明：指令碼使用
pdfimages提取 PDF 中所有嵌入圖片，生成fig_01.png,fig_02.png等檔案。 注意：提取的圖片可能包含圖示、線條等小檔案（<10KB），Vision 子 Agent 需要篩選真正的 Figure（通常 >100KB）。 -
自動識別支援圖片的模型（主控 Agent 執行）：
# 從配置中自動查詢支援圖片輸入的模型 VISION_MODEL=$(jq -r ' .models.providers | to_entries[] | .value.models[] | select(.input and (.input | index("image"))) | .id | first ' "~/.openclaw/openclaw.json" 2>/dev/null) # 如果找不到支援圖片的模型，使用主模型 if [[ -z "$VISION_MODEL" || "$VISION_MODEL" == "null" || "$VISION_MODEL" == "" ]]; then VISION_MODEL=$(jq -r '.agents.defaults.model.primary' "~/.openclaw/openclaw.json") echo "⚠️ 未找到支援圖片的模型，使用主模型：$VISION_MODEL" else echo "👁️ Vision 模型（自動識別）：$VISION_MODEL" fi -
派生配圖子 Agent（主控 Agent 呼叫
sessions_spawn）：sessions_spawn task="你是一個視覺處理專家 (Vision)。 **任務**： 1. 逐個讀取 $PAPER_DIR/images 下的圖片，確認圖中包含正確的 Figure/Table 標題及內容。 2. 使用 feishu_doc action=upload_image 上傳圖片到飛書文件 (token: $DOC_TOKEN)。 3. **精確定位插入**：使用 parent_block_id + index 引數將圖片插入到對應章節。 🚨 **飛書操作關鍵規則**（必須遵守，否則失敗）： **1. 防限流**： - 每次 `upload_image` 後必須 `sleep 3` 秒 - 嚴重限流時等待 10 秒後重試 **2. 智慧匹配佔位符（修正版流程）** ⭐： - **步驟 1**：`list_blocks` 獲取所有 blocks，**從 root block 的 children 陣列中查詢佔位符的位置** **關鍵**：佔位符的 `index` 是它在 root block 的 `children` 陣列中的位置（0-based）- 獲取 root block（第一個 block）
- 讀取 root_block.children 陣列
- 遍歷 children 陣列，找到佔位符 block_id 的位置
-
該位置就是 index（0-based）
**記錄**：每個佔位符的 `block_id` 和 `index`（在 children 陣列中的位置）
-
步驟 2：對每張圖片執行（必須按順序執行，嚴格遵守）：
2a. OCR 提取文字：
tesseract image.png stdout --psm 6提取 Figure 編號和標題。
2b. 視覺模型理解（重要！OCR 失敗時必須執行）：
使用 `read` 工具讀取圖片檔案（路徑：$PAPER_DIR/images/xxx.png） 讀取時附帶問題（讓模型分析圖片）： "請分析這張圖片： - 這是什麼型別的圖表？（流程圖/柱狀圖/森林圖/表格/其他） - 圖中有什麼關鍵詞或標題？ - 能否識別 Figure 編號或 Table 編號？ 請用簡潔的格式回覆，例如： 型別：柱狀圖 關鍵詞：條件識別率，GPT-4o, Llama 3, 94.7% Figure 編號：Figure 2"說明：
- 你的
model引數已設定為支援圖片的模型（如 qwen3.5-plus） - 使用
read工具讀取圖片後，模型會自動"看到"並分析 - 從模型回覆中提取：圖表型別、關鍵詞、Figure 編號
2c. 匹配佔位符：
- 根據 OCR 結果 + 視覺模型提取的關鍵詞 + 佔位符預期描述，匹配最合適的佔位符
- 記錄佔位符的
block_id和index
- 你的
-
步驟 3：先刪除佔位符，再上傳圖片 ⭐
a. delete_block(block_id: 佔位符的 block_id) b. 記錄原 index = N c. sleep 1 秒（讓飛書處理刪除） d. upload_image(..., parent_block_id: 文件根 ID, index: N) e. 【關鍵驗證】檢查 file_token： - 如果 file_token 為空字串 → 上傳失敗，等待 10 秒後重試 - 如果 file_token 不為空 → 上傳成功 f. sleep 3 秒（防限流，必須執行！） g. 記錄：圖片上傳成功，block_id = xxx -
匹配原則：
- Figure 編號優先（OCR 或視覺模型識別的"Figure 1"→匹配
【FIGURE_1】） - 關鍵詞輔助（視覺模型提取的關鍵詞與佔位符預期描述重疊）
- 如果 OCR 失敗，必須使用視覺模型理解，不得直接退化
- Figure 編號優先（OCR 或視覺模型識別的"Figure 1"→匹配
-
步驟 4：最終驗證
list_blocks 檢查 Image block (block_type 27) 數量 應該等於上傳的圖片數量
3. 精確定位引數：
parent_block_id: 文件根 ID（和doc_token相同）index: 佔位符 block 的 index（在佔位符位置插入）- 不填
parent_block_id則追加到末尾
4. 上傳後驗證：
- 檢查
file_token不為空字串 - 執行
read檢視文件，確認圖片數量正確 - 開啟飛書文件確認圖片顯示（不轉圈）
5. 失敗處理（重置法）：
- 觸發條件：
delete_block返回 404（block 不存在）- 連續 2 次
upload_image返回空file_token - 文件結構混亂（block IDs 失效）
- 操作步驟：
- 向主控 Agent 報告需要重置
- 主控 Agent 執行：
feishu_doc action=write doc_token="$DOC_TOKEN" content="$(cat $PAPER_DIR/summary.md)"（使用完整檔案，不要精簡） - 重新從步驟 1 開始（
list_blocks→ 找佔位符 → 上傳圖片）
- 注意：重置後所有佔位符會恢復，需要重新上傳所有圖片
操作流程：
- 用
write寫入 summary.md（含佔位符【FIGURE_X】和預期描述） list_blocks獲取所有 blocks，讀取佔位符預期描述-
對每張圖片執行智慧匹配（詳細步驟）：
a. OCR 提取：tesseract image.png stdout --psm 6 b. 視覺模型理解（OCR 失敗時必需）： 呼叫 read 工具讀取圖片，附帶問題： "請分析這張圖片的型別、關鍵詞、Figure 編號" 示例模型回覆： "型別：柱狀圖 關鍵詞：條件識別率，GPT-4o, 94.7% Figure 編號：Figure 2" c. 匹配佔位符： - 如果 OCR 識別到"Figure 2"→匹配 `【FIGURE_2】` - 如果 OCR 失敗，用關鍵詞匹配： "柱狀圖" + "條件識別率" → 匹配預期描述為"柱狀圖，展示條件識別率"的佔位符 d. 獲取佔位符的 index（從 list_blocks 結果中） - 在匹配到的佔位符
index位置upload_image delete_block刪除佔位符- 重複步驟 3-5 直到所有圖片上傳完成
圖片驗證：
- 如果 pdfimages 提取的圖片數量 < 文件中 Figure 數量，使用截圖備選方案
- 驗證每張截圖是否包含'Figure X'或'Table X'標題文字
- 純文字頁面不要使用，檢查相鄰頁面（±3 頁範圍）
進度日誌（必須寫入）：
- 開始任務時，立即寫入 $PAPER_DIR/progress/vision.log：
[YYYY-MM-DD HH:MM:SS] Vision 子 Agent 啟動 [YYYY-MM-DD HH:MM:SS] 飛書文件 token: <token> [YYYY-MM-DD HH:MM:SS] 待上傳圖片：X 張 - 寫入文本後：
[YYYY-MM-DD HH:MM:SS] ✅ 寫入 summary.md（含佔位符和預期描述） [YYYY-MM-DD HH:MM:SS] ✅ list_blocks 獲取 blocks 列表 [YYYY-MM-DD HH:MM:SS] ✅ 找到佔位符：【FIGURE_1】(index: X, 預期：流程圖) - 每上傳一張圖片，追加進度：
[YYYY-MM-DD HH:MM:SS] 📸 處理圖片：figure_1.png [YYYY-MM-DD HH:MM:SS] 🔍 OCR 結果：Figure 1, 流程圖 [YYYY-MM-DD HH:MM:SS] 👁️ 視覺模型分析：型別=流程圖，關鍵詞=研究設計，分組 [YYYY-MM-DD HH:MM:SS] 🎯 匹配佔位符：【FIGURE_1】(index: 4, 預期：流程圖) [YYYY-MM-DD HH:MM:SS] ✅ Fig. 1 上傳成功 (file_token: xxx, 527 KB, index: 4) [YYYY-MM-DD HH:MM:SS] ✅ 刪除佔位符【FIGURE_1】 [YYYY-MM-DD HH:MM:SS] ⏳ 等待 3 秒（防限流）... [YYYY-MM-DD HH:MM:SS] 🔍 OCR 結果：失敗（無文字） [YYYY-MM-DD HH:MM:SS] 👁️ 視覺模型分析：型別=柱狀圖，關鍵詞=條件識別率，GPT-4o, 94.7% [YYYY-MM-DD HH:MM:SS] 🎯 匹配佔位符：【FIGURE_2】(index: 13, 預期：柱狀圖，展示條件識別率) [YYYY-MM-DD HH:MM:SS] ✅ Fig. 2 上傳成功 (file_token: xxx, 442 KB, index: 13) ... - 完成後寫入最終報告：
[YYYY-MM-DD HH:MM:SS] ✅ Vision 任務完成 [YYYY-MM-DD HH:MM:SS] 成功上傳：X/ Y 張圖片 [YYYY-MM-DD HH:MM:SS] 智慧匹配成功：X 張（命中率 XX%） [YYYY-MM-DD HH:MM:SS] 總耗時：X 分鐘
完成後彙報（向我報告）：
## Vision 子 Agent 完成報告 **開始時間**: YYYY-MM-DD HH:MM **完成時間**: YYYY-MM-DD HH:MM **耗時**: X 分鐘 ### 執行結果 - ✅ 成功建立飛書文件 - ✅ 寫入 summary.md（含佔位符） - ✅ 上傳 X 張圖片（使用佔位符定位） - ✅ 刪除所有佔位符 ### 輸出檔案 - 飛書文件連結：https://feishu.cn/docx/<doc_token> - `$PAPER_DIR/progress/vision.log` (進度日誌) ### 圖片上傳詳情 | Figure | 大小 | 佔位符 index | file_token | 匹配方式 | 狀態 | |--------|------|-------------|------------|----------|------| | Fig. 1 | 527 KB | 4 | MsRLbdZbVo9... | OCR | ✅ | | Fig. 2 | 442 KB | 13 | NjuFbqaz8oT... | 視覺模型 | ✅ | ### 匹配統計 - OCR 成功：X 張 - 視覺模型輔助：Y 張 - 匹配成功率：XX% ### 問題與備註 <如有問題，在此說明；如無問題，填寫"無">確認後向我（主控 Agent）報告。" model="$VISION_MODEL"
-
等待子 Agent 完成並確認圖片已正確插入。
階段三：真實資料比對稽核 (Sub-agent: Reviewer)
日誌要求：
- 所有日誌輸出到 $PAPER_DIR/progress/reviewer.log
- 使用標準格式：[YYYY-MM-DD HH:MM:SS] [級別] 訊息
- 關鍵步驟必須記錄（開始、完成、錯誤）
- 完成後生成進度報告到 $PAPER_DIR/progress/reviewer_report.md
- 稽核報告儲存到 $PAPER_DIR/progress/audit_report.md
目標：通過注入真實資料防止稽核幻覺。
核心防幻覺機制：必須將原始文本的切片直接餵給稽核模型，不能讓它空對空稽核。
-
讀取 Fallback 模型（主控 Agent 執行）：
FALLBACK_MODEL=$(jq -r '.agents.defaults.model.fallbacks[0]' "~/.openclaw/openclaw.json")如果沒有配置，則使用當前主模型。告知使用者正在啟動交叉稽核。
-
派生稽核子 Agent（帶真實資料注入）（主控 Agent 呼叫
sessions_spawn）：sessions_spawn task="你是一個嚴苛的學術稽核員 (Reviewer)。 **【原始論文關鍵資料提取】**： $(cat $PAPER_DIR/paper.txt | grep -E '%|p<|p=|CI|n=' | head -n 30) **【生成的總結內容】**： $(cat $PAPER_DIR/summary.md) **請重點核查**： 1. 飛書文件中的百分比、p 值、置信區間、樣本量是否與原始資料存在偏差？ 2. 結論是否有無依據的誇大？ 3. 格式是否完全符合 summary_template.md 的精度要求？ **進度日誌**（必須寫入）： 1. 開始任務時，立即寫入 $PAPER_DIR/progress/reviewer.log：[YYYY-MM-DD HH:MM:SS] Reviewer 子 Agent 啟動 [YYYY-MM-DD HH:MM:SS] 稽核模型：<模型名稱> [YYYY-MM-DD HH:MM:SS] 開始資料一致性核對
2. 完成後寫入最終報告：[YYYY-MM-DD HH:MM:SS] ✅ Reviewer 任務完成 [YYYY-MM-DD HH:MM:SS] 稽核結果：通過 / 需要修改 [YYYY-MM-DD HH:MM:SS] 總耗時：X 分鐘
**輸出要求**： 請直接輸出一份詳盡的《稽核報告及修改建議清單》，格式如下： ```markdown ## 稽核報告 ### 一致的內容 - <列出哪些地方與原文一致> ### 需要修改的內容 - <列出哪些地方需要修改，具體修改建議> ### 格式問題 - <列出格式不符合要求的地方> ### 總體評價 <通過/需要修改>完成後彙報（向我報告）：
## Reviewer 子 Agent 完成報告 **開始時間**: YYYY-MM-DD HH:MM **完成時間**: YYYY-MM-DD HH:MM **耗時**: X 分鐘 **稽核模型**: <模型名稱> ### 執行結果 - ✅ 稽核通過 / ⚠️ 需要修改 ### 稽核統計 - 一致的內容：X 處 - 需要修改的內容：Y 處 - 格式問題：Z 處 ### 輸出檔案 - `$PAPER_DIR/progress/reviewer.log` (進度日誌) - `$PAPER_DIR/audit_report.md` (稽核報告全文) ### 關鍵問題 <如有嚴重問題（如資料錯誤、結論誇大），在此說明> ### 修改建議清單 1. <具體修改建議 1> 2. <具體修改建議 2> ...確認後向我（主控 Agent）報告。" model="$FALLBACK_MODEL"
-
收集稽核報告，準備提交使用者確認。
-
應用稽核修改（主控 Agent 執行） ⭐：
步驟 4a：讀取稽核報告
# 讀取稽核報告 AUDIT_REPORT="$PAPER_DIR/progress/audit_report.md" # 提取修改建議清單 MODIFY_LIST=$(grep -A 20 "修改建議清單" "$AUDIT_REPORT")步驟 4b：逐項應用修改
# 對每個修改建議： # 1. 使用 list_blocks 找到需要修改的 block_id # 2. 使用 update_block 修改文本塊 # 3. 使用 insert/append 新增缺失內容 # 4. 記錄修改日誌修改原則：
- 資料錯誤 → 使用
update_block修改對應文本塊 - 缺失資料 → 使用
insert在相應位置新增 - 格式問題 → 使用
update_block調整格式 - 每次修改後驗證
success: true
步驟 4c：驗證修改
# 使用 read 檢視飛書文件 # 確認所有修改已應用 # 記錄驗證結果到 progress/audit_apply.log - 資料錯誤 → 使用
階段四：人工確認 (主控 Agent 執行)
目標：讓使用者確認稽核報告並決定是否修改。
-
主控 Agent 收集 Reviewer 的《稽核報告及修改建議清單》。
-
向用戶傳送以下內容：
📄 飛書初稿連結：<doc_link> ## 稽核報告摘要 <稽核報告內容> ## 修改建議清單 <具體修改建議> --- ⏳ 請確認是否採納以上修改建議： | 回覆 | 操作 | |------|------| | 【確認】 | 自動應用修改，輸出最終版 | | 【修改 xxx】 | 進行微調（告訴我具體修改內容） | | 【跳過】 | 保留現狀，輸出最終版 | -
掛起等待使用者回覆。
階段五：定稿完善 (主控 Agent 執行)
目標：應用修改並輸出最終版。
-
應用修改（根據使用者確認） ⭐：
如果使用者回覆【確認】：
# 1. 讀取稽核報告中的修改建議清單 AUDIT_REPORT="$PAPER_DIR/progress/audit_report.md" # 2. 對每個修改建議執行： # a. 使用 list_blocks 找到目標 block_id # b. 使用 update_block 修改內容 # c. 驗證修改成功 (success: true) # d. 記錄修改日誌 # 3. 使用 read 驗證所有修改已應用 # 4. 記錄驗證結果到 progress/audit_apply.log修改方法： 修改型別 使用工具 說明 修改文本 update_block需要提供正確的 block_id 新增內容 insert/appendinsert 在指定位置，append 追加到末尾 修改表格 write_table_cells修改表格單元格內容 新增表格行 insert_table_row在表格中新增新行 驗證流程：
# 1. 使用 read 檢視飛書文件 # 2. 確認所有修改已應用 # 3. 如果有遺漏，重新執行修改 # 4. 記錄最終驗證結果如果使用者回覆【修改 xxx】：根據使用者具體要求修改。
如果使用者回覆【跳過】：保持現狀，記錄"使用者選擇跳過修改"。
-
強制署名（主控 Agent 必須執行）： 在文件末尾追加署名塊（嚴格按照
summary_template.md的表格要求）：## 📝 文件資訊 | 專案 | 資訊 | |------|------| | 撰寫人 | Lux（qwencode/qwen3.5-plus） | | 稽核狀態 | ✅ 已稽核 / ⏭️ 已跳過 | | 稽核模型 | <稽核模型名稱> | | 生成時間 | <YYYY-MM-DD HH:MM> | | 文件版本 | v1.0（最終版） | **稽核修改記錄**： - ✅ 核實接受日期：已確認 - ✅ 關鍵資料已核對（X 處一致，Y 處已補充） - ✅ 圖片已上傳（X 張） -
更新本地後設資料： 儲存最終狀態到
$PAPER_DIR/final_metadata.json。 -
向用戶交付最終版連結，流程結束。
-
記錄修改日誌 ⭐：
# 儲存修改記錄到 progress/audit_apply.log # 包含：修改項、修改前、修改後、修改時間、驗證結果
附加流程：補充材料處理
如果在【階段零】判定傳入的 PDF 為補充材料：
-
主控 Agent 讀取已有的飛書文件 token：
DOC_TOKEN=$(cat "$PAPER_DIR/feishu_doc_token.txt") -
執行合併指令碼：
scripts/merge_supplement.sh "$PAPER_DIR" "<supplement.pdf>" "$DOC_TOKEN" -
主控 Agent 呼叫
feishu_doc action=append將補充摘要追加到主文件的"📎 補充材料"章節中。 -
無需走完整生成和稽核流程。
主控 Agent 注意事項
子 Agent 清理機制（重要！）
原則：每個階段完成後，立即清理已完成的子 Agent，只保留主控 Agent
實現：
- 派生子 Agent 時記錄 session_key
- 等待子 Agent 完成（
sessions_yield） - 獲取子 Agent 結果
- 立即清理：
subagents action=kill target="$session_key"
示例：
# 階段一：Reader Agent
reader_session=$(sessions_spawn task="Reader..." label="Reader-Agent")
sessions_yield # 等待完成
summary_md=$(cat "$PAPER_DIR/summary.md") # 獲取結果
subagents action=kill target="$reader_session" # ← 清理 Reader
# 階段二：Vision Agent
vision_session=$(sessions_spawn task="Vision..." label="Vision-Agent")
sessions_yield
doc_token=$(cat "$PAPER_DIR/feishu_doc_token.txt")
subagents action=kill target="$vision_session" # ← 清理 Vision
# 階段三：Reviewer Agent
reviewer_session=$(sessions_spawn task="Reviewer..." label="Reviewer-Agent")
sessions_yield
audit_report=$(cat "$PAPER_DIR/audit_report.md")
subagents action=kill target="$reviewer_session" # ← 清理 Reviewer
# 最終：只保留主控 Agent好處：
- ✅ 只保留主控 Agent，降低記憶體佔用（節省 ~300-400MB/每個階段）
- ✅ 避免子 Agent 堆積
- ✅ 明確的資源管理
職責邊界
-
✅ 應該做的：
- 排程流程
- 執行系統指令碼
- 呼叫
sessions_spawn派生子 Agent - 整合子 Agent 的結果
- 與使用者溝通確認
-
❌ 不應該做的：
- 親自閱讀長文本（交給 Reader）
- 親自處理圖片上傳（交給 Vision）
- 自我稽核（交給 Reviewer + 真實資料注入）
🚨 飛書操作關鍵原則（本業務特有）
核心原則：
📌 通用工具用法參考
feishu-doc技能文件 📌 本節只記錄本業務特有的糾偏規則和易錯點
1. 圖片上傳防限流（高優先順序）
規則：任何涉及 upload_image 的迴圈操作，必須：
feishu_doc action=upload_image ...
sleep 3 # 必須間隔 3 秒
feishu_doc action=upload_image ...
sleep 3 # 必須間隔 3 秒違反後果：
file_token為空字串- 圖片 block 建立但圖片轉圈不顯示
- 需要刪除所有空 token block 重新上傳
嚴重限流時：
- 等待 10 秒後重試
- 增加間隔到 5 秒
2. 刪除失敗 → 重置法（兜底方案）
適用場景：
delete_block返回 404（block 不存在）- 文件結構混亂，需要清理
- Block IDs 失效，無法定位
- 連續 2 次
upload_image返回空file_token
操作步驟：
# 1. 使用 Reader 生成的完整 summary.md（不要精簡）
# 2. 全量覆蓋（清除所有舊 blocks）
feishu_doc action=write doc_token="$DOC_TOKEN" content="$(cat $PAPER_DIR/summary.md)"
# 3. 重新 upload_image 上傳圖片
# 4. read 檢視文件確認結果效果：清除所有舊 blocks，恢復到乾淨狀態。
| 方案對比： | 場景 | 方案 | 地位 |
|---|---|---|---|
| 文件結構混亂、block IDs 失效 | 重置法（write 全量覆蓋） |
兜底方案 | |
| 圖片精確定位 | 佔位符法（【FIGURE_X】） |
首選方案 |
歷史經驗：
- 2026-03-26/27：遇到
delete_block404 錯誤，使用重置法成功 - 2026-03-28：佔位符方案驗證成功，成為首選方案
3. 操作前確認流程
任何飛書文件修改操作前，必須：
list_blocks獲取最新 blocks 列表- 確認目標 blocks 存在（檢查 block IDs）
- 逐個呼叫工具（不批次）
- 操作後再次
list_blocks+read驗證
4. 圖片精確定位技巧
引數說明：
parent_block_id: 文件根 ID（和doc_token相同）index: 從list_blocks的children陣列獲取（0-based）- 不填
parent_block_id則自動追加到末尾
定位方法：
# 從 list_blocks 返回中找到章節標題的 block_id
# 計算其 index（在 children 陣列中的位置）
# 上傳圖片時 index = 章節 index + 1插入策略：
- 從文件末尾往前插（倒序），避免索引偏移
- Fig. 1 插入到 4.1 章節後，Fig. 2 插入到 4.2 章節後
5. 上傳後驗證清單
這個技能的最新版本可以在7w4.net小蔥技能站找到。
必須檢查：
- [ ]
upload_image返回的file_token不為空字串 - [ ]
read檢視文件，確認圖片數量正確 - [ ] 開啟飛書文件確認圖片顯示（不轉圈）
驗證命令：
feishu_doc action=read doc_token="$DOC_TOKEN"
# 檢查 "Image" 數量是否正確
# 如果 "Image": 7，說明 7 張圖片都已成功上傳6. 區分兩種"delete"
| 不要混淆： | 操作 | 用途 | 常見錯誤 | 解決方案 |
|---|---|---|---|---|
feishu_doc delete_block |
刪除文件塊 | 404（block 不存在） | 用重置法（write 全量覆蓋） | |
feishu_drive delete |
刪除雲空間檔案 | 400（許可權問題） | 檢查檔案許可權 |
錯誤處理
子 Agent 錯誤報告機制：
錯誤處理
子 Agent 錯誤報告機制：
如果子 Agent 執行失敗，必須寫入錯誤報告：
# 錯誤報告格式 ($PAPER_DIR/errors/<agent>.log)
## 錯誤報告
**子 Agent**: Reader/Vision/Reviewer
**錯誤型別**: 指令碼執行失敗 / API 限流 / 檔案不存在 / 超時 / ...
**錯誤資訊**: <具體錯誤內容>
**發生時間**: YYYY-MM-DD HH:MM:SS
**重試次數**: X/3
### 建議操作
<主控 Agent 應該採取的行動，如：重試、跳過、人工介入等>主控 Agent 響應流程：
- 檢查錯誤日誌：讀取
$PAPER_DIR/errors/<agent>.log - 判斷錯誤型別：
- 可重試錯誤（如 API 限流、網路超時）：重試最多 3 次
- 致命錯誤（如檔案不存在、許可權不足）：停止任務，告知使用者
- 使用者溝通：如重試失敗，向用戶說明情況並提供建議
常見錯誤處理：
| 錯誤型別 | 錯誤程式碼 | 處理方案 |
|---|---|---|
| 飛書 API 限流 | 429 | 等待 10 秒後重試，增加 sleep 時間到 5 秒 |
| Block 不存在 | 404 | 重新獲取 blocks 列表，或使用重置法 |
| PDF 無法提取文本 | - | 檢查是否為掃描版，建議使用 OCR |
| 子 Agent 超時 | - | 增加 timeoutSeconds，或拆分任務 |
| 檔案不存在 | - | 檢查路徑，重新執行前置指令碼 |
| jq 解析失敗 | - | 檢查 JSON 格式，手動修復 metadata.json |
| OCR 識別失敗 | - | 檢查 tesseract 是否安裝，語言包是否存在 |
| 圖片上傳失敗 | - | 檢查圖片檔案是否存在，大小是否超過限制 |
重試機制示例：
# 飛書 API 呼叫重試
max_retries=3
retry_count=0
while [[ $retry_count -lt $max_retries ]]; do
result=$(feishu_doc action=upload_image ...)
if echo "$result" | grep -q '"success": true'; then
echo "✅ 上傳成功"
break
elif echo "$result" | grep -q "429"; then
retry_count=$((retry_count + 1))
echo "⚠️ API 限流，等待 10 秒後重試 ($retry_count/$max_retries)"
sleep 10
else
echo "❌ 上傳失敗：$result"
break
fi
done
if [[ $retry_count -eq $max_retries ]]; then
echo "❌ 達到最大重試次數，任務失敗"
# 寫入錯誤日誌
echo "錯誤型別：API 限流" >> "$PAPER_DIR/errors/vision.log"
echo "重試次數：$max_retries" >> "$PAPER_DIR/errors/vision.log"
echo "建議操作：等待 5 分鐘後重試，或聯絡使用者" >> "$PAPER_DIR/errors/vision.log"
fi子 Agent 職責說明
| 子 Agent | 職責 | 關鍵技能 | 進度日誌 |
|---|---|---|---|
| Reader | 長文本閱讀、總結生成 | 分段讀取、資訊提取、結構化輸出 | progress_reader.log |
| Vision | 圖片稽核、飛書上傳 | 圖片識別、upload_image、限流規避 |
progress_vision.log |
| Reviewer | 資料一致性核對 | 資料比對、格式檢查、報告生成 | progress/reviewer.log |
進度日誌檔案說明
每個子 Agent 執行時都會生成進度日誌檔案，便於除錯和審計：
進度日誌位置
| 檔案 | 說明 | 生成時機 |
|---|---|---|
$PAPER_DIR/progress/reader.log |
Reader 子 Agent 進度 | 閱讀論文時 |
$PAPER_DIR/progress/vision.log |
Vision 子 Agent 進度 | 上傳圖片時 |
$PAPER_DIR/progress/reviewer.log |
Reviewer 子 Agent 進度 | 稽核資料時 |
$PAPER_DIR/errors/<agent>.log |
錯誤報告 | 發生錯誤時 |
進度日誌格式
[YYYY-MM-DD HH:MM:SS] <Agent> 子 Agent 啟動
[YYYY-MM-DD HH:MM:SS] 開始 <任務描述>
[YYYY-MM-DD HH:MM:SS] ✅ 完成：<步驟 1>
[YYYY-MM-DD HH:MM:SS] ✅ 完成：<步驟 2>
[YYYY-MM-DD HH:MM:SS] ✅ <Agent> 任務完成
[YYYY-MM-DD HH:MM:SS] 輸出檔案：<檔案路徑>
[YYYY-MM-DD HH:MM:SS] 總耗時：X 分鐘錯誤報告格式
## 錯誤報告
**子 Agent**: <Agent 名稱>
**錯誤型別**: <錯誤型別>
**錯誤資訊**: <具體錯誤>
**發生時間**: YYYY-MM-DD HH:MM:SS
**重試次數**: X/3
### 建議操作
<主控 Agent 應該採取的行動>版本歷史
- v2.0.0 (2026-03-28)：重構為多 Agent 協作架構，新增防幻覺機制 + 飛書操作知識精簡
- v1.x：單 Agent 全流程（已廢棄）
附錄：改進的彙報模板
Reader 子 Agent 完成報告（詳細版）
## Reader 子 Agent 完成報告
**開始時間**: YYYY-MM-DD HH:MM
**完成時間**: YYYY-MM-DD HH:MM
**耗時**: X 分鐘
### 執行結果
- ✅ 成功生成 summary.md
### 輸出檔案
- `$PAPER_DIR/summary.md` (XXX KB, XXX 行)
- `$PAPER_DIR/progress/reader.log` (進度日誌)
### 論文關鍵資訊
- **研究型別**: <如 RCT、佇列研究等>
- **樣本量**: <如 2,069 人>
- **主要結局**: <如 問診時長減少 28.7%>
### 問題與備註
<如有問題，在此說明；如無問題，填寫"無">
### 詳細進度
| 步驟 | 狀態 | 耗時 |
|------|------|------|
| 讀取 paper.txt | ✅ 完成 | X 秒 |
| 提取研究背景 | ✅ 完成 | X 秒 |
| 提取研究設計 | ✅ 完成 | X 秒 |
| 提取核心結果 | ✅ 完成 | X 秒 |
| 生成 summary.md | ✅ 完成 | X 秒 |Vision 子 Agent 完成報告（詳細版）
## Vision 子 Agent 完成報告
**開始時間**: YYYY-MM-DD HH:MM
**完成時間**: YYYY-MM-DD HH:MM
**耗時**: X 分鐘
### 執行結果
- ✅ 成功上傳 X/Y 張圖片
### 圖片上傳清單
| Figure | file_token | 大小 | 插入位置 | 狀態 |
|--------|------------|------|----------|------|
| Fig. 1 | `xxx...` | XXX KB | 4.1 章節後 | ✅ |
### 輸出檔案
- `$PAPER_DIR/progress/vision.log` (進度日誌)
### 問題與備註
<如有問題，在此說明>
### 詳細進度
| 步驟 | 狀態 | 耗時 |
|------|------|------|
| 獲取 blocks 列表 | ✅ 完成 | X 秒 |
| 上傳 Fig. 1 | ✅ 完成 | X 秒 |
| 上傳 Fig. 2 | ✅ 完成 | X 秒 |
| 上傳 Fig. 3 | ✅ 完成 | X 秒 |
| 驗證圖片數量 | ✅ 完成 | X 秒 |Reviewer 子 Agent 完成報告（詳細版）
## Reviewer 子 Agent 完成報告
**開始時間**: YYYY-MM-DD HH:MM
**完成時間**: YYYY-MM-DD HH:MM
**耗時**: X 分鐘
**稽核模型**: <模型名稱>
### 執行結果
- ✅ 稽核通過 / ⚠️ 需要修改
### 稽核統計
- 一致的內容：X 處
- 需要修改的內容：Y 處
- 格式問題：Z 處
### 輸出檔案
- `$PAPER_DIR/progress/reviewer.log` (進度日誌)
- `$PAPER_DIR/audit_report.md` (稽核報告全文)
### 關鍵問題
<如有嚴重問題，在此說明>
### 修改建議清單
1. <具體修改建議 1>
2. <具體修改建議 2>
...
### 詳細進度
| 步驟 | 狀態 | 耗時 |
|------|------|------|
| 讀取原始資料 | ✅ 完成 | X 秒 |
| 讀取總結內容 | ✅ 完成 | X 秒 |
| 資料一致性核對 | ✅ 完成 | X 秒 |
| 格式檢查 | ✅ 完成 | X 秒 |
| 生成稽核報告 | ✅ 完成 | X 秒 |附錄：關鍵步驟確認函式
# 關鍵步驟確認函式
confirm_step() {
local step_name=$1
local log_file=$2
log_master "🔍 確認步驟：$step_name"
if [[ ! -f "$log_file" ]]; then
log_master "❌ 日誌檔案不存在：$log_file"
return 1
fi
# 檢查是否有 ERROR
if grep -q "\[ERROR\]" "$log_file"; then
log_master "❌ 檢測到錯誤，檢視錯誤日誌"
cat "$log_file" | grep "\[ERROR\]"
return 1
fi
# 檢查是否完成
if grep -q "✅ 完成\|\[SUCCESS\]" "$log_file"; then
log_master "✅ 步驟確認成功：$step_name"
return 0
else
log_master "⚠️ 步驟未完成：$step_name"
return 1
fi
}
# 使用示例（在每個階段完成後呼叫）
# confirm_step "Reader 完成" "$PAPER_DIR/logs/reader.log" || exit 1
# confirm_step "Vision 完成" "$PAPER_DIR/logs/vision.log" || exit 1
# confirm_step "Reviewer 完成" "$PAPER_DIR/logs/reviewer.log" || exit 1附錄：Vision 模型自動識別
工作原理
技能會自動從 ~/.openclaw/openclaw.json 中查詢支援圖片輸入的模型：
# 自動識別邏輯
VISION_MODEL=$(jq -r '
.models.providers | to_entries[] |
.value.models[] |
select(.input and (.input | index("image"))) |
.id |
first
' "~/.openclaw/openclaw.json")識別邏輯：
- 遍歷所有 provider 的 models
- 查詢
input欄位包含"image"的模型 - 使用找到的第一個模型
- 如果找不到，回退到
model.primary
如何判斷模型是否支援圖片：
檢視 models.providers[].models[] 中的 input 欄位：
{
"models": {
"providers": {
"qwencode": {
"models": [
{
"id": "qwen3.5-plus",
"name": "Qwen3.5 Plus",
"input": ["text", "image"] ← 支援圖片
}
]
}
}
}
}優點：
- ✅ 無需手動配置
- ✅ 自動選擇支援圖片的模型
- ✅ 向後相容（無配置也能用）
- ✅ 符合"約定優於配置"原則
版本歷史
- v2.0.0 (2026-03-28)：重構為多 Agent 協作架構，新增防幻覺機制 + 飛書操作知識精簡
- 完全重寫 SKILL.md，從單 Agent 改為多 Agent 協作（Reader/Vision/Reviewer）
- 新增 5 個核心指令碼（extract_metadata.sh, check_duplicate.sh, extract_pdf_text.sh, locate_figures.sh, merge_supplement.sh）
- 新增防幻覺機制：強制注入原始資料到 Reviewer 子 Agent
- 新增標準化彙報機制（進度日誌 + 完成報告 + 錯誤報告）
- 精簡飛書操作知識：刪除通用內容，保留本業務特有的 6 大核心原則
- v1.x：單 Agent 全流程（已廢棄）
🤖 AI 評測
這是一款高質量的論文總結工具，能夠自動讀取 PDF 論文、提取關鍵資訊、生成結構清晰的總結文件，並支援將圖表圖片上傳到飛書文件。採用了多 Agent 協作模式，讓不同 Agent 分別負責閱讀理解、圖片處理、內容稽核，流程嚴謹且不容易出錯，還有人工確認環節把關質量。優點是總結規範、資料準確、帶圖片，缺點是依賴外部工具處理 PDF，對掃描版論文效果可能有限。
📊 多維度評分
適應性4.6
規範性4.5
有效性4.5
可靠性4.4
可信度5
📁 包含檔案 (8 個)
📄 SKILL.md
42.5 KB
📄 _meta.json
148 B
📄 references/summary_template.md
4.1 KB
📄 scripts/check_duplicate.sh
5.4 KB
📄 scripts/extract_metadata.sh
2.9 KB
📄 scripts/extract_pdf_text.sh
1.4 KB
📄 scripts/locate_figures.sh
4.6 KB
📄 scripts/merge_supplement.sh
2.6 KB
