gws-shared

gws-shared 技能概览

gws-shared 是做什么的

gws-shared 技能是 gws 工作流自动化的通用层：它帮助你在 Google Workspace CLI 任务中一致地使用共享认证、全局标志和输出处理。如果你希望使用可复用的命令模式，而不是每次都临时想一套提示词，它会特别有用。

谁应该安装它

如果你正在围绕 gws 构建脚本、agent 或运维工作流，并且需要一个可靠参考来处理登录、service-account 认证、分页、dry run 和安全输出格式，那么就应该安装 gws-shared 技能。如果你只需要一次性的 CLI 命令，而且不打算复用这套模式，它的价值就会小很多。

它在实际使用中会带来什么变化

gws-shared skill 的核心价值，是减少你对命令结构和标志位的猜测。它提供一套稳定方式来表达：你要操作的 service/resource 是什么、你要调用哪个 method、哪些 flags 是全局适用的，以及如何在 JSON、table、YAML 或 CSV 输出之间做选择。

如何使用 gws-shared 技能

安装并验证这个技能

仓库说明里写得很明确：gws 二进制必须已经在你的 $PATH 里；这个技能本身是共享参考，不是二进制安装器。对于 gws-shared install，先确认 gws 可用，然后在把命令模式用于自动化之前，先把 SKILL.md 当作主要事实来源来读。

先读这些文件

先看 skills/gws-shared/SKILL.md，然后再查看仓库级 README 或相邻文档，了解实际的 gws 安装选项和环境配置。在这个仓库里，skill 路径很简洁，也没有辅助脚本或支持目录，所以 skill 正文才是关键信息来源：认证、flags、语法和安全规则都在里面。

把模糊目标改写成可用提示词

一个高质量的 gws-shared usage 提示词，应当包含目标 service、resource、method、期望输出格式，以及动作是只读还是可能具有破坏性。比如不要说“管理用户”，而应说：“使用 gws-shared 以 table 格式列出 Workspace 用户，避免写入，并在可用时说明带 --dry-run 的最安全命令。”

建议遵循的命令结构

核心语法是 gws <service> <resource> [sub-resource] <method> [flags]。用 method flags 来收窄调用范围：--params 用于查询参数，--json 用于请求体，--upload 用于文件内容，-o 用于二进制输出，--page-all 只在你预期会返回多页结果时才使用。对于 gws-shared for Workflow Automation，要明确这一步是交互式、基于 service-account，还是完全自动化的，这样技能才能选择合适的认证和输出行为。

gws-shared 技能常见问题

gws-shared 只适合高级用户吗？

不是。gws-shared skill 对新手同样有帮助，因为它消除了认证和命令格式上的歧义。主要前提是你已经安装了 gws，并且知道自己要操作哪个 Google Workspace 对象。

什么时候不该用它？

如果你需要从零开始学习 gws 产品，或者你的任务超出了 CLI 支持的 service/resource 模型，就不该用 gws-shared。当你想要的是泛泛的 API 说明，而不是可直接执行的命令语法时，它也不是最佳选择。

它和普通提示词有什么不同？

普通提示词可能只描述目标，而 gws-shared guide 的行为会给你一套共享的操作规则：认证选项、安全 flags、输出模式和分页控制。这通常意味着在自动化场景里，重试更少，格式漂移也更少。

主要边界是什么？

这个技能只支持 SKILL.md 中所记录的 gws CLI 约定范围内的读写工作流。你仍然需要自己选择正确的凭据，写入或删除操作要遵守确认要求，并避免在输出中暴露密钥。

如何改进 gws-shared 技能

把缺失的上下文补全给技能

最好的输入会明确写出具体的 service、resource、method 和输出目标。比如：“把 Calendar 事件导出为 CSV，使用 --page-all，仅限只读调用，并确保响应适合后续解析。” 这比“总结我的日历数据”更好，因为它能让 gws-shared 选择正确的 flags 和流程。

先说明安全与自动化约束

由于仓库强调安全规则，你应该提前告诉技能：任务是否允许修改数据，是否应使用 --dry-run，以及响应是否必须做清理。对于 gws-shared for Workflow Automation 来说，这一点尤其重要，因为一个模糊请求很容易生成具备写入能力的命令。

先迭代第一条命令，不要一上来改整个工作流

如果第一次输出已经接近目标，但还不完全准确，就一次只改一个变量：认证模式、格式、分页，或者 body 参数。提升 gws-shared usage 效果最快的方法，是先修正命令结构，再扩大范围，尤其是在处理二进制输出、上传或多页响应时。