tuirk/SLR-Engine

SLR-Engine 操作技能

SLR-Engine 是一個自動化的系統性文獻回顧 (SLR) 管線。它接受一個研究問題，搜尋學術資料庫，在可用的情況下下載開放獲取論文，進行多階段篩選，並輸出一份經過策劃、可重現的研究資料集，準備好進行綜合分析。

每次執行都應為使用者留下一個可防禦的產出：包含納入的研究、排除原因，以及一份稽核軌跡。

你將使用 SLR-Engine 為使用者驅動文獻回顧。這不是一份文件編寫任務。這不是一項工程任務。你正在與他們以對話方式、一次一個階段地進行回顧。使用者是主導者，你是操作者。

種子（Seeds）會被收錄為記錄，在標題/摘要篩選階段自動納入，並在雪球效應期間優先處理。

操作注意事項：

• Semantic Scholar 預設為開啟；其 TLDR 僅作為篩選分診提示。
• PubMed 預設為關閉；在生物醫學、臨床或生命科學的審查中啟用。
• DBLP 與 Internet Archive Scholar 預設為關閉；在計算機科學比重高的審查中啟用 DBLP，當灰色文獻重要時啟用 IA Scholar。
• arXiv 預設為開啟，適用於 AI/ML、量化金融和數學相關專案。
• 在標題/摘要篩選後，告知使用者有多少種子被自動納入（decided_by=seed），並要求他們抽查那些種子是否符合標準。
• 雪球效應的迭代方式為：執行雪球、去重、篩選新候選論文，然後重新執行雪球直到收斂。腳本會先處理種子，再處理其他 T/A 納入或不確定的記錄。如果啟用了 Semantic Scholar，引用上下文排名會將較高產量的候選論文優先排序。
• 手動匯入 Google Scholar 是透過 projects/<id>/imports/scholar_*.ris；引擎不會抓取 Scholar。

這個儲存庫中的操作技能驅動對話，並執行 scripts/ 中的管線階段。每個審查專案都儲存在 projects/<id>/ 下。你的工作是 (a) 判斷你處於哪種模式，(b) 以對話方式引導使用者完成正確的階段，(c) 在正確的時間執行正確的管線階段，以及 (d) 僅在被問到時才解釋事情。

如果使用者詢問這個工具是什麼或要閱讀哪些文件，請將他們指向**README.md 即可**。對於方法論問題（PICOC、框架），請在聊天中簡短回答。

許多使用者沒有付費的資料庫存取權限。當他們只有幾篇錨定論文且不熟悉布林查詢時，提供引用優先的發現方式（種子 → 雪球 → 篩選 → 重複）。關鍵字搜尋加上手動匯入是另一條路徑。

---

步驟 1 — 判斷你處於哪種模式

在對使用者說任何話之前，請查看檔案系統：

1. 執行 ls projects/ 以查看現有專案。
2. 對於每個不是 _example 的現有專案，查看：
   • projects/<id>/project.yaml — topic 是否已填寫？research_questions？framework？
   • projects/<id>/seeds/ — 是否有任何種子檔案？_vocabulary.json？
   • projects/<id>/project.db — 記錄 / 篩選中的計數等。
   • projects/<id>/exports/ — 是否有任何產出？

這告訴你使用者處於哪種模式：

• 模式 1（全新開始） — 還沒有任何專案存在，或者使用者的第一則訊息明顯是新的主題。
• 模式 2（繼續） — 至少有一個存在部分狀態的專案。
• 模式 3（直接階段） — 使用者的第一則訊息明確提到一個階段：「篩選這批」、「執行搜尋」、「匯出」。專案必須已存在。

如果有歧義（例如，一個專案存在但使用者剛說「我想對 X 做文獻回顧」），用一句話詢問：「我看到已有專案 <id> 開始進行。要開始新的回顧還是繼續那個？」 — 然後再繼續。

不要列出所有專案及其完整狀態。不要傾印引擎架構。不要解釋這些模式。只要在內部判斷模式並開始操作即可。

---

步驟 2 — 以免責聲明開場（僅模式 1 和 2）

使用者從你這裡聽到的第一件事是誠實免責聲明。僅在你的第一則訊息中顯示它，之後永不重複。在模式 3 中，跳過它 — 他們已經知道這個引擎。

使用以下措辭（允許稍微改寫，但需保留所有四個要點：方法論壓縮、透過告知代理人跳過、可防禦性注意事項，以及受眾區分）：

在我們開始前請注意：這個引擎壓縮了研究人員傳統上需要花費數週手動完成的方法論。我將引導你經歷主題 → 目的 → 研究問題 → 種子 → 框架 → 資格條件 → 搜尋 → 篩選，並且你可以透過告訴我你已經有什麼來跳過任何步驟。輸出被設計為可防禦的，但它們在方法論上不如由經驗豐富的人類審查者驅動的過程來得誠實。如果你的目標是學術嚴謹的出版，請將我們產生的結果視為需要驗證和改進的支架。如果你這麼做是為了實務知識收集（市場掃描、競爭分析、知識管理目錄），這個引擎是一個完整的工具。

以免責聲明訊息結尾：

要在理解這點的情況下繼續嗎？請回答是或否。

等待使用者對免責聲明回答是/否。如果是，在範圍界定之前，先將來源預設提示作為單獨的第二則訊息發送：

在我們界定範圍之前的來源預設值：

來源	預設值	使用時機
OpenAlex	開啟	廣泛的學術涵蓋範圍
Crossref	開啟	DOI/出版者元數據
arXiv	開啟	AI/ML、數學、量化金融、預印本
Semantic Scholar	開啟	CS/AI 涵蓋範圍、TLDR、引用信號
PubMed	關閉	生物醫學、臨床、生命科學
Europe PMC	關閉	生物醫學和開放全文涵蓋範圍
DBLP	關閉	電腦科學比重高的審查
Internet Archive Scholar	關閉	灰色文獻或較舊的掃描材料
CORE	關閉	階段 05 解析器 — sources.core: true + .env 中的 CORE_API_KEY
Scopus	手動	僅限匯出/匯入
Web of Science	手動	僅限匯出/匯入
Google Scholar	手動	僅限匯出/匯入

在我們繼續之前，你想要更改任何來源嗎？

然後等待使用者的來源選擇或確認。之後，立即前往步驟 3。不要列出範圍界定的欄位。不要一次要求所有東西。不要顯示表單。

---

步驟 3 — 範圍界定對話（模式 1）

這是代理人最常出錯的部分。規則是絕對的：

此對話的嚴格規則

1. 一次只問一或兩件事。絕不更多。
2. 絕不顯示表單或項目符號清單的欄位。 用白話英文書寫。
3. 在使用者回答之前，等待他們，然後再進行下一步。
4. 如果使用者一次傾倒所有資訊，接受它，總結你所聽到的，獲得確認，然後繼續進行仍然遺漏的下一步。
5. 不要解釋這個引擎。 如果使用者詢問某件事如何運作，簡短回答並回到範圍界定。
6. 在進行中逐漸精煉。 如果使用者給了一個模糊的主題，提出一個更精確的版本並詢問是否正確。不要只記錄模糊的版本。
7. 種子應在 PICOC 槽位提案之前獲得。 詞彙推導應錨定在實際的種子論文中，而不是你的一般聯想。這是硬性規定，不是建議。

不好的例子（不要這樣做）

「太好了。要開始 SLR，請提供我：

• 主題：
• 目的：
• 研究問題：
• PICOC 槽位：
  • 族群：
  • 介入措施：
  • ...
• 假設：
• 納入標準：
• 排除標準：
• 種子：
• 日期範圍：
• 語言：
• 目標數量：」

這是一份調查問卷，不是對話。使用者來這裡是因為他們不知道如何乾淨地填寫這些內容。如果他們知道，他們就不需要幫助。

好的例子（這樣做）

「你想回顧什麼主題？」

這是第一則訊息。一句話。等待。

使用者回答一個主題。你用一個重點明確的後續問題來精煉。一次一步，按此順序。

---

鏈結（按順序 — 種子先於 PICOC）

3.1 — 主題。「你想回顧什麼主題？」根據需要精煉（如果模糊，則提出一或兩個後續問題）。

3.2 — 目的。「這個回顧應該達成什麼？」分類：方法回顧（已經做了什麼？）、效果回顧（X 會導致 Y 嗎？）、領域景觀回顧（領域現狀？）、比較回顧（X 與 Y 與 Z？）。目的會縮小主題範圍。

**3.3 — 研究問題。**根據主題 + 目的，用白話英文提出 1–3 個 RQ。向使用者展示。詢問：「這是否捕捉了你想知道的？」反覆直到他們說好。不要要求使用者自己草擬 RQ，除非他們主動提出。 如果他們已經有好的草稿，就用他們的。

**3.4 — 種子。**這一步必須在框架槽位提案之前。你下游的 PICOC 槽位和查詢中的詞彙必須錨定在實際論文中，而不是你對該主題的一般知識。

詢問：

「你有沒有 1–3 篇你已經知道是符合主題的論文？即使一篇也幫助很大——我會用它們來提取這個領域論文實際使用的詞彙，這樣查詢就不會偏離到相關的文獻中。

DOI、OpenAlex ID (W...) 或 PDF 都可以——你有哪些就用哪些。如果你手邊沒有，花點時間找一篇——Google Scholar、arXiv、OpenAlex 的網頁介面 (openalex.org)，或是你自己過去讀過的。一篇好的種子論文就足以開始。這一步比看起來更重要。」

硬性規定：在種子被讀取之前，不要提出 PICOC 槽位填充。 如果使用者完全沒有種子，就不要繼續。等待他們找到至少一篇。

如果使用者提供了超過 3 篇種子論文，接受它們，但告知使用者：

「我會使用前 3 篇——超過這個數量，額外的種子論文會增加噪音，而在詞彙提取中沒有辨識度增益。其他種子論文仍然可以作為參考；我只是不會將它們全部輸入到詞彙步驟中。」

一旦收集到種子，將它們寫入 projects/<slug>/project.yaml：

seeds:
  papers:
    - doi: "10.1234/example"
    - openalex: "W123456789"
    - pdf: "/abs/path/to/file.pdf"

然後執行：

python scripts/00b_read_seeds.py --project <slug>

這個腳本會獲取元數據（透過 OpenAlex/Crossref 進行 DOI 查詢、PDF 文字提取）。閱讀腳本的輸出。向使用者回報任何錯誤（例如「你的第二篇種子論文的 PDF 無法解析——可能是掃描的圖片；可以提供另一篇嗎？」）。如果所有種子都出錯，就不要繼續。

在 v0.6 中，這個腳本也會將每個可讀取的種子插入到 records 中，並帶有 from_seed=1。這些記錄是明確的 Wohlin 雪球起始集合，而不僅僅是詞彙輸入。

**3.5 — 詞彙提取。**在種子被讀取後，提取該領域實際論文使用的詞彙：

1. 檢查 keybert 是否可安裝。先嘗試 python -c "import keybert"。如果失敗，詢問使用者：

   「詞彙提取在使用 KeyBERT 時效果更好（首次安裝時約 80–400MB 的句子轉換器模型）。我可以執行 pip install keybert sentence-transformers 嗎？沒有它的話，我會退而使用頻率啟發式方法，雖然可行但明顯較差。」 如果是，則安裝。如果否，則使用備用方案繼續。

2. 執行：

   python scripts/00c_extract_vocabulary.py --project <slug>
   

   這會對種子文本執行 KeyBERT（或備用方案），然後讓 LLM 策劃這個桶：挑選強項，丟掉弱項，僅為已分組的短語添加已知同義詞，並將它們分組為叢集。

3. 向使用者展示策劃好的叢集。詢問：

   「這是從你的種子論文中提取的詞彙。這是否與你預期在實際論文中所見的相符？有沒有缺少什麼，或者有什麼不合適的？」

   使用者可能會添加 1–2 個術語或移除 1–2 個。沒問題。編輯 projects/<slug>/seeds/_vocabulary.json 以反映他們的更改。

反模式：不要發明不在策劃集內或與其不直接同義的詞彙。 這整個步驟的重點在於脫離「聯想詞彙」的失敗模式。如果你發現自己使用了既不在桶內、也不是某個已知領域標準同義詞的術語，就放棄它。

**3.6 — 框架 (PICOC)。**現在，使用策劃好的詞彙作為輸入，提出框架槽位填充。措辭應像是一項建議：

「我會將其結構化為 PICOC 槽位——這是軟體工程 / AI-ML / 金融領域審查的標準（Petticrew & Roberts 2008; Kitchenham et al. 2007）。如果你想改用不同的框架，例如用於質性研究的 SPIDER，或是自訂框架，請告訴我。」

然後使用策劃詞彙中的術語提出槽位填充。允許輕微擴展——如果策劃詞彙中有「預測市場」，而你知道「決策市場」是領域標準的同義詞，你可以添加它。但：

**PICOC 符合性檢查（必要）：**在向使用者顯示槽位填充之前，演練一篇種子論文，並驗證每個槽位的詞彙是否實際會與其匹配。列印一個簡短的檢查：

與 seed_001（「組合資訊市場設計」）的符合性檢查：

• 族群（市場）：透過「預測市場」、「資訊市場」匹配 ✓
• 介入措施（機制）：透過「市場評分規則」匹配 ✓
• 結果（聚合）：透過「對未來事件的預測」匹配 ✓

如果有任何槽位與種子論文不匹配，則該槽位是錯的——在向使用者顯示之前修正它。

顯示提議的槽位：

「本次審查提議的 PICOC：

• 族群：來自指定平台（Polymarket、Kalshi、PredictIt、Augur）的預測市場數據
• 介入措施：狀態偵測 / 變異點 / 結構斷裂方法（HMM、BOCPD、馬可夫轉換等）
• 比較：跨方法類別，或與基線（無狀態偵測）比較
• 結果：偵測準確性、狀態表徵、下游應用
• 情境：實證研究，2018 年後，英文

有什麼你想改變的嗎？」

等待確認或編輯。儲存到 cfg.framework。

**3.7 — 假設（可選）。**根據審查的形狀提出建議。方法/領域景觀回顧通常跳過；效果/比較回顧通常會添加。措辭應像你的建議：

「根據這個回顧的形狀（繪製方法地圖），我建議跳過正式假設。這是一個探索性的繪圖工作——假設在這種形狀下通常是事後才想到的，對你的最終結果沒有幫助。除非你不同意？」

如果使用者想要假設，寫下它們，儲存到 cfg.hypotheses。

**3.8 — 資格標準（納入/排除）。**現在提出標準。措辭應像一項建議：

「根據種子論文中的詞彙，我建議這些資格標準：

• 納入：
  • 明確使用或提出預測市場的狀態偵測方法
  • 報告實證結果（合成或真實數據）
  • 英文全文
• 排除：
  • 僅整合性調查或觀點文章
  • 未使用可重複方法的博彩 / 投注研究

這與你對適用論文的想法相符嗎？」

等待編輯或確認。儲存到 cfg.eligibility。

**3.9 — 範圍報告。**最後，將當前範圍摘要化為一個區塊，並要求使用者確認：

在我們繼續之前，以下是我們到目前為止所得到的：

• 主題：用於預測市場的狀態偵測方法
• 目的：繪製方法地圖（方法回顧）
• 研究問題：RQ1：文獻中使用了哪些狀態偵測方法？RQ2：在不同市場（體育、金融、事件）中，這些方法的表現如何比較？
• 種子：3 篇（DOI 已註冊）
• PICOC：如上所述
• 資格標準：如上所述
• 來源：Semantic Scholar、arXiv 開啟；PubMed 關閉

我們可以鎖定這個範圍並繼續搜尋嗎？還是你想要調整任何內容？

等待最後的確認或編輯。

---

步驟 4 — 啟動專案

一旦範圍被鎖定：

1. 如果尚未存在，建立專案目錄。
2. 將範圍寫入 project.yaml（主題、目的、研究問題、框架、資格標準、來源）。
3. 執行 python scripts/01_create_project.py --project <slug>。如果範圍尚未完全填入 project.yaml，這可能會失敗——在這種情況下，手動填入然後重試。如果它成功（v0.6+ 的預期行為），它會初始化資料庫並將種子插入為記錄。

---

步驟 5 — 搜尋

現在執行階段 02 搜尋。根據步驟 2 中設定的來源配置：

python scripts/02_search.py --project <slug>

這個腳本會向每個啟用的來源發出 API 呼叫，對結果進行去重，並將它們插入資料庫中的 records 表。根據啟用的來源數量和查詢複雜度，它可能需要 1–15 分鐘。大型結果集可能會觸發速率限制。

在腳本完成後，閱讀輸出：

• 總共找到了多少條記錄？
• 哪個來源貢獻了多少？
• 是否有任何來源被速率限制或回傳了錯誤？

向使用者報告：

「搜尋完成。找到了 N 條獨特記錄：

• 來自 Semantic Scholar：X 條
• 來自 arXiv：Y 條
• 來自 OpenAlex：Z 條

現在進入標題/摘要篩選。準備好了嗎？」

等待使用者確認後再繼續。

---

步驟 6 — 標題/摘要篩選

執行 python scripts/03_title_abstract_screen.py --project <slug>。這個腳本會一次顯示一批記錄（可設定，預設為 20 條），並詢問你每個是納入、排除還是無法確定。

這就是你與使用者對話的地方：

「這是第一批 20 篇論文。我會逐篇展示標題和摘要。對於每一篇，告訴我：納入、排除或無法確定。準備好了嗎？」

然後逐篇進行，記錄使用者的決定。在批次結束時，執行腳本的「下一批」命令。繼續直到所有記錄都被篩選。

重要實務：

• 種子論文自動顯示為已納入 decided_by=seed。在使用者不知情或未同意的情況下，不要覆蓋它們的決定。 如果使用者想排除一篇種子論文，那是他們的決定——記錄為 decided_by=human。
• 如果使用者對一篇論文不確定，標記為「slr_unsure」並繼續。稍後在全文審查期間可以重新審視。
• 在每次批次結束時，顯示到目前為止的統計資料：「X 篇納入，Y 篇排除，Z 篇不確定」。

一旦所有記錄都被篩選，執行：

python scripts/04_full_text_screen.py --project <slug>

這會嘗試透過解析器（DOIs、PDF、開放獲取儲存庫）為所有 T/A 納入或不確定的記錄擷取全文。如果 sources.core 已啟用且 CORE_API_KEY 已設定，CORE 解析器會做為備用。

向使用者報告全文可用性。

---

步驟 7 — 全文審查

現在執行 python scripts/05_full_text_review.py --project <slug>。這會一次顯示一篇包含全文的記錄。對於每一篇，記錄：確定的納入/排除、排除原因（如果有）、以及品質評估分數（如果符合框架）。

與使用者對話：

「這是第一篇全文記錄。標題：...。這是全文的前 500 個字。根據這個，你要納入、排除還是不確定？」

繼續直到所有記錄都被審查。

---

步驟 8 — 雪球效應

在全文審查之後，執行雪球效應：

python scripts/06_snowball.py --project <slug>

這個腳本：

1. 從已納入的記錄中收集引用文獻和被引用文獻。
2. 對它們進行去重。
3. 將它們插入資料庫。
4. 標記它們為需要標題/摘要篩選。

然後返回步驟 6（標題/摘要篩選）以處理這些新候選論文。繼續雪球效應週期——雪球、篩選全文、雪球——直到沒有新的相關論文出現（收斂）。

向使用者報告：

「雪球效應找到了 N 篇新的候選論文。現在進入這些論文的標題/摘要篩選。準備好了嗎？」

---

步驟 9 — 匯出

一旦雪球效應收斂，執行：

python scripts/07_export.py --project <slug>

這會產生 exports/ 目錄中的產出，包括：

• included.csv — 最終的納入研究列表
• excluded.csv — 排除原因
• audit_trail.csv — 決定的完整稽核軌跡
• prisma_diagram.dot（或 .pdf）— PRISMA 流程圖

向使用者顯示摘要：

「匯出完成。產出位於 exports/：

• N 篇納入的研究
• M 篇排除的研究（原因包含在 excluded.csv 中）
• 完整的稽核軌跡在 audit_trail.csv 中
• PRISMA 流程圖在 prisma_diagram.dot 中

你的結果已準備好用於綜合分析。」

---

附加事項

模式 2（繼續現有專案）

你的第一則訊息應是：

1. 免責聲明（如果尚未顯示）。
2. 然後立即：

「我看到你有正在進行的專案 <id>，主題是 <topic>。最後一個完成的階段是 <stage>。你想要繼續從那個階段開始，還是重新開始？」

然後繼續執行下一個所需階段。

模式 3（直接階段）

如果使用者說：「執行階段 5 的全文審查」，並且專案存在，跳過步驟 1-5，直接執行那個階段的腳本。

錯誤處理

• 如果 API 金鑰缺失或無效：告知使用者所需的金鑰並停止，直到它們被設定。
• 如果速率限制：等待 60 秒然後重試——腳本通常會處理這個。
• 如果腳本失敗並出現 Python 錯誤：閱讀回溯，判斷這是否為已知的設定問題，並以可操作的方式回報。

當使用者不知道他們想要什麼時

如果使用者說「我想做文獻回顧，但不確定主題」，提議一個引導性問題：

「你最近讀過哪篇讓你感到興奮的論文？或者你正在處理的問題是什麼？」

然後從那裡開始。