Community研究與資料分析github.com

論文轉筆記本

將一篇研究論文(PDF、HTML 或純文字來源,如 LaTeX、Markdown 等)轉換為一個引導式、可執行的 marimo 學習筆記本。

論文轉筆記本 是什麼?

此技能旨在將一篇研究論文轉化為一個互動式的 marimo 筆記本,以協助讀者理解該論文。它並非簡單摘要,而是一堂課程:包含白話解釋、互動式小工具,以及沿途的非正式小測驗。使用者可提供論文檔案、URL 或識別碼,技能會提取全文,分析其結構、方程式、圖表及術語,並據此規劃學習路徑。最終產出為一個可透過 `uvx marimo edit --sandbox` 開啟的 `.py` 筆記本。此技能支援自適應解釋,能根據不同讀者程度(從孩童到專家)提供分層說明。它特別適合用於製作單篇論文的互動式導覽,不應用於多篇文獻回顧或非 marimo 格式的輸出。該技能依賴於多個 marimo 相關技能和資源,如 `marimo-notebook-patterns`、`awesome-marimo-notebook` 和 `resources/field-maturity.md`,以確保筆記本品質並提供領域特定的詞彙導入。最終筆記本將包含一篇論文的核心概念解釋、互動式小工具、非正式測驗,以及一個五題的最終測驗。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericmjl/paper-to-notebook-skill/tree/main

Installed? Explore more 研究與資料分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

論文轉筆記本 是做什麼的?

引導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: 預設方向——從簡單開始並增加複雜度,或從高階開始並在讀者困惑時降低難度。兩者都曾被提出,但均未被選定。核心概念應有完整的階梯(請參閱多層次解釋)。

建議的主線(可根據論文調整):

  1. 這篇論文為何重要。
  2. 在引入複雜符號之前,先提供直覺或一個玩具範例。
  3. 設定:符號、假設、術語、領域詞彙導入(詞彙表;必要時進行歧義消除或變動中的術語——請參閱 resources/field-maturity.md)。
  4. 核心概念,並連結到一個方程式或圖表。
  5. 依照論文順序逐步解說。
  6. 段落後的非正式測驗,與解釋等級匹配:解釋、預測、應用或批判(非正式評量——正式評量超出範圍)。
  7. 對於研究生及以上讀者:批判環節——實驗設計是否解決了所述問題?統計框架是否為適當選擇?缺少了什麼?讀者正在做出哪些假設?
  8. 結尾:限制、下一步閱讀建議、引用。
  9. 最終測驗:五道關於論文的選擇題,永遠是最後一個章節(請參閱最終測驗)。

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. 根據論文勾勒先備知識概況(階段 1): 對於每個級別,讀者知道什麼、不知道什麼,以及筆記本必須教導什麼。將使用者陳述的背景(來自合約中的可選輸入)映射到一個級別。

  2. 每個級別只解釋一個機制。 首先撰寫一句話的機制主線;每個級別為其增加精度。沒有任何級別可以用一個更模糊或不同的機制來取代。

  3. 每個級別都必須準確。 簡化時應省略內容,絕不能說出錯誤的事。將每個簡化記錄在一個帳目中,並在後續級別中修正。

  4. 建立類比並說明其限制。 保留一個錨點直到級別 3,將其組成部分映射到方法的組成部分,並在級別 3 時說明其不適用的地方。

  5. 測驗需與級別匹配:

    • 兒童:解釋。
    • 青少年:預測。
    • 大學生:應用。
    • 研究生:應用並批判假設。
    • 專家:批判。

    每個測驗應包含預期答案、推理過程以及論文中對應的位置。

  6. 階梯專用於核心概念: 每個筆記本 1–3 個概念。

  7. 有根據: 引用你讀入的文字中的位置,切勿猜測。在起草時,使用 [cite: …] 標記缺口,並在交付前解決它們。

  8. 數字需附帶其條件: 表格、群體、特徵集或範圍應放在同一個句子中。在對真實論文進行測試時,階梯導致的兩個誤解均源於一個被剝離了條件的數字。

在筆記本中: 在靠近頂部添加一個級別選擇器。每個階梯使用 mo.ui.tabs,依據讀者的級別開啟,並在該級別下方放置相應的測驗。

撰寫前請閱讀: resources/explanation-levels.md 包含概況和帳目範本、一個完整的範例、經測試的 marimo 儲存格,以及常見陷阱。resources/examples/ 包含兩個更完整的階梯。

…

[為翻譯而截斷]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能