跳至主要內容

您的保管庫，就在終端機裡

taskforge 是一個小巧的命令列工具，用來讀寫您 Obsidian 保管庫中的任務。它使用與 App 相同的剖析器，因此重複任務會正確推進、封存會歸到正確位置，任務行也會維持您原本的格式。把它交給 shell 指令碼或代理，它編輯的就是真正的 Markdown 檔案，沒有任何內容託管在雲端。

即將隨 TaskForge 3.0 推出

TaskForge 命令列工具與 MCP 伺服器將隨 TaskForge 3.0 版本一同推出。本頁內容說明的是它們正式上線後的運作方式。TaskForge 應用程式本身現在就能下載使用。

CLI 還是 MCP 伺服器？

在沒有 MCP 連線的 shell 環境中使用 CLI：指令碼、cron、CI，或是在儲存庫簽出目錄中工作的程式代理。如果您的代理已經與 TaskForge 建立 MCP 連線，請優先使用 MCP 工具；它們具有型別，會回傳結構化錯誤，方便代理據此自我修正，而且不需要在您的 PATH 中安裝任何東西。兩者驅動的是同一個引擎，語意完全一致，選擇您執行環境中已經接好的那一個即可。手動編輯保管庫檔案是最後的手段。

安裝

macOS 與 Linux，透過 Homebrew：

上線後即可使用 
brew install azhard/tap/taskforge

偏好使用 npm？同一個執行檔也以套件形式提供：

上線後即可使用 
npm install -g taskforge

未來將推出隨 App 內建、開啟保管庫時自動安裝的版本。在那之前，請透過上方的 tap 安裝。

快速上手

使用 --vault 指向保管庫，或設定一次 TASKFORGE_VAULT 環境變數即可。每個讀取指令都接受 --json，輸出代理可解析的機器可讀格式。

taskforge schema

印出保管庫的任務語法：狀態符號、日期格式、自訂欄位，以及新任務要寫到哪裡。這是代理最先讀取的內容。

taskforge add "call the plumber" --due 2026-07-10 --priority high

把任務附加到保管庫的預設新任務位置，格式與您保管庫寫任務的方式一致。

taskforge query 'prop:priority_label=urgent' --sort priority --count

計算帶有自訂欄位 priority_label:: urgent 的任務數量，最緊急的排在最前面。拿掉 --count 即可列出這些任務。

taskforge query 'desc:"invoice" text:acme' --json

以 JSON 格式找出描述中提到 invoice、標題中提到 acme 的任務。重音符號與大小寫都會被忽略，所以 cafe 也能比對到 café。

taskforge done <task-id>

完成一項任務。如果它會重複，下一次發生的任務會寫回檔案中，做法與 App 完全一致。

taskforge show <task-id> --json

讀取一項任務及其內容雜湊值，讓後續編輯可以帶上 --if-hash，拒絕覆寫過時的版本。

查詢語法

查詢參數是一組以空格分隔的字詞（token），全部都必須符合。常見的有：

text:word 標題包含該字詞（不分重音與大小寫）。 text:groceries
desc:"phrase" 任務描述包含該片語。 desc:"send invoice"
tag:name 任務帶有 #name 標籤。 tag:work
prop:key=value 自訂欄位 key 的值等於 value。 prop:area=home
prop:key 自訂欄位 key 存在，值不限。 prop:estimate
--sort due|priority|created 排序結果。預設依到期日排序，最緊迫的排最前面。 --sort priority
--count 回傳符合筆數，而非任務本身。 --count

自訂欄位的 key 可以包含字母、數字與底線，因此 priority_label 與 area_2 都能使用。

唯一的要求：保管庫合約

taskforge 會讀取一個由 TaskForge 寫入您保管庫的小型合約檔案 taskforge/schema.json。它描述了您確切的任務格式，讓 CLI 依照您的方式編輯任務，而不是用猜的。請至少用 TaskForge 3.0 以上版本開啟過保管庫一次，前往 Settings > AI & Agents，並保持'Generate agent files'開啟。這樣就會寫入合約檔案。

如果 taskforge 找不到保管庫，它會告訴您三種指向保管庫的方式：

  1. 在指令中加上 --vault /path/to/vault。
  2. 設定 TASKFORGE_VAULT 環境變數。
  3. 用 TaskForge 3.0 以上版本開啟保管庫一次，讓 taskforge/schema.json 存在，然後在保管庫資料夾內執行指令。

僅限本機

taskforge 在您的機器上執行，只會動到您所指定保管庫中的 Markdown 檔案。不需要帳號、不需要 API 金鑰，也不會有任何網路連線。您原本用來同步保管庫的方式，無論是 iCloud、Dropbox 或 Obsidian Sync，都會把這些變更帶到您的其他裝置。

想讓代理來操作嗎？

CLI 適合終端機與指令碼使用。如果您想讓 Claude Desktop 或其他 MCP 客戶端透過工具介面新增和完成任務，請改為設定 MCP 伺服器。同一個保管庫，同樣的規則。兩種方式用的都是同一個 taskforge 執行檔，執行 taskforge mcp --stdio 就能把它切換成 MCP 伺服器。

設定 MCP 伺服器 →

CLI 負責編輯任務，App 讓它們持續運作。

taskforge 能從任何終端機寫入你的保管庫；TaskForge 則把同樣的檔案變成手機和桌面上的清單、小工具和提醒。可在 iPhone、iPad、Mac 和 Android 上免費下載。

Apple 免費 - iOS 和 Mac Android 免費 - Android