实用提示：使用 Gemini 与 MCP 调试无服务器版 Apache Spark

本指南将逐步展示如何从原始材料构建出一个可用的系统，用于：利用 Gemini 和 MCP 调试无服务器 Apache Spark。重点在于可操作的步骤、明确的检查点，以及可直接放入代码库的代码，无需猜测其用途。 在概览阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。 建议使用小型、可测试的单元而非庞大的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。

零上下文 AI 的局限性

在处理“零上下文限制”阶段时，首先需列出相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。 每次调用时都要记录请求ID、模型ID以及延迟时间。若没有这些记录，间歇性的服务端错误就会被误认为是应用程序的故障。

py4j.protocol.Py4JJavaError: An error occurred while calling o80.load.
org.apache.spark.SparkException: Job aborted due to stage failure.
Traceback (most recent call last):
  File "spark_job.py", line 26, in main
    df_with_status = df.withColunm("status", lit("active"))
AttributeError: 'DataFrame' object has no attribute 'withColunm'

利用 Google Antigravity CLI 为终端带来上下文功能

在实施“将上下文引入开发环境”这一步骤时，首先需列出相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合预期。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 每次调用都要记录请求ID、模型ID以及延迟时间。若没有这些记录，间歇性的服务端错误就会被视为应用程序的故障。

export GOOGLE_CLOUD_PROJECT="$PROJECT_ID"

mkdir -p ~/.gemini/antigravity-cli
cat << 'EOF' | tee ~/.gemini/antigravity-cli/settings.json ~/.gemini/jetski/cli/settings.json ~/.gemini/antigravity/settings.json ~/.gemini/settings.json
{
  "toolPermission": "always-proceed",
  "permissions": {
    "allow": [
      "read_file(*)",
      "write_file(*)",
      "mcp(*)"
    ]
  }
}
EOF

agy -p "examine spark_job.py, fix the DataFrame method typo, and save the file"

利用Spark MCP服务器进行全基础设施调试

在通过测试环境进行全基础设施调试时，首先需明确相关规范：所需输入、成功信号以及部分故障时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务错误就会被视为应用程序的缺陷。 在通过测试环境进行全基础设施调试时，首先需明确相关规范：所需输入、成功信号以及部分故障时的处理方式。这样的清单能确保后续的代码修改保持一致性。 优先使用小型、可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应能指向单一的责任模块，而非复杂的流程链。

mkdir -p ~/.gemini/config
cat << EOF | tee ~/.gemini/config/mcp_config.json
{
  "mcpServers": {
    "spark": {
      "serverUrl": "https://dataproc-${REGION}.googleapis.com/mcp"
    }
  }
}
EOF

agy -p "inspect my latest failed Spark batch via MCP, identify the root cause, and fix spark_job.py so it succeeds"

利用智能体技能编写操作手册

将“利用智能体技能编写操作手册”这一阶段视为可度量的工作界面最为有效。在扩大范围之前，先记录一份最佳案例、一个失败案例以及回滚说明。 应将此阶段视为输入与已验证输出之间的契约。为相关文档命名，明确成功标准，杜绝默许的半完成状态。 在讲解循环逻辑之前，先锁定解释器及依赖项文件。在笔记本电脑与持续集成环境之间切换是API演示中最常见的隐性故障来源。

mkdir -p .agents/skills/spark-troubleshooter
cat << 'EOF' > .agents/skills/spark-troubleshooter/SKILL.md
---
name: spark-troubleshooter
description: Diagnoses failed Apache Spark batches on Managed Service for Apache Spark, inspects live batch logs via the Spark MCP server, and recommends resolution commands. Use when troubleshooting Spark job failures.
---

# Spark Troubleshooter Skill

This skill diagnoses failed Apache Spark batches on Managed Service for Apache Spark and offers rapid solutions.

## Instructions
1. Verify local syntax: Locate the PySpark script in the current directory and check for compilation or syntax issues.
2. Fetch live batch state: Call the Spark MCP server tool list_batches and inspect the status of the most recent batch.
3. Check JVM and PySpark logs: Look for standard Spark exceptions, such as FileNotFoundException, AnalysisException, or out-of-memory errors in the batch logs.
4. Recommend action:
    * If a Cloud Storage path is invalid, recommend the exact gcloud storage buckets create command or update the script path.
    * If the job fails due to configuration, generate the correct gcloud dataproc batches submit command with the appropriate parameters.
    * If a syntax error is detected, fix the code in-place.
    * For other errors, recommend a fix.
EOF

agy -p "Diagnose why my last Spark batch failed and recommend a fix"

[Spark Troubleshooter] Running diagnostic playbook...
- Local Syntax: OK (spark_job.py has valid python syntax)
- Spark Batch Status: FAILED (batch-928f1)
- Log Exception: java.io.FileNotFoundException for gs://my-missing-bucket/input.csv

Recommendation:
The bucket gs://my-missing-bucket does not exist. Run this command to create it:

  gcloud storage buckets create gs://my-missing-bucket --location=$REGION

Once created, submit the batch again with:

  gcloud dataproc batches submit pyspark spark_job.py \
      --region=$REGION \
      --deps-bucket=gs://$BUCKET_NAME

利用Cloud Logging中的Gemini进行基于网页的故障排查

将 Gemini 阶段的基于 Web 的故障排查视为可测量的界面使用效果最佳。在扩大范围之前，先记录一份理想的测试转录内容、一个故障案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。在讲解循环逻辑之前，先锁定解释器及依赖项的配置文件。笔记本电脑与持续集成环境之间的差异是 API 演示中最常见的隐性故障原因。

总结

将“总结阶段”视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想的运行日志、一个故障案例以及回滚说明。 应将配置置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。 在讲解循环逻辑之前，先锁定解释器及依赖项的版本。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障来源。 将“总结阶段”视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想的运行日志、一个故障案例以及回滚说明。 相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤出现故障时，故障点应指向单一职责，而非复杂的流程链。

操作检查清单

将操作检查清单视为可度量的基准，这样效果最佳。在扩大范围之前，先记录一份完美的操作流程、一个故障案例以及回滚说明。

同时记录正常运行路径和恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。

在讲解循环逻辑之前，先确定解释器版本及依赖项的锁定文件。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障来源。

在网关处进行身份验证，在数据层再次授权。仅靠承载令牌并不能构成租户边界。

编写简短的操作手册：说明如何轮换密钥、如何清空队列、以及如何回滚上一次的数据导入操作。

在功能测试结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。

在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如注重扎实的可靠性。

关于3af041a23886的批注：请将提供商密钥移出代码仓库，设定单会话令牌上限，并将日志存储在评估用示例文件旁，以便后续模型更换时保持数据可比性。