opendraft 是做什麼的？
將一個主題轉化為一份具有真實文獻基礎的完整論文。
從 OpenDraft (github.com/federicodeponte/opendraft, MIT 授權) 移植而來，原專案以託管引擎運行。在此版本中，引擎就是您：十八個階段，每個階段對應 agents/ 中的一個提示，外加五個腳本，用於處理語言模型不應手動執行的部分。
您就是模型。 無需密鑰、無需服務、無需帳戶。唯一的網路呼叫是 Crossref、OpenAlex 和 DataCite，這些均為開放端點。
單一指令
撰寫一篇關於 <主題> 的論文
以下所有步驟均由此指令衍生。請勿要求使用者自行運行各階段；由您來執行。
事先詢問四件事
在第五階段之前，如果使用者尚未提供，請詢問：
- 目標期刊，或「無，一般學術」。
- 總字數限制。
- 引文風格，從
references/citation-styles.md中的六種風格中選擇一種。 - 文件類型，從
references/paper-types.md中的類型中選擇一種。
這四個問題應在一則訊息中提出，而非進行面試，並且這些是管道會詢問的唯一問題。其他所有事項均由管道自行決定。
之所以詢問，是因為猜測的成本會在最後階段顯現，且無法在該處補救。一個字數上限嚴格（例如 150 字摘要）的期刊，其規則必須在第六階段或更早執行：到了第 17 階段撰寫摘要時，每個章節所依據的字數預算已無法更改。在起始階段而非第六階段選擇引文風格，意味著整個草稿是在錯誤的標記密度下撰寫的。
如果使用者拒絕回答，或表示「你選」，則使用 references/paper-types.md 中的預設值，將其寫入第六階段的期刊格式區塊，並用一行文字說明使用了哪些預設值。切勿基於未告知使用者的假設繼續進行。
腳本擁有的四件事，您不得插手
語言模型擅長判斷，但不擅長記帳。這種分工是刻意設計的，偏離此分工將導致輸出錯誤。以下每一項都由一個腳本強制執行，若不符合則會以非零退出碼終止，因此這些都不是主觀判斷。
切勿手動撰寫已渲染的引文標記。 不是 [3]，也不是 (Smith, 2020)。在起草過程中，您應在提出主張的準確位置內聯寫入 {cite_<doi>}。scripts/citations.py compile 會將這些標記轉換為實際引用，並透過字典查詢生成參考文獻。這是確定性的，因此散文與參考文獻之間的映射是機械性的，而非憑記憶。
切勿為無法支持的論點發明來源。 如果一個論點是真實的，但您找不到來源，請寫下 {cite_MISSING: 對該論點的簡短描述} 並繼續進行。compile 會拒絕渲染此標記，將其命名，並以非零退出碼終止，而 integrity.py 會將其視為嚴重問題，因此它無法出現在完成的論文中。這就是重點：這不是為了讓您將未經證實的論點交付出去，而是為了在起草過程中保持誠實，而不是悄悄刪除該論點或將其附在一個虛構的 DOI 上。在閘門檢查之前，透過使用 sources.py find 找到真實來源，或故意刪除該論點，來清除每個此類標記。
切勿手動將章節合併到草稿中。 scripts/assemble.py 會執行此操作，按數字順序合併，並拒絕將任何非編號章節的內容拼接到論文中。手動合併若遺漏某個章節，這種失敗在讀者發現之前不會被注意到。
切勿憑視覺判斷論文內部是否一致。 scripts/integrity.py 會進行檢查並以非零退出碼終止。請運行它並讀取退出碼。
設定
mkdir -p research sections review
無需 API 密鑰、無需帳戶、無需安裝步驟：這些腳本僅依賴 Python 標準庫。有一個可選的環境變數，並且這是此處任何腳本唯一會讀取的變數。將 OPENDRAFT_CONTACT_EMAIL 設置為您自己的電子郵件地址，sources.py 會將其附加到 User-Agent 中，這會將 Crossref 請求移至禮貌池，並獲得更好的速率限制。如果不設置，每個階段仍可正常運行；沒有內置地址，因為發貨的預設值會將所有安裝者合併為一個身份，並將其速率限制問題路由到陌生人的收件箱。
管道會寫入固定路徑，每個階段會讀取之前階段寫入的內容。這些路徑是階段之間的契約：
research/sources.md research/sources.json research/summaries.md
research/gaps.md research/citations.json research/citation-notes.md
outline.md outline_formatted.md
sections/*.md full_draft.md final.md
review/thread.md review/narrator.md review/skeptic.md
review/verifier.md review/referee.md review/voice.md
review/entropy.md review/polish.md
關於這些路徑的四條規則，每一條都曾被違反過：
sections/僅存放論文章節，不存放其他內容。 其中的每個檔案都會被scripts/assemble.py拼接到完成的論文中。若將階段報告存放在此處，最終會出現在某人的論文中。報告應放在review/中。research/sources.json是機器輸入，research/sources.md是人類閱讀。 第一階段會同時寫入這兩個檔案。citations.py build讀取的是 JSON 檔案。- 切勿手動寫入
research/citations.json。 它由citations.py build構建，並且只能透過重新運行build來更改。那些腳本無法處理的判斷（例如沒有 DOI 的來源、需要審查的條目、無法轉換為佔位符的提及）應放入research/citation-notes.md，這是散文格式，永遠不會被腳本讀取。手動編輯資料庫會導致verified標誌被翻轉以通過閘門，這會使未解析的 DOI 看起來像已檢查過，最終出現在參考文獻中。 - 在 9.5 階段之後，
full_draft.md是唯一的草稿。 下游的任何內容都不會再讀取sections/*.md，因此在組裝後編輯章節檔案不會產生任何效果，並會悄悄丟失編輯內容。
管道
按順序運行。除一個階段外，每個階段都是 agents/ 中的一個檔案：讀取該檔案，執行其指示，寫入其指定的輸出，然後繼續。例外是 9.5 階段，這是一個需要您運行的腳本。即使主題看起來很簡單，也不得跳過任何階段。
| # | 階段 | 代理檔案或腳本 | 寫入內容 |
|---|---|---|---|
| 1 | 尋找來源 | agents/01-scout.md | research/sources.md, research/sources.json |
| 2 | 閱讀並總結 | agents/02-scribe.md | research/summaries.md |
| 3 | 尋找值得撰寫的知識缺口 | agents/03-signal.md | research/gaps.md |
| 4 | 建立引文資料庫 | agents/04-citation-manager.md | research/citations.json, research/citation-notes.md |
| 5 | 大綱論證 | agents/05-architect.md | outline.md |
| 6 | 應用期刊格式與字數預算 | agents/06-formatter.md | outline_formatted.md |
| 7 | 撰寫每個章節 | agents/07-crafter.md | sections/*.md, 附加到 research/gaps.md |
| 8 | 檢查跨章節一致性 | agents/08-thread.md | 修正 sections/*.md, review/thread.md |
| 9 | 統一語調 | agents/09-narrator.md | 修正 sections/*.md, review/narrator.md |
| 9.5 | 將章節組裝成一份草稿 | scripts/assemble.py | full_draft.md |
| 10 | 攻擊論證 | agents/10-skeptic.md | review/skeptic.md, 然後修正 |
| 11 | 根據來源檢查論點 | agents/11-verifier.md | review/verifier.md, 然後修正 |
| 12 | 模擬同儕審查 | agents/12-referee.md | review/referee.md, 然後修正 |
| 13 | 匹配作者語調（可選） | agents/13-voice.md | 修正 full_draft.md, review/voice.md |
| 14 | 變化散文節奏 | agents/14-entropy.md | 修正 full_draft.md, review/entropy.md |
| 15 | 語法與最終潤飾 | agents/15-polish.md | full_draft.md, review/polish.md |
| 16 | 添加附錄（可選） | agents/16-enhancer.md | full_draft.md |
| 17 | 撰寫摘要 | agents/17-abstract.md | 預先附加到 full_draft.md |
| 18 | 撰寫標題 | agents/18-titlemaker.md | 預先附加到 full_draft.md |
第 7 階段針對每個章節運行一次，而非整個論文。第 10 到 12 階段會產生問題列表；無人應用的問題列表等同於無操作，因此請應用修正並重新運行該階段，直到不再有嚴重問題為止。
第 12 階段有數字依據，而非感覺。當一次新的運行報告零個嚴重問題且總體平均分數至少達到 3.0 分（滿分 5 分），且沒有任何單一維度低於 3 分（除非您在 review/referee.md 中記錄原因）時，即可停止。"足夠好可以寄出"並非停止條件，因為要求模型判斷自己的草稿時，它總會在第三次迭代時認為足夠好。
第 13 階段是唯一一個輸入內容永遠不會由管道產生的階段。它會將草稿與作者自己的散文進行匹配，並從工作目錄中的 samples/ 目錄讀取該散文：兩到三篇先前的論文、章節或長篇文章，格式為 .md 或 .txt。沒有內容會創建該目錄，也沒有內容會要求您提供它，因此從未創建該目錄的運行會乾淨地跳過第 13 階段，這是正常結果而非失敗。如果您希望論文看起來像自己寫的，請在運行前將自己的作品放入該目錄。
第 9.5 階段被編號為半個步驟，因為它是一個腳本而非代理提示，並且為了使十八個代理階段的編號保持不變。它不是可選的。第 1 到 9 階段作用於 sections/*.md；第 10 到 18 階段作用於 full_draft.md；除了以下指令外，沒有其他內容會產生該檔案：
python3 scripts/assemble.py sections -o full_draft.md
它會按數字順序合併章節檔案，拒絕包含任何非編號章節的檔案，並在出現編號間隙、重複編號或空目錄時以非零退出碼終止。使用 --check 可以報告它將執行的操作而不實際寫入。
它還會跳過名稱中包含 report、review、notes、checklist 或 log 的任何編號檔案，這是防止過時的階段報告最終出現在論文中的機制。這是一個檔案名稱啟發式規則，因此有一個明顯的邊緣情況：名為 "Review of the literature" 的真實章節會被跳過，您只會在標準輸出中看到一行 "Skipped"，而不是錯誤。請將該章節命名為 related-work 或 literature。請閱讀跳過行；一個在此處消失的章節會靜默消失。
在 full_draft.md 已存在的情況下重新運行需要使用 --force，而 --force 會丟棄第 10 階段及之後對草稿所做的所有編輯，因此僅在您有意從章節重新開始時才重新組裝。
規模
根據要求匹配管道。階段相同；深度不同。
- 短文，1,500 到 3,000 字。 第 1 到 7 階段，然後是 9.5、10、11、15 階段。十到十五個來源。
- 完整論文，預設值。 所有十八個階段，加上 9.5。二十五到五十個來源，或者當論文是文獻綜述時，五十個或更多來源，此時其自身的下限（
references/paper-types.md）適用。 - 論文章節或長篇綜述。 所有十八個階段，加上 9.5，來源數量在五十個或更多，並且第 7 階段針對每個子章節而非每個章節運行一次。
第 9.5 階段出現在上述每個列表中。沒有任何規模的論文可以自行組裝。
兩個參考檔案
references/paper-types.md包含每種文件類型的章節骨架、字數預算和來源數量。請在第 5 階段閱讀。references/citation-styles.md展示所有六種風格的實際編譯輸出，包括文內標記和參考文獻條目，以便您可以根據期刊選擇一種風格並知道其外觀。請在第 6 階段閱讀，並在閘門檢查之前再次閱讀，如果引文渲染方式不符預期。它還說明了編譯器不支援的內容：無卷號、期號或頁碼，無期刊縮寫。如果指導教授要求這些，此處會誠實說明，而不是讓您在事後才發現。
這兩個檔案並非偽裝成參考資料的可選讀物。未閱讀第二個檔案而選擇的風格是憑記憶選擇的風格，而編譯器並未實作您記憶中的 APA 格式。
腳本
python3 scripts/sources.py find "<查詢>" --n 15 # Crossref 加 OpenAlex
python3 scripts/sources.py find "<查詢>" --json # 機器可讀
python3 scripts/sources.py verify <doi> <doi> ... # Crossref 加 DataCite
python3 scripts/citations.py build research/sources.json -o research/citations.json
python3 scripts/citations.py verify -d research/citations.json
python3 scripts/citations.py compile full_draft.md -d research/citations.json --style apa -o final.md
python3 scripts/citations.py bibtex -d research/citations.json -o refs.bib
python3 scripts/assemble.py sections -o full_draft.md
python3 scripts/assemble.py sections -o full_draft.md --check
python3 scripts/integrity.py final.md -d research/citations.json --target 8000
python3 scripts/integrity.py final.md -c research/summaries.md # 建議性數字檢查
python3 scripts/export.py final.md --format docx -o final.docx
每個腳本在失敗時都會以非零退出碼終止。該退出碼就是信號；請讀取它，而不是粗略瀏覽輸出。
sources.py find 在完全無法連接到任何 API 時會以退出碼 1 終止，這與成功連接但未獲得結果不同。agents/01-scout.md 是關於如何讀取該退出碼以及在第一階段停止而非繼續進行的來源下限的權威來源；請在那裡閱讀，而不是信任空結果。
citations.py build 接受第一階段寫入 research/sources.json 的 JSON 陣列，而非 research/sources.md 中的 markdown。將 markdown 檔案作為輸入是錯誤的，它會明確指出。
如果第一輪搜尋結果稀少，請同時搜尋兩三個更具體的子查詢。一份只有五個來源的論文讀起來就像只有五個來源。
驗證，及其證明與未證明的內容
citations.py verify 將每個 DOI 分為四種狀態之一，unknown 永遠不會被靜默地轉換為 absent：
- resolved. Crossref 或 DataCite 傳回了記錄。引用它。
- absent. 兩者都返回了 404。刪除它。不要修復它，不要猜測替代 DOI，返回去
…
[此處為截斷內容]
...