gogcli-ops

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）

工作流决策树

1. 通过 scripts/gog_parse_url.py 确定目标类型：sheet | doc | slide | file | folder | id | unknown。
2. 选择最精简的只读命令来确认访问权限：
   • Sheets：gog sheets metadata <spreadsheetId>
   • Docs：gog docs info <docId>
   • Slides：gog slides info <presentationId>
   • Drive 文件/文件夹：gog drive get <fileId> 或 gog drive permissions <fileId>
3. 只有在用户明确确认后，才继续执行写入操作（更新/追加/移动/共享/删除）。

核心任务

身份验证和账号选择

• 显示已保存的账号：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。
• 如果访问失败，请用户将文件共享给所选账号，或提供正确的账号。

资源

• 精简的命令列表请参阅 ${CLAUDE_SKILL_DIR}/references/gogcli-cheatsheet.md。
• 运行命令前，使用 scripts/gog_parse_url.py 将 URL 标准化为 ID。