gws-docs

gws-docs 介绍

gws-docs 能做什么

gws-docs skill 用于通过 gws CLI 读写 Google Docs。它最适合需要结构化文档访问，而不只是一次性提示词的场景：比如创建文档、获取已有文档，以及在保留 API 行为的前提下批量更新内容。

最适合哪些用户

如果你在做技术写作自动化、文档运营，或围绕 Google Docs 搭建工作流工具，那么 gws-docs skill 很适合你。它尤其适合那些要求结果可重复、可审计，并且基于真实文档方法而不是凭空生成的内容。

这个 skill 为什么不一样

gws-docs 的核心价值在于方法级控制。它直接暴露文档资源和方法，同时也会指向前置的共享 skill，用于处理认证、全局标志和安全规则。对于重视 API 正确性和安全执行的人来说，它比泛泛的“写一个文档”提示词更可靠。

如何使用 gws-docs skill

安装与前置检查

使用 npx skills add googleworkspace/cli --skill gws-docs 安装。使用前先阅读 ../gws-shared/SKILL.md；gws-docs skill 依赖这个共享文件来处理认证、全局标志和安全规则。如果共享 skill 不存在，先运行 gws generate-skills。

先看什么

先从 SKILL.md 开始，再查看 gws docs --help 的输出，以及你要调用的具体方法对应的 schema。最有用的阅读顺序是：

1. SKILL.md
2. gws docs --help
3. gws schema docs.<resource>.<method>

按这个顺序看，能避免猜参数、猜标志或猜资源名。

如何写出好的提示词

高质量的 gws-docs usage 请求，应该明确写出文档目标、资源和方法。例如：“使用 gws-docs 创建一个标题为 X 的空白 Google Doc，然后获取文档 ID 并确认标题。”如果需要编辑，请说明你要的是单次更新还是 batchUpdate，并附上精确内容或变更清单。

实际工作流

在 gws-docs for Technical Writing 场景下，最好从粗略需求逐步收敛到具体方法请求：

• 先决定需要 documents.create、documents.get 还是 documents.batchUpdate
• 用 gws schema 查看必填字段
• 把内容映射到 --params 或 --json
• 必要时再次获取文档，验证结果

这样可以减少静默失败，也让输出更容易审阅。

gws-docs skill 常见问题

gws-docs 只是用来编辑文本吗？

不是。这个 skill 是通过已文档化的 API 方法来读写 Google Docs。它既包括创建文档、获取文档数据，也包括批量更新，比用自然语言简单说一句“帮我编辑一个文档”要精确得多。

什么情况下不该用 gws-docs？

如果你只需要一个随手草稿，而且不在意精确的文档操作，就不必用 gws-docs。如果你无法访问必需的 gws CLI、共享的 gws-shared 配置，或无法拿到安全调用所需的 schema 信息，它也不是合适选择。

它适合新手吗？

适合，只要你按安装和 schema 步骤来。把它当作一个有引导的 CLI 工作流时，入门最轻松：先看方法帮助，再检查 schema，最后运行准确命令。新手通常只会在跳过发现步骤、靠猜 flag 的时候出错。

如何改进 gws-docs skill

给 skill 正确的输入形状

提升质量最大的办法，是把具体的文档操作说清楚。要说明会对哪个文档做什么，以及适合用哪种方法。例如，“创建一个标题为 Q1 launch notes 的空白文档”比“做一个文档”更好，“追加这三段文字”也比“更新文档”更明确。

执行前先用 schema

常见失败模式是把内容和方法配错。gws schema docs.<resource>.<method> 会告诉你需要哪些字段、有哪些默认值，以及该如何组织 flags。这一点对 gws-docs install 阶段的校验尤其重要，也适用于任何包含多个操作的 batchUpdate 请求。

通过验证结果来迭代

第一次运行后，把返回的文档数据和你的预期对照。如果标题、内容或方法输出不对，就通过缩小操作范围、把大编辑拆成更小的更新，或提供更明确的输入载荷来修正请求。