# https://github.com/firebase/firebase-tools 项目说明书 生成时间：2026-06-06 07:39:34 UTC ## 目录 - [Overview and System Architecture](#page-1) - [Deployment Pipeline and Release Lifecycle](#page-2) - [Emulators, Local Development and Common Failure Modes](#page-3) - [MCP Server, AI Tools and VS Code Extension](#page-4) ## Overview and System Architecture ### 相关页面 相关主题：[Deployment Pipeline and Release Lifecycle](#page-2), [Emulators, Local Development and Common Failure Modes](#page-3), [MCP Server, AI Tools and VS Code Extension](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/firebase/firebase-tools/blob/main/README.md) - [package.json](https://github.com/firebase/firebase-tools/blob/main/package.json) - [src/mcp/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) - [src/mcp/antigravity/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/antigravity/README.md) - [src/emulator/auth/README.md](https://github.com/firebase/firebase-tools/blob/main/src/emulator/auth/README.md) - [firebase-vscode/src/data-connect/explorer-provider.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/explorer-provider.ts) - [firebase-vscode/src/data-connect/code-lens-provider.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) - [firebase-vscode/src/data-connect/ad-hoc-mutations.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/ad-hoc-mutations.ts) - [scripts/agent-evals/src/runner/gemini-cli-runner.ts](https://github.com/firebase/firebase-tools/blob/main/scripts/agent-evals/src/runner/gemini-cli-runner.ts) - [scripts/agent-evals/src/mock/tool-mock-utils.ts](https://github.com/firebase/firebase-tools/blob/main/scripts/agent-evals/src/mock/tool-mock-utils.ts) - [scripts/mcp-tests/package.json](https://github.com/firebase/firebase-tools/blob/main/scripts/mcp-tests/package.json) - [scripts/webframeworks-deploy-tests/angular/src/index.html](https://github.com/firebase/firebase-tools/blob/main/scripts/webframeworks-deploy-tests/angular/src/index.html)
# Overview and System Architecture ## 项目定位与目标 `firebase-tools` 是 Firebase 官方发布的统一命令行工具集（CLI），面向开发者在本地与云端之间提供项目管理、部署与模拟运行等能力。其根目录的 [package.json](https://github.com/firebase/firebase-tools/blob/main/package.json) 声明支持 Node.js 20/22/24，并以 `preferGlobal: true` 引导全局安装；该 npm 包发布到 Firebase 自有 Registry `wombat-dressing-room.appspot.com` [资料来源：[package.json:25-55]()]. 主入口的 [README.md](https://github.com/firebase/firebase-tools/blob/main/README.md) 列举了 Hosting、Functions、Realtime Database、Extensions、Emulators 等大量子命令 [资料来源：[README.md:40-95]()]. 从 v15.x 版本演进来看，工具集在传统 CLI 能力之外逐步引入 GenAI 协同（`firebase:consult`、Data Connect GenAI）、SQL Connect（Data Connect 的新展示名）、Pub/Sub 与 Auth 模拟器升级，以及对多 Firestore 数据库、`backendId` 校验等改进，定位从单一 CLI 演化为"CLI + MCP + IDE"的多面入口。 ## 系统架构 `firebase-tools` 采用"多入口 + 共享核心"的分层结构。CLI 主进程、MCP 服务器与 VS Code 扩展均复用同一套命令、配置与模拟器代码，从而在多个交互面之间保持行为一致。 ```mermaid graph TD CLI["firebase CLI
(src/bin/firebase.ts)"] --> Core["核心命令与配置
(src/commands, src/config)"] MCP["MCP Server
(experimental:mcp)"] --> Core IDE["VS Code 扩展
(firebase-vscode/)"] --> Core Core --> Emu["本地模拟器套件
(src/emulator/*)"] Core --> Deploy["部署流水线
(Hosting/Functions/RTDB)"] Eval["Agent Evals
(scripts/agent-evals)"] --> MCP Eval -->|mock-tools-main.js| Core ``` - **CLI 主入口**：`src/bin/firebase.ts` 启动主进程，`src/bin/mcp.ts` 启动 Model Context Protocol 服务器，二者加载同一套业务模块，使 AI 代理与终端用户共享命令实现。 - **共享核心**：命令注册（`src/commands/**`）、项目配置加载（`src/config.ts`）、部署流水线（Hosting、Functions、RTDB）作为公共能力被所有入口调用，避免在 MCP 与 IDE 中重复实现。 - **模拟器层**：以 Auth 模拟器为例，源码通过 `gen-auth-api-spec.ts` 将 Google Identity Platform 的发现文档转换为 OpenAPI 3.0 规范，并使用 `exegesis-express` 在运行时注册路由与请求校验 [资料来源：[src/emulator/auth/README.md:1-45]()]. - **AI 侧通道**：`experimental:mcp` 暴露 Tool、Prompt、Resource 三类能力，Tool 用于执行动作，Prompt 提供 `firebase:deploy`、`firebase:init`、`firebase:consult` 等可复用模板，Resource 则下发针对各产品的初始化指南 [资料来源：[src/mcp/README.md:1-55]()] [资料来源：[src/mcp/antigravity/README.md:1-30]()]. ## 核心组件与职责 - **MCP 服务器**：提供 `firebase_login`、`firebase_get_project`、`dataconnect_build`、`apphosting_fetch_logs` 等跨产品工具，以及 Crashlytics 报告查询、Realtime Database 读写等垂直能力，使 AI 代理可以直接操作 Firebase 资源 [资料来源：[src/mcp/README.md:1-60]()]。 - **VS Code 扩展**：`DataConnectExplorerProvider` 解析 GraphQL Schema 并渲染树形视图；`OperationCodeLensProvider` 在 `.graphql` 文件的操作定义处注入 "Run (local)" CodeLens，`ConfigureSdkCodeLensProvider` 则在 `connector.yaml` 中提示配置生成的 SDK [资料来源：[firebase-vscode/src/data-connect/explorer-provider.ts:30-90]()] [资料来源：[firebase-vscode/src/data-connect/code-lens-provider.ts:1-60]()]。 - **ad-hoc 变更生成器**：基于当前 GraphQL 文档与光标位置自动生成 Mutation 草稿，简化在 IDE 中快速验证 SQL Connect 服务的流程 [资料来源：[firebase-vscode/src/data-connect/ad-hoc-mutations.ts:1-35]()]。 - **Agent 评估框架**：`scripts/agent-evals` 下 `GeminiCliRunner` 通过本地遥测日志与 `mock-tools-main.js` 模拟工具，驱动 Gemini CLI 与 Firebase MCP 之间的端到端交互，并产出可重复的代理行为评估 [资料来源：[scripts/agent-evals/src/runner/gemini-cli-runner.ts:1-80]()]。 - **MCP 测试支撑**：`scripts/agent-evals/src/mock/tool-mock-utils.ts` 中的 `toMockContent` 将任意字符串包装为 MCP 工具响应结构，使离线与单测场景更易构造 [资料来源：[scripts/agent-evals/src/mock/tool-mock-utils.ts:1-10]()]；`scripts/mcp-tests/package.json` 引入 `@modelcontextprotocol/sdk` 与 `tsx`，提供独立于主仓库运行的烟雾测试 [资料来源：[scripts/mcp-tests/package.json:1-20]()]. ## 部署与扩展点 `scripts/webframeworks-deploy-tests/` 维护 Angular 等 SPA 框架的最小可部署样例，用于验证 Hosting 部署链路对各 Web 框架入口文件（`index.html`、`base href`）的兼容行为 [资料来源：[scripts/webframeworks-deploy-tests/angular/src/index.html:1-10]()]. 与此同时，`firebase.json` 的 `firestore.edition` 字段、`emulators.firestore.edition` 字段已支持 Enterprise Edition，表明配置层也在同步模拟器演进，为本地体验与生产对齐提供了基础。 ## 社区关注点 社区中高频议题反映了 CLI 的演进方向：单仓库（mono-repo）部署（#653，197 条评论）、Storage 模拟器（#1738）、Cloud Functions ES Modules 支持（#2994）、Auth 模拟器（#1677）以及 Firestore 索引在模拟器中的持久化（#2027）。这些诉求对应到架构中即"共享核心"的扩展面与模拟器层的功能补齐，例如 `functions` 命令在多包仓库中如何定位子项目、模拟器如何在重启后保留索引与规则状态等。 ## See Also - MCP 工具与资源完整清单：[src/mcp/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) - Auth 模拟器与 OpenAPI 转换说明：[src/emulator/auth/README.md](https://github.com/firebase/firebase-tools/blob/main/src/emulator/auth/README.md) - Data Connect 浏览器实现：[firebase-vscode/src/data-connect/explorer-provider.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/explorer-provider.ts) - Agent Evals 运行器：[scripts/agent-evals/src/runner/gemini-cli-runner.ts](https://github.com/firebase/firebase-tools/blob/main/scripts/agent-evals/src/runner/gemini-cli-runner.ts) --- ## Deployment Pipeline and Release Lifecycle ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Emulators, Local Development and Common Failure Modes](#page-3), [MCP Server, AI Tools and VS Code Extension](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/firebase/firebase-tools/blob/main/README.md) - [package.json](https://github.com/firebase/firebase-tools/blob/main/package.json) - [scripts/webframeworks-deploy-tests/nextjs/package.json](https://github.com/firebase/firebase-tools/blob/main/scripts/webframeworks-deploy-tests/nextjs/package.json) - [scripts/mcp-tests/package.json](https://github.com/firebase/firebase-tools/blob/main/scripts/mcp-tests/package.json) - [src/mcp/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) - [src/emulator/auth/README.md](https://github.com/firebase/firebase-tools/blob/main/src/emulator/auth/README.md)
# Deployment Pipeline and Release Lifecycle ## 1. 概述与定位 `firebase-tools` 是 Firebase 官方提供的命令行与服务器端 SDK 集合,其核心职责之一是承载 Firebase 全家桶(Hosting、Cloud Functions、Firestore、Realtime Database、Auth、Storage、Extensions、App Distribution 等)的本地开发、模拟与生产部署流程。仓库根目录的 [README.md](README.md) 列出了从 `firebase deploy` 到 `database:instances:create`、再到 `auth:import`/`auth:export` 的完整命令矩阵,这一矩阵共同构成了 "部署管道与发布生命周期" 的用户面入口。 在仓库发布层面,`firebase-tools` 本身遵循 npm 包的语义化发布流程。[package.json](package.json) 中声明的 `files` 数组将 `lib`、`prompts`、`schema`、`standalone`、`templates` 五个目录作为发布产物,并通过 `publishConfig.registry` 指向 `https://wombat-dressing-room.appspot.com` 这一 Firebase 内部 npm 注册表。这意味着每次版本号的推进(社区上下文显示已迭代至 v15.19.1)都会触发一次针对上述子目录的全新构建与重新发布。资料来源：[package.json:1-50]() ## 2. 构建与发布阶段(Build → Publish) 构建管道由 [package.json](package.json) 中的 `scripts` 字段驱动。`prepare` 脚本串接 `clean` 与 `build:publish`,确保发布前的产物干净且一致。`build:publish` 负责把 TypeScript 源码编译并拷贝到 `lib/` 目录,这也是 `files` 中第一个被列入发布范围的子目录。`prompts/` 与 `templates/` 目录则承载了 `firebase init` 与 IDE 集成的模板内容,在发布周期中以静态资源形式分发。资料来源：[package.json:1-50]() 测试矩阵同样围绕部署管道设计:`test:emulator`、`test:extensions-emulator`、`test:dataconnect-deploy`、`test:dataconnect-emulator`、`test:all-emulators` 等脚本分别针对本地模拟器、扩展、SQL Connect 等不同部署目标执行验证。资料来源：[package.json:1-50]() ## 3. 部署目标与运行时 部署管道的多目标特性通过一组子项目工作区来体现。以 Web 框架集成测试为例,[scripts/webframeworks-deploy-tests/nextjs/package.json](scripts/webframeworks-deploy-tests/nextjs/package.json) 是一个 Next.js 16.2.4 + React 19.2.1 的最小化宿主应用,`dev`、`build`、`start`、`lint` 四条标准脚本与 `firebase deploy --only hosting` 协同,验证 Firebase Hosting 在 Next.js 框架下的部署路径。这一子项目本身即是 "部署管道端到端" 的回归靶场。资料来源：[scripts/webframeworks-deploy-tests/nextjs/package.json:1-20]() ```mermaid flowchart LR A[firebase.json
firebase deploy] --> B[Lifecycle Hooks] B --> C[Hosting
Web Frameworks] B --> D[Cloud Functions
v1 / v2 / Dart] B --> E[Firestore / RTDB / Storage] B --> F[Extensions] C --> G[Production Release] D --> G E --> G F --> G ``` 在认证模拟器方面,[src/emulator/auth/README.md](src/emulator/auth/README.md) 描述了一条独立的 "规范→模拟" 管道:从 Google API Discovery Document 出发,经 `scripts/gen-auth-api-spec.ts` 转换为 OpenAPI 3.0 规范,再由 `exegesis-express` 在运行时挂载到 Express 路由,并由 `operations.ts` 中的操作实现处理。该管道的产物 `apiSpec.js` 随发布一同分发,以保证本地 `firebase emulators:start` 时身份认证行为与生产一致。资料来源：[src/emulator/auth/README.md:1-30]() ## 4. AI/MCP 集成与发布协同 `firebase-tools` v15.15 起引入的 Model Context Protocol(MCP)服务器同样进入发布管道,作为部署生命周期的 "AI 协作者" 层。[src/mcp/README.md](src/mcp/README.md) 详尽列出了 Tools、Prompts、Resources 三类能力,其中 `firebase:deploy` prompt 可在 AI 代理驱动下触发整个部署动作;`backend_init_guide`、`firestore_init_guide` 等资源则把部署前后的初始化知识嵌入到 LLM 上下文。资料来源：[src/mcp/README.md:1-30]() MCP 子项目独立维护依赖与测试入口。[scripts/mcp-tests/package.json](scripts/mcp-tests/package.json) 通过 `tsx ./gemini-smoke-test.ts` 调用 `@modelcontextprotocol/sdk`,验证 MCP 工具在 Gemini 代理下的可用性,该 smoke test 与发布管道并行,作为 AI 集成侧的部署前置检查。资料来源：[scripts/mcp-tests/package.json:1-15]() ## 5. 已知风险与社区反馈 社区上下文显示,部署管道存在若干高影响故障模式:**Cloud Functions v1 LIST API 回归**(issue #10590)导致 `firebase deploy --only functions` 在 gen2-only 项目上持续返回 `HTTP 400: Precondition check failed`,说明 v1/v2 后端解析的容错仍是管道薄弱点;**Functions 模拟器间歇性 "Failed to load function"**(issue #10585)则反映本地到生产的对称性尚未完全收敛;**project 软删除后的 PROJECT_SOFT_DELETED**(issue #10603)说明部署目标本身的状态恢复在生命周期中缺乏兜底;**单仓多仓部署**(issue #653, 197 条评论)与 **ES Modules for Node 14**(issue #2994)仍是呼声最高的结构性需求。资料来源：[package.json:1-50]() [README.md:1-80]() ## 6. 最佳实践 1. 在 `firebase.json` 中显式声明目标(`hosting`、`functions`、`firestore` 等),并在 CI 中固定 `firebase-tools` 版本,与 v15.13.0 引入的 `backendId` 校验协同。资料来源：[package.json:1-50]() 2. 部署 Functions 前,使用 `firebase emulators:start` 在本地对齐认证、数据库、Pub/Sub 行为,降低线上回归概率。 3. 涉及外部密钥时,提前在 GCP Secret Manager 中创建并使用与 `defineSecret` 参数一致的 ID(issue #10597 反馈的松绑定需求尚未原生支持)。 4. 启用 MCP 集成时,确保 AI 代理的 `firebase:deploy` 调用前已完成 `firebase_login`,并将 `firebase.json` 纳入版本控制。 ## See Also - [Firebase Emulator Suite](README.md) - [MCP Server Capabilities](src/mcp/README.md) - [Auth Emulator Internals](src/emulator/auth/README.md) - [Release History v15.13.0 → v15.19.1](package.json) --- ## Emulators, Local Development and Common Failure Modes ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Deployment Pipeline and Release Lifecycle](#page-2), [MCP Server, AI Tools and VS Code Extension](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/emulator/controller.ts](https://github.com/firebase/firebase-tools/blob/main/src/emulator/controller.ts) - [src/emulator/registry.ts](https://github.com/firebase/firebase-tools/blob/main/src/emulator/registry.ts) - [src/emulator/hub.ts](https://github.com/firebase/firebase-tools/blob/main/src/emulator/hub.ts) - [src/emulator/ui.ts](https://github.com/firebase/firebase-tools/blob/main/src/emulator/ui.ts) - [src/emulator/functionsEmulator.ts](https://github.com/firebase/firebase-tools/blob/main/src/emulator/functionsEmulator.ts) - [src/emulator/functionsEmulatorRuntime.ts](https://github.com/firebase/firebase-tools/blob/main/src/emulator/functionsEmulatorRuntime.ts) - [src/emulator/auth/README.md](https://github.com/firebase/firebase-tools/blob/main/src/emulator/auth/README.md) - [src/mcp/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) - [src/mcp/antigravity/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/antigravity/README.md) - [package.json](https://github.com/firebase/firebase-tools/blob/main/package.json) - [README.md](https://github.com/firebase/firebase-tools/blob/main/README.md) - [firebase-vscode/src/data-connect/code-lens-provider.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts)
# Emulators, Local Development and Common Failure Modes ## 1. 概述与目标 `firebase-tools` 中的模拟器套件（Emulator Suite）是一组本地运行的容器化或进程化服务，用于在离线或 CI 环境下模拟 Firebase 后端行为，包括 Authentication、Firestore、Realtime Database、Cloud Functions、Pub/Sub、Storage、Hosting、Eventarc 以及新增的 SQL Connect（Data Connect）。开发者可以通过 `firebase emulators:start` 一键启动这些服务，并在本地使用与生产一致的 SDK 调用而无需联网 [README.md:1-50]。 该套件的核心目标是：① 降低开发成本，使单元测试和端到端测试无需真实 GCP 凭据；② 提供 `firebase.json#emulators` 的声明式配置；③ 与 VSCode 扩展及 MCP Server 协同，使 AI Agent 能够安全地对本地数据执行查询 [firebase-vscode/src/data-connect/code-lens-provider.ts:1-40] [src/mcp/README.md:1-30]。 ## 2. 架构与关键组件 模拟器架构采用 **Controller / Registry / Hub** 三层模式： ```mermaid graph TD CLI[firebase emulators:start] --> Controller[controller.ts] Controller --> Registry[registry.ts] Registry --> Auth[Auth Emulator] Registry --> Firestore[Firestore Emulator] Registry --> Functions[Functions Emulator] Registry --> PubSub[Pub/Sub Emulator] Registry --> DataConnect[SQL Connect Emulator] Functions --> Runtime[functionsEmulatorRuntime.ts] Controller --> Hub[hub.ts: 端口发现 & 转发] Controller --> UI[ui.ts: Emulator UI] ``` - **Controller**：负责解析 `firebase.json`、按依赖顺序启动各模拟器、收集日志并把状态暴露给 UI [src/emulator/controller.ts]。 - **Registry**：保存所有已注册 `Emulator` 子类的元信息（如默认端口、二进制路径），是模拟器查找和初始化的中心 [src/emulator/registry.ts]。 - **Hub**：实现“Emulator Hub”代理，客户端 SDK 只需连接 Hub 的固定端口即可访问任意后端模拟器，避免硬编码多个端口 [src/emulator/hub.ts]。 - **UI**：`@firebase/emulator-ui` 通过 `ui.ts` 启动，提供图形化查看 Firestore 文档、Auth 用户、Functions 日志的能力 [src/emulator/ui.ts]。 - **Functions Runtime**：在 `functionsEmulatorRuntime.ts` 中通过子进程 + IPC 加载用户函数，模拟 HTTP / onCall / Firestore 触发器 [src/emulator/functionsEmulatorRuntime.ts]。 支持的 Node.js 引擎为 `>=20.0.0 || >=22.0.0 || >=24.0.0` [package.json:1-60]，低于此版本将导致 `firebase emulators:start` 启动失败。 ## 3. 本地开发典型工作流 1. **初始化配置**：运行 `firebase init emulators` 会在 `firebase.json` 中生成 `emulators` 段，可指定每个模拟器的 `host`、`port` 及是否启用。例如 v15.14.0 引入的 `firestore.edition` 用于切换 Enterprise Edition [README.md]。 2. **启动套件**：`firebase emulators:start --import ./seed --export-on-exit ./seed` 可在启动前导入数据并在退出时导出，方便回归测试。 3. **连接 SDK**：客户端通过环境变量 `FIREBASE_AUTH_EMULATOR_HOST`、`FIRESTORE_EMULATOR_HOST` 等自动路由到 Hub [src/emulator/hub.ts]。 4. **MCP 集成**：通过 `firebase experimental:mcp` 启动 MCP Server，AI Agent 可调用 `firestore_query_collection`、`auth_get_users`、`realtimedatabase_get_data` 等工具直接操作本地数据库 [src/mcp/README.md:1-40] [src/mcp/antigravity/README.md]。 5. **VSCode 集成**：`firebase-vscode` 扩展通过 CodeLens 在 `.graphql` 文件上提供“Run (local)”按钮，调用本地 SQL Connect 模拟器执行 [firebase-vscode/src/data-connect/code-lens-provider.ts:1-60]。 Auth 模拟器默认暴露 OpenAPI 规范于 `http://localhost:/emulator/openapi.json`，可在 Swagger Editor 中调试 [src/emulator/auth/README.md]。 ## 4. 常见失败模式与排查 根据社区高频 Issue 与版本变更记录，以下故障最具代表性： | 故障现象 | 触发原因 | 缓解措施 | |---|---|---| | `PROJECT_SOFT_DELETED` | 项目被删除后恢复，但 Identity Toolkit 索引未同步 | 在 Google Cloud Console 中重置 Auth 资源，或新建项目重新初始化 | | Functions 模拟器间歇性 `Failed to load function` 且无诊断 | Runtime 子进程未捕获到 `MODULE_NOT_FOUND` 等异常（#10585） | 在 `functionsEmulatorRuntime.ts` 增加 worker 退出码打印；确保 `node_modules` 在 functions 目录内 | | `firebase deploy --only functions` 返回 `Precondition check failed 400` | 依赖 v1 LIST API，gen2-only 项目中 v1 端点被关闭（#10590） | 显式传入 `--only functions:v2` 或在 deploy 前跳过 v1 列表查询 | | Storage 模拟器缺失功能（#1738，50+ 评论） | 长期未实现 Object Lifecycle、Resumable Upload | 关注版本说明，使用 Cloud Storage SDK 直连测试桶 | | ES Modules 在 Node 函数中无法被解析（#2994） | 触发器扫描器仅识别 CJS 入口 | 使用 TypeScript 编译为 CJS，或迁移到 Functions v2 | | 多 Firestore 数据库配置导致启动错误（#8114，v15.17.0 修复） | `firebase.json` 解析时未合并多 `database` 节点 | 升级至 v15.17.0+，或显式指定 `database` 字段 | | PowerShell 下 CLI 参数解析失败（#7506，v15.14.0 修复） | 引号转义被 shlex 误处理 | 升级 CLI，或改用 `cmd` / WSL | | 静默部署失败（#6989，v15.14.0 修复） | Deploy 阶段异常被 try/catch 吞掉 | 升级至 v15.14.0 并启用 `--debug` 日志 | 此外，**monorepo 部署**（#653，197 评论）依旧是长期痛点：当前 `firebase.json` 默认仅识别仓库根目录，模拟器与 Deploy 都会按根目录解析函数与配置。建议的临时方案是利用 `projectId` + 多个 `firebase.json`（每个子包一份），或使用工作区级 CI 脚本分别 deploy。 ## 5. 最佳实践 - **锁定版本**：在 `package.json` 中固定 `firebase-tools` 版本以匹配模拟器二进制；v15.16.0 起 Firestore 模拟器已支持 `let(...)` 等新查询阶段 [README.md]。 - **数据隔离**：CI 中为每个 job 启动独立 `firebase emulators:exec` 会话，避免端口冲突。 - **安全规则测试**：使用 `firebase_validate_security_rules` MCP 工具或 `@firebase/rules-unit-testing` 在本地覆盖规则 [src/mcp/antigravity/README.md]。 - **监控版本说明**：Data Connect 工具链经常更新（v15.19.1 已至 v3.4.10），每次升级前检查 changelog 中关于 “client cache consistency” 等破坏性变更。 - **结合 MCP**：在 Agent 流程中通过 `firebase_get_project`、`firestore_list_collections` 等只读工具做上下文收集，再调用 `firebase:deploy` 提示模板完成变更 [src/mcp/antigravity/README.md]。 ## See Also - Firebase MCP Server Wiki - Cloud Functions Deployment Wiki - Firestore Security Rules Wiki - SQL Connect (Data Connect) Schema Guide --- ## MCP Server, AI Tools and VS Code Extension ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Deployment Pipeline and Release Lifecycle](#page-2), [Emulators, Local Development and Common Failure Modes](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcp/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) - [src/mcp/antigravity/README.md](https://github.com/firebase/firebase-tools/blob/main/src/mcp/antigravity/README.md) - [scripts/mcp-tests/package.json](https://github.com/firebase/firebase-tools/blob/main/scripts/mcp-tests/package.json) - [README.md](https://github.com/firebase/firebase-tools/blob/main/README.md) - [firebase-vscode/src/data-connect/code-lens-provider.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) - [firebase-vscode/src/data-connect/ad-hoc-mutations.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/ad-hoc-mutations.ts) - [firebase-vscode/src/data-connect/explorer-provider.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/explorer-provider.ts) - [firebase-vscode/src/data-connect/execution/execution.ts](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/execution/execution.ts) - [package.json](https://github.com/firebase/firebase-tools/blob/main/package.json) - [scripts/agent-evals/src/mock/tool-mock-utils.ts](https://github.com/firebase/firebase-tools/blob/main/scripts/agent-evals/src/mock/tool-mock-utils.ts)
# MCP Server, AI Tools and VS Code Extension ## 概述 Firebase 工具链（firebase-tools）除了提供传统的命令行接口（CLI）之外，还提供两套面向 AI 与编辑器生态的能力：基于 **Model Context Protocol (MCP)** 的服务端，以及集成 Data Connect（现称 SQL Connect）能力的 **VS Code 扩展**。这两套能力使 AI 代理（例如 Gemini CLI、Claude Code、Cursor、Cline 等）和编辑器能够直接与 Firebase 项目、数据库以及部署产物进行交互，而无需手动复制命令或上下文。资料来源：[src/mcp/README.md:1-15](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) 项目根目录的 `package.json` 中声明了 `mcp` 子命令入口，并且支持 Node 20/22/24 运行时，这正是 MCP 服务进程运行所需的环境。资料来源：[package.json:39-44](https://github.com/firebase/firebase-tools/blob/main/package.json) ## Firebase MCP Server ### 角色与定位 Firebase MCP Server 是一个符合 MCP 规范的进程，能够让任何兼容 MCP 协议的客户端将其作为后端能力源。资料来源：[src/mcp/README.md:1-9](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md) > "The Firebase Model Context Protocol (MCP) Server gives AI-powered development tools the ability to work with your Firebase projects and your app's codebase. It turns your agent into an expert Firebase developer..." 它通过三类原语对外暴露能力：**Tools**（可执行函数）、**Prompts**（可复用的命令模板）、**Resources**（供模型读取的文档资源）。资料来源：[src/mcp/antigravity/README.md:39-46](https://github.com/firebase/firebase-tools/blob/main/src/mcp/antigravity/README.md) ### 三类能力 下表按能力分组汇总 MCP Server 提供的高频入口，定义来自 `src/mcp/README.md` 与 `src/mcp/antigravity/README.md` 中的工具清单。 | 能力组 | 示例 Tool / Prompt / Resource | 用途 | | --- | --- | --- | | core | `firebase_login`、`firebase_validate_security_rules`、`firebase_get_project` | 登录、规则校验、项目信息查询 | | firestore | `firestore_query_collection`、`firestore_list_collections`、`firestore_delete_document` | 文档级与集合级读写 | | auth | `auth_get_users`、`auth_update_user`、`auth_set_sms_region_policy` | 用户管理与 SMS 区域策略 | | dataconnect | `dataconnect_build`、`dataconnect_list_services`、`dataconnect_execute` | SQL Connect 模式构建、列表与执行 | | realtimedatabase | `realtimedatabase_get_data`、`realtimedatabase_set_data` | RTDB 数据读写 | | crashlytics | `crashlytics_list_notes`、`crashlytics_get_top_issues` | 崩溃数据统计与备注 | | Prompts | `firebase:deploy`、`firebase:init`、`firebase:consult`、`crashlytics:connect` | 一键触发的复合流程 | | Resources | `backend_init_guide`、`firestore_init_guide`、`data_connect_init_guide` | 引导文档，供模型检索 | 资料来源：[src/mcp/README.md:38-115](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md)、[src/mcp/antigravity/README.md:39-87](https://github.com/firebase/firebase-tools/blob/main/src/mcp/antigravity/README.md) ### 启动与测试 `scripts/mcp-tests/package.json` 暴露了一个独立的冒烟测试入口，使用 `@modelcontextprotocol/sdk` 与 `tsx` 启动客户端，验证 MCP 协议握手与工具调用。资料来源：[scripts/mcp-tests/package.json:1-19](https://github.com/firebase/firebase-tools/blob/main/scripts/mcp-tests/package.json) ## VS Code 扩展与 Data Connect 集成 ### CodeLens：在编辑器中直接生成与执行 `code-lens-provider.ts` 中实现了多个 `vscode.CodeLensProvider`，它们监听 `dataConnectConfigs` 信号，针对 GraphQL 模式与操作文件注入“生成 / 运行”动作。资料来源：[firebase-vscode/src/data-connect/code-lens-provider.ts:1-30](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) - `SchemaCodeLensProvider` 解析 `OBJECT_TYPE_DEFINITION` 节点，对每个对象类型提供 `$(sparkle) Generate Operation` 与 `Connect.schemaReadData` 等 Code Lens。资料来源：[firebase-vscode/src/data-connect/code-lens-provider.ts:55-104](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) - `OperationsCodeLensProvider` 仅对 `OPERATION_DEFINITION` 和 `FRAGMENT_DEFINITION` 注入 `$(play) Run (local)`，并附带本地执行所需的 `ExecutionInput`。资料来源：[firebase-vscode/src/data-connect/code-lens-provider.ts:140-180](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) - `ConfigureSdkCodeLensProvider` 在 `Connector.yaml` 文件顶部展示 `$(tools) Configure Generated SDK`，用于将当前 connector 与生成的 SDK 关联。资料来源：[firebase-vscode/src/data-connect/code-lens-provider.ts:107-138](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) ### Ad-hoc Mutations 与执行历史 `ad-hoc-mutations.ts` 中的 `registerAdHoc` 监听 Code Lens 命令 `schemaReadData`，根据当前 `ObjectTypeDefinitionNode` 推断基础类型（`String / Int64 / Date / Timestamp / Boolean` 等），在 `operations/` 目录生成临时查询文件。资料来源：[firebase-vscode/src/data-connect/ad-hoc-mutations.ts:1-60](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/ad-hoc-mutations.ts) `execution/execution.ts` 则维护 `ExecutionItem` 状态机，封装 `createExecution / updateExecution / selectExecutionId` 等操作，并通过 `extension-broker` 把执行结果回写到 Webview。资料来源：[firebase-vscode/src/data-connect/execution/execution.ts:1-40](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/execution/execution.ts) ### Explorer：模式驱动的对象树 `explorer-provider.ts` 基于 GraphQL 内省结果构建 `typeForName` 索引，对 `__schema.queryType` 与 `mutationType` 做递归解析，渲染可折叠的字段树。资料来源：[firebase-vscode/src/data-connect/explorer-provider.ts:1-50](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/explorer-provider.ts) ## 架构与请求流程 ```mermaid flowchart LR A[MCP 客户端 / AI 代理] -->|tools/call| B(MCP Server) A -->|resources/read| B A -->|prompts/get| B B --> C[firebase-tools CLI 后端] C --> D[(Firestore / Auth / SQL Connect / RTDB)] E[VS Code 编辑器] --> F[Code Lens / Ad-hoc Mutations] F --> G[Data Connect Emulator / Backend] F --> H[Execution History Webview] ``` MCP 客户端（Cursor、Claude Code 等）通过 `tools/call` 触发 CLI 后端的真实 API；VS Code 扩展则通过 Code Lens 触发本地构建与执行链路，两者最终都消费 `dataConnectConfigs` 信号共享的最新配置。资料来源：[src/mcp/README.md:17-25](https://github.com/firebase/firebase-tools/blob/main/src/mcp/README.md)、[firebase-vscode/src/data-connect/code-lens-provider.ts:1-15](https://github.com/firebase/firebase-tools/blob/main/firebase-vscode/src/data-connect/code-lens-provider.ts) ## 常见问题与社区关注点 - **MCP 工具输入校验失败**：v15.17.0 修复了部分 MCP 工具因 “Invalid input: expected record, received array” 报错的回归（#10437）。当使用受影响的工具时，确认参数已序列化为对象而非数组。 - **多数据库 / 多后端场景**：v15.17.0 同时修复了 `firebase.json` 配置多个 Firestore 数据库时的解析问题（#8114），调用 `firestore_*` 系列工具前请确保 `firebase.json` 的 `firestore` 字段已更新。 - **VS Code 扩展 + MCP 联用**：社区中关于 monorepo 部署（#653）等长期讨论也影响编辑器侧的初始化资源（`backend_init_guide`），建议在 monorepo 根目录使用 `firebase:init` prompt。 ## See Also - [Data Connect (SQL Connect) 部署与执行](https://firebase.google.com/docs/data-connect) - [Firebase MCP Server 官方文档](https://firebase.google.com/docs/ai-assistance/mcp-server) - 项目根 `README.md` 中的 Realtime Database 与 Extensions 命令清单。资料来源：[README.md:1-40](https://github.com/firebase/firebase-tools/blob/main/README.md) --- --- ## Doramagic 踩坑日志 项目：firebase/firebase-tools 摘要：发现 26 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：[cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues。 ## 1. 安装坑 · 来源证据：[cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_4f2a1ec2bb424d1686851f68154c4080 | https://github.com/firebase/firebase-tools/issues/10591 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：functions emulator: "Failed to load function" intermittent failure with no diagnostic information - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：functions emulator: "Failed to load function" intermittent failure with no diagnostic information - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_84267a150a9947d2be48a0fed4c04fba | https://github.com/firebase/firebase-tools/issues/10585 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 3. 安全/权限坑 · 失败模式：security_permissions: Support loose binding / aliasing for existing GCP Secrets in `defineSecret` - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Support loose binding / aliasing for existing GCP Secrets in `defineSecret` - 对用户的影响：Developers may expose sensitive permissions or credentials: Support loose binding / aliasing for existing GCP Secrets in `defineSecret` - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Support loose binding / aliasing for existing GCP Secrets in `defineSecret`. Context: Observed when using docker - 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/firebase/firebase-tools/issues/10597 - 证据：failure_mode_cluster:github_issue | fmev_99c9e511eabefddccfad471be174c50f | https://github.com/firebase/firebase-tools/issues/10597 | Support loose binding / aliasing for existing GCP Secrets in `defineSecret` ## 4. 安全/权限坑 · 失败模式：security_permissions: functions emulator: "Failed to load function" intermittent failure with no diagnostic informa... - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: functions emulator: "Failed to load function" intermittent failure with no diagnostic information - 对用户的影响：Developers may expose sensitive permissions or credentials: functions emulator: "Failed to load function" intermittent failure with no diagnostic information - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: functions emulator: "Failed to load function" intermittent failure with no diagnostic information. Context: Observed when using windows, macos, linux - 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/firebase/firebase-tools/issues/10585 - 证据：failure_mode_cluster:github_issue | fmev_441197228e621e13cb5b731e277d1106 | https://github.com/firebase/firebase-tools/issues/10585 | functions emulator: "Failed to load function" intermittent failure with no diagnostic information ## 5. 安全/权限坑 · 来源证据：Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys for gen2-only projects (24h… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys for gen2-only projects (24h+ active) - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_c546fc217e664baa87450621587fee31 | https://github.com/firebase/firebase-tools/issues/10590 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 安全/权限坑 · 来源证据：Support loose binding / aliasing for existing GCP Secrets in `defineSecret` - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support loose binding / aliasing for existing GCP Secrets in `defineSecret` - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_6d785c6692184850a18951f28749620f | https://github.com/firebase/firebase-tools/issues/10597 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 安装坑 · 失败模式：installation: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround bui... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues - 对用户的影响：Developers may fail before the first successful local run: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues. Context: Observed when using linux - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_caf934975aa33855b8941b352a3e56ef | https://github.com/firebase/firebase-tools/issues/10591 | [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues ## 8. 安装坑 · 失败模式：installation: v15.11.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v15.11.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.11.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.11.0. Context: Observed when using macos - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_f32bcea39b7c3fc39503955cd4dcec71 | https://github.com/firebase/firebase-tools/releases/tag/v15.11.0 | v15.11.0 ## 9. 安装坑 · 失败模式：installation: v15.12.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v15.12.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.12.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.12.0. Context: Observed during installation or first-run setup. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_b1e3fdd4c3a2c14194df3ccdd059cdff | https://github.com/firebase/firebase-tools/releases/tag/v15.12.0 | v15.12.0 ## 10. 安装坑 · 失败模式：installation: v15.18.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v15.18.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.18.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.18.0. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_37e78bf4fc82806298e92f88c2607e5f | https://github.com/firebase/firebase-tools/releases/tag/v15.18.0 | v15.18.0 ## 11. 配置坑 · 失败模式：configuration: Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys f... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys for gen2-only projects (24h+ active) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys for gen2-only projects (24h+ active) - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys for gen2-only projects (24h+ active). Context: Observed when using python - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_db6c88f426952b1deb5160d624950d65 | https://github.com/firebase/firebase-tools/issues/10590 | Cloud Functions v1 LIST API regression — "Precondition check failed" 400 blocks ALL deploys for gen2-only projects (24h+ active) ## 12. 配置坑 · 失败模式：configuration: Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_f7d5bb1217b384d360f1543ca266b21c | https://github.com/firebase/firebase-tools/issues/10603 | Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken ## 13. 配置坑 · 失败模式：configuration: v15.14.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v15.14.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.14.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.14.0. Context: Observed during version upgrade or migration. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_60236fd3dad5a5040b9cbf6452d0cdcb | https://github.com/firebase/firebase-tools/releases/tag/v15.14.0 | v15.14.0 ## 14. 配置坑 · 失败模式：configuration: v15.17.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v15.17.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.17.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.17.0. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_e60ef8279de95a9fad16eb03d7dd7455 | https://github.com/firebase/firebase-tools/releases/tag/v15.17.0 | v15.17.0 ## 15. 配置坑 · 失败模式：configuration: v15.19.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v15.19.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.19.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.19.0. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_4a54c5d21d0ccd1ce16d05e582be6ce2 | https://github.com/firebase/firebase-tools/releases/tag/v15.19.0 | v15.19.0 ## 16. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | npm_package:firebase-tools | https://www.npmjs.com/package/firebase-tools | README/documentation is current enough for a first validation pass. ## 17. 运行坑 · 失败模式：runtime: v15.16.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: v15.16.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.16.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.16.0. Context: Observed when using node, python - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_a949aa963c0429ecb066ee6f630c1995 | https://github.com/firebase/firebase-tools/releases/tag/v15.16.0 | v15.16.0 ## 18. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | npm_package:firebase-tools | https://www.npmjs.com/package/firebase-tools | last_activity_observed missing ## 19. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | npm_package:firebase-tools | https://www.npmjs.com/package/firebase-tools | no_demo; severity=medium ## 20. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | npm_package:firebase-tools | https://www.npmjs.com/package/firebase-tools | no_demo; severity=medium ## 21. 安全/权限坑 · 来源证据：Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Project restored but still showing PROJECT_SOFT_DELETED - Firestore deleted, Auth broken - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_26f71b583fb244da9b6f3616e3908266 | https://github.com/firebase/firebase-tools/issues/10603 | 来源类型 github_issue 暴露的待验证使用条件。 ## 22. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | npm_package:firebase-tools | https://www.npmjs.com/package/firebase-tools | issue_or_pr_quality=unknown ## 23. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | npm_package:firebase-tools | https://www.npmjs.com/package/firebase-tools | release_recency=unknown ## 24. 维护坑 · 失败模式：maintenance: v15.13.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v15.13.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.13.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.13.0. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_818089584768470c31eb75ebd10e629b | https://github.com/firebase/firebase-tools/releases/tag/v15.13.0 | v15.13.0 ## 25. 维护坑 · 失败模式：maintenance: v15.15.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v15.15.0 - 对用户的影响：Upgrade or migration may change expected behavior: v15.15.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.15.0. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_91f6177d89e9dba6ecd4adc734b5469a | https://github.com/firebase/firebase-tools/releases/tag/v15.15.0 | v15.15.0 ## 26. 维护坑 · 失败模式：maintenance: v15.19.1 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v15.19.1 - 对用户的影响：Upgrade or migration may change expected behavior: v15.19.1 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v15.19.1. Context: Source discussion did not expose a precise runtime context. - 防护动作：State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_e9a996709ca8368e88873cb90407e793 | https://github.com/firebase/firebase-tools/releases/tag/v15.19.1 | v15.19.1