Firescope 使用手冊

安裝

1. 從下載頁面取得 Mac 版的.dmg(可選擇 Apple Silicon / Intel)。
2. 開啟下載的 .dmg,將 Firescope 圖示拖曳到「應用程式」資料夾。
3. 從應用程式資料夾啟動 Firescope。

Windows

1. 從下載頁面取得 Firescope-Setup.exe並執行。
2. 首次執行若出現 SmartScreen 警告,請點選「其他資訊」→「仍要執行」繼續。

初始設定(語言與主題)

首次啟動時,會開啟 4 個步驟的設定畫面。首先選擇顯示語言(內建日文・English・简体中文・繁體中文・한국어・Español・Português・Français・Deutsch 共 9 種語言)。點選後畫面會立即套用,猶豫的話按按看就知道了。

接著選擇外觀主題。包含 Light / Dark 在內共 10 種,同樣點選後就能即時預覽。

連接 Firestore

連線方式有兩種。比較簡單的是以 Google 帳戶登入,不需要事先準備金鑰檔案。當然也可以照以往的做法使用服務帳戶私密金鑰(JSON)。

方式 1:以 Google 帳戶登入

用您平常的 Google 帳戶驗證 Firescope,接著從有權存取的 Firebase 專案清單中選取即可完成連線。不需要下載金鑰檔案,也不必費心保管。

1. 在新增連線對話方塊的「Google」分頁點選「以 Google 登入」,瀏覽器就會開啟同意畫面。
2. 回到應用程式後,會列出您有權存取的 Firebase 專案。可以用搜尋縮小範圍,也可以用「全選顯示中的 N 個項目」一次選取。已經連線過的專案無法選取(為避免重複登錄,會顯示為「已連線」)。
3. 為選取的每個專案指定環境標籤與唯讀設定。環境標籤會依專案 ID 自動推測,只要修正推測有誤的項目即可。
4. 點選「新增 N 個連線」完成。

方式 2:使用服務帳戶私密金鑰(JSON)

如果想使用 CI 專用的服務帳戶,或不想透過 Google 帳戶連線,請採用這個方式。就算目前沒有金鑰,按照畫面指示操作,大約 1 分鐘就能取得。

1. 點選「開啟服務帳戶設定頁面」,會在瀏覽器開啟 Firebase 主控台的對應頁面(位置:專案設定 → 服務帳戶)。
2. 點選「產生新的私密金鑰」下載 JSON 檔。
3. 回到 Firescope,從「選擇 JSON 檔案並連線」選取剛下載的 JSON。也可以一次選取多個專案的 JSON同時連線。
4. 選擇連線的環境(開發 / 測試 / 預備 / 正式)。 會以彩色標籤顯示在側邊欄,安全防護的強度也由此標籤決定。

整理連線(群組與隱藏)

連線一多,就很難分辨側邊欄裡哪一項對應哪個專案。Firescope 會在您完全不必動手排序的情況下,自動加上標題分類整理。

自動分區

連線首先會依使用哪種驗證資訊連線來分區。

• Google 帳戶 — 會依登入的帳戶分開。即使同時使用多個帳戶,也能一眼看出連線來自哪一個
• AdminSDK 金鑰 — 依各個服務帳戶私密金鑰分開
• 模擬器 — 本機的 Firestore 模擬器連線

在各分區之中,還會再依連線名稱的共通部分歸類。由於比對時會先去除結尾的dev / staging / production / test / env 等代表環境的字詞,因此OCEAN-dev、ocean-pro、OCEAN-staging、OCEAN-test 會歸在 OCEAN 這一個標題底下(不區分大小寫)。

隱藏不常用的連線

您可以在不中斷連線的情況下,將它從清單中隱藏。設定與金鑰都會原封不動保留,隨時可以還原。

1. 在連線上按右鍵 →「隱藏這個連線」。 從群組標題可以選擇「隱藏這個群組」, 多選(⌘ / Shift 點擊)時則可以選擇「隱藏選取的連線」。
2. 有隱藏項目時,側邊欄上方會出現眼睛圖示(附帶數量標記)。
3. 點選該圖示,被隱藏的連線就會以淡色顯示。按右鍵 →「重新顯示」即可還原。也可以依群組或多選一次還原。

瀏覽資料

開啟側邊欄的連線並點擊集合,文件就會以表格顯示。每個欄位的標題都會附上型別標籤(string / int / time 等),資料的結構一看就懂。

• 點擊列,右側面板會顯示文件的所有欄位。
• 排序、顯示筆數、群組搜尋(集合群組)都可以在工具列變更。
• 讀取筆數會持續顯示在狀態列(可作為計費的參考)。

命令選擇區(⌘K)

按下 ⌘K 就能在任何畫面呼叫出跨集合搜尋。可以一次搜尋集合名稱、連線名稱、畫面、「最近瀏覽」/ 書籤,只要輸入6 個字元以上的字串,還會出現以文件 ID 跨集合搜尋的候選項目。

• 用 ↑↓ 移動候選項目,按 Enter 執行。不需要移動滑鼠就能切換畫面。
• 切換主題、開關值遮罩、開啟設定與快捷鍵一覽等常用操作,也都可以從這裡呼叫。

表格內搜尋(⌘F)

在開啟表格的狀態下按 ⌘F(Windows 為 Ctrl+F),即可對表格內所有儲存格進行部分符合搜尋。符合的儲存格會以琥珀色醒目標示, 每按一次 Enter,游標就會平滑捲動到下一個符合位置。

• 包含 ID 在內的所有顯示欄位都在搜尋範圍內(不區分大小寫)。
• 按 Enter 移至下一個,Shift+Enter 移至上一個。到達結尾後會回到開頭。
• 符合的儲存格會直接進入選取狀態,可以接著用方向鍵移動,或用 ⌘C、F2 繼續編輯。
• 在載入全部資料之前,只會搜尋已載入的範圍(筆數旁會顯示 *)。
• 側邊欄的集合搜尋改為 ⌘⇧F(在沒有開啟表格的畫面,按 ⌘F 也和以往一樣可以移動)。

查詢功能強化

組合好的查詢條件可以命名為已儲存查詢儲存起來,之後隨時可以從清單中呼叫(條件、排序、筆數會一併還原)。

選擇數值(int / double)欄位後,工具列會顯示套用目前篩選條件後的合計與平均值。

「圖表」功能會根據目前已載入的文件,將數值欄位繪製成長條圖,字串/enum 欄位則繪製成出現頻率圖(前 10 名),即時呈現且不會產生額外的讀取。

「產生程式碼」功能可以將組合好的條件複製為 firebase-admin(Node.js)程式碼,若條件需要複合索引,也能複製為firestore.indexes.json 格式的定義。

邏輯名稱(欄位名稱翻譯顯示)

可以將像 carryingOutCoffinMasterId 這樣的英文欄位名稱,改以中文等邏輯名稱顯示。透過工具列的「邏輯名稱」切換開關,隨時都能切換實際名稱⇔邏輯名稱。

• 辭典可從工具列的 📖 圖示編輯。適用範圍分為「整個連線共用」與「僅此集合(覆寫)」兩層。
• 透過「自動翻譯」,可利用內建辭典 + 免費翻譯 API 一次填入空白欄位。
• 點選「開啟 Google 翻譯」,會以英文化的欄位名稱開啟翻譯頁面,只要複製譯文回到應用程式,就能一次套用。
• 在欄標題按右鍵 →「設定邏輯名稱…」,即可立即編輯該欄位。
• 標題的型別標籤(string / int 等)可透過「顯示型別」切換開關來顯示/隱藏。

分頁與群組

在集合上按右鍵 →「在新分頁中開啟」,就能像瀏覽器一樣新增分頁。分頁可以像 Chrome 一樣整理成群組。

• 在分頁上按右鍵 →「加入新群組」建立群組,可以設定名稱與顏色。
• 點擊群組標籤即可摺疊/展開。
• 雙擊分頁即可變更名稱與背景顏色。
• 拖放即可重新排序,或加入/移出群組。
• 重新啟動後仍會還原分頁狀態(可在設定中關閉)。

分割檢視

在集合上按右鍵 →「在右側分割顯示」,即可將兩個集合左右並排。方便用來核對主檔與交易紀錄。

• 也可以從側邊欄將集合拖曳到畫面左右邊緣來分割顯示。
• 拖曳窗格的標籤,即可左右交換或取出成新分頁。
• 分割狀態會依分頁各自保留。

即時監看

點選工具列的「監看」,目前顯示集合的變更就會即時反映到表格中。即使是其他應用程式或伺服器寫入的內容,也不需重新整理就能直接顯示。

• 開始前的對話框中,可以依條件(欄位・數值)、排序、筆數縮小範圍。
• 右側的變更動態會依時間順序列出「新增 / 更新 / 刪除」,也會顯示變更的欄位名稱。
• 監看本身是唯讀的。監看期間的寫入操作,一樣會照常經過安全管線。
• 最多可同時監看 5 個項目。
• 經過指定時間後會自動停止(可在設定中變更時間),避免過度耗用讀取次數。

編輯資料

雙擊儲存格即可就地編輯。Enter 確認,Esc 取消。 int、timestamp 等型別會在寫入時保持不變。

所有寫入都會經過安全管線:

1. 確認 — 會依環境標籤 × 操作危險度顯示對話框。正式環境的破壞性操作,需要輸入專案 ID。
2. 自動備份 — 受影響的文件會在執行前建立快照。
3. 執行 — 進行寫入。
4. 操作紀錄 — 無論成功或失敗都會被記錄(可在底部列的「操作紀錄」查看)。

備份與還原

在破壞性操作前建立的快照,會累積在底部列的「備份」中。點選後會開啟還原預覽,確認重新建立 / 覆寫 / 無變更的差異後再進行還原。

• 使用 ⌘Z(或側邊欄的 ↩︎ 圖示)可以立即還原最近一次寫入。
• 快照數量超過上限後,會從最舊的開始刪除。想保留的可以釘選 📌。

主控台

側邊欄的「主控台」可以用 firebase-admin 風格的 JavaScript 撰寫查詢。按下 ⌘Enter 執行後,結果會以標註型別的表格顯示。

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

• 偏好用滑鼠操作的話,也有視覺化建構工具(取得 / 更新 / 新增 / 刪除)。組好的條件可透過「反映到程式碼」轉換成 JS。
• 包含寫入的程式碼,會依試跑 → 寫入預覽 → 套用的順序執行,資料不會突然被改變。
• 也支援 join(關聯)顯示。

CSV 匯入匯出

匯出

在集合工具列點選「CSV 匯出」,即可將目前顯示的查詢結果(已套用篩選與排序)儲存為 CSV。標題列會附上型別標註,之後重新匯入也不會破壞型別。

匯入

1. 點選工具列的「匯入」→ 選擇 CSV 檔案(可自動判別 Shift_JIS 編碼)。
2. 確認每欄的型別,以及模式(upsert / 僅新增 / 僅更新)。
3. 點選「確認筆數」預覽新增與覆寫的筆數。
4. 點選「執行匯入」→ 經過確認對話框後完成匯入。將被覆寫的部分,會在執行前自動備份。

結構檢查(偵測結構異常)

在集合上按右鍵 →「結構檢查…」,即可讀取整個集合,自動偵測型別混雜的欄位、僅部分文件缺少的欄位,以及可能是打字錯誤的罕見欄位(上限 20,000 筆)。

• 同一批文件中共同缺少的欄位,會彙整成一張卡片。點選「全部開啟」即可勾選所有相關列,直接進行批次刪除等操作。
• 點擊對應文件的 ID,表格會自動捲動到該列並反白顯示。
• 即使關閉精靈,結果也會被保留,可以一邊確認文件一邊反覆來回查看。
• 在Zod 結構驗證分頁中,可以貼上 Zod 結構(TypeScript)來驗證所有文件。

以結構保護寫入

在結構檢查的「Zod 結構驗證」分頁中,除了驗證之外,還能設定寫入時的強制檢查。可從無 / 警告 / 封鎖三個等級中選擇,設為封鎖後,違反結構的寫入會在主行程(main process)被拒絕(即使繞過 UI 也無法避開)。強制檢查只會套用在完全符合該集合路徑的文件上。

只要註冊 Zod 結構,新增文件時就能使用「表單輸入」模式。表單會依結構的型別自動產生,不需要手動撰寫 JSON,只要填寫必填欄位即可建立文件(尚未註冊結構的集合,也可以從結構檢查推測出的型別來組成表單)。

匯出ER圖

右鍵側邊欄中的連線 → 「匯出ER圖…」,對每個集合取樣(各最多100筆)並自動產生ER圖。除 reference 欄位與子集合外,像 customerId 這樣的字串ID參照也會依欄位名稱推斷,並以虛線關聯繪製。

• 「顯示欄位」「僅鍵名」「顯示型別」「包含邏輯名稱」點擊即切換(所有模式皆已預先產生,無需等待)。
• 捏合或 Ctrl+滾輪縮放,拖曳平移,一鍵回到整體檢視。
• 支援複製 Mermaid 文字、儲存為 .mmd / .svg——可直接貼到 GitHub 或 Notion。
• 為便於閱讀,指向擁有大量子集合的父集合的連線在圖中省略(Mermaid 文字中保留)。

資料遷移

「批次更新」除了可以批次設定欄位值之外,還能變更欄位名稱、轉換型別。執行前務必先用 dry-run 預覽確認全部筆數的差異,再進行執行。

在集合上按右鍵 →「刪除集合…」會連同子集合一併遞迴刪除。確認對話方塊中的筆數也包含子集合,執行前會自動為目標文件建立快照。

「產生種子資料」會根據現有文件的型別分布(結構檢查)推測欄位結構,並一次建立指定數量的假資料文件。適合用於開發或模擬器環境的動作驗證。

環境比較與複製

與其他環境比較

在集合上按右鍵 →「與其他環境比較…」,即可核對兩個環境中同名的集合(例如開發與正式)。差異(新增 / 刪除 / 變更)會以文件與欄位為單位列出。

• 可以指定像 updatedAt 這類要從比較中排除的欄位。
• 差異內容可以匯出為 CSV。

複製到其他環境

透過「複製到其他環境…」,可以將集合複製到另一個連線(環境)。執行前會預覽筆數與是否覆寫,寫入正式環境時,一樣會經過嚴格的確認防護。

比較與差異

環境比較也支援差異同步:選取差異(內容不同/僅單側存在的文件)後,可以直接反映到目標連線。同步方向會依連線的環境標籤提出建議,反映時一樣會經過安全管線(確認・自動備份)。

在文件右側面板的「比較」按鈕,可以將目前開啟的文件與任意文件(可跨集合、跨連線)以欄位為單位進行比較。

文件的「變更歷史」會將自動備份依版本按時間順序排列,可以選取任意兩個版本(包含目前版本)來比較差異。

Authentication 使用者

從側邊欄的「Authentication」,可以列出並管理 Firebase Authentication 的使用者。

• 以列表顯示電子郵件、顯示名稱、提供者、建立日期、最後登入時間。透過邏輯名稱切換開關,也能以中文顯示欄位名稱。
• 支援使用者的停用 / 啟用、刪除,以及發送重設密碼的電子郵件。
• 可以複製使用者的 UID,用來與 Firestore 端的文件核對。
• 破壞性操作(如刪除)會經過與 Firestore 相同的安全管線(確認 → 操作紀錄)。

共享日誌(誰・何時・做了什麼)

將寫入操作的中繼資料記錄到專案的 Firestore,連線同一專案的所有人都能看到「誰在何時做了什麼」。

• 按連線啟用: 在側邊欄右鍵連線 →「記錄共享日誌」。確認對話方塊會說明詳情,並可當場設定操作者顯示名稱。
• 僅記錄中繼資料(操作者名稱・操作類型・目標路徑・結果・耗時)。絕不包含文件的值,也不會傳送到外部伺服器 — 事件保存在該專案的 _firescope_audit 集合中。
• 在 操作日誌 →「共享日誌」分頁查看: 按日期分組的時間軸,支援操作者/類型/期間篩選。點一下列查看詳情,並可直接在網格中開啟目標文件。
• 日誌超過30天後自動刪除。

搜尋與分享

「數值搜尋」可以在不知道值位於哪個欄位的情況下,從集合內所有文件、所有欄位中尋找。執行前會顯示讀取筆數的估算值,即使是大型集合也能安心使用。

將文件加上★ 書籤後,即可從側邊欄的 ★ 圖示跨連線隨時呼叫。「最近瀏覽」分頁則會自動保留開啟過的歷史紀錄。

• 從文件右側面板的「連結」可以複製深層連結(firescope://),在 Slack 等工具分享後,對方的 Firescope 就能直接開啟該文件。
• 點選麵包屑上的外部連結圖示,即可直接跳轉到 Firebase 主控台(網頁版)的對應路徑(模擬器連線時不會顯示)。

維運

即時監看可以設定條件式警示。只要註冊「新增時」「刪除時」「指定欄位變更時」,符合條件的變更就會發送桌面通知。

點擊頁尾的讀取次數,即可在彈出視窗中查看本次工作階段的概略讀取筆數、概略計費金額與變化趨勢。

在設定的「共享與轉移」分頁,可以將欄位邏輯名稱、已儲存查詢、書籤等部分 UI 設定匯出/匯入成一個 JSON 檔案。由於完全不包含連線的私密金鑰、授權資訊、環境標籤,適合用於團隊共享或更換裝置。

開啟工具列的「隱藏值」後,會在保留欄位名稱、型別、結構的狀態下,將實際資料以遮罩符號(••••)顯示。適合在畫面分享或截圖時使用(僅為顯示上的功能,不會變更實際資料)。

MCP 伺服器(AI 代理整合)

Firescope 內建了 MCP(Model Context Protocol) 伺服器。從 Claude Code 等 AI 代理連接後,就能在對話中直接列出 Firestore 的集合清單、取得文件、執行查詢。

啟動方式(於儲存庫根目錄執行):

# 連接模擬器時
FIRESCOPE_MCP_PROJECT_ID=your-project \
FIRESCOPE_MCP_EMULATOR_HOST=127.0.0.1:8080 \
npm run mcp

# 透過服務帳戶 JSON 連接正式專案時
FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH=/path/to/service-account.json \
npm run mcp

MCP 用戶端的設定範例(.mcp.json):

{
  "mcpServers": {
    "firescope": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/firescope",
      "env": {
        "FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json"
      }
    }
  }
}

• 提供的工具共 3 個:集合清單(firestore_list_collections)、取得文件(firestore_get_document)、執行查詢(firestore_query_collection,支援篩選/排序/筆數上限)。
• 由於重用了與 GUI 查詢建構工具相同的內部邏輯,結果的格式會與應用程式的顯示一致。

更新

• 更新會每 6 小時 + 每次啟動時自動檢查(也可以在「設定 → 關於」的「檢查更新」手動確認)。
• 若釋出必要更新,啟動時的更新畫面會自動下載 → 重新啟動 → 套用,全程無需按任何按鈕。
• 只有在失敗時(例如離線),才會引導您透過瀏覽器手動下載。

價格與授權

• 從首次啟動起 14 天為試用期,可使用所有功能。免註冊、免付款資訊。
• 即使試用期結束,資料的瀏覽功能仍可繼續免費使用。
• 購買可在應用程式內完成:於右下角的 ⚙ 設定 → 授權選擇方案(Pro / TEAM,月繳 / 年繳),即會在瀏覽器開啟 Stripe 的付款頁面。付款完成後,應用程式會自動啟用授權。
• 更換到另一台 Mac 時,請先在舊機器上「解除授權」,再於新機器上啟用。

方案的詳細內容,請參閱價格頁面。

常見問題

無法連線 / 出現「驗證失敗」

請確認 JSON 是否為目標專案的服務帳戶金鑰。若重新產生過金鑰,建議先中斷舊的連線,再用新的 JSON 重新連線,較為保險。

資料會被傳送到其他地方嗎?

不會。Firescope 會從您的 Mac 直接存取 Firestore 。金鑰與資料都不會傳送到外部伺服器。

「正式環境防護」是做什麼的?

這是依連線的環境標籤與操作危險度,自動調整確認強度的機制。例如在正式環境刪除集合時,若不手動輸入專案ID 就無法執行。由於驗證是在應用程式的核心(主行程)進行,而不是 UI 上的提醒文字,因此不會因為一時疏忽而被繞過。

有 Windows 版嗎?

有的。請從下載頁面取得Firescope-Setup.exe(若出現 SmartScreen 警告,請點選「其他資訊」→「仍要執行」繼續)。

可以新增語言嗎?

可以。從設定 → 語言匯出語言包(JSON)進行翻譯,再匯入即可新增任意語言。