論文轉筆記本 是做什麼的?
引導AI代理從一篇論文建立一個可執行的 marimo 筆記本,幫助讀者理解該論文。這個筆記本是一堂課程,而非摘要頁面:包含白話解釋、有幫助的互動式小工具,以及沿途的非正式小測驗。寫作必須清晰易懂且能代表論文內容,而非泛泛的AI文體。
這是一個骨架檔案。許多細節將在後續補上。標有 TODO 的項目表示尚未決定或僅有草稿。
合約
| 輸入 | 一篇論文,格式為 PDF、HTML 或純文字來源(LaTeX、Markdown 等)。只要能夠獲取全文,路徑、URL 或識別碼皆可。 |
| 輸出 | 一個可執行的 marimo 筆記本 (*.py),讀者可以使用 uvx marimo edit --sandbox … 開啟。 |
可選輸入(若缺少時可詢問使用者,但不要因使用者只提供了論文而阻塞流程):
- 起始目標受眾或「隨我調整」。預設工作假設:大學部到研究生,以及對該論文或領域不熟悉但具備一般科學知識的專業人士。 TODO: 確定預設值。
- 額外背景資訊:使用者希望作為根據(不僅是常識)的支持性資訊、引用的論文或其他來源。
- 深度:完整導覽 vs. 僅限方法、結果或某張圖表。
- 輸出路徑與執行時期限制。
不要將此技能視為審查大量文獻的工具。那是不同的工作。
工作流程
1. 吸收論文(PDF / HTML / 純文字來源)
2. 提取結構、術語、方程式、圖表及缺口
3. 規劃學習路徑
4. 產生 marimo 筆記本
5. 使用 `uv run` 驗證其可執行,然後交付
1. 吸收論文
取得全文,而非僅摘要。根據輸入類型分支處理;將格式特定的注意事項放在 resources/ 中,任何輔助工具放在 scripts/ 中(一律使用 uv run,不要全域 pip install)。
- PDF: TODO: 如何取得並解析(文字、數學、圖表、閱讀順序)。失敗時應標記,而非猜測。
- HTML: TODO: 如何取得並解析(主要文字 vs. 導覽/外框、MathJax/MathML、圖表)。
- 純文字來源(LaTeX、Markdown 等): TODO: 如何追蹤引入檔、參考文獻和圖表檔案;如何保留方程式和圖表的標籤。
記錄論文的標題、作者、年份以及(若有的話)穩定的連結或識別碼。
2. 提取結構、方程式及圖表
在撰寫任何筆記本之前,先建立論文的中間表示。 TODO: 確定此步驟的資料結構(另請參閱「良好的中間結構能讓後續工作更輕鬆」這個想法)。
至少提取以下項目:
- 以你自己的話描述問題與貢獻。
- 先備知識概況:每個級別的讀者知道什麼、不知道什麼,以及需要教導什麼(請參閱多層次解釋)。
- 關鍵概念以及論文使用但未定義的術語(核心元資料或領域術語)。設計討論中舉例:一篇關於心臟病發作的論文從未解釋「心肌梗塞」。
- 關鍵方程式,編號與論文中相同,並包含變數。
- 關鍵圖表:每個圖表編碼了什麼、如何標記,以及底層資料是否似乎可用。
- 產生過程中的風險點:複雜的 LaTeX 或數學式、希臘字母圖表標籤、其他非 ASCII 文字。
- 方法或報告中明顯的缺口。不要憑空捏造缺失的實驗結果。
使用 resources/field-maturity.md 中的評分標準和輕量文獻樣本,將領域成熟度分類(成熟、新興、跨領域或混合)。記錄類別、證據,以及需要哪些詞彙導入的筆記本元件(詞彙表、歧義消除、變動中的術語)。
TODO: 是否將論文分類為演算法型(編碼練習、逆向工程方法) vs. 概念型(由代理編寫的解釋器小工具)。討論中使用的化學例子:質量平衡、反應動力學、一個新的動力學模型。
3. 規劃學習路徑
設計一個人可以一次性完成的路徑。 TODO: 目標時長。
不要將整個筆記本鎖定在單一閱讀等級。規劃自適應解釋:讀者應能在困難段落獲得較簡單或更進階的說明。 TODO: 預設方向——從簡單開始並增加複雜度,或從高階開始並在讀者困惑時降低難度。兩者都曾被提出,但均未被選定。核心概念應有完整的階梯(請參閱多層次解釋)。
建議的主線(可根據論文調整):
- 這篇論文為何重要。
- 在引入複雜符號之前,先提供直覺或一個玩具範例。
- 設定:符號、假設、術語、領域詞彙導入(詞彙表;必要時進行歧義消除或變動中的術語——請參閱
resources/field-maturity.md)。 - 核心概念,並連結到一個方程式或圖表。
- 依照論文順序逐步解說。
- 段落後的非正式測驗,與解釋等級匹配:解釋、預測、應用或批判(非正式評量——正式評量超出範圍)。
- 對於研究生及以上讀者:批判環節——實驗設計是否解決了所述問題?統計框架是否為適當選擇?缺少了什麼?讀者正在做出哪些假設?
- 結尾:限制、下一步閱讀建議、引用。
- 最終測驗:五道關於論文的選擇題,永遠是最後一個章節(請參閱最終測驗)。
TODO: 在第一版中,批判、結果分析章節和圖表解讀提示應涵蓋到何種程度,相較於單純的引導式導覽。
如果使用者提供了額外來源,請規劃在筆記本中何處引用這些來源,以及如何區分有來源佐證的證據與一般知識。 TODO: 區分機制的細節,以及是否應在稍後加入一個小型的概念圖或「知識維基」。
4. 產生 marimo 筆記本
從 assets/ 中的範本開始(若有的話)(TODO: 新增 assets/notebook_template.py)。撰寫一個可以用 uvx marimo edit --sandbox 開啟的 marimo 筆記本。
遵循安裝在 .agents/skills/ 中的 marimo 技能(一個 import marimo as mo 儲存格;獨特的全域名稱;驅動探索而非裝飾的小工具):
marimo-notebook-patterns:在撰寫或編輯任何筆記本儲存格之前閱讀(匯入和儲存格參數規則、獨特變數、小工具 API 簽名、常見錯誤)。marimo:更廣泛的編寫參考,包括在網頁上即時配對和嵌入筆記本。awesome-marimo-notebook:如何讓論文或資料集解釋器更具吸引力和精緻度。
在檔案頂部使用 PEP 723 內聯腳本元資料區塊 (# /// script … # ///) 聲明依賴關係,列出 marimo 以及筆記本匯入的每個套件,每個都帶有下界版本(例如 numpy>=2.0)。這讓 uv run 和 marimo edit --sandbox 可以安裝它們。
以最終測驗中描述的五題測驗結束筆記本。
對文字的嚴格要求:
- 清晰易懂且能代表論文的核心理念。
- 非泛泛的「AI 垃圾」。如果一個句子可以套用在任何論文上,請改寫。
- 在符號和領域術語首次出現時進行定義,或指向詞彙表/工具提示/反白即解釋輔助功能。遵循
resources/field-maturity.md以進行成熟度特定的導入章節。 TODO: 哪些讀者輔助功能應優先實作。討論中曾提到「Marimo Lens」可能適合用於反白即解釋;請確認實際功能名稱和主機支援。
其他產生規則:
- 方程式:在
mo.md中使用 LaTeX;在參數上放置小工具以建立直覺。 - 圖表:當資料允許時,重製或簡化;連結回論文的圖表編號。如果資料不可用,請說明——不要憑空捏造圖表。 TODO: 在第一版中,基於視覺的估計或讀者撰寫的圖表解讀應進行到何種程度。
- 圖表導覽:當關鍵圖表需要引導式的逐步解說時,請閱讀
resources/dynamic_figure_annotation.md(FigureAnnotatorWidget加上scripts/中的座標稽核輔助工具)。 - 核心概念(每個筆記本 1–3 個)應配有解釋階梯(多層次解釋)。
- 非正式測驗:簡短問題,非評分評量。使用
resources/explanation-levels.md第 9 節中的show_check模式(單選題、帶容差的數值答案,或帶有模型答案的開放式答案)。 - 步驟 2 中的領域模式:對於演算法型論文,提供編碼練習和方法重建;對於概念型論文,提供由代理編寫的可視化/小工具解釋器(例如,儲存格中的機制)。
- 標記任何超出論文範圍的內容(「我們的示範」、「簡化假設」)。
- 包含論文元資料和引用。
5. 驗證並交付
最低要求(v1 骨架):筆記本必須可執行。
uv run scripts/validate_notebook.py path/to/notebook.py --run
它會檢查 Python 語法、執行 marimo check --strict,並在加上 --run 時從頭到尾執行筆記本。在交付前修復所有報告的問題。
告知使用者:
- 筆記本路徑以及開啟指令 (
uvx marimo edit --sandbox …)。 - 假定的目標受眾以及簡化了哪些內容。
- TODO 事項和已知缺口(包括遺失的資料或未定義的術語)。
- 論文參考資訊(標題、作者、年份、連結)。
規劃中的驗證(超出「可執行」的範圍)(並非所有項目都需在最初草稿中完成):
- 寫作清晰易懂且能代表論文,非垃圾內容。
- 核心概念和元資料術語確實被解釋。
- 無虛構數字或主張。
- 筆記本以五題測驗結束,且問題是關於論文的主張、發現和限制,而非其實作細節。
- 每個階梯在每個級別解釋相同的機制主線;每個階梯的簡化都在後續級別中被修正;類比法的限制被明確說明。
- 詞彙導入: 對於成熟、新興和跨領域的案例研究,驗證詞彙表的覆蓋範圍,並在必要時,根據
resources/field-maturity.md第 8 節驗證歧義消除或變動中的術語章節。 - TODO: 斷言式或金問題評估;多模型執行(提供了中國開源模型和 Claude 模型);LLM 作為評判僅作為第一道篩選,其對「這個很糟」的判斷比對「這個很好」更可信;人類對陌生論文進行試用;領域專家在經過自身領域的初步測試後進行審查。
- TODO: 一套共用的測試論文集,涵蓋成熟、新興和跨領域的工作,以及子領域,而非僅限於單一領域。2016 年的一篇流感論文被提出作為一個可能的案例;清單尚未選定。
多層次解釋
核心概念應配備一個解釋階梯:一個機制以五個級別進行解釋,每個級別針對具有特定先備知識的讀者。其模型來自 WIRED 的 5 Levels 系列。級別名稱是簡稱。定義一個級別的關鍵在於讀者具備的學科知識和數學背景,以及該級別所增加的精度。
| 級別(簡稱) | 假定的學科知識 | 假定的數學背景 | 對機制的補充說明 |
|---|---|---|---|
| 1 · 兒童 | 日常經驗 | 計數和比較 | 因果關係,用日常用語 |
| 2 · 青少年 | 一般科學素養 | 算術、百分比、簡單圖表 | 一個使用真實小數字的玩具範例 |
| 3 · 大學生 | 該領域的入門課程 | 該領域的入門工具 | 精確的方程式或演算法,每個符號都有定義 |
| 4 · 研究生 | 相鄰領域的標準方法 | 能跟隨論文推導 | 假設、何時成立、何時失效、以及與標準方法的比較 |
| 5 · 專家 | 該子領域的文獻 | 完整形式主義 | 新穎之處、權衡取捨、限制與開放問題 |
規則:
-
根據論文勾勒先備知識概況(階段 1): 對於每個級別,讀者知道什麼、不知道什麼,以及筆記本必須教導什麼。將使用者陳述的背景(來自合約中的可選輸入)映射到一個級別。
-
每個級別只解釋一個機制。 首先撰寫一句話的機制主線;每個級別為其增加精度。沒有任何級別可以用一個更模糊或不同的機制來取代。
-
每個級別都必須準確。 簡化時應省略內容,絕不能說出錯誤的事。將每個簡化記錄在一個帳目中,並在後續級別中修正。
-
建立類比並說明其限制。 保留一個錨點直到級別 3,將其組成部分映射到方法的組成部分,並在級別 3 時說明其不適用的地方。
-
測驗需與級別匹配:
- 兒童:解釋。
- 青少年:預測。
- 大學生:應用。
- 研究生:應用並批判假設。
- 專家:批判。
每個測驗應包含預期答案、推理過程以及論文中對應的位置。
-
階梯專用於核心概念: 每個筆記本 1–3 個概念。
-
有根據: 引用你讀入的文字中的位置,切勿猜測。在起草時,使用
[cite: …]標記缺口,並在交付前解決它們。 -
數字需附帶其條件: 表格、群體、特徵集或範圍應放在同一個句子中。在對真實論文進行測試時,階梯導致的兩個誤解均源於一個被剝離了條件的數字。
在筆記本中: 在靠近頂部添加一個級別選擇器。每個階梯使用 mo.ui.tabs,依據讀者的級別開啟,並在該級別下方放置相應的測驗。
撰寫前請閱讀: resources/explanation-levels.md 包含概況和帳目範本、一個完整的範例、經測試的 marimo 儲存格,以及常見陷阱。resources/examples/ 包含兩個更完整的階梯。
…
[為翻譯而截斷]