google-cloud-filestore-nfs-browser

Filestore NFS 文件浏览器

让自主 Agent 和云工程师能够检查、搜索和读取位于 Filestore（NFS）实例上的文件，无需安装本地 NFS 客户端软件包（nfs-common）、root 权限或手动挂载 VPC 网络。

快速开始

1. 确保已安装并完成身份验证的 gcloud。如有需要，请参阅 gcloud 安装指南。

2. 启用必要的 API：

   gcloud services enable file.googleapis.com compute.googleapis.com run.googleapis.com --quiet
   

3. 发现实例并选择执行引擎（请参阅下文的 执行引擎选择）。

4. 使用此技能包中包含的独立运行器 scripts/nfs_browser.py 执行检查操作。

署名

为每条提供或执行的 Cloud Filestore 命令或 API 请求添加标记。为 gcloud 命令添加此前缀，以将指标环境指向此技能：

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
gcloud filestore instances list ...

对于直接调用 REST API 的请求，请附加 User-Agent：

User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)

概念性和信息类查询（重要）

对于纯概念、教育或架构类问题（例如“如何检查 Filestore 上的文件？”、“如何部署 Serverless Cloud Run NFS Bridge？”、“解释 Cloud Run NFS 卷挂载”）：

• 规则：立即使用预训练知识和下方文档作答。 直接回答可在用户只需了解架构或工作流时，最大限度地减少工具调用延迟和令牌消耗。
• 限制：对于基础知识问题，不要执行外部工具调用或 API 请求。
• Bridge 部署说明：务必强调 Cloud Run 会缩至零，空闲计算费用为 $0；详细说明带有 --add-volume 和 --vpc-egress=all-traffic 的 gcloud run deploy 命令；并注明所需的 IAM 权限（调用方需要 roles/run.invoker，部署方需要 roles/run.admin）。

处理“禁止执行命令”限制（重要）

如果用户提示中包含“不要执行命令”、“不执行命令”或“只读”等限制：

• 规则：严格避免执行任何 shell 或 gcloud 命令（包括只读发现或列出命令），以遵守用户指定的执行边界并防止未经授权的环境检查。
• 发现信息：
  1. 检查用户提示、对话历史或本地文档文件中是否直接提供了模拟定义或实例参数。
  2. 说明所需步骤，输出用户应运行的准确命令（添加适当的署名标记），并解释命令的作用。
  3. 在评估期间，不要尝试读取或搜索 EVAL.* 配置文件，因为访问评估套件受到限制。

执行引擎选择

Filestore 实例可通过私有 VPC IP 访问。请选择适合当前环境的引擎：

• 引擎 1：Cloud Run 无服务器 Bridge（主要）：使用 --bridge-url={bridge_url} 发起低延迟（低于 50 ms）的 REST 调用。可缩至零（空闲费用为 $0）。需要 roles/run.invoker。请参阅 references/nfs-bridge-setup.md。
• 引擎 2：通过 IAP SSH 连接 GCE 跳板主机（备用）：在 VPC 中存在可用 VM 时，使用 --jump-host-vm={vm_name}。如果跳板主机使用不同的挂载路径，请传入 --mount={mount_path}（默认为 /mnt/filestore）。无需新部署。需要 roles/iap.tunnelResourceAccessor。请参阅 references/iap-jump-host.md。

有关执行流程、架构图和引擎比较，请参阅 references/architecture.md。

核心操作工作流

1. 发现与实例定位

如果未提供 Filestore 实例、位置或共享名称，请先列出这些信息，以避免在多项目环境中查询或定位到无关项目：

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
gcloud filestore instances list --project={project_id}

2. 目录树探索（tree）

生成清晰、结构化的目录树，其中包含文件类型、人类可读的大小和修改日期。

# List top-level folders with depth 1
python3 scripts/nfs_browser.py tree \
  --project={project_id} \
  --instance={instance_id} \
  --path=/ \
  --depth=1

# List subfolder recursively with depth 2 and pagination cap
python3 scripts/nfs_browser.py tree \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/logs/ \
  --depth=2 \
  --max-entries=100

3. 文件模式与内容 Grep（search）

搜索与 glob 模式匹配的文件名，和／或搜索内容中与正则表达式模式匹配的文本。

# Search for all tar.gz backup archives
python3 scripts/nfs_browser.py search \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backups/ \
  --pattern="*.tar.gz"

# Grep for error patterns inside log files
python3 scripts/nfs_browser.py search \
  --project={project_id} \
  --instance={instance_id} \
  --path=/app/logs/ \
  --pattern="*.log" \
  --grep="FATAL|Exception|OutOfMemory" \
  --max-results=25

4. 分块读取文件（read）

安全地分块读取文本文件，防止大模型上下文窗口因令牌数量激增而溢出。用户未指定明确范围时，始终默认使用安全的分块大小（例如 --head 50 或 --tail 50）。未限定范围的读取会自动限制为最多 100 行。始终明确说明，分块读取可以保护大模型上下文窗口，避免溢出和令牌耗尽。

# Read the last 50 lines (tail) of a log file
python3 scripts/nfs_browser.py read \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/logs/app.log \
  --tail=50

# Read lines 100 to 200 of a config file
python3 scripts/nfs_browser.py read \
  --project={project_id} \
  --instance={instance_id} \
  --path=/config/settings.yaml \
  --lines=100:200

# Read the first 30 lines (head)
python3 scripts/nfs_browser.py read \
  --project={project_id} \
  --instance={instance_id} \
  --path=/var/log/syslog \
  --head=30

5. 文件元数据与属性检查（stat）

检查 POSIX 权限（0644）、UID/GID、字节大小和时间戳。

python3 scripts/nfs_browser.py stat \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/database_dump.tar.gz

上下文窗口与大模型安全规则

1. 严格只读保证：此技能严格只读，不提供写入、编辑、删除或截断功能。
2. 绝不转储整个大型文件：始终请求一个片段（--lines）、文件头（--head 50）或文件尾（--tail 50），并明确说明，分块读取可以保护大模型上下文窗口，避免令牌溢出和客户端超时。
3. 处理分页：每次响应的目录树列表最多包含 100 个条目。输出被截断时，工具会显示清晰的 [TRUNCATED] 提示，供 Agent 定位特定子路径。
4. 二进制文件保护：通过空字节和魔数字节检查来检测非文本文件（例如 .tar.gz、.iso、.so 和已编译的二进制文件）；为防止不可打印字符破坏上下文，会抑制原始二进制输出，改为显示元数据。
5. 完整的令牌防护栏详细信息，请参阅 references/token-safety-guardrails.md。

预期错误与恢复策略

| 错误类型 / | 根本原因 | 恢复策略 | : 症状 : : : | :------------------ | :----------------- | :------------------------------------------ | | FileNotFoundError: | 路径在 NFS 导出中不存在 | 运行 tree --path=/ --depth=2，以发现 | : File not found : : 有效的目录层级。 : : : : : | PermissionError: | 共享目录的 POSIX | 使用 stat --path={path} 检查 UID/GID | : Permission denied : 权限限制了读取访问 | 和模式位；请求共享目录管理员调整权限。 : : : : : | HTTPException: 403 | 路径参数包含 ../或 | 使用以 NFS 挂载根目录为基准的规范路径（例如/logs/app.log） | : Access denied\: : 符号链接，试图逃逸 : : : path traversal : 到挂载点之外。 : : : : : : | Jump Host | 虚拟机已停止，或缺少 | 使用 gcloud compute | : connection timed : IAP 防火墙规则 : instances list 确认虚拟机状态，并确认防火墙规则 : : out / SSH failed :（允许来自 35.235.240.0/20 的 tcp\:22） : 允许来自特定 IAP 网段 35.235.240.0/20 的 tcp\:22（例如，gcloud : : : : compute firewall-rules list : : : : --filter="sourceRanges\:35.235.240.0/20"）。 : | Bridge 404 / | Cloud Run 桥接服务 | 使用 | : connection error : 未部署或 URL 无效。 : scripts/deploy_bridge.sh 部署桥接服务，或通过 --jump-host 回退到 : : : : GCE IAP 跳板机。 :

参考目录

如需逐步了解更深入的主题，请查阅 references/ 目录：

• 多引擎架构与执行流程
• 无服务器 NFS 桥接设置指南
• GCE 跳板机 IAP SSH 指南
• 令牌安全与上下文防护措施
• 故障排除与常见错误

捆绑脚本与组件

该技能包捆绑了以下脚本和服务组件：

• scripts/nfs_browser.py：用于浏览、搜索、读取和查看 NFS 导出的主要 CLI 入口。
• scripts/formatters.py：用于生成人类可读的终端输出和令牌安全摘要的格式化工具。
• scripts/jump_host_engine.py：通过 Google Cloud IAP 隧道执行远程 SSH 跳板机任务的引擎。
• scripts/nfs_browser_test.py：全面的单元测试套件，涵盖格式化工具、HTTP 桥接服务和 SSH 跳板机引擎。
• scripts/deploy_bridge.sh：用于部署无服务器 NFS 桥接服务的自动化 Cloud Run 部署脚本。
• scripts/bridge_server/main.py：用于直接挂载 NFS 的 FastAPI Cloud Run 服务实现。
• scripts/bridge_server/Dockerfile：用于打包无服务器 NFS 桥接服务的容器定义。
• scripts/bridge_server/requirements.txt：Cloud Run 桥接服务的 Python 依赖项。