Bear CLI 與 MCP 如何重塑 Apple 原生筆記的自動化版圖

Bear 長年以 macOS 與 iOS 原生體驗、字體排版質感與無縫的 CloudKit 同步見長。但在開發者與 Geek 眼裡，其封閉架構與長年缺乏 CLI 始終是一道難以跨越的高牆——筆記資料被深鎖在 CoreData 與 SQLite 資料庫中，外界幾乎無法透過命令列乾淨地介入。

在 Bear 2.8 中，官方正式在應用程式套件中內建了原生的命令列工具 bearcli，並同步整合了基於 Model Context Protocol 的官方 MCP Server。這項改變讓使用者無需再依賴脆弱的 URL Scheme 或冒險逆向操作 SQLite，補齊了這款以設計著稱的筆記軟體在 AI Agent 時代欠缺的自動化介面。

歷史枷鎖：x-callback-url 的致命傷與 SQLite 黑箱代價

過去要在終端機或自動化腳本中操作 Bear，開發者基本上只有兩條路徑可走，但兩者皆伴隨顯著的系統代價。

x-callback-url 的三大致命缺陷

在 bearcli 問世前，官方唯一的自動化介面是基於 Apple 的 URL Scheme（x-callback-url），其標準呼叫形式如：

bear://x-callback-url/create?title=Log&text=Hello&tags=journal

雖然 x-callback-url 能應付 iOS Shortcuts（捷徑）的簡易收集，但在現代桌面開發者工作流程中，存在三大難以忍受的致命傷：

1. 奪取視窗焦點（Focus Stealing）：預設情況下，透過指令觸發 URL Scheme，macOS 都會強行將 Bear 視窗推到最前端（僅部分端點支援傳入 show_window=no 豁免），瞬間奪走編輯器焦點、打斷心流。
2. 非同步回傳難以捕捉（Asynchronous & Disjointed）：傳送 URL 請求後，回傳資料必須透過註冊回呼 URL 或監聽連接埠接收，Shell 腳本、Makefile 或 CI/CD 無法同步取得新增筆記的 ID，阻斷管線串接。
3. 無頭環境（Headless）完全癱瘓：在 SSH 遠端連線、macOS launchd 常駐守護行程或純終端機環境中，URL Scheme 完全無法被解析或執行。

直接存取 SQLite 的資料損毀風險

面對 URL Scheme 的限制，部分進階工程師選擇直接存取 Bear 在 macOS 底層的資料庫檔案：

~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

然而直接對底層 SQLite 執行 SQL INSERT 或 UPDATE，在系統架構層面伴隨著極高風險：

• CoreData 快取不一致：Bear 桌面端依賴 Apple CoreData 框架的記憶體物件圖譜。外部行程若私自竄改 SQLite，正在執行的 Bear GUI 無從得知資料變動，極易引發快取覆寫造成資料遺失。
• CloudKit 同步機制損毀：跨裝置同步高度仰賴 CoreData 與 CloudKit 維護的 Tombstones（墓碑標記）與 Change Tokens。直接變動資料庫往往會破壞同步鏈，在跨裝置間產生難以修復的重複或幽靈筆記。
• Schema 升級脆弱性：隨著 Bear 大版本升級，資料庫 Schema 與加密邏輯經常重構，任何基於逆向 SQL 結構撰寫的外部工具皆會在升級當下徹底失效。

bearcli：官方安全代理層

bearcli 的本質，是 Shiny Frog 為 Bear 打造的官方安全代理層（Broker / Bridge）。它直接呼叫 Bear 原生底層核心邏輯：

• 確保每次寫入皆能正確觸發 CoreData 的完整生命週期事件。
• 自動維持 CloudKit 同步中繼資料與變更標籤的完整性。
• 完全在終端機背景靜默運作，零彈窗、不奪取焦點，且支援純同步呼叫與錯誤回傳。

這讓工程師既能享受極速的終端機操控，又無需承擔搞掛數年累積知識庫的代價。

工程設計：符合 Unix 哲學的現代架構

bearcli 的架構設計相當扎實，處處體現對命令列管線與自動化情境的考量。

隨附的原生二進位檔

bearcli 採用原生 Swift 編寫，無需額外執行環境，直接隨 Bear macOS 主程式封裝發布：

/Applications/Bear.app/Contents/MacOS/bearcli

使用者僅需建立符號連結（Symlink）即可隨處取用：

sudo ln -s /Applications/Bear.app/Contents/MacOS/bearcli /usr/local/bin/bearcli

多格式輸出與語法擴充支援

bearcli 設計了三種符合不同情境的結構化輸出模式：

1. TSV（Tab-separated values，預設）：不帶標題列，天然適合終端機使用者透過 awk、cut、xargs 或 ripgrep 等工具直接組合管線。
2. 結構化 JSON（--format json）：輸出標準 JSON 文件；發生錯誤時亦會在 stdout 輸出標準 JSON 物件 {"error":{"code":"...","message":"..."}}，極易於腳本解析。
3. 符合標準的 CSV（--format csv）：完全遵循 RFC 4180 標準，附帶標題列，便於直接匯入資料分析工具。

在內容表現上，bearcli 原生完整支援 Bear 豐富的 Markdown 語法擴充，包括標籤（#tag、#nested/child）、雙向維基連結（[[Title]]、[[Title|alias]]）、螢光標記（==highlight== 與彩色標記）、底線（~underline~）、GitHub 風格提示區塊（Callout，> [!NOTE]）與標準數學公式（$math$）。

區段級別精確定址與樂觀並行控制

傳統筆記應用的 CLI 往往僅能「讀取全文」或「整篇覆寫」，bearcli 引入了強大的標題層級定址機制（Section Addressing）：

• 唯一標題定址：--section "## Setup"
• 巢狀標題定址：--section "# Build\n## Install"
• 多重同名標題索引定位：--section "# Build\n## Install\n2"（定位至第二個匹配區段）
• 序文段落定位（Preamble）：--section "## Install\npreamble"（選取該標題至第一個子標題間的前導內容）

透過 bearcli outline <note-id>，外部程式甚至能精確獲取整篇筆記所有區段的位元組範圍（byte ranges）與結構化位址。

在寫入安全方面，bearcli 實作了樂觀並行控制（Optimistic Concurrency Control）。

當透過 bearcli cat 讀取筆記或特定區段時，指令會回傳專屬的 hash 收據；執行 bearcli overwrite 時可帶入 --base <hash> 核對，若在讀取與寫入之間筆記已被修改，該次寫入會被立即拒絕，杜絕競態條件（CLI 呼叫可省略 --base，此時為無條件寫入；經 MCP 伺服器呼叫則強制必填）。

除了並行防護，系統也針對資料完整性設有安全防線。若覆寫操作會導致圖片或 PDF 等附件脫落遺失，bearcli 會自動攔截並列出即將遺失的附件名稱，唯有明確附加 --force 旗標才會執行破壞性變更。

生態競爭：面對 Obsidian 本地優先浪潮的防守

在個人知識管理（PKM）的演進史中，Obsidian 的崛起改寫了遊戲規則，也對長年深耕 Apple 生態的 Bear 帶來持續的競爭壓力。

本地純文字架構的天然優勢

Obsidian 自誕生起便堅守一條純粹原則：使用者筆記僅僅是儲存在本機硬碟上的純文字 Markdown 檔案（Vault）。這種設計在工程師與 Geek 社群中獲得高度認同：

• 零廠商鎖定（Zero Vendor Lock-in）：筆記就是普通資料夾與 .md 檔案，即使軟體停止維護，資料亦絲毫無損。
• 終端機原生公民（Terminal-native）：搜尋直接使用 rg，模糊篩選交給 fzf，批次修改可以用腳本完成，甚至直接在 Vault 目錄執行 git init 納入版控。
• 原生 CLI 與外掛生態：Obsidian 1.12.7+ 提供官方的 Obsidian CLI，可搜尋、讀取、建立與修改筆記；社群 REST API 與外掛則延伸更多整合情境。

相較之下，Bear 雖然在 Apple 原生渲染、排版細節與行動端流暢度上具備優勢，但其「封閉式 SQLite + 綁定 Apple 生態」的架構，讓追求終端機掌控力的開發者感到受限。社群討論中屢見這樣的兩難心聲——深愛 Bear 的設計與手感，卻難以接受筆記對終端機與自動化工具關起門來。

Shiny Frog 的折衷抉擇

面對使用者流失，Shiny Frog 面臨兩難：若將底層徹底重構成純文字目錄，雖然透明，卻會摧毀 Bear 賴以生存的流暢富文字附件管理、加密筆記、CloudKit 差異同步與高效全文索引；若維持現狀，則無可避免地在技術社群中邊緣化。

Shiny Frog 最終選擇了折衷方案：維持精雕細琢的 SQLite/CoreData 底層，但對外提供媲美純文字體驗的現代化 CLI 與安全代理工具層。有了 bearcli，工程師在終端機中透過 bearcli search 或 bearcli cat，便能獲得與 rg、cat 極為接近的操作感受，縮減了長期以來的自動化鴻溝。

AI 戰略突圍：原生 MCP Server 與標籤沙盒隔離

除了追趕本地終端機操作體驗，AI Agent 的普及是促成 Bear 推出原生 CLI 的另一個關鍵動力。

為什麼 Agent 時代需要 MCP？

在 2024 至 2026 年間，大模型應用已從單純的聊天對話，演進為能自主規劃並呼叫外部工具的 AI Agents（如 Claude Desktop、Claude Code、Cursor 等）。對於知識工作者而言，AI 的重要定位之一是成為個人筆記庫的專屬助理。

在純文字架構下，Obsidian 天然適合 AI Agent：模型可直接將 Vault 目錄掛載為工作區，也可透過官方 Obsidian CLI 搜尋、讀取與修改筆記。

CLI 需連線至執行中的桌面版 Obsidian，與 Bear 的 MCP Server 並非相同介面；若 Bear 依然無法提供可程式化的結構化介面，仍可能在個人知識助理的建構中失去立足點。

bearcli mcp-server 的架構特色

bearcli 原生支援了 Anthropic 推動的開源協定標準——Model Context Protocol (MCP)。它內建了完整的 MCP 伺服器，直接透過標準輸入/輸出（stdio）以 JSON-RPC 2.0 協定運作：

bearcli mcp-server [--only-tags <tags>] [--exclude-tags <tags>]

這項實作具備三項關鍵設計：

1. 細粒度標籤沙盒（Tag Scoping）：AI 存取個人筆記最大的疑慮是隱私洩漏。透過 --only-tags dev,work，可強制 AI 只能讀取特定標籤及其子標籤下的筆記，若試圖存取私人日記則直接回傳 out_of_scope；搭配 --exclude-tags private，敏感筆記對模型完全不可見。
2. 意圖提示與破壞性操作閘門（Intent Hints）：伺服器宣告的每個工具皆標註了 readOnlyHint 與 destructiveHint metadata。相容用戶端在 Agent 試圖呼叫刪除（trash）或覆寫（overwrite）工具時，會依這些標註攔截並要求人類授權。
3. 選單單鍵安裝 Claude Connector：Bear 在應用程式選單提供「Help -> Advanced -> Install Claude Connector」，點選後自動完成 MCP 設定與掛載（官方強調無需手動編輯任何設定檔），數秒內即可完成。

實務應用：社群高價值終端機工作流程

自 bearcli 發布以來，社群開發者在論壇與開源專案中實踐了大量提升生產力的高價值應用情境。

情境 1：Claude Code / Cursor 開發環境無縫取用

工程師在終端機撰寫程式碼時，常需調閱先前記錄在 Bear 中的內部架構決策（ADR）或環境設定備忘。透過在 Claude Desktop 設定檔（claude_desktop_config.json）或專案級 .mcp.json 中加入 MCP 宣告：

{
  "mcpServers": {
    "bear-notes": {
      "command": "/Applications/Bear.app/Contents/MacOS/bearcli",
      "args": [
        "mcp-server",
        "--only-tags",
        "tech,dev,architecture"
      ]
    }
  }
}

開發者在終端機中只需對 Claude 下達自然語言指令：

「查閱我在 Bear 裡標籤為 #tech 的筆記，找出 staging 環境的 Redis 連線規則，並幫我寫入目前的 .env.example。」

Claude 即可透過 MCP 自動搜尋並讀取筆記，完全無需在視窗間切換或手動複製貼上。

情境 2：終端機快速靜默捕捉（Silent Quick Capture）

在終端機遇到重要日誌、指令輸出，或想快速將剪貼簿內容存入筆記時，可透過極簡的 Shell 函式達成背景捕捉：

# 快速將剪貼簿內容存入 Bear 臨時收集箱
bclip() {
  local title="${1:-Clipboard Capture $(date '+%Y-%m-%d %H:%M')}"
  pbpaste | bearcli create "$title" --tags "inbox/quick" --content -
  echo "✓ Saved clipboard to Bear: $title"
}

# 將指令管線輸出直接追加到特定筆記區段
bnote() {
  local title="$1" section="$2"
  bearcli append --title "$title" --section "$section" --content -
}

所有操作皆在背景毫秒級完成，不跳出任何 GUI 視窗，徹底保證工作心流不中斷。

情境 3：每日工作紀錄自動化追加

利用 macOS 的 launchd 或 cron，結合 Git 提交歷史與 bearcli，可在每日傍晚自動彙整當天工作：

#!/usr/bin/env bash
TODAY=$(date '+%Y-%m-%d')
NOTE_TITLE="Daily Log $TODAY"

# 確保今日筆記存在
if ! bearcli search --query "@title \"$NOTE_TITLE\"" --count | grep -q "1"; then
  bearcli create "$NOTE_TITLE" --tags "journal/daily" \
    --content "# $NOTE_TITLE\n\n## Standup\n- [ ] Morning sync\n\n## Git Commits Today\n\n## Completed Tasks\n"
fi

# 抓取今天在指定專案目錄下的所有提交紀錄
COMMITS=$(git -C "$HOME/Projects/repo" log --since="midnight" --oneline --author="$(git config user.name)")
[ -n "$COMMITS" ] && bearcli append --title "$NOTE_TITLE" --section "## Git Commits Today" --content "$COMMITS"

情境 4：筆記基礎設施即程式碼與排版檢查

在社群工具方面，開源專案 noxctl 將 bearcli 作為驅動核心，實踐了「筆記基礎設施即程式碼（Notes as Code）」。

它以 noxctl.toml 宣告標籤、主記錄與樞紐結構，冪等地將筆記庫收斂到宣告狀態，自動生成主記錄與樞紐筆記，並在每篇受管筆記頂端寫入規範的 tag-line，讓雙向連結自動成立；其 audit/lint 則檢查損壞的 H1 標題、格式錯誤的 canonical 行、孤兒筆記與重複標題。

另一款開源工具 BearKit（原名 bear-lint）則透過 bearcli cat --format json 走訪庫存 Markdown，自動檢查失效連結（指向不存在筆記的維基連結）與格式錯誤的標籤，並透過 bearcli overwrite（附 --base hash 核對）批次修正語法異常。

選型決策：Bear 搭配 bearcli vs. Obsidian

bearcli 並非企圖將 Bear 改造為另一個 Obsidian，而是在保有產品獨特質感的同時，補齊現代技術環境不可或缺的互操作性。

全方位技術對比矩陣

給技術工作者的決策指引

在當前的工具版圖中，兩者適合截然不同的工作模式：

• 適合選擇 Bear 搭配 bearcli 的族群：主力工作環境深度處於 Apple 生態系，對字體排版渲染、原生微互動與隨手記錄手感有極高要求；過去因缺乏自動化或無法整合 AI 而卻步；或需要使用 Claude 等 AI Agent 輔助工作，但高度重視個人隱私、要求透過 --only-tags 嚴格沙盒隔離知識庫的技術工作者。
• 依然建議選擇 Obsidian 的族群：工作環境包含 Linux 或 Windows 系統，跨平台為不可妥協的剛性需求；筆記庫重度依賴 Dataview、Canvas、Excalidraw 等外掛建構的複雜資料庫工作流；堅守 純文字本位主義，無法接受任何非純檔案目錄儲存結構的使用者。

bearcli 與 MCP 的加入，讓深耕 Apple 生態的開發者在保有原生介面質感的同時，補齊了終端機操作與 AI 工具鏈的最後一哩路。