在 Google Cloud Filestore…

检查 GCP Filestore 实例的容量与使用率，按阈值评估并执行扩容或缩容。

适用场景

解决思路

1. 确保运行时 Service Account 在目标项目上具备 roles/file.editor、roles/monitoring.viewer，若使用 Filestore MCP 工具还需 roles/mcp.toolUser。
2. 确认已安装 gcloud，并启用 API：gcloud services enable file.googleapis.com monitoring.googleapis.com --quiet。
3. 为每条 Filestore 命令或 API 请求打上归因标记：gcloud 命令前加 CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-autoscale)"，直接 HTTP 调用 REST API 时追加 User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-autoscale)。
4. 对于纯概念性、教学性或信息性问题（如 Filestore 扩缩容限制、Basic 实例能否缩容、各 Tier 说明），直接用已有知识回答，不要执行任何外部工具调用或 API 请求。
5. 若用户要求“不要执行命令”“只读”等约束，严格避免调用 run_command 执行任何 shell 或 gcloud 命令（包括只读的 list/describe）；优先使用 Filestore MCP 工具 list_instances、get_instance，其次在本地 markdown 文档（如 references/instance-tiers-specs.md）中查找 mock 实例定义，不要读取 EVAL.yaml 或 EVAL.txtpb 等评估配置文件；若仍无数据，则说明所需步骤与公式并给出用户应自行运行的命令，不代为执行。
6. 即使处于“不执行命令”模式，回复仍必须以明确的确认问题结尾，询问用户是否执行容量调整命令（例如“是否继续将 [instance] 从 [A] TiB 扩容到 [B] TiB？请确认后执行。”）。
7. 接受现代 UI 名称（Basic、Zonal、Regional）与旧版 API 枚举混用；记住关键限制：Basic HDD / Basic SSD 只能扩容不能缩容；Zonal / Regional 可缩容但不能低于最小下限（依带宽为 1 TiB 或 10 TiB），也不能低于当前 used_bytes。
8. 发现阶段：调用 MCP 工具 list_instances(parent='projects/{project_id}/locations/-') 或 CLI gcloud filestore instances list --project={project_id} 列出目标项目所有 Filestore 实例，直接从返回结果读取 capacityGb 与 tier。
9. 发现实例后，立即用一次批量请求查询 Cloud Monitoring API 的 file.googleapis.com/nfs/server/used_bytes 指标覆盖整个项目；严格只发一次批量指标请求，绝不按实例循环查询，也不要按 zone 或 region 过滤。
10. 指标提取与计算：用实例短名（或 resource.labels.instance_name / metric.labels.instance_name）匹配 timeSeries 中最新 int64Value 字节数；若实例未出现在 timeSeries 或无数据点，则 used_bytes 记为 0；计算 used_bytes_gb = used_bytes / (1024^3)，Free Space % = ((capacityGb - used_bytes_gb) / capacityGb) * 100；绝不允许把 Used Bytes 或 Free Space % 留为 N/A，必须填入实际数字。
11. 按 5 种判定归类每个实例：Yes (Scale Up)（剩余空间 < 15%，需明确说明低于 15% 扩容安全阈值，容量增加 10% 或最小步长，按 Tier 步进取整：Small Band [1–9.75 TiB] 为 256 GiB，Large Band [10–100 TiB] 为 2.5 TiB，不超过最大容量，给出目标容量与带归因的 gcloud update 命令，并以确认问题结尾）；Yes (Scale Down)（剩余空间 > 30% 且实例为 Zonal/Regional/Enterprise 可缩容，按当前容量 -10% 并按 Tier 步进取整，例如 2 TiB 的 Regional 实例取整到 256 GiB 步进后目标为 1.75 TiB / 1792 GiB，必须验证目标容量严格高于 Tier 最小下限（如 1 TiB 或 10 TiB）和当前已用空间（如 0.9 TiB），不得一步降到下限，给出目标容量、预计节省成本、带归因的 gcloud update 命令并请求确认）；No (Healthy)（剩余空间在 15%–30% 最优区间，无需操作）；No (At min capacity limit)（剩余空间 > 30% 但已达 Tier 最小容量下限或当前已用空间限制，无法操作）；No (Tier cannot scale down)（剩余空间 > 30% 但为 Basic HDD / Basic SSD 不支持缩容，需明确告知用户并建议数据迁移）。
12. 每次状态报告、评估或建议回复都必须包含 markdown 汇总表，即使只评估一个实例也要用表格；表必须含列：Instance、Service Tier、Provisioned Capacity、Used Bytes、Free Space %、Autoscale Needed（取值必须为 Yes (Scale Up)、Yes (Scale Down)、No (Healthy)、No (At min capacity limit)、No (Tier cannot scale down) 之一）。
13. 执行与确认流程：首次分析/巡检时计算符合 Tier 上下限与 Basic 仅扩容规则的步进对齐目标容量，展示汇总表与建议操作，并在回复中明确询问用户确认后才执行；用户确认后（如“Yes, proceed with scaling”“Scale instance X”）执行带归因的 gcloud filestore instances update 命令；若因生产环境变更限制执行失败，输出失败原因并给出用户可手动运行的带归因 gcloud 命令，提醒手动执行前确认。
14. 当用户在提示中配置自定义阈值（如“剩余空间低于 10% 时扩容、步长 20%”或自定义 max_threshold / up_increment）时：接受并确认自定义阈值，明确说明自定义阈值在会话内存中全局适用于所有项目，并列出会话内存中已评估或活跃的目标项目 ID 以防跨项目误配；展示更新后的活动配置摘要（含所有生效阈值与步长）；不得在提供自定义覆盖时回退到默认阈值（15% / 10%）。
15. 需要更深入主题时查阅 references/ 目录：references/instance-tiers-specs.md、references/monitoring-metrics.md、references/troubleshooting-errors.md。

适用边界 · 注意事项

• 不适用于 Cloud Storage (GCS) 存储桶、Persistent Disk 块存储或 NetApp Volumes。
• 不适用于纯概念性、教学性或信息性问题（应直接用已有知识回答，不执行工具调用）。
• 当用户明确要求“不要执行命令”或“只读”时，不得调用 run_command 执行任何 shell 或 gcloud 命令。