Google Docs 操作

Z3 全文↑ Z2 条目

术-操作 · 术层 skill 全文

← 返回术层 skill 索引 · 返回方法论区

本页是 <code>rules/skills/google_docs.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/google_docs.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

Skill: Google Docs 操作

通过 CLI 命令操控 Google Docs：发布 Markdown 文件、创建文档、搜索、修改、分享、Tab 管理。

When to Use

用户说出以下意图时触发：

"帮我创建一个 Google Doc"
"把这个 Markdown 发到 Google Docs"
"搜索我的 Google Docs"
"把这个文档分享给 xxx"
"修改那个文档的标题 / 内容"
任何涉及 Google Docs 创建、搜索、修改、分享的需求

Prerequisites

项目位置：adhoc_jobs/gdocs_skill/
Python venv：adhoc_jobs/gdocs_skill/.venv/（用 uv 创建）
OAuth 凭证：adhoc_jobs/gdocs_skill/secrets/credentials.json 必须存在
首次使用需完成 OAuth 授权（浏览器弹窗），详见项目 README.md

调用方式

所有命令在项目目录下通过 python -m gdocs 调用，输出均为 JSON。

cd /path/to/knowledge_working/adhoc_jobs/gdocs_skill && source .venv/bin/activate

常见场景

场景 1：把一个 Markdown 文件发布到 Google Docs

这是最常见的需求。

python -m gdocs publish path/to/report.md --title "AI 前线 2026-03-08"

发布后立刻分享给某人：

python -m gdocs publish path/to/report.md --title "报告" --share someone@example.com --role writer

场景 2：Tab 管理

列出文档所有 Tab：

python -m gdocs tab list DOC_ID

给文档添加新 Tab：

python -m gdocs tab add DOC_ID "Tab标题"
python -m gdocs tab add DOC_ID "Tab标题" path/to/content.md --format markdown

更新已有 Tab 的内容（清空后重写）：

python -m gdocs tab replace DOC_ID TAB_ID path/to/updated.md

默认使用 markdown 格式。如需纯文本：

python -m gdocs tab replace DOC_ID TAB_ID file.txt --format plain

重命名 Tab：

python -m gdocs tab rename DOC_ID TAB_ID "新标题"

场景 3：创建空文档

python -m gdocs create --title "新文档"

场景 4：搜索文档

python -m gdocs search "关键词"
python -m gdocs search "关键词" --max-results 20

场景 5：分享文档

python -m gdocs share DOC_ID --email user@example.com --role writer
python -m gdocs share DOC_ID --email user@example.com --role reader --message "请查看"

场景 5.5：删除文档（清理 test / 废 docs）

python -m gdocs delete DOC_ID                # 移到回收站（默认，30 天可恢复）
python -m gdocs delete DOC_ID --permanent    # 立即永久删除（不可恢复）

何时用：

调试 publish / create 失败留下的 test docs
一次操作产生多份重复 doc（参见 §故障排查）
Sub-agent 跑测试自动产生的 scaffold doc

纪律：每次 create / publish 之前，先想清楚是否会留下不需要的 doc。如果是 debug 用 doc，用完立即 delete，不要留在用户的 Drive 里污染。Default trash 模式保留 30 天可恢复窗口。

场景 6：修改标题 / 获取链接

python -m gdocs title DOC_ID "新标题"
python -m gdocs link DOC_ID
python -m gdocs link DOC_ID --public

场景 7：在文档中插入本地图片

python -m gdocs image DOC_ID path/to/image.png --width 468

默认插入到文档末尾。指定位置插入需要知道字符 index：

python -m gdocs image DOC_ID image.png --index 2050 --width 468

--width 468 是全宽。图片会先上传到 Google Drive 再插入文档。

带图片的 Markdown 发布流程：Markdown 中的 !alt（local_path.png） 不会自动变成图片，publish 后 alt text 会保留为纯文本。正确做法：

先 publish markdown（图片占位符变成 alt text）
用 Google Docs API 扫描文档找到 alt text 的 index
从文档底部往顶部逐个 gdocs image --index 插入，避免 index 偏移

支持的 Markdown 格式

语法	效果
`# 标题`	Heading 1
`## 标题`	Heading 2
`### 标题`	Heading 3
`加粗`	加粗
`斜体`	斜体
`加粗斜体`	加粗+斜体
` 代码 `	等宽字体 (Courier New)
`文本（url）`	超链接
`- 项目`	无序列表
`1. 项目`	有序列表
`---`	分割线（灰色居中线）
`> 引用文本`	引用块（左缩进 + 左边框）
`\	col \	col \	`	原生表格（表头自动加粗）

注意事项

OAuth scope 为 drive.file，只能访问本应用创建或用户主动打开的文件
搜索只能找到上述范围内的文档，无法搜索整个 Google Drive
已知 doc ID 时直接操作，不要绕道 search。 search 在 drive.file scope 下可见范围极窄，用户给了 URL/ID 的情况下直接调用 tab list、tab replace 等命令即可
所有输出为 JSON，错误输出到 stderr
凭证存储在项目内 secrets/ 目录，已 gitignore
Token 自动刷新，过期后会自动重新授权

故障排查

CLI publish 失败时怎么办

正常错误信息应包含 status code 和 response body，例如 {"error": "Failed to create document '...': HTTP 503 — <body>"}。先看 status code 和 body，再决定重试还是修参数。

Status code 速查:

429 / 5xx：transient 错误，client.py 已经自动 retry 3 次；如果仍失败，直接重试整个 CLI 命令，不要 fallback 到 workaround chain。
400：request 格式错。看 response body 找具体字段。
401 / 403：OAuth 失效。删 secrets/token.json 后重新授权。
404：doc_id 不存在或没权限。

反 pattern：fallback 到 workaround chain

如果 CLI publish 失败，不要先创建 debug doc、再绕过 CLI 直接调 client、再 tab replace、再 share。这样容易留下 test doc 污染 Drive。正确做法是先读错误细节；如果不得不创建 debug doc 验证 auth，用完立即 gdocs delete DOC_ID。

CLI publish 排版不对

症状：doc 创建成功但所有内容是纯文本，没有 heading / table 样式。

原因：直接调用 client.create_document() 没走 content_format="markdown" 路径。

修复：用 gdocs tab replace DOC_ID t.0 file.md --format markdown 重写同一份 doc。Tab id 可以用 gdocs tab list DOC_ID 查到。不要重新 create 新 doc。

OAuth 重新授权

如果遇到 OAuth 相关错误：

删除 secrets/token.json
重新运行命令，浏览器会弹出授权页面
确认当前 Google 账号在 OAuth consent screen 的 Test users 列表中

← 返回术层 skill 索引 · 返回方法论区