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 账号完成认证,只需从有权限访问的 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 等),数据结构一目了然。

• 点击一行,右侧面板会显示该文档的全部字段。
• 排序方式、显示条数、分组搜索(集合组)都可以在工具栏中更改。
• 读取次数会一直显示在状态栏(作为计费用量的参考)。

逻辑名称(字段名翻译显示)

可以将 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)来校验全部文档。

环境对比与复制

与其他环境对比

右键点击集合 →“与其他环境对比…”,即可比较开发和生产等两个环境下同名的集合。差异(新增 / 删除 / 变更)会按文档和字段列出。

• 可以指定 updatedAt 等要从对比中排除的字段。
• 差异内容可以导出为 CSV。

复制到其他环境

通过“复制到其他环境…”,可以将集合复制到另一个连接(环境)。执行前会预览数量以及是否存在覆盖,写入生产环境时依然会经过与平时相同的严格确认防护。

Authentication 用户

在侧边栏的“Authentication”中,可以查看和管理 Firebase Authentication 的用户。

• 列表显示邮箱、显示名称、登录方式、创建日期和最后登录时间。也可通过逻辑名称开关以中文显示字段名。
• 支持对用户进行禁用 / 启用 / 删除,以及发送密码重置邮件。
• 可以复制用户的 UID,用于与 Firestore 中的文档进行核对。
• 破坏性操作(如删除)同样会经过与 Firestore 相同的安全流水线(确认 → 操作日志)。

共享日志(谁・何时・做了什么)

将写入操作的元数据记录到项目的 Firestore,连接同一项目的所有人都能看到「谁在何时做了什么」。

• 按连接启用: 在侧边栏右键连接 →「记录共享日志」。确认对话框会说明详情,并可当场设置操作者显示名称。
• 仅记录元数据(操作者名称・操作类型・目标路径・结果・耗时)。绝不包含文档的值,也不会发送到外部服务器 — 事件保存在该项目的 _firescope_audit 集合中。
• 在 操作日志 →「共享日志」标签页查看: 按日期分组的时间线,支持操作者/类型/期间筛选。点击行查看详情,并可直接在网格中打开目标文档。
• 日志超过30天后自动删除。

更新

• 系统会每 6 小时以及每次启动时自动检查更新(也可以在“设置 → 关于”中点击“检查更新”手动检查)。
• 如果发布了强制更新,启动时的更新界面会自动完成下载 → 重启 → 应用,无需任何点击操作。
• 仅在失败时(例如离线),才会提示通过浏览器手动下载。

价格与许可

• 首次启动起的 14 天为试用期,可使用全部功能。无需注册,也无需支付信息。
• 即使试用到期,数据的浏览功能依然可以免费继续使用。
• 购买可在应用内完成:点击右下角的 ⚙ 设置 → 许可证,选择套餐(Pro / TEAM,月付 / 年付)后,会在浏览器中打开 Stripe 的结算页面。支付完成后,应用会自动激活许可证。
• 更换到另一台 Mac 时,请先在旧设备上“解除许可证”,再在新设备上激活。

套餐详情请参阅价格页面。

常见问题

无法连接 / 显示“认证失败”

请确认该 JSON 是否为目标项目的服务账号密钥。如果重新生成过密钥,建议断开旧连接后使用新的 JSON 重新连接,更加保险。

数据会被发送到其他地方吗?

不会。Firescope 会直接从你的 Mac 访问 Firestore 。密钥和数据都不会发送到外部服务器。

“生产环境防护”具体是做什么的?

这是一种根据连接的环境标签和操作风险,自动调整确认强度的机制。例如在生产环境删除集合时,必须手动输入项目 ID 才能执行。由于验证是在应用核心(主进程)而非界面提示层面完成的,因此不会因为疏忽而被绕过。

有 Windows 版吗?

有。请从下载页面获取Firescope-Setup.exe(如果出现 SmartScreen 警告,请点击“更多信息”→“仍要运行”继续)。

可以添加其他语言吗?

可以。在设置 → 语言中导出语言包(JSON)进行翻译,再导入即可添加任意语言。

命令面板(⌘K)

按 ⌘K 即可随时随地呼出跨集合搜索。可以一次性搜索集合名称・连接名称・界面・「最近查看」/ 书签,输入6 个字符以上的字符串时,还会出现按文档 ID 进行跨集合搜索的候选项。

• 用 ↑↓ 移动候选项,按 Enter 执行。无需将手伸向鼠标即可切换界面。
• 切换主题、开关值遮罩,打开设置和快捷键列表等常用操作,也都可以从这里调用。

表格内搜索(⌘F)

打开表格后按 ⌘F(Windows 为 Ctrl+F),即可对表格中的所有单元格进行跨列的部分匹配搜索。命中的单元格会以琥珀色高亮显示,每按一次Enter,光标就会平滑滚动到下一个命中位置。

• 包括 ID 在内的所有显示列都在搜索范围内(不区分大小写)。
• 按 Enter 跳到下一个,按 Shift+Enter 跳到上一个。到达末尾后会回到开头。
• 命中的单元格会保持选中状态,可以继续用方向键移动,或用 ⌘C・F2 进行编辑。
• 在全部数据加载完成之前,只会搜索已加载的范围(条数旁边会显示 *)。
• 侧边栏的集合搜索快捷键已改为 ⌘⇧F(在没有打开表格的界面上,按 ⌘F 也和以前一样可以跳转)。

查询增强

构建好的查询条件可以命名保存为保存的查询,随时从列表中调用(条件・排序・数量会一并恢复)。

选择数值(int / double)字段后,工具栏会显示当前筛选条件下的总和与平均值。

「图表」功能会根据已加载的文档,将数值字段绘制为直方图,将字符串/枚举字段绘制为出现频率(前10名)。不会产生额外的读取。

「代码生成」功能可以将构建好的条件复制为 firebase-admin(Node.js)代码,如果条件需要复合索引,也可以复制为firestore.indexes.json 格式的定义。

用架构守护写入

在架构检查的「Zod 架构校验」标签页中,不仅可以校验,还可以设置写入时的强制级别。可从无 / 警告 / 阻止三档中选择,选择阻止后,主进程会拒绝违反架构的写入(即使绕过界面也无法避开)。强制仅适用于与该集合路径完全一致的文档。

注册 Zod 架构后,新建文档时即可使用「表单输入」模式。表单会根据架构的类型自动生成,无需手写 JSON,只需填写必填项即可创建(对于尚未注册架构的集合,也可以根据架构检查推断出的类型来构建表单)。

导出ER图

右键侧边栏中的连接 → 「导出ER图…」,对每个集合进行采样(各最多100条)并自动生成ER图。除 reference 字段和子集合外,像 customerId 这样的字符串ID引用也会根据字段名推断,并以虚线关系绘制。

• 「显示字段」「仅键名」「显示类型」「包含逻辑名称」点击即切换(所有模式均已预先生成,无需等待)。
• 捏合或 Ctrl+滚轮缩放,拖拽平移,一键回到整体视图。
• 支持复制 Mermaid 文本、保存为 .mmd / .svg——可直接粘贴到 GitHub 或 Notion。
• 为便于阅读,指向拥有大量子集合的父集合的连线在图中省略(Mermaid 文本中保留)。

数据迁移

「批量更新」除了可以批量设置字段之外,还可以变更字段名称・进行类型转换。执行前请务必先用 dry-run 预览确认全部文档的 diff,再执行。

右键点击集合 →「删除集合…」会连同子集合一起递归删除。确认对话框中的数量也包含子集合部分,执行前会自动为目标文档生成快照。

「生成种子数据」会根据现有文档的类型分布(架构检查)推断字段结构,一次性批量创建指定数量的虚拟文档。适用于开发・模拟器环境下的功能验证。

对比与差异

环境对比也支持将差异(内容不同/仅存在于一侧的文档)选中后直接反映到目标环境的差异同步。同步方向会根据连接的环境标签给出建议,反映过程照常经过安全流水线(确认・自动备份)。

文档右侧面板的「对比」按钮,可以按字段将当前打开的文档与任意文档(也可以是其他集合、其他连接)进行比较。

文档的「变更历史」会将自动备份作为版本按时间顺序排列,可以选择任意两个版本(包括当前版本)比较差异。

查找与共享

「值搜索」可以在集合内的所有文档、所有字段中,查找不确定位于哪个字段的值。执行前会显示读取次数的预估,即使是大型集合也可以放心使用。

将文档加入 ★ 书签后,可以随时通过侧边栏的 ★ 图标跨连接调用。「最近查看」标签页会自动保留打开过的历史记录。

• 在文档右侧面板的「链接」中可以复制深层链接(firescope://),通过 Slack 等分享后,对方可以在自己的 Firescope 中直接打开该文档。
• 点击面包屑导航的外部链接图标,即可直接跳转到 Firebase 控制台(网页版)中对应的路径(使用模拟器连接时不显示)。

运维

可以为实时监控设置条件警报。预先注册「新增时」「删除时」「指定字段变化时」,一旦发生匹配的变更,就会收到桌面通知。

点击底部栏的读取次数,会以弹出框的形式显示本次会话中的预估读取次数・预估计费金额及其变化趋势。

在设置的「共享・迁移」标签页中,可以将字段逻辑名称・保存的查询・书签等部分界面设置导出为一个 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 查询构建器相同的内部逻辑,返回结果的形式与应用界面显示一致。