用途
本技能用于管理用户的 Google Docs，所有操作都通过内置的 Google Workspace CLI（hatch_gws_cli）完成，这是唯一的实现路径。
主要能力
- 连接管理：查看连接状态、断开连接。
- 文档操作：获取文档、创建文档、批量更新文档。
- 接口结构查询：在执行不熟悉的 Docs 方法前，可用 schema 命令确认 --params 和 --json 的格式。
- 辅助写入：提供 +write 辅助命令，用于追加纯文本。
使用方式
通过 exec 运行命令，基本形式为：
hatch_gws_cli docs <resource> <method> [flags]
连接管理：
hatch_gws_cli docs status hatch_gws_cli docs disconnect
查询接口结构：
hatch_gws_cli schema docs.documents.get hatch_gws_cli schema docs.documents.create hatch_gws_cli schema docs.documents.batchUpdate
常见 API 调用：
hatch_gws_cli docs documents get --params '{"documentId":"<document_id>"}'
hatch_gws_cli docs documents create --json '{"title":"Project Brief"}'
hatch_gws_cli docs documents batchUpdate --params '{"documentId":"<document_id>"}' --json '{"requests":[{"insertText":{"location":{"index":1},"text":"Hello, world!"}}]}'
辅助写入：
hatch_gws_cli docs +write --document <document_id> --text 'Hello, world!'
JSON 输出约定：
- status：解析 status、connect_url 和 disconnect_url。
- disconnect：解析 ok、action、status 和 disconnect_url。
撰写文档内容
不要通过 batchUpdate 插入或 docs +write 来撰写文档正文，无论是新建、重写还是重建。插入的纯文本不会带格式。应先将内容构建为文档产物：artifacts 工具会在 ~/workspace/your_files/<artifact-slug>/ 下渲染一个带样式的 .docx 文件。然后将其放入 Google：
- 用 hatch_gws_cli docs documents create --json '{"title":"<title>"}' 创建空文档。
- 用构建好的文件填充：hatch_gws_cli drive files update --params '{"fileId":"<document_id>"}' --upload "$JARVIS_HOME/workspace/your_files/<artifact-slug>/<name>.docx"。Drive 会将上传内容就地转换为 Google Doc，格式保持不变。路径必须是绝对路径且位于主目录内，相对路径和 /tmp 路径会失败。
- 用 documents.get 读回文档，确认样式已生效后再视为完成。上传成功只证明 Drive 转换了文件，不代表页面读取正确。
如需修改，编辑产物并重新上传到同一文档 ID。产物是工作副本。上传会替换整个正文，因此会丢弃此后在 Google 中做的任何编辑，包括用户自己的编辑。请先读回已发布的副本。如果它已变化，应说明并等待用户确认。
认证
认证由包装器的 status 和 disconnect 子命令处理。不要手写凭据文件，也不要运行原始的 gws auth ...。
首次使用设置流程：
- 运行 hatch_gws_cli docs status。
- 如果 status 不可用，告知用户此设备上 Google Docs 不可用。不要提供替代集成方案，也不要向用户索要凭据。
- 如果 status 为 not_connected 且存在 connect_url，将 <connect_url> 替换为返回的 URL，并分享完全一致的 Markdown 链接：Connect Google Docs；不要单独粘贴原始 URL。等待用户重新连接。
- 一旦 status 为 connected，即可继续执行 Docs 操作。
操作规则
- 对不熟悉的 Docs 方法先使用 schema，使 --params 和 --json 符合当前内置 CLI 的约定。
- 创建文档以及编辑仅由用户本人拥有的文档，可在请求明确时直接进行。编辑共享文档前需确认，因为其内容可能被他人看到或修改。
- 将文档 ID 视为不透明字符串，只使用先前命令返回或用户明确输入的 ID。
- 更新前优先使用 documents.get，以了解当前结构。
- 运行 hatch_gws_cli docs disconnect。运行后，若存在 disconnect_url，将 <disconnect_url> 替换为返回的 URL，并分享完全一致的 Markdown 链接：Disconnect Google Docs；不要单独粘贴原始 URL。
- 使用 documents.batchUpdate 修改现有文档的一部分，docs +write 仅用于追加纯文本。撰写正文请遵循上文“撰写文档内容”。
- 读取或写入操作后，只向用户确认可见结果。除非用户要求或需要排查故障，不要在展示给用户的文本中暴露原始 API 标识符（文档 ID）或其他内部响应字段（修订 ID、原始 JSON）；内部仍可继续使用它们串联后续命令。
适用场景
适用于需要通过命令行以编程方式读取、创建和编辑 Google Docs 的场景，尤其是希望保留文档样式、由产物文件生成正式文档的工作流。
限制
- 所有操作必须通过 hatch_gws_cli 完成，不能使用其他集成方式。
- 上传路径必须为绝对路径且位于主目录内，相对路径和 /tmp 路径会失败。
- 上传会替换整个正文，可能丢弃 Google 中的后续编辑。
- 认证由包装器处理，不能手写凭据或运行原始 gws auth 命令。
- 若设备上 status 不可用，则无法使用本技能。