Google Docs from Markdown

核心用法

gdocs-markdown 解决了 gog docs CLI 无法直接写入 Google Docs 内容的痛点，通过 Markdown → DOCX → Drive 上传 的三步工作流实现内容填充。

主要操作方式：

• 快捷模式：运行 gdocs-create.sh /path/to/file.md "文档标题" 一键完成转换与上传
• 手动模式：调用 pandoc 生成 DOCX，再通过 gog drive upload 上传，Google Drive 自动完成 DOCX 到 Google Docs 的格式转换

显著优点

1. 填补工具缺口：官方 gog CLI 仅支持创建空文档/导出/复制，此技能实现了完整的"带内容创建"能力
2. 保留格式完整性：借助 pandoc 的成熟转换引擎，Markdown 的标题、列表、代码块等结构得以准确保留
3. 原生可编辑：上传后的文档为真正的 Google Docs 格式，非 PDF 或只读附件，支持团队实时协作
4. 零依赖配置：pandoc 在首次使用时自动下载，降低部署门槛

潜在局限

• 中间文件残留：DOCX 文件上传后仍存于 Drive，需手动清理
• 格式兼容性边界：复杂 Markdown（如嵌套表格、自定义 CSS）可能转换失真
• 外部工具链依赖：需同时维护 gog CLI 认证状态与 pandoc 版本

适合人群

• 使用 gog CLI 管理 Google Workspace 的开发者/运维人员
• 需要将技术文档（README、API 文档）快速迁移至 Google Docs 协作文档库的工程师团队
• 偏好 Markdown 写作但交付物需为 Google Docs 格式的内容创作者

常规风险

• 认证令牌安全：脚本依赖 gog CLI 的 OAuth 凭证，共享环境需注意令牌权限范围
• 临时文件清理：/tmp 路径下的 pandoc 二进制与中间 DOCX 文件建议设置定期清理策略
• 版本漂移：pandoc 自动下载固定版本（3.1.11），长期可能需手动更新以支持新 Markdown 语法

核心用法

gdocs-markdown 是一个填补 gog CLI 功能空缺的实用工具。由于 gog docs 仅支持创建空文档、导出、读取和复制，但不支持写入或更新内容，该 Skill 通过 "Markdown → DOCX → Drive 上传 → 自动转 Google Docs" 的间接路径解决这一痛点。

典型使用流程极为简单：

gdocs-create.sh /path/to/file.md "文档标题"

底层自动完成：检查并首次下载 pandoc（92 行代码，3 个文件）→ 转换 Markdown 为 DOCX → 调用 gog drive upload → Google Drive 自动转为可编辑的 Google Docs 格式。

---

显著优点

| 维度 | 说明 |

|------|------|

| **精准补位** | 完美解决 gog CLI 无法写入 Google Docs 的核心痛点，生态位明确 |

| **零依赖设计** | 除系统工具（bash、wget）和 gog CLI 外，无第三方包依赖 |

| **安全沙箱** | 使用 `mktemp` 创建临时目录，执行后自动清理，无持久化残留 |

| **隐私友好** | 不采集用户数据，仅处理主动提供的 Markdown 内容，GDPR/CCPA 合规 |

| **透明可审计** | 代码量少（92 行），结构清晰，无危险函数（eval/exec）调用 |

---

潜在缺点与局限性

1. 运行时网络依赖（首次使用）

• 必须从 GitHub Releases 动态下载 pandoc 二进制文件（约 30MB），离线环境无法直接运行。
• 缓解方案：可手动预下载 pandoc 并放置到指定路径，或在高安全网络中完成首次初始化。

2. 外部工具链依赖

• 强依赖 gog CLI 的认证状态，若 token 失效或权限不足会中断流程。
• 无版本兼容性检查，未来 gog CLI 接口变更可能导致故障。

3. 来源可信度 T3

• 开发者 techla 为个人开发者，GitHub 上未找到公开仓库，无法评估社区维护历史和代码审查记录。

4. 功能边界固定

• 仅支持创建新文档，不支持更新已有文档内容；格式转换依赖 pandoc 的 Markdown→DOCX 能力，复杂排版可能丢失。

---

适合人群

• gog CLI 重度用户：需要程序化创建 Google Docs 内容的开发者、自动化运维人员
• Markdown 优先的内容工作者：习惯用 Markdown 写作，但需要最终交付为 Google Docs 格式
• 轻量级自动化场景：CI/CD 流水线生成报告、脚本化文档生成等，无需复杂格式控制

---

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 网络下载完整性 | 中 | 首次下载 pandoc 无 SHA256 校验，存在中间人攻击或文件篡改理论可能 |

| 供应链安全 | 低 | pandoc 来自 GitHub 官方仓库（jgm/pandoc），来源可信，但版本固定（3.1.11） |

| 认证失效 | 低 | gog CLI 认证过期会导致上传失败，需重新授权 |

| 长期维护 | 中 | 无公开仓库，更新来源不透明，建议 Fork 后内部维护 |

安全建议：首次使用前在受信网络环境完成初始化，或手动下载 pandoc 并校验 SHA256；定期关注 Skill 更新，考虑将代码迁移至组织内部仓库。