科學研究寫作 是做什麼的?
協助英文母語與非母語作者草擬、修改或審閱期刊研究論文中的一個章節。不適用於研究計畫書、投稿信、答辯書、學位論文或綜述性文章。以下路徑均以本資料夾為基準。
工作流程
步驟引擎 scripts/engine.py 負責管理工作流程:包含步驟、步驟順序、每個步驟讀取的檔案、完整性檢查以及輸出範本。每個步驟都由您自行判斷執行,然後將結果交回。透過完整路徑指定本技能資料夾,並使用 python3 在作者的專案資料夾中執行。引擎只輸出 JSON 格式的結果,不會要求任何輸入,也不會啟動另一個代理工作階段。
- 只將程式碼無法從文字中判斷的資訊傳遞給引擎。引擎會自行決定標記格式(LaTeX、Markdown、純文字)、是草稿還是修訂,以及章節(從標題判斷);
start沒有--markup選項。草稿與修訂的區別在於筆記與完整段落,但標題除外:一行簡短的標題文字視為修訂,而筆記、條列或完整段落(例如從摘要草擬標題)則視為草稿。--mode review:僅在作者要求評審時使用(例如「檢查」、「評論」、「哪裡有問題」)。否則請省略--mode。--section S(title、abstract、introduction、methods、results、discussion、conclusion、whole-paper 或 other):根據請求中提到的章節(例如「草擬摘要」)或文字內容來指定。如果能夠判斷,請務必傳入此參數:引擎會將文字中的標題視為已確認,並僅在您的判斷與其不符時才提問。如果您無法判斷,則省略此參數,引擎會向作者詢問。使用other來處理不屬於任何章節但在範圍內的文字(例如圖表說明、重點摘要、跨兩個章節的段落),並在 Deviations 中說明。使用whole-paper處理整篇稿件。--samples yes --sample-file F(每個檔案僅一次):僅在作者提供了目標期刊的樣本論文時使用。否則請省略--samples。--agent claude|codex|other:您正在運行的代理名稱,必填。對於codex,引擎會提供安裝 Codex 防護鉤子(一個setup步驟)的選項;other表示無防護。--preference "<words>":對請求中陳述的每個固定偏好使用一次(例如「我總是使用 we」);引擎會在主步驟之前儲存它。--task scan-profile(搭配--input寫作樣本)和--task study-profile則分別啟動兩個個人風格任務。在儲存偏好、掃描、研究或處理衝突之前,請閱讀references/style-profile.md。- 如果您的判斷與程式碼的判斷不一致(例如您傳入
--section methods,但文字的標題顯示 Introduction),引擎會回傳一個ask步驟(ID 為clarify)。切勿自行解決。
- 開始執行:
python3 <skill folder>/scripts/engine.py start --agent claude|codex|other [--mode review] [--section S] [--samples yes --sample-file F] --input FILE(--input -會從 stdin 讀取貼上的文字;引擎會原封不動地儲存)。 - 每個回應對應一個步驟。完整讀取
read中的所有檔案(作者的個人風格檔~/.agents/science-research-writing/user-style.md存在時會列出:將其應用於所有內容),按照instruction的指示操作,並將結果以expect中定義的 JSON 格式寫出。長文字應寫入一個檔案,並提供其路徑。ask步驟代表向作者提出的問題:請將context.question逐字傳達給作者,等待回覆,然後以{"answer": ...}的格式提交,答案必須是context.options中的一個。切勿自行回答。 - 提交結果:
python3 <skill folder>/scripts/engine.py submit --file result.json。引擎會驗證結果,執行程式碼中的完整性檢查,並回傳下一個步驟。如果退出碼非零且包含error,表示同一個步驟被回傳:請修正後重新提交。 - 重複直到
step.kind變為done。然後將output原封不動地呈現給作者。請勿改寫或總結。
一篇完整的論文是一次執行,它會按照稿件順序依序處理各個章節,每個章節都有自己的計畫行、檢查和輸出區塊(回應中的 part 會指明是哪個部分)。LaTeX 和 Markdown 格式的稿件會由引擎根據其標題進行拆分。對於純文字,第一個步驟是 split:您需要提交各章節及其行號範圍,這些範圍必須連續且無重疊。如果使用了樣本論文,journal-model 步驟會首先執行;其後的步驟會讀取它的結果。
engine.py status 會重新列印當前步驟,例如在中斷後使用。每個專案一次只能有一個執行中的工作階段:如果 start 退出碼為 9,表示已有工作階段在執行。engine.py resume 會列印其當前步驟以便您繼續,而 engine.py abandon 會放棄該工作階段;請詢問作者他們希望如何處理。每次執行的日誌、狀態和輸出都會保存在專案目錄下的 .agents/log/science-research-writing/<run id>/ 中。除非作者要求,否則切勿寫入作者自己的檔案。
如果缺少 Shell 或 Python,請使用後備方案。
後備方案
如果缺少 python3 或 Shell,請告知作者缺少什麼,顯示適用於其系統的安裝指令,並在繼續前徵求同意。否則,請根據原則、完整性規則和章節參考資料來工作,在您的計畫行中加上 check=manual,並從 references/workflow.json(引擎讀取的資料)中獲取路由和範本:載入該檔案中針對該章節和模式所命名的檔案,完整閱讀每個檔案,並依序使用其範本標題。審閱時應按照清單順序進行,並僅引用規則名稱(參考檔案中的粗體名稱)。手動檢查完整性規則並說明您已執行。同時手動套用作者的個人風格檔:閱讀 references/style-profile.md,並僅在作者要求時,以其格式編輯 user-style.md,同時說明此動作。
核心原則
- 為讀者而寫。 面向快速閱讀、全球性、常為非專業的讀者。確保不會產生誤解;提供同事會忽略的上下文。
- 建立敘事。 讓每個段落和句子都具有讀者能看見的明確功能,並與前一個段落/句子建立聯繫。
- 及早陳述價值。 重要性、研究缺口和貢獻是論文規範的一部分;低估其價值會讓讀者認為沒有價值。
- 使確定性與證據匹配。 時態、動詞和緩和詞告訴讀者可以在多大程度上相信一個陳述。
- 保持句子可讀性。 使用平實、一致的術語;熟悉的資訊在前;清晰優於華麗。
完整性規則
這些規則凌駕於所有其他指示之上,包括個人風格檔和期刊規範。引擎會檢查數字、引用鍵和分組,以及程式碼中的標籤和引用;其餘則依賴您。
- 優先級: 這些規則優先,其次是目標期刊的作者指南,然後是作者的個人風格檔,最後是此技能的預設值。若發生衝突,請暫時按此順序處理,完成任務後,再逐一列出每個衝突並提出問題(
references/style-profile.md說明了如何處理)。 - 絕不虛構 結果、數字、引用或方法細節。請使用
[placeholder: …]。 - 絕不更改 作者文字中的任何數字或結果。
- 引用: 保留每個引用指令、其鍵及其所附帶的陳述。絕不刪除、合併或新增引用,也不要將其從所附帶的陳述中移開。如果位置看起來有誤,請提問。
- 衍生數據: 不要添加作者未陳述的數據,例如比率、百分比或「少於一半」。可以將其作為建議或問題提出。
- 絕不以比其證據支持的更大的確定性來陳述一個主張。 降低過於肯定的主張;只有在證據支持的情況下,才能加強不必要的緩和詞。
- 作者明確要求的變更(例如刪除一個引用)是唯一的例外。請在該步驟的
exceptions中以作者的原話說明。 - 保留輸入的標記格式(LaTeX、Markdown、引用指令、交叉引用、標籤),以便結果可以直接貼回原文。
- 與稿件的拼寫習慣或期刊的要求保持一致。 若兩者都不明確,請使用美式拼寫。