项目定位与目标

firebase-tools 是 Firebase 官方发布的统一命令行工具集（CLI），面向开发者在本地与云端之间提供项目管理、部署与模拟运行等能力。其根目录的 package.json 声明支持 Node.js 20/22/24，并以 preferGlobal: true 引导全局安装；该 npm 包发布到 Firebase 自有 Registry wombat-dressing-room.appspot.com 资料来源：[package.json:25-55]. 主入口的 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 扩展均复用同一套命令、配置与模拟器代码，从而在多个交互面之间保持行为一致。

graph TD
  CLI["firebase CLI<br/>(src/bin/firebase.ts)"] --> Core["核心命令与配置<br/>(src/commands, src/config)"]
  MCP["MCP Server<br/>(experimental:mcp)"] --> Core
  IDE["VS Code 扩展<br/>(firebase-vscode/)"] --> Core
  Core --> Emu["本地模拟器套件<br/>(src/emulator/*)"]
  Core --> Deploy["部署流水线<br/>(Hosting/Functions/RTDB)"]
  Eval["Agent Evals<br/>(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
• Auth 模拟器与 OpenAPI 转换说明：src/emulator/auth/README.md
• Data Connect 浏览器实现：firebase-vscode/src/data-connect/explorer-provider.ts
• Agent Evals 运行器：scripts/agent-evals/src/runner/gemini-cli-runner.ts

1. 概述与定位

firebase-tools 是 Firebase 官方提供的命令行与服务器端 SDK 集合,其核心职责之一是承载 Firebase 全家桶(Hosting、Cloud Functions、Firestore、Realtime Database、Auth、Storage、Extensions、App Distribution 等)的本地开发、模拟与生产部署流程。仓库根目录的 README.md 列出了从 firebase deploy 到 database:instances:create、再到 auth:import/auth:export 的完整命令矩阵,这一矩阵共同构成了 "部署管道与发布生命周期" 的用户面入口。

在仓库发布层面,firebase-tools 本身遵循 npm 包的语义化发布流程。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 中的 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 是一个 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

flowchart LR
    A[firebase.json<br/>firebase deploy] --> B[Lifecycle Hooks]
    B --> C[Hosting<br/>Web Frameworks]
    B --> D[Cloud Functions<br/>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 描述了一条独立的 "规范→模拟" 管道:从 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 详尽列出了 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 通过 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
• MCP Server Capabilities
• Auth Emulator Internals
• Release History v15.13.0 → v15.19.1

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 三层模式：

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:<port>/emulator/openapi.json，可在 Swagger Editor 中调试 [src/emulator/auth/README.md]。

4. 常见失败模式与排查

根据社区高频 Issue 与版本变更记录，以下故障最具代表性：

此外，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

概述

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

项目根目录的 package.json 中声明了 mcp 子命令入口，并且支持 Node 20/22/24 运行时，这正是 MCP 服务进程运行所需的环境。资料来源：package.json:39-44

Firebase MCP Server

角色与定位

Firebase MCP Server 是一个符合 MCP 规范的进程，能够让任何兼容 MCP 协议的客户端将其作为后端能力源。资料来源：src/mcp/README.md:1-9

"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

三类能力

下表按能力分组汇总 MCP Server 提供的高频入口，定义来自 src/mcp/README.md 与 src/mcp/antigravity/README.md 中的工具清单。

资料来源：src/mcp/README.md:38-115、src/mcp/antigravity/README.md:39-87

启动与测试

scripts/mcp-tests/package.json 暴露了一个独立的冒烟测试入口，使用 @modelcontextprotocol/sdk 与 tsx 启动客户端，验证 MCP 协议握手与工具调用。资料来源：scripts/mcp-tests/package.json:1-19

VS Code 扩展与 Data Connect 集成

CodeLens：在编辑器中直接生成与执行

code-lens-provider.ts 中实现了多个 vscode.CodeLensProvider，它们监听 dataConnectConfigs 信号，针对 GraphQL 模式与操作文件注入“生成 / 运行”动作。资料来源：firebase-vscode/src/data-connect/code-lens-provider.ts:1-30

• SchemaCodeLensProvider 解析 OBJECT_TYPE_DEFINITION 节点，对每个对象类型提供 $(sparkle) Generate Operation 与 Connect.schemaReadData 等 Code Lens。资料来源：firebase-vscode/src/data-connect/code-lens-provider.ts:55-104
• OperationsCodeLensProvider 仅对 OPERATION_DEFINITION 和 FRAGMENT_DEFINITION 注入 $(play) Run (local)，并附带本地执行所需的 ExecutionInput。资料来源：firebase-vscode/src/data-connect/code-lens-provider.ts:140-180
• ConfigureSdkCodeLensProvider 在 Connector.yaml 文件顶部展示 $(tools) Configure Generated SDK，用于将当前 connector 与生成的 SDK 关联。资料来源：firebase-vscode/src/data-connect/code-lens-provider.ts:107-138

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

execution/execution.ts 则维护 ExecutionItem 状态机，封装 createExecution / updateExecution / selectExecutionId 等操作，并通过 extension-broker 把执行结果回写到 Webview。资料来源：firebase-vscode/src/data-connect/execution/execution.ts:1-40

Explorer：模式驱动的对象树

explorer-provider.ts 基于 GraphQL 内省结果构建 typeForName 索引，对 __schema.queryType 与 mutationType 做递归解析，渲染可折叠的字段树。资料来源：firebase-vscode/src/data-connect/explorer-provider.ts:1-50

架构与请求流程

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、firebase-vscode/src/data-connect/code-lens-provider.ts:1-15

常见问题与社区关注点

• 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) 部署与执行
• Firebase MCP Server 官方文档
• 项目根 README.md 中的 Realtime Database 与 Extensions 命令清单。资料来源：README.md:1-40

Pitfall Log / 踩坑日志

项目：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