Deepnote 把 Notebook 變成可編輯專案

Deepnote 的開源 repo 讓我把 Jupyter notebook 轉成可在 VS Code、Cursor、Windsurf 編輯的 .deepnote 專案。

我在 notebook 地獄待夠久了，最知道那種不對勁：看起來像程式，實際上像一包被 JSON 包起來的運氣。Cell state 一亂，結果就開始飄；輸出一多，diff 就像在看垃圾場。後來 AI 編輯器又把事情弄更煩，我想直接在 VS Code 或 Cursor 改 notebook，卻不想再接一個半殘的橋接工具，硬把 notebook 當二等公民。

我最近盯上 Deepnote 的開源 repo：deepnote/deepnote。它不是只做一個漂亮 UI 而已，而是想把 notebook 變成一種能版本控制、能轉換、能在本地跑的專案格式，之後你要不要回到 Deepnote Cloud 再說。這個順序我很買單：先轉、先編、先跑、先同步，最後才決定要不要上雲。比起一開始就逼你搬家，這種做法正常太多。

我把它拆開看，重點不是「Deepnote 是什麼」，而是這個 repo 到底怎麼讓 notebook 工作流不再像在補洞。官方文件在 Deepnote，編輯器支援則落在 VS Code、Cursor、Windsurf。我下面要講的，是怎麼拿這套方法論去救你自己的 notebook 工作。

先別把 .ipynb 當成神聖文件

Human-readable format: The .deepnote YAML format replaces .ipynb's messy JSON with clean, version-control and human-friendly structure for projects and notebooks.

翻譯一下就是：Deepnote 先動刀的不是功能，而是檔案格式。這點我其實很認同，因為我開過太多 .ipynb 的 diff，裡面不是程式變動，是輸出噪音、metadata、還有一堆執行順序殘骸。你很難真的看懂改了什麼，只會覺得自己在讀一坨序列化後的焦慮。

Deepnote 把格式換成 .deepnote，用 YAML 取代 JSON。這不是為了文青，是真的比較適合人看，也比較適合 Git。至少我不用每次 review notebook 時，都先把 parser 打開再找重點。你一眼就能看出結構，知道哪裡是內容、哪裡是設定、哪裡只是輸出垃圾。

更重要的是，它不是在說「一個 notebook 檔案」，它在說「一個專案」。這差很多。Notebook 一旦牽涉到資料來源、設定、圖表、說明文字、甚至多個分析步驟，單檔思維就開始失效。你會發現大家都在各自的 cell 裡亂塞東西，最後沒人知道誰依賴誰。

我之前幫團隊整理內部分析 notebook 的時候，最痛的不是程式錯，是交接錯。新人打開檔案後，根本不知道哪個 cell 是主流程、哪個是臨時試算。那種東西看起來像工作成果，實際上比較像一次性手工藝。

實操寫法很簡單：先挑一個真的在用的 notebook，不要拿玩具範例。把它轉成 .deepnote，丟進 Git，然後看 YAML diff 能不能讓你更快理解變動。如果你現在還把 notebook 當孤立檔案在管，我會先從「專案化」開始，而不是先從 UI 開始。

• 把原本的 .ipynb 轉成 .deepnote 再進版本控制。
• 優先觀察結構差異，不要只看畫面有沒有變漂亮。
• 只要一個工作牽涉多個 notebook、資料連線或共用設定，就該用專案思維。

Block 化才像真的在做資料工作

Block-based architecture: Extend notebooks beyond code cells with blocks for SQL, inputs, charts, and much more — all defined and validated through the open @deepnote/blocks package.

也就是說，Deepnote 不想再假裝所有東西都該塞進 code cell。這件事我早就受夠了。SQL、參數、圖表、輸入框、按鈕，這些東西明明不是程式碼，卻常常被硬塞進 notebook 的角落，像是工具不夠成熟，只好拿 Markdown 和註解湊合。

Deepnote 的 block 模型比較誠實。它把 SQL、Input、Visualization、Button、Big Number、Image 這些都變成一等公民，背後還有開源的 @deepnote/blocks 套件去定義和驗證。這代表它不是單純「渲染得比較好看」，而是把 notebook 當成一種混合型工作流：計算、參數、展示、互動控制，全都在同一個結構裡。

我以前做內部報表時，最煩的是日期區間、資料集選擇器、篩選條件都只能靠變數和註解維持。每次都有人忘記改，然後結果就錯得很安靜。這種錯最討厭，因為它不是爆炸，是悄悄污染你的判斷。

實操寫法是這樣：把 notebook 裡那些「不是程式碼的東西」拆出來。日期範圍用 input block，查詢用 SQL block，圖表用 visualization block，說明文字用 markdown 或 text block。你要的不是排版漂亮，你要的是別人接手時不會因為漏改一個變數就整份分析報廢。

如果你是做資料分析、營運報表、內部 dashboard，我會直接建議你先列一張清單：哪些 cell 只是參數，哪些 cell 只是展示，哪些 cell 才是核心邏輯。能 block 化的先 block 化，別再把所有東西都塞成 Python。

• 把日期、環境、資料集名稱改成明確的輸入 block。
• SQL 查詢不要混在 Python 文字串裡，直接獨立出來。
• 圖表和說明文字分開，別讓分析邏輯跟展示層互相污染。

轉換工具才是它真正能落地的地方

Effortless conversion: Convert .ipynb notebooks into .deepnote projects and back again using the open @deepnote/convert CLI and API.

翻譯一下就是：Deepnote 沒有逼你把 Jupyter 一刀切掉。這點我很在意，因為我不信那種要求你先全面遷移、再來談好處的工具。大部分團隊卡住，不是因為不想改善，而是因為舊工作流還得繼續跑。能不能雙向轉換，才是真正的門檻。

README 裡直接給了 CLI 範例：

npx @deepnote/convert notebook.ipynb # This will convert the notebook and create notebook.deepnote

這種做法很對。我不想先註冊、先配置、先看一堆 onboarding 短片，只想先轉一個檔案看看。轉完之後，你可以在編輯器裡打開，檢查 block 結構、輸出、設定有沒有保住。再轉回去，確認跟 Jupyter 的兼容性還在。這樣才叫試用，不是信仰測試。

我以前看過太多 notebook 工具死在「只能單向搬家」。單向轉換很像搬家公司只負責把家具運到新家，然後把舊家門鎖換掉。你當然會猶豫。Deepnote 至少把回頭路留著，這讓它比較像工具，不像宗教。

實操寫法：先拿一個有真實輸出、真實圖表、真實資料載入的 notebook 做 round trip。第一次轉成 .deepnote，第二次再轉回 .ipynb。你要檢查的不是「能不能跑」，而是「你團隊能不能接受這個格式變成標準」。

• 批次轉檔時用 CLI，比手工拖檔案可靠。
• 如果你要塞進 Node.js / TypeScript 流程，就用 API。
• 先驗證 round-trip fidelity，再決定要不要全面導入。

真正有感的是能在你平常的編輯器裡做事

What can you do right now? This open-source repository lets you, edit and run Deepnote notebooks directly in your favorite AI-native code editors: VS Code extension - Full Deepnote support in Visual Studio Code Cursor extension - AI-powered notebook editing in Cursor Windsurf extension - Collaborative development in Windsurf

翻譯一下就是：Deepnote 想把 notebook 拉回你本來就在用的地方。這比「我們有雲端平台」重要多了。因為我真的不想為了改一個 notebook cell，就跳去另一個獨立 UI，再跳回 IDE，來回切到腦袋發熱。

它明確支援 VS Code Marketplace、Cursor、Windsurf。這三個地方本來就是很多開發者每天待最久的環境。Notebook 如果能直接在這裡編輯、執行、同步，它就不再是「另一個產品」，而是工作流的一部分。

我很討厭那種把 notebook 當成獨立宇宙的設計。你寫分析在 A，修錯在 B，最後把結果貼回 C。這不是效率，這是搬運工。Deepnote 的本地編輯策略比較合理，因為它先承認你已經有主工作區，不需要再造一個新的。

實操寫法：如果你團隊已經在用 VS Code、Cursor 或 Windsurf，就直接把 Deepnote extension 裝起來，當成 notebook 原生格式來看待，不要把它當匯出檔。Notebook 跟程式碼、測試、文件放在同一個專案裡，review、重構、AI 輔助編輯都會順很多。

我也注意到 repo 提到 Deepnote Toolkit 和相關 extension，這表示它不是一次性的插件，而是有意在做一整套工作流。這種東西我通常才會多看兩眼，因為單點功能很容易死，生態比較有機會活下來。

Reactive execution 才是避免舊結果害死人的地方

Reactive notebook execution: Automatically re-runs dependent blocks when inputs or data change, ensuring notebooks stay consistent and reproducible without manual execution.

也就是說，Deepnote 想處理 notebook 最陰險的問題：你改了一個地方，卻忘了重跑後面一半。這不是小事，我看過太多分析結果看起來對，實際上只是舊輸出還躺在那裡。Notebook 最可怕的地方，不是會壞，是會假裝自己沒壞。

Reactive execution 的意思是，當 input 或資料變了，依賴它的 block 會自動重跑。這讓可重現性不是靠人腦記憶，而是靠依賴關係。你不用每次都祈禱自己有沒有漏按 Shift+Enter，系統會幫你盯住。

我自己最怕的是報表型 notebook。你改了一個篩選條件，圖表卻還是舊的；你看著它，以為分析沒問題，結果其實是昨天的答案。這種錯誤很安靜，但殺傷力很大。Reactive execution 不會解決所有問題，但至少把最蠢的那種人為失誤拿掉。

實操寫法：只要你的 notebook 會輸出給別人看，我會把依賴關係當成設計前提。日期、SQL、資料載入、圖表顯示，這些步驟都要能追蹤依賴。不要讓「手動重跑」成為唯一保險。

這也是為什麼 block 模型和專案格式要一起看。結構清楚，執行規則才有意義；不然你只是把亂七八糟的 cell 換個皮而已。

它不是要你放棄 Jupyter，而是別再忍受 Jupyter 的老毛病

Deepnote is a drop-in replacement for Jupyter. It uses the Deepnote kernel, which is more powerful but still backwards compatible, so you can seamlessly move between both, but it adds an AI agent, sleek UI, new block types, and native data integrations.

翻譯一下就是：Deepnote 想當 Jupyter 的兼容升級，不是來跟你宣戰。這點我很吃。因為 Jupyter 真的還在很多工作裡活著，尤其是研究、資料分析、教學、原型驗證。你不可能假裝整個世界明天就搬走，所以工具最好老實一點，先把兼容性做好。

repo 也明講它是基於 Jupyter kernel，保留相容性，讓你可以在兩邊之間切換。這就比較合理：你可以先在本地把 notebook 整理好，等真的需要團隊協作、共用算力、資料連接，再往 Deepnote Cloud 移。它不是逼你立刻改信仰，而是給你一條比較不痛的路。

我很少會喜歡「替代品」這種詞，但這次例外，因為它沒有裝作要重寫整個世界。它只是承認 notebook 的現實：Jupyter 很有用，但也很容易把人搞得很累。Deepnote 做的事情，是把那些累人的部分抽掉。

實操寫法：把 Deepnote 當成兼容層，而不是一次性搬家專案。先從一個現有 notebook 開始，保留 Jupyter 的回退路，等你真的看到 block 化、版本控制、反應式執行有幫助，再決定要不要擴大採用。這樣比較像工程決策，不像衝動下單。

如果你在學校或研究環境，repo 也提到學生和教育者可免費用 Deepnote Cloud，還有研究引用格式。這至少說明它不是只想吃商業分析場景，學術工作流它也有想碰。

可抄的模板

# Deepnote notebook workflow template for a real team

## 1) Convert one existing notebook
npx @deepnote/convert notebook.ipynb

## 2) Open the generated .deepnote project in your editor
# Use VS Code, Cursor, or Windsurf
# Treat .deepnote as the working source, not just an export

## 3) Split notebook content into blocks
- Code blocks for Python or R logic
- SQL blocks for queries
- Input blocks for dates, filters, dataset names, and environment flags
- Visualization blocks for charts and summaries
- Markdown/Text blocks for notes, assumptions, and handoff context
- Button blocks for explicit actions when needed

## 4) Keep the project in Git
- Commit the .deepnote project
- Review YAML diffs instead of raw .ipynb JSON
- Group related notebooks, settings, and data connections together

## 5) Make execution dependency-aware
- Re-run dependent blocks when inputs change
- Avoid manual reruns as the only safety mechanism
- Verify charts and outputs always match the current inputs

## 6) Round-trip before standardizing
npx @deepnote/convert notebook.deepnote --outputFormat ipynb

## 7) Use Deepnote Cloud only when it earns its keep
- Shared collaboration
- Managed compute
- Native data integrations
- Team-based notebook workflows

## 8) Migration checklist
- Pick one notebook with real outputs
- Convert it to .deepnote
- Edit it in your normal code editor
- Check block structure, outputs, and diffs
- Convert it back to confirm compatibility
- Decide whether the new format is worth adopting team-wide

這份拆解主要來自 deepnote/deepnote on GitHub，我把原始 repo 的 workflow、格式、block 概念和轉換路線整理成比較能直接上手的版本。原始材料是 Deepnote 的開源內容，我做的是翻譯、重組和實戰化。