使用文件
安裝 pude、熟悉日常流程，再動手寫第一個外掛——就像在 pude 裡閱讀一樣。
版本 0.1.1 · 已發布版本
總覽
pude 是本地優先的桌面程式碼編輯器。它開啟本機資料夾、編輯文字、呈現 Git、按需啟動終端機並載入本機外掛——其餘的一律不放進核心。
0.1 包含什麼
- 本機工作區、按需載入的檔案總管與多視窗
- 多分頁編輯、語法突顯、尋找與取代、Markdown 預覽
- 透過系統 Git 呈現狀態、提交圖譜、差異與常用操作
- 以真實 PTY 運作、按需啟動的多個終端機
- 具權限審核的本機外掛（API 2）與受控 LSP 程序管理器
刻意不做什麼
- 全專案索引、除錯器或建置系統
- AI 服務、雲端同步與帳號
- 外掛市集、自動更新與內附語言伺服器
如何閱讀本文件
檔案總管裡的每個檔案就是一個主題。用狀態列的 Source / Preview 切換，就能看到每一頁背後的 Markdown，與 pude 顯示的完全相同。
安裝與更新
| 平台 | 安裝檔 |
|---|---|
| Windows 11 x64 | pude-windows-x64-setup.exe（未簽署） |
| macOS 14+ Apple Silicon | pude-macos-arm64.dmg |
| Linux | 規劃中 |
驗證下載檔
每個版本都附有 SHA256SUMS.txt，涵蓋兩個安裝檔與授權文件。安裝前請先比對雜湊值：
bash# macOSshasum -a 256 pude-macos-arm64.dmg# Windows (PowerShell)Get-FileHash .\pude-windows-x64-setup.exe -Algorithm SHA256手動更新
pude 不會自動更新，啟動時也不會連線檢查。更新時請關閉 pude，下載較新的安裝檔並執行。穩定版的「關於」視窗可以查詢最新版本——只在你點擊時才會連線。
使用教學
開啟工作區
選擇 Open folder（⌘K ⌘O，Windows 為 Ctrl+K Ctrl+O）並挑選本機資料夾。pude 只讀取最上層，展開時才載入子資料夾。全新啟動會顯示最近的專案；每個新視窗都有自己的工作區、分頁與終端機。
檔案總管
- 建立、重新命名與刪除檔案和資料夾。刪除會移到資源回收筒或垃圾桶，絕不永久刪除。
- 右鍵選單提供
Copy Path、Copy Relative Path，以及在系統檔案管理器中顯示。 - 很長的資料夾也保持流暢：只渲染看得到的列。
編輯
- 分頁支援拖曳排序、釘選、中鍵關閉、關閉其他、關閉右側，以及重新開啟剛關閉的分頁。
- 尋找與取代支援大小寫、正規表示式與全字比對；
⌘G跳至指定行。 - 多游標、復原與重做、縮排由 CodeMirror 6 提供。
- 按住
⌘（或Ctrl）在編輯器上捲動滾輪，可將字體大小調整為 11 到 24。 - Markdown 預設顯示原始碼；用狀態列的
Source / Preview切換為渲染預覽。
可開啟的檔案
- UTF-8 與含 BOM 的 UTF-8。無效的 UTF-8 或其他編碼會被拒絕，不會默默轉碼。
- 超過 5 MiB 的檔案以大型檔案模式開啟：保留編輯與搜尋，關閉重型解析與預覽。
- 文字檔上限為 20 MiB；支援的圖片會以圖片預覽開啟。
安全地儲存
每個檔案的儲存會依序排隊，並以原子化方式取代原檔。每一行都保留原本的 LF 或 CRLF。若檔案在你尚未儲存時被外部修改，pude 會提供 Compare、Reload 或 Keep Editor Version——絕不默默覆寫任何一方。
未儲存的內容會在本機建立復原檢查點。復原會還原最後一次完成的檢查點，而不是每一次按鍵。
Git
pude 使用你系統上安裝的 Git，因此 git 必須在 PATH 中。沒有 Git 時仍可正常編輯，Git 面板會顯示無法使用。
狀態與歷史
- 把側邊欄切到
GIT，即可看到分支，以及已暫存、未暫存、未追蹤、已重新命名與衝突的檔案。 - 提交圖譜能處理 detached HEAD、尚無提交的分支與多個 refs，並按需載入更早的歷史。
- 任何變更都能以並排或堆疊方式檢視差異。
操作
暫存與取消暫存、提交、推送與拉取、建立／切換／安全刪除分支、stash 與 pop。指令失敗時，完整的 Git 輸出會顯示在對話框中，而不是一閃即逝的提示。
終端機
用 ⌘`（Windows 為 Ctrl+`）切換面板，需要幾個分頁就開幾個。每個分頁第一次顯示時，才會載入 xterm.js 並啟動自己的 PTY。
- 隱藏面板時工作階段仍會執行。關閉分頁、切換工作區或關閉視窗，會停止該分頁的程序樹。
- Windows 使用
ComSpec，未設定時改用powershell.exe；macOS 與 Linux 使用SHELL，未設定時改用/bin/sh。 - 若工作區的
.venv、venv或env中有 Python 虛擬環境，新終端機會自動啟用它。 - scrollback 保留 5,000 行，支援 ANSI 色彩、alternate screen、滑鼠追蹤、中日韓文字與輸入法。
設定與本機資料
| 設定 | 作用 |
|---|---|
| Font size | 編輯器字體大小，也可以用 ⌘ + 滾輪調整。 |
| Tab size | Tab 與縮排的寬度。 |
| Word wrap | 在編輯器內自動換行。 |
| Hide dot files | 在檔案總管中隱藏以 . 開頭的名稱。 |
| Watcher excluded paths | 檔案監看要忽略的路徑，例如建置輸出。 |
資料存放位置
- 工作區檔案留在原本的路徑，pude 不會複製到其他地方。
- 設定與工作階段資訊存放在本機 WebView 儲存空間。
- 復原檢查點使用 IndexedDB，並有本機備援；清除應用程式儲存空間可能會移除它們。
- 已安裝的外掛會複製到應用程式資料目錄。
鍵盤快捷鍵
| 動作 | macOS | Windows |
|---|---|---|
| 儲存 | ⌘S | Ctrl+S |
| 另存新檔 | ⌘⇧S | Ctrl+Shift+S |
| 全部儲存 | ⌘⌥S | Ctrl+Alt+S |
| 開啟檔案 | ⌘O | Ctrl+O |
| 開啟資料夾 | ⌘K ⌘O | Ctrl+K Ctrl+O |
| 關閉分頁 | ⌘W | Ctrl+W |
| 下一個／上一個分頁 | ⌃⇥ / ⌃⇧⇥ | Ctrl+Tab / Ctrl+Shift+Tab |
| 尋找 | ⌘F | Ctrl+F |
| 取代 | ⌘⌥F | Ctrl+H |
| 跳至行號 | ⌘G | Ctrl+G |
| 命令面板 | ⌘⇧P | Ctrl+Shift+P |
| 切換終端機 | ⌘` | Ctrl+` |
| 字體大小 | ⌘ + 滾輪 | Ctrl + 滾輪 |
製作外掛
外掛是一個本機資料夾，包含 plugin.json 宣告檔與一個 JavaScript 進入點。它在 opaque-origin 沙箱裡的 Web Worker 中執行，只能透過非同步的 pude API 與 pude 溝通——無法取得 DOM、CodeMirror、Tauri 或瀏覽器儲存空間。
1. 撰寫宣告檔
以下是 examples/plugins/document-case-toggle 中可直接執行的範例。每個貢獻的命令都需要對應的 onCommand:<id> 事件；另外也可使用 onLanguage:<id>、onFileOpen、onFileSave 與 onWorkspaceOpen。
json{ "id": "pude.example.document-case-toggle", "name": "Document Case Toggle", "version": "1.0.0", "apiVersion": "2", "entry": "extension.js", "permissions": ["editor.read", "editor.write", "commands.register", "ui.notification"], "activationEvents": ["onCommand:pude.example.document-case-toggle.toggleCase"], "contributes": { "commands": [ { "command": "pude.example.document-case-toggle.toggleCase", "title": "Toggle Document Case" } ] }}2. 撰寫進入點
jsconst commandId = "pude.example.document-case-toggle.toggleCase";function toggleCase(text) { return text === text.toUpperCase() ? text.toLowerCase() : text.toUpperCase();}void pude.commands.register(commandId, async () => { const file = await pude.editor.getFileInfo(); const text = await pude.editor.getText(); if (text.length === 0) { await pude.ui.notify("The active document is empty."); return; } await pude.editor.applyEdits(file.revision, [ { from: 0, to: text.length, insert: toggleCase(text) }, ]); await pude.ui.notify("Document case toggled.");});3. 安裝與迭代
- 開啟
Plugins，選擇Install local plugin並選取資料夾。 - 檢視要求的權限，只核准外掛真正需要的。按
Cancel會保留現有版本與授權。 - 啟用外掛，並從命令面板執行它的命令。
- 修改後使用
Update from folder；新版本要在你核准後才會取代舊版本。
API 一覽
| 權限 | 呼叫 | 說明 |
|---|---|---|
editor.read | getText、getTextRange、getSelection、getCursor、getFileInfo | 每次最多 128 Ki 個字碼單位 |
editor.write | applyEdits(revision, edits) | 最多 1,000 筆編輯；走一般的復原與未儲存狀態 |
workspace.read | list、readFile、getFileInfo、readFileRange | 每次 128 KiB；大型檔案以範圍讀取 |
workspace.write | writeFile | 會檢查衝突；不提供刪除 |
commands.register | commands.register | 僅限已宣告的命令 |
ui.* | ui.notify、ui.statusBar、ui.quickPick | 由 pude 繪製，文字長度有限 |
git.read | git.getStatus、git.getDiff | 唯讀 |
terminal.write | terminal.write | 只能寫入使用者已開啟的終端機 |
network | network.fetch | 僅限核准網域的 HTTPS |
process.spawn:lsp | lsp.start、send、cancel、stop | 僅限已宣告的伺服器 |
每次執行最多 512 個並行請求、每秒 20 個請求、30 秒逾時、請求 64 KiB 與回應 1 MiB。完整參考請見儲存庫中的 docs/plugin-api-v2.md。
從原始碼建置
- Node.js
22.12+、24+或26+，以及 npm10.9+（建議 Node.js 24） - 透過
rustup安裝的 Rust stable，以及在PATH中的 Git - macOS：Xcode Command Line Tools · Windows：MSVC C++ 建置工具與 WebView2 · Linux：Tauri 需要的 GTK/WebKit 套件
bashgit clone <repository-url>cd pudenpm ci常用指令
| 指令 | 用途 |
|---|---|
npm run tauri:dev | 執行原生桌面應用程式 |
npm run dev | 在瀏覽器殼層中執行桌面介面（port 5173） |
npm run web:dev | 本網站（port 5174） |
npm test | 桌面版 Vitest 測試 |
npm run tauri:build | 建置目前平台的原生安裝包 |
送出 Pull Request 前
bashnpm run checkcargo test --locked --manifest-path apps/desktop/src-tauri/Cargo.toml