Google Docs Formatter — Google Docs 格式化工具

Google Docs Formatter 使用此技能来格式化或更新 Google Docs 通过现有的 gog 技能/CLI。该技能仅限指令，不要引入新的 API 客户端、脚本、依赖项或凭证流。

核心规则 依赖 gog 进行所有 Google Docs 和 Drive 操作。如果 gog 技能未加载且需要命令详细信息，首先加载 gog 技能。优先使用 Google Docs 原生工作流程而不是 DOCX 转换。除非用户明确请求，否则避免使用第三方代理服务。

安全和批准 在进行任何写入操作之前，说明目标文档和预期更改，然后获取用户的明确批准，除非用户已经明确批准了该确切更改。始终在以下情况下询问用户：

• 使用 gog docs clear 替换整个文档正文
• 大规模多节替换
• 删除文本范围
• 更改共享/工作文档，其所有权或受众不明确

当已经在用户批准的文档上工作时，可以在不需要额外批准的情况下进行以下操作：

• 检查元数据/结构
• 导出/读取内容
• 本地准备 Markdown
• 运行支持的 dry-run 风格检查

标准工作流程

• 确定目标文档。接受 Google Docs URL 或文档 ID。从 URL 中提取 ID，例如 https://docs.google.com/document/d//....
• 编辑前检查：gog docs info --json、gog docs structure 、gog docs export --format md --out /tmp/doc.md
• 决定编辑策略。

- 从 Markdown 创建新文档：使用 gog docs create --file。 - 替换已知占位符或节：使用 gog docs find-replace --format markdown。 - 小的文本修复：使用 gog docs edit 或 gog docs sed。 - 附加内容：使用 gog docs write --append 或 gog docs insert。 - 全面重写：仅在获得明确批准后进行；首先创建副本。

• 以 Markdown 格式准备内容。使用 Markdown 标题、项目符号、编号列表、表格、粗体/斜体和链接。保持语义结构简单；Google Docs 转换更可靠地支持干净的 Markdown。对于图像，仅使用支持的 Markdown 图像语法，如果 gog docs create/find-replace --format markdown 支持源。
• 使用 gog 应用更改。编辑后验证：gog docs structure 、gog docs export --format md --out /tmp/doc-after.md。比较导出的 Markdown 或结构与预期结果。简要报告更改、任何限制和链接或文档 ID（如果有用）。

常见操作

• 从 Markdown 创建格式化的 Google Doc：准备本地 Markdown 文件，然后使用 gog docs create "文档标题" --file /path/to/content.md。除非用户需要 DOCX 行为，否则使用此方法代替 Markdown → DOCX → Drive 上传。
• 用格式化的 Markdown 替换占位符：最适合文档包含标记（如 {{SECTION_DRAFT}}）。使用 gog docs find-replace '{{SECTION_DRAFT}}' --content-file /path/to/section.md --format markdown --first。替换唯一占位符时，优先使用 --first 以避免意外重复更改。
• 替换现有节：如果可能，首先要求用户添加或批准稳定的标记器：旧内容。然后使用准备好的 Markdown 文件和 gog docs find-replace --format markdown 替换边界内容。如果没有稳定的标记器，使用 gog docs structure 确定段落并谨慎进行。不要猜测破坏性范围。
• 小的文本编辑：gog docs edit "旧文本" "新文本" --match-case。对于正则式替换：gog docs sed 's/旧模式/新文本/g'。仅在匹配无歧义时使用正则编辑。
• 附加内容：gog docs write --file /path/to/content.md --append。如果需要 Markdown 格式，优先使用 --format markdown 的占位符替换（如果可用）。
• 全文档重写：仅在获得明确批准后进行。首先创建副本：gog docs copy "重写前备份"、gog docs clear 、gog docs write --file /path/to/content.md。告知用户写入路径是否仅保留文本而不是丰富的 Markdown 格式；使用 create --file 或 find-replace --format markdown 进行丰富的 Markdown 转换。

格式化指导 使用简单、健壮的 Markdown：# 标题 ## 节 简短段落。- 项目符号一 - 项目符号二 | 列 A | 列 B | | --- | --- | | 值 A | 值 B | 粗体 和 斜体 文本。避免脆弱的格式化，除非经过测试：深度嵌套列表、复杂合并表格、不寻常的 HTML、自定义字体/颜色无法通过 Markdown 表达。对于 gog 不支持的高级视觉格式化，解释限制并提出最接近的 gog 支持的替代方案。

何时停止并询问 如果以下情况，请在继续之前询问用户：

• 文档 ID 不明确
• 请求的格式化需要 gog 未暴露的功能
• 编辑将删除或覆盖大量内容
• 导出的/检查的结构不符合预期
• gog 报告身份验证/范围错误

不要安装其他 Google Docs 技能。