企业官网建设流程全解析

gog-docs 技能指南：用 gog CLI 安全操控 Google Docs 的完整命令体系

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

导读

本文围绕 gog 开源项目中的gog-docs技能文档（.agents/skills/gog-docs/SKILL.md），系统梳理 gog CLI 面向 Google Docs 的完整操作能力：从只读安全起步、49 个文档子命令的用途索引，到 Markdown 写入、文本/段落格式化、原生表格、页眉页脚、Tabs 与智能芯片等结构化编辑，再到--readonly、--dry-run、--wrap-untrusted等 Agent 安全护栏。读完本文，你将掌握如何像操作本地文件一样在终端中安全、可脚本化地创建、读取、编辑与导出 Google Docs，并理解每个命令背后的 Docs API 调用原理与源码实现位置。

技能定位：gog-docs 是什么

gog-docs是 gog 仓库中为 Agent（LLM 自动化）准备的技能包之一，其定义位于 .agents/skills/gog-docs/SKILL.md，配套的 Agent 接口声明在 .agents/skills/gog-docs/agents/openai.yaml（display_name: "gog Google Docs"，默认提示词为"Use $gog-docs to perform this Google Docs task safely."）。

技能文档开篇给出了三条核心约定：

1. 先读共享规则：使用本技能前，必须先阅读 .agents/skills/gog/SKILL.md，其中定义了全局的认证（auth）、输出（output）、安全（safety）与实时写入（live-write）规则；
2. 不猜命令语法：所有命令的运行参数以gog docs <command> --help与gog schema docs <command> --json为准；
3. 文件由脚本生成：该 SKILL.md 由 scripts/gen-agent-skills.mjs 生成，不应手工编辑。

从源码结构看，Google Docs 功能是 gog 中命令最多的域之一：入口聚合在 internal/cmd/docs.go 的DocsCmd结构体，实现散布在 internal/cmd 下数十个docs_*.go文件中（如 docs_read.go、docs_mutation.go、docs_sed.go 等），驱动层基于 Google Docs API v1。

Safe start：三行命令完成安全起步

SKILL.md 给出的安全起步模板，适合任何首次对接 Google Docs 的场景：

gog auth list --check --json --no-input gog schema docs --json gog --readonly --account user@example.com docs cat DOCUMENT_ID --json --wrap-untrusted

三条命令各司其职：

对应的安全铁律（从 .agents/skills/gog/SKILL.md 继承并适用于 Docs）：

• 显式选账号：始终用--account指定账号，避免默认账号误用；
• Agent 可解析输出：读取 Google 内容一律使用--json --wrap-untrusted；
• 只读优先：任务不允许改动 Google 数据时加--readonly（运行时拦截所有变更类 API 请求）；
• 非交互与演练：自动化中加--no-input，受支持的写入前先加--dry-run；
• 写前确认：任何写/删操作前，确认账号、对象 ID 与确切变更内容。

--readonly、--dry-run、--no-input均为全局根级 flag，定义于 docs/commands/gog-docs.md 的 Flags 表中（如-n/--dry-run/--noop/--preview打印预期动作并成功退出、--readonly同时让auth add只申请只读 OAuth scope、--wrap-untrusted在 JSON/raw 输出中把抓取的文本字段包上外部不可信内容标记）。

命令全景：49 个 docs 子命令速查表

SKILL.md 给出了gog docs的完整子命令索引，下文原样继承并补充了别名与关键 flag 说明（源码依据 internal/cmd/docs.go 中的 kong 声明）：

SKILL.md 的结语规则同样重要：gog docs <command> --help查看 flag，gog schema docs <command> --json查看机器可读契约，不要猜测命令语法。

读取与发现：只读是默认姿势

纯文本与结构化读取

最常用的读取命令是docs cat，其实现位于 internal/cmd/docs_read.go。核心 flag 包括：

gog docs cat <docId> # 纯文本 gog docs cat <docId> --json --wrap-untrusted # Agent 友好 JSON gog docs cat <docId> -N # 段落编号 gog docs cat <docId> --tab "Notes" # 读取指定 Tab gog docs cat <docId> --all-tabs # 全部 Tab（带标题头） gog docs cat <docId> --raw # 原始 API JSON gog docs cat <docId> --chips # 内联渲染智能芯片/文本链接

注意--tab与--all-tabs互斥（源码在 docs_read.go 做了显式校验），空--tab会被拒绝而非静默回退。--max-bytes默认 2,000,000 字节，防止超大文档撑爆内存。

元数据、结构与元素发现

• 元数据：gog docs info <docId>返回id、name、mimeType、webViewLink、revisionId；实现中通过Fields("documentId,title,revisionId")限制传输量（internal/cmd/docs.go）。
• 内容清单：docs tables list、docs images list、docs headings list、docs paragraphs list四命令均支持--tab，JSON 输出含稳定元素索引与 Docs API 位置，--plain输出无表头 TSV 便于 shell 管道。
• 无损原始输出：gog docs raw <docId> --pretty直接输出Documents.Get的完整响应（无 Fields 限制），专为脚本与 LLM 消费设计——它保留info会丢弃的表格、建议、逐 run 样式、列表嵌套、命名区间与内联对象。internal/cmd/docs.go 注释明确指出其语义："lossless; for scripting and LLM consumption"。
• 待处理建议：gog docs suggestions list <docId>只读地请求 Google 的 inline suggestions 视图，报告建议 ID、插入/删除类型、UTF-16 区间、文本与所在段落；当前刻意排除纯样式建议与接受/拒绝变更。

查找定位：UTF-16 索引是底层编辑的"坐标"

Docs API 的所有区间都用UTF-16 码元索引表示。docs find-range帮你把字面文本解析成精确坐标：

gog docs find-range <docId> "Release status" --json gog docs find-range <docId> "Owner" --all --tab "Plan" --plain gog docs find-range <docId> "Quarterly" --segment "$header_id" --json

关键约束：emoji 等非 BMP 字符占用 2 个 UTF-16 单元，返回的索引可直接用于 Docs API 区间，不要用字节或 rune 偏移重算。直接定位类命令（insert、update、delete、insert-person、insert-page-break）都支持--at <text>字面锚点，配合--occurrence N处理重复文本、--match-case区分大小写：

gog docs insert <docId> "Prefix: " --at "Release status" gog docs update <docId> --at "Draft" --text "Ready" gog docs delete <docId> --at "Remove me"

写入与 Markdown 渲染：从文本到格式化文档

基础写入

docs write支持三种内容来源（--text/--file <path>/-读 stdin）与两种写入模式（--append追加、--replace整体替换）：

gog --account user@example.com docs write <docId> --append --text '...' gog --account user@example.com docs write <docId> --replace --markdown --file report.md gog --account user@example.com docs write <docId> --append --tab "Data" --markdown --replace --file data.md

--markdown会调用项目自研的本地 Markdown 渲染器（而非 Drive 的整文档转换），把 Markdown 转成 Docs 原生格式。根据 docs/docs-editing.md，渲染器特性包括：标题紧跟其后正文、行内替换不破坏原段落（除非替换以换行结尾）、替换前重置继承样式、表格单元格内支持 HTML<br>变体、围栏代码块使用 Roboto Mono + 深绿色文本 + 段落底纹。

精确区间写入

docs update提供更细粒度的控制，START:END是 Google Docs UTF-16 API 区间，必须通过docs cat --raw、docs raw或其它documents.get回读解析，禁止猜测索引：

gog docs update <docId> --replace-range START:END --text 'replacement' gog docs update <docId> --replace-range START:END --markdown --file block.md gog docs update <docId> --at "Draft" --text "Ready" # 字面锚点 gog docs update <docId> --tab "Data" --markdown --file block.md

注意--replace-range与--index互斥。insert --markdown则只插入不删除，适合在解析位置追加整块 Markdown。

孤儿评论保护

写替换（--replace --markdown）前可加--check-orphans做离线预检：若替换会吞掉当前处于打开状态的评论引用文本（quote），命令以退出码 11 在变更前中止。预检复用docs comments locate的实体与空白匹配规则，跳过已解决、无引文与已孤儿化的评论；--tab模式下只检查被替换 Tab 中的评论；JSON 输出在wouldOrphan字段中给出受影响的评论。

格式化：文本、段落、列表与链接

文本与段落格式

docs format <docId> --match <文本>支持全部文本与段落属性：

gog docs format <docId> --match Status --bold --font-size 18 gog docs format <docId> --match "Action item" --text-color '#b00020' gog docs format <docId> --match Heading --alignment center --line-spacing 120 gog docs format <docId> --match "Summary" --indent-start 24 --indent-first-line 12 gog docs format <docId> --match "Summary" --space-above 6 --space-below 12 --keep-with-next

标题样式可用--heading-level N（1..6 快捷方式）或--named-style NAME（完整枚举NORMAL_TEXT、TITLE、SUBTITLE、HEADING_1..HEADING_6，大小写不敏感），二者都写paragraphStyle.namedStyleType，可与--alignment、--line-spacing组合：

gog docs format <docId> --match "Status" --heading-level 2 gog docs format <docId> --match "Overview" --named-style title --alignment center

布尔 keep 控件有对应的--no-...清除形式；--spacing-mode接受 Docs API 值NEVER_COLLAPSE与COLLAPSE_LISTS。--match-all用于格式化所有匹配出现。docs write的纯文本模式接受同一套列表/段落 flag。

原生列表

创建或移除原生列表，可指定精确的字形预设：

gog docs format <docId> --match "Action item" --bullets # 默认 disc 圆点 gog docs format <docId> --match "Step one" --ordered # 默认 decimal 编号 gog docs format <docId> --match "Task" --bullet-preset BULLET_CHECKBOX # 复选框列表 gog docs format <docId> --match "Action item" --no-bullets # 移除

docs write的 flag 表中也列出了--bullets、--ordered、--bullet-preset、--no-bullets。--append模式下若要先建列表再排段落，建议在随后的docs format调用中应用段落布局，让 Docs 先解析插入后的索引。

链接

gog docs format <docId> --match "Project site" --link https://example.com gog docs format <docId> --match "Project site" --no-link

--link接受 HTTP(S)、mailto:、书签 ID 与同文档标题锚点 slug；--link与--no-link互斥。

原生表格：插入、单元格、行列与合并

Markdown 渲染的表格与 Docs 原生表格存在差异，需要保证原生表格时应使用直接表格命令。

插入表格

gog docs insert-table <docId> --rows 3 --cols 2 --at-end gog docs insert-table <docId> --rows 2 --cols 2 --index 1 \ --values-json '[["A","B"],["C","D"]]'

--values-json接受 2D 字符串数组，维度必须与--rowsx--cols一致；省略则插入空表格结构。--at-end追加到文档（或指定--tab）末尾，--index N精确插入。

单元格级编辑

gog docs cell-update <docId> --table-index 1 --row 2 --col 3 \ --content "**Ready**" --format markdown gog docs cell-update <docId> --table-index 1 --row 2 --col 3 \ --content $'- First\n- Second'

坐标为 1 基；--tab定位 Tab；--append追加到单元格末尾而非替换。Markdown 列表内容会在单元格内生成原生 Docs 项目符号/编号（含嵌套层级），Markdown 表格导入也保留同样的嵌套列表结构。

行列结构操作

gog docs table-row insert <docId> --table 2 --at end gog docs table-row insert <docId> --table "Status" --at 2 \ --values-json '["Ready","Owner"]' gog docs table-row delete <docId> --table -1 --row 3 gog docs table-column insert <docId> --table 1 --at 2 gog docs table-column delete <docId> --table '*' --col -1

--table选择器非常灵活：1 基索引、从末尾计的负索引、精确首格文本、或*表示全部表格；数字或类语法文本前加text:前缀（如--table text:2026）；首格文本匹配必须唯一。行列索引均为 1 基且可为负数，--at end追加。所有直接表格变更命令都接受--tab、--dry-run、--json、--plain；多表变更会预检并在 Docs API 批量上限内保持文档降序。

列宽与合并

gog docs table-column-width <docId> --table-index 1 --col 1 --width 120 gog docs table-column-width <docId> --table-index 1 --evenly-distributed gog docs table-merge <docId> --table 1 --range 1,1:1,3 gog docs table-unmerge <docId> --table 1 --cell 1,1

--width以点为单位且必须配--col；--evenly-distributed在给出--col时只重置该列，否则等宽分布全部列。行列结构操作会拒绝非矩形 API 表格形态，避免合并单元格场景下的猜测性引用扩大变更范围（相关测试见 docs_table_ops_test.go、docs_insert_table_test.go）。

图片与智能芯片：富媒体内容

插入与替换图片

# 公网 URL 直接插入，不改变 Drive 权限 gog docs insert-image <docId> --url https://example.com/chart.png --at end # 本地上传 PNG/JPEG/GIF（会临时上传到 Drive，可能需要链接共享） gog docs insert-image <docId> --file chart.png --at "Quarterly chart" # 替换既有图片而不改位置/边界 gog docs replace-image <docId> --object-id <imageObjectId> --url https://example.com/chart.png gog docs replace-image <docId> --match-alt "Quarterly chart" --file chart.png

图片的 object ID 与 alt 文本来自docs images list；所选 Tab 恰好只有一张图片时，replace-image可省略两个选择器。锚点行为：--at <text>会删除并替换首个字面文本匹配，--before <text>/--after <text>则保留锚文本。

智能芯片与页眉页脚

gog docs insert-person <docId> --email owner@example.com --at "@owner" gog docs insert-file-chip <docId> --file-id <driveFileId> --at "附件" gog docs insert-date-chip <docId> --at "截止"

页眉页脚使用header/footer聚合命令，创建返回segmentId供后续定位：

header_id=$(gog docs header create <docId> --text "Quarterly report" --json | jq -r .segmentId) gog docs header list <docId> --json gog docs footer create <docId> --file footer.txt gog --force docs header delete <docId> "$header_id"

--segment接受 create/list/raw 返回的不透明 ID，不要加header:或footer:前缀，可配合--tab在多 Tab 文档中限定查找。注意：当前 Docs API 只能创建DEFAULT页眉/页脚，raw 输出暴露的首页与偶数页 ID 是只读的；段内插入/更新仅支持纯文本（Markdown 中的表格、图片等结构在页眉/页脚/脚注中非法）。

结构元素：分页符、分节符、脚注、水平线与多栏

Markdown 没有原生分页符/分节符/水平线概念，多页交付物需要直接调用 Docs API：

gog docs insert-page-break <docId> --at-end gog docs insert-page-break <docId> --index 250 --tab "Notes" gog docs insert-footnote <docId> --at "Claim" --text "Source note" gog docs insert-section-break <docId> --at "Appendix" --type next-page gog docs insert-horizontal-rule <docId> --at "Summary"

三类结构插入共用同一组放置选择器（--index、--at、--occurrence、--match-case、--at-end、--tab）。实现细节值得注意：脚注是两步操作——API 先返回新脚注段 ID 才能填充文本，因此不支持持久化--batch模式；水平线用"换行 + 底部段落边框"实现，因为 Docs API 没有原生的水平线插入请求（源码见 docs_sed.go 相关段落与 docs_insert_page_break_test.go 测试）。

分节栏数（Google Docs 支持 1–3 栏）：

gog docs section-columns <docId> --at "Newsletter" --count 2 gog docs section-columns <docId> --at-end --count 3 --separator between gog docs section-columns <docId> --at "Appendix" --count 1 # 复位单栏

Tabs 与命名区间：现代 Docs 的组织方式

Tab 管理

gog docs list-tabs <docId> # 发现 tab 标题/ID gog docs add-tab <docId> --title "Notes" gog docs rename-tab <docId> <tabId> "Archive" gog docs delete-tab <docId> <tabId> --force

几乎所有编辑命令都支持--tab（按标题或 ID），例如gog docs write <docId> --append --tab "Notes" --text "Follow-up"、gog docs find-replace <docId> old new --tab "Notes" --dry-run。

整 Tab 重渲染的推荐姿势是把 Markdown 作为唯一事实来源：

gog docs write <docId> --replace --markdown --tab "Gold list" --file gold.md

原理（docs/docs-editing.md 明确说明）：Drive 的 Markdown 转换器只能整文档操作，所以该路径用DeleteContentRange清空目标 Tab 再经 Docs API 本地重渲染 Markdown，其他 Tab 不受影响。

命名区间

命名区间是持久的文档锚点，可基于匹配文本或显式 Docs API 索引创建：

gog docs named-range create <docId> --name ReleaseStatus --at "Ready to ship" gog docs named-range create <docId> --name ReleaseStatus --start 42 --end 55 gog docs named-range list <docId> --json gog docs named-range replace <docId> ReleaseStatus --text "Released" gog docs named-range delete <docId> ReleaseStatus

命名区间命令是 Tab 感知的：不带--tab时作用于默认 Tab，且即便文档还有其它 Tab 也能正确限定变更范围（相关测试见 docs_named_ranges_test.go）。

查找替换与 sed：三种替换武器

• docs find-replace：字面替换，支持--dry-run（完全离线，不开文档即报告预期替换）、空替换串删除匹配、--first单次、--content-file+--format markdown用 Markdown（含图片）替换占位符。
• docs edit：经典查找替换入口。
• docs sed：sed 风格正则，s/pattern/replacement/g，是 Docs 域中最庞大的实现之一——internal/cmd 下以docs_sed_*.go命名的文件超过 30 个，覆盖解析、表格单元格、图片替换、批量（batch）、dry-run、模糊测试与 live 测试（如 docs_sed_fuzz_test.go、docs_sed_live_test.go），适合在超长文档中做模式化批量改写。

gog docs find-replace <docId> old new --dry-run gog docs find-replace <docId> old '' --first gog docs find-replace <docId> PLACEHOLDER --content-file replacement.md --format markdown

页面布局与导出

分页/无页模式与页面尺寸

gog docs page-layout <docId> --layout pageless gog docs page-layout <docId> --layout pages --page-width 8.5in --page-height 11in \ --margin-left 0.5in --margin-right 0.5in gog docs write <docId> --replace --markdown --file report.md --pageless --page-width 960

长度默认用点（pt），也接受in、cm、mm。docs page-layout只给尺寸/边距时不改当前分页模式（要切换才需要--layout）；--pageless除非显式给--page-width，否则保留 Docs 现有宽度。docs write的 flag 中还提供--page-size A4|A5|Letter|Legal|Tabloid、--page-width/--page-height/--margin-*等页面级配置（见 docs/commands/gog-docs-write.md）。

导出

gog docs export <docId> --format pdf # 默认 pdf gog docs export <docId> --format docx --out report.docx gog docs export <docId> --format md --tab "Notes" # 实验性按 Tab 导出 gog docs export <docId> --format html --overwrite

--format支持 pdf|docx|txt|md|html，经 Drive 导出实现（源码中DocsExportCmd的 Run 走exportViaDrive，见 internal/cmd/docs.go）；--overwrite覆盖既有输出文件。create命令通过 DriveFiles.Create+Media(text/markdown)让 Drive 做格式转换，随后进行"第二遍"图片插入（先建占位符再替换为内联图片，见 internal/cmd/docs.go）。

命令发现与 Schema 契约

SKILL.md 反复强调"不要猜测语法"，项目为此提供了三件套：

gog docs --help # 服务级帮助（全部子命令索引） gog docs <command> --help # 子命令 flag 详情 gog schema docs <command> --json # 机器可读契约（语法、退出码、有效安全状态）

配套的人类可读文档包括 docs/index.md、docs/commands/README.md、docs/agent-skills.md 与 docs/safety-profiles.md；Google Docs 的深度编辑专题见 docs/docs-editing.md。生成式命令文档位于 docs/commands（gog-docs-*.md），由make docs-commands从gog schema --json生成。

源码与测试佐证：功能可信度

• 命令注册：internal/cmd/docs.go 的DocsCmd结构体一次性声明全部 49 个子命令及别名（export→download,dl、cat→text,read、copy→cp,duplicate、insert-page-break→page-break,pb、named-range→named-ranges,namedranges,nr等）；
• 读取实现：internal/cmd/docs_read.go（DocsCatCmd，含--max-bytes上限与--raw原始 JSON 分支）；
• 写入实现：docs_write_*.go系列（docs_write_file_test.go、docs_write_markdown_tab_test.go 等验证 Markdown 写入与 Tab 定位）；
• 表格操作：docs_table_*系列，测试覆盖插入、单元格、列宽、合并与多表偏移（docs_insert_table_test.go、docs_table_ops_test.go、docs_multi_table_offset_test.go）；
• sed 正则引擎：docs_sed_*三十余个文件，含模糊测试与实时测试；
• 智能芯片：docs_smart_chips.go（person/file/date chip）；
• 页眉页脚：docs_header_footer.go 与对应测试 docs_header_footer_test.go；
• 评论系统：docs_comments*.go（locate/poll/list/resolve，含--tab过滤语义）。

总结：把 Docs 变成可编程对象

gog-docs技能把 Google Docs 从"网页编辑器"降维成一组可脚本化、可审计、对 Agent 友好的终端命令：读取侧有纯文本、JSON、无损 raw 三种视图；写入侧有文本、Markdown、原生表格、结构化插入四种粒度；安全侧有--readonly、--dry-run、--no-input、--wrap-untrusted、--check-orphans与命令白名单多重护栏。配合gog schema docs --json的机器契约，Agent 可以在不猜测语法的前提下完成"创建 → 写入 → 格式化 → 审查 → 导出"的完整文档生命周期，而每次变更都可通过docs raw与版本回读进行验证。

延伸阅读

• gog-docs 技能定义
• gog 全局技能与安全规则
• Google Docs 深度编辑指南
• gog docs 命令索引
• 安全配置文档
• 无损原始 API 输出说明

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli