gdocs

用途

本技能用于通过 gog CLI（v0.10.0）操作 Google 文档，覆盖文档的创建、读取、写入、插入、删除、查找替换、复制、导出和标签页管理等常见操作。

执行路径为 gog，认证账号为 gog 中已认证的账号。使用 exec 工具执行时，需指定 timeout: 60。文档 ID 可从 URL https://docs.google.com/document/d/<docId>/edit 中获取。

主要能力与命令

创建文档

gog docs create "<title>"
gog docs create "<title>" --parent "<folderId>"    # 在指定文件夹中创建
gog docs create "<title>" --file "./content.md"     # 从 Markdown 文件导入

获取文档信息

gog docs info <docId>
gog docs info <docId> --json

读取文档（纯文本）

gog docs cat <docId>
gog docs cat <docId> --tab "<tabTitle>"      # 仅读取指定标签页
gog docs cat <docId> --all-tabs              # 显示全部标签页
gog docs cat <docId> --max-bytes 0           # 不限制（默认 2MB）

写入文档

# 追加到末尾（默认）
gog docs write <docId> "追加文本"
gog docs write <docId> --file "./content.txt"
echo "文本" | gog docs write <docId> --file -

# 整体替换
gog docs write <docId> "新内容" --replace
gog docs write <docId> --file "./content.md" --replace --markdown

插入文本（指定位置）

gog docs insert <docId> "插入文本" --index 1          # 插入到开头
gog docs insert <docId> "插入文本" --index 50         # 插入到第 50 个字符处
gog docs insert <docId> --file "./snippet.txt" --index 1

删除文本（指定范围）

gog docs delete <docId> --start 1 --end 100

查找替换

gog docs find-replace <docId> "查找字符串" "替换字符串"
gog docs find-replace <docId> "old" "new" --match-case    # 区分大小写

复制文档

gog docs copy <docId> "副本标题"
gog docs copy <docId> "副本标题" --parent "<folderId>"

导出（下载）

gog docs export <docId>                              # PDF（默认）
gog docs export <docId> --format docx                # Word 格式
gog docs export <docId> --format txt                 # 文本格式
gog docs export <docId> --format pdf --out "./out.pdf"

标签页列表

gog docs list-tabs <docId>
gog docs list-tabs <docId> --json

内容更新（update）

gog docs update <docId> --content "新内容"                    # 整体替换
gog docs update <docId> --content "追加文本" --append          # 追加到末尾
gog docs update <docId> --content-file "./doc.md" --format markdown  # Markdown 转换

输出选项

选项	说明
--json / -j	JSON 输出
--plain / -p	TSV 输出（便于解析）
--results-only	JSON 时仅输出结果
--select "field1,field2"	JSON 时筛选字段
--dry-run / -n	不执行变更，仅显示意图

典型工作流

新建文档并写入

# 1. 创建（获取 ID）
gog docs create "会议纪要 2026-02-15" --json

# 2. 写入内容
gog docs write <docId> --file "./minutes.md" --replace --markdown

读取文档并编辑

# 1. 确认内容
gog docs cat <docId>

# 2. 文本替换
gog docs find-replace <docId> "旧项目名" "新项目名"

导出

# PDF 输出
gog docs export <docId> --format pdf --out "./report.pdf"

# Word 输出
gog docs export <docId> --format docx --out "./report.docx"

从模板复制

# 1. 复制模板
gog docs copy <templateDocId> "新文档" --json

# 2. 替换占位符
gog docs find-replace <newDocId> "{{NAME}}" "田中太郎"
gog docs find-replace <newDocId> "{{DATE}}" "2026年2月15日"

标签页操作

# 查看标签页列表
gog docs list-tabs <docId>

# 读取指定标签页内容
gog docs cat <docId> --tab "Sheet1"

# 一次性显示全部标签页内容
gog docs cat <docId> --all-tabs

注意事项

• 文档列表获取：gog docs 没有 list 命令，需通过 Drive 搜索：gog drive ls --query "mimeType='application/vnd.google-apps.document'"
• write 默认是追加：如需整体改写，必须加 --replace
• Markdown 转换：--markdown 需与 --replace 配合使用（write）；update 中使用 --format markdown
• insert 的 index：从 1 开始，文档开头为 index=1
• delete 的范围：--start 与 --end 为必填，建议先用 cat 确认内容后再指定索引
• 大文档：cat 默认上限为 2MB，--max-bytes 0 表示不限制
• 特殊字符：注意 shell 转义（引号、换行等）
• 长正文：使用 --file 选项或 stdin（--file -）