firestore-data

用法

所有脚本都可以使用 Node.js 执行。将 <param_name> 和 <param_value> 替换为实际值。

Bash： node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell： node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

注意：脚本会自动从各种 .env 文件中加载环境变量。除非技能执行因缺少环境变量而失败，否则不要要求用户设置环境变量。

脚本

add_documents

向 Firestore 集合添加新文档。请遵循以下最佳实践：

1. 始终在 documentData 中使用带类型的值：每个字段都必须使用相应的类型标识符封装（例如，{"stringValue": "text"}）
2. 整数值可以在 documentData 中使用字符串：工具接受以字符串形式表示的整数值（例如，{"integerValue": "1500"}）
3. 谨慎使用 returnData：仅在需要验证实际写入的数据时才设为 true
4. 发送前验证数据：确保数据符合 Firestore 的原生 JSON 格式
5. 正确处理时间戳：时间戳字符串使用 RFC3339 格式
6. 对二进制数据进行 Base64 编码：二进制数据必须在 bytesValue 字段中进行 Base64 编码
7. 注意安全规则：确保 Firestore 安全规则允许在目标集合中创建文档

参数

名称	类型	描述	必填	默认值
collectionPath	string	将要添加文档的集合的相对路径（例如，'users' 或 'users/userId/posts'）。注意：这是相对路径，而非 'projects/{project_id}/databases/{database_id}/documents/...' 这类绝对路径	是
documentData	object	Firestore 原生 JSON 格式的文档数据。每个字段都必须使用类型标识符封装：

• 字符串：{"stringValue": "text"}
• 整数：{"integerValue": "123"} 或 {"integerValue": 123}
• 双精度浮点数：{"doubleValue": 123.45}
• 布尔值：{"booleanValue": true}
• 时间戳：{"timestampValue": "2025-01-07T10:00:00Z"}
• 地理点：{"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
• 数组：{"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
• 映射：{"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
• 空值：{"nullValue": null}
• 字节：{"bytesValue": "base64EncodedString"}
• 引用：{"referenceValue": "collection/document"} | 是 | | | returnData | boolean | 如果设为 true，输出将包含已创建文档的数据。将此标志设为 false 有助于避免 Agent 的上下文过载。 | 否 | false |

---

delete_documents

从 Firestore 删除多个文档

参数

名称	类型	描述	必填	默认值
documentPaths	array	要从 Firestore 删除的相对文档路径数组（例如，'users/userId' 或 'users/userId/posts/postId'）。注意：这些是相对路径，而非 'projects/{project_id}/databases/{database_id}/documents/...' 这类绝对路径	是

---

get_documents

根据文档路径从 Firestore 获取多个文档

参数

名称	类型	描述	必填	默认值
documentPaths	array	要从 Firestore 获取的相对文档路径数组（例如，'users/userId' 或 'users/userId/posts/postId'）。注意：这些是相对路径，而非 'projects/{project_id}/databases/{database_id}/documents/...' 这类绝对路径	是

---

list_collections

列出给定父路径下的 Firestore 集合

参数

名称	类型	描述	必填	默认值
parentPath	string	要从中列出子集合的父文档相对路径（例如，'users/userId'）。如果未提供，则列出根集合。注意：这是相对路径，而不是 'projects/{project_id}/databases/{database_id}/documents/...' 这样的绝对路径	否

---

query_collection

通过完整文档路径指定集合，从当前项目的数据库中的集合检索一个或多个 Firestore 文档。 如果你知道集合的确切路径以及要用于文档的筛选条件，请使用此工具。

参数

名称	类型	描述	必填	默认值
collectionPath	string	要查询的 Firestore 集合的相对路径（例如，'users' 或 'users/userId/posts'）。注意：这是相对路径，而不是 'projects/{project_id}/databases/{database_id}/documents/...' 这样的绝对路径	是
filters	array	要应用于查询的筛选条件对象数组。每个筛选条件都是一个 JSON 字符串，包含：

• field：要筛选的字段名称
• op：要使用的运算符（"<"、"<="、">"、">="、"=="、"!="、"array-contains"、"array-contains-any"、"in"、"not-in"）
• value：要比较的值（可以是字符串、数字、布尔值或数组） 示例：{"field": "age", "op": ">", "value": 18} | 是 | | | orderBy | string | 指定排序字段和方向的 JSON 字符串（例如，{"field": "name", "direction": "ASCENDING"}）。未指定时留空 | 是 | | | limit | integer | 要返回的文档最大数量 | 否 | 100 | | analyzeQuery | boolean | 如果为 true，则返回查询解释指标，包括执行统计信息 | 否 | false |

---

update_document

更新 Firestore 中的现有文档。支持完整文档更新，也支持使用更新掩码选择性更新字段。请遵循以下最佳实践：

1. 精确使用更新掩码：仅需更新特定字段时，使用 updateMask 参数以避免意外更改
2. 始终在 documentData 中使用带类型的值：每个字段都必须用相应的类型标识符包装（例如，{"stringValue": "text"}）
3. 使用更新掩码删除字段：要删除字段，请将其包含在 updateMask 中，但从 documentData 中省略
4. 整数值可以是字符串：该技能接受以字符串形式提供的整数值（例如，{"integerValue": "1500"}）
5. 谨慎使用 returnData：仅在需要验证更新后的确切数据时才将其设为 true
6. 正确处理时间戳：时间戳字符串使用 RFC3339 格式
7. 考虑安全规则：确保 Firestore 安全规则允许更新文档

参数

名称	类型	描述	必填	默认值
documentPath	string	需要更新的文档的相对路径（例如，'users/userId' 或 'users/userId/posts/postId'）。注意：这是相对路径，而不是 'projects/{project_id}/databases/{database_id}/documents/...' 这样的绝对路径	是
documentData	object	Firestore 原生 JSON 格式的文档数据。每个字段都必须使用类型标识符封装： - 字符串：{"stringValue": "text"} - 整数：{"integerValue": "123"} 或 {"integerValue": 123} - 双精度浮点数：{"doubleValue": 123.45} - 布尔值：{"booleanValue": true} - 时间戳：{"timestampValue": "2025-01-07T10:00:00Z"} - 地理点：{"geoPointValue": {"latitude": 34.05, "longitude": -118.24}} - 数组：{"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}} - 映射：{"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}} - 空值：{"nullValue": null} - 字节：{"bytesValue": "base64EncodedString"} - 引用：{"referenceValue": "collection/document"}	是
updateMask	array	要更新的指定字段。如果未提供，则会更新 documentData 中的所有字段。提供后，只会更新指定的字段。掩码中引用但未出现在 documentData 中的字段将从文档中删除	否
returnData	boolean	如果设为 true，输出将包含已更新文档的数据。将此标志设为 false 有助于避免 Agent 上下文过载。	否	false

---