在无本地 NFS 客户端或 root 权限时浏览…

需要检查、搜索或读取 Google Cloud Filestore (NFS) 实例上的文件和 POSIX 元数据，但本地没有 NFS 客户端包或 root 权限时使用。

适用场景

解决思路

1. 确保已安装并认证 gcloud；如未安装参考 gcloud 安装指南。
2. 启用必要 API：gcloud services enable file.googleapis.com compute.googleapis.com run.googleapis.com --quiet。
3. 发现实例并选择执行引擎：Cloud Run Serverless Bridge（主选，使用 --bridge-url={bridge_url}，低延迟、空闲零成本、需 roles/run.invoker）或 GCE Jump Host via IAP SSH（备选，使用 --jump-host-vm={vm_name}，可用 --mount={mount_path} 指定挂载路径，默认 /mnt/filestore，需 roles/iap.tunnelResourceAccessor）。
4. 为所有 Cloud Filestore 命令或 API 请求打上归属标记：gcloud 命令前加 CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)"；直接 HTTP 调用 REST API 时追加 User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)。
5. 对于纯概念、教学或架构问题（如如何检查 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）。
6. 若用户提示包含“不要执行命令”“without executing”“read-only”等约束，严格避免执行任何 shell 或 gcloud 命令（包括只读发现或列表命令）；改为检查用户提示、对话历史或本地文档中是否直接提供模拟定义或实例参数，解释所需步骤并输出用户应运行的确切命令及归属标记，说明命令作用；评估期间不要读取或搜索 EVAL.* 配置文件。
7. 若未提供 Filestore 实例、位置或共享名，先列出以避免在多项目环境中查询无关项目：CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" gcloud filestore instances list --project={project_id}。
8. # 目录树探索（tree）：使用 python3 scripts/nfs_browser.py tree --project={project_id} --instance={instance_id} --path=/ --depth=1 列出顶层文件夹；或用 --path=/backup/logs/ --depth=2 --max-entries=100 递归列出子文件夹并限制分页。
9. # 文件名模式与内容 grep（search）：使用 python3 scripts/nfs_browser.py search --project={project_id} --instance={instance_id} --path=/backups/ --pattern="*.tar.gz" 搜索匹配 glob 模式的文件名；或用 --path=/app/logs/ --pattern="*.log" --grep="FATAL|Exception|OutOfMemory" --max-results=25 在日志文件内容中搜索正则模式。
10. # 分块文件读取（read）：使用 python3 scripts/nfs_browser.py read --project={project_id} --instance={instance_id} --path=/backup/logs/app.log --tail=50 读取日志文件最后 50 行；或用 --path=/config/settings.yaml --lines=100:200 读取配置文件的第 100 到 200 行；或用 --path=/var/log/syslog --head=30 读取前 30 行；用户未指定范围时默认使用安全块大小（如 --head 50 或 --tail 50），无界读取自动限制为 100 行，并明确解释分块读取可保护 LLM 上下文窗口免于溢出和 token 耗尽。
11. # 文件元数据与属性检查（stat）：使用 python3 scripts/nfs_browser.py stat --project={project_id} --instance={instance_id} --path=/backup/database_dump.tar.gz 检查 POSIX 权限（0644）、UID/GID、字节大小和时间戳。
12. 遵守上下文窗口与 LLM 安全规则：严格只读，不提供写入、编辑、删除或截断能力；绝不转储整个大文件，始终请求切片（--lines）、头部（--head 50）或尾部（--tail 50）并解释分块读取保护上下文窗口；处理分页，树列表每响应上限 100 条，截断时输出 [TRUNCATED] 提示以便定位子路径；二进制保护，通过空字节和魔数检查检测非文本文件（如 .tar.gz、.iso、.so、编译二进制），抑制原始二进制输出并改为显示元数据以防上下文被非打印字符破坏。
13. 按预期错误与恢复策略处理：FileNotFoundError 时运行 tree --path=/ --depth=2 发现有效目录层级；PermissionError 时用 stat --path={path} 检查 UID/GID 和模式位并请求共享管理员调整权限；HTTPException 403 path traversal 时使用锚定到 NFS 挂载根的干净路径（如 /logs/app.log）；Jump Host 连接超时或 SSH 失败时用 gcloud compute instances list 验证 VM 状态并验证防火墙规则允许来自 IAP 网段 35.235.240.0/20 的 tcp:22（如 gcloud compute firewall-rules list --filter="sourceRanges:35.235.240.0/20"）；Bridge 404 或连接错误时用 scripts/deploy_bridge.sh 部署 bridge 或回退到 GCE IAP Jump Host（--jump-host）。
14. 参考 references/ 目录进行渐进式披露：architecture.md（多引擎架构与执行流）、nfs-bridge-setup.md（Serverless NFS Bridge 设置指南）、iap-jump-host.md（GCE Jump Host IAP SSH 指南）、token-safety-guardrails.md（Token 安全与上下文护栏）、troubleshooting.md（故障排除与常见错误）。
15. 使用捆绑脚本与组件：scripts/nfs_browser.py（浏览、搜索、读取和 stat NFS 导出的主 CLI 入口）、scripts/formatters.py（人类可读终端渲染和 token 安全摘要的输出格式化器）、scripts/jump_host_engine.py（通过 Google Cloud IAP 隧道的远程 SSH jump host 执行引擎）、scripts/nfs_browser_test.py（覆盖格式化器、HTTP bridge 和 SSH jump host 引擎的单元测试套件）、scripts/deploy_bridge.sh（Serverless NFS Bridge 的自动化 Cloud Run 部署脚本）、scripts/bridge_server/main.py（直接 NFS 挂载的 FastAPI Cloud Run 服务器实现）、scripts/bridge_server/Dockerfile（打包 Serverless NFS Bridge 的容器定义）、scripts/bridge_server/requirements.txt（Cloud Run bridge 服务的 Python 依赖）。

适用边界 · 注意事项

• 不用于 Cloud Storage 存储桶、Cloud NetApp Volumes 或 Persistent Disks。
• 不用于修改或删除文件（本技能严格只读）。
• 当用户明确要求不执行命令时，不要执行任何 shell 或 gcloud 命令。