name: gogcli-ops description: “使用 gogcli 进行 Google Workspace 操作（Drive/Sheets/Docs/Slides）。当用户通过 gogcli 请求检查、列出、搜索、导出、读取或更新 Google 文件时使用。触发条件：当用户通过 gogcli 询问检查、列出、搜索、导出、读取或更新 Google 文件；当需要解析 Google URL/ID；当需要认证/账户选择或安全的只读工作流；或当故障排除 gogcli 访问/错误时。” description-en: 使用 gogcli 进行 Google Workspace CLI 操作（Drive/Sheets/Docs/Slides）。触发条件：当用户通过 gogcli 询问检查、列出、搜索、导出、读取或更新 Google 文件；当需要解析 Google URL/ID；当需要认证/账户选择或安全的只读工作流；或当故障排除 gogcli 访问/错误时。 description-ja: “使用 gogcli 进行 Google Workspace 操作（Drive/Sheets/Docs/Slides）。当用户通过 gogcli 请求检查、列出、搜索、导出、读取或更新 Google 文件时使用。触发条件：当用户通过 gogcli 询问检查、列出、搜索、导出、读取或更新 Google 文件；当需要解析 Google URL/ID；当需要认证/账户选择或安全的只读工作流；或当故障排除 gogcli 访问/错误时。”
Gogcli 操作
概述
标准化 gogcli 使用：验证认证，从 URL 解析 ID，默认执行只读检查，然后运行所需的最小命令。
快速开始
- 确认 gogcli 可用：
gog --version - 列出账户并明确选择一个（如果有多个）：
gog auth list - 使用
python3 scripts/gog_parse_url.py "<url-or-id>"将 URL 解析为 ID - 首先运行只读元数据命令（Drive/Sheets/Docs/Slides）
工作流决策树
- 通过
scripts/gog_parse_url.py识别目标类型：sheet | doc | slide | file | folder | id | unknown。 - 选择最小的只读命令来确认访问：
- Sheets：
gog sheets metadata <spreadsheetId> - Docs：
gog docs info <docId> - Slides：
gog slides info <presentationId> - Drive 文件/文件夹：
gog drive get <fileId>或gog drive permissions <fileId>
- Sheets：
- 只有在用户明确确认后才进行写操作（更新/追加/移动/共享/删除）。
核心任务
认证和账户选择
- 显示存储的账户：
gog auth list - 显示认证配置：
gog auth status - 添加/授权账户：
gog auth add <email> - 当存在多个账户时，始终使用
--account <email>。
从 URL 解析 ID
- 解析 URL 或 ID：
python3 scripts/gog_parse_url.py "<url-or-id>"
- 如果输出类型是
unknown，请询问直接 ID 或不同的 URL。
Drive（文件/文件夹）
- 列出根目录或文件夹：
gog drive ls - 通过查询搜索：
gog drive search "<query>" - 获取元数据：
gog drive get <fileId> - 下载/导出：
gog drive download <fileId> - 权限检查：
gog drive permissions <fileId>
Sheets
- 元数据：
gog sheets metadata <spreadsheetId> - 读取值：
gog sheets get <spreadsheetId> <range> - 导出：
gog sheets export <spreadsheetId> - 写操作（更新/追加/清除/格式）：需要明确确认和精确范围。
Docs
- 元数据：
gog docs info <docId> - 读取文本：
gog docs cat <docId> - 导出：
gog docs export <docId>
Slides
- 元数据：
gog slides info <presentationId> - 导出：
gog slides export <presentationId>
输出模式
- 使用
--plain获取稳定的 TSV 输出。 - 当调用者需要结构化输出时使用
--json。 - 在非交互式流程中使用
--no-input以避免挂起。
错误处理
- 403/404：验证账户（
gog auth list），检查权限（gog drive permissions <fileId>），并确认 ID。 - 如果访问失败，请求用户将文件与所选账户共享或提供正确的账户。
资源
- 查看
references/gogcli-cheatsheet.md获取紧凑的命令列表。 - 在运行命令之前，使用
scripts/gog_parse_url.py将 URL 规范化成 ID。