gws-forms

gws-forms 技能概览

gws-forms 的作用

gws-forms 是用于通过 gws 命令读写 Google Forms 的 Google Workspace CLI 技能。它可以帮助你检查表单 schema、创建空表单、分步骤更新表单内容，以及在不靠猜测 API 字段的情况下处理表单相关操作。

适合谁使用

gws-forms skill 最适合已经在 Google Workspace 自动化流程中工作、并且需要可靠执行 Forms API 的代理和用户。它尤其适用于你想要可重复的表单创建、批量更新，或基于程序的检查，而不是在 Forms UI 里手动点击。

这个技能为什么重要

gws-forms for Workflow Automation 的核心价值在于，它直接暴露了真实的 API 工作流，包括方法发现和基于 schema 的输入构造。这一点很重要，因为表单创建不是一步到位的：forms.create 只会先创建一个空表单，后续还需要通过类似 forms.update 的操作来添加条目和设置。

需要先了解的关键限制

这个技能不是一个通用的“根据提示词直接生成表单”封装。它依赖 gws CLI，需要共享的 Google Workspace 认证和安全配置，并且遵循仓库里的 Forms API 约束。如果你需要的是更偏对话式、宽泛的草稿生成，而不是精确的 API 动作，直接用普通提示词可能更简单。

如何使用 gws-forms 技能

安装与前置准备

要进行 gws-forms install，请使用技能元数据里给出的 CLI：npx skills add googleworkspace/cli --skill gws-forms。在运行 Forms 命令前，先按技能文件中的说明阅读 ../gws-shared/SKILL.md，因为认证、全局参数和安全规则都在那里。如果那个共享文件不存在，先运行 gws generate-skills。

先发现方法，再执行操作

最稳妥的 gws-forms usage 模式是：先检查，再调用。先用 gws forms --help 浏览可用资源和方法，然后在构建参数之前运行 gws schema forms.<resource>.<method>，确认必填参数、类型和默认值。这样可以避免请求格式错误，也能让你的提示词或任务更贴合实际 API 结构。

把粗略目标转成可执行请求

一条好的 gws-forms guide 输入，应该说明你在 API 层面想做什么，而不只是业务目标。比如，不要只说“做一个反馈表单”，而是要说明标题、文档标题、计划使用的问题类型、表单是否应从空白开始，以及是否需要发布设置或响应相关操作。这样技能才有足够结构去判断应调用 forms.create、forms.batchUpdate，还是其他方法。

先阅读这些文件和输出

先从 SKILL.md 开始，然后查看它指向的共享父技能文件以及 CLI help/schema 输出。在这个仓库里，技能正文很精简，也没有额外的 helper 文件夹，所以 SKILL.md 加上 gws forms --help 和 gws schema 就是主要事实来源。如果你的工作流会借鉴相邻的 Google Workspace 技能，可以对照它们的模式，但不要想当然地把它们的字段名或执行顺序直接套到这里。

gws-forms 技能 FAQ

gws-forms 主要是用来创建表单吗？

是，但只是在 API 意义上。gws-forms 支持读写表单，而且创建过程本来就是分阶段的：先创建外壳，再在后续步骤里添加条目或更新内容。如果你期待一句提示词就生成一个字段齐全、内容完整的成品表单，这和仓库里的工作流并不匹配。

使用它一定需要 gws CLI 吗？

是。这个技能明确要求使用 gws 二进制文件，而技能文件里展示的命令形式是 gws forms <resource> <method> [flags]。如果你的环境不能运行 CLI，或者无法对 Google Workspace 完成认证，那么这个技能就无法按预期使用。

这比普通提示词更好吗？

如果是 API 工作，答案是肯定的。普通提示词可以描述表单，但 gws-forms skill 能帮助你按 schema 约束执行真正的资源和方法调用，从而减少猜测和错误请求。需要构思内容时用提示词；需要真正把表单操作做出来时用这个技能。

什么情况下不该用它？

如果你只需要快速起草一份调查问题，如果你没有 Workspace 凭据，或者你的流程超出了 Forms API 的范围，就不要用 gws-forms。当你想跳过命令检查、完全依赖自由形式自然语言时，它也不是合适的选择。

如何改进 gws-forms 技能

提供 API 形状的输入

最好的结果来自那些明确指定目标资源、方法和所需字段的输入。请包含表单标题，document_title 是否需要不同，以及你是在新建、读取还是更新表单。例如，“创建一个标题为 X 的表单，保持为空，然后添加 5 个单选题”就比“做一个调查”强得多。

遵循先创建、后更新的行为

一个常见失败模式，是在 API 只允许创建时提交部分数据的情况下，却要求一步生成完整表单。仓库说明指出，forms.create 只会复制 form.info.title 和 form.info.document_title，并且在创建时不允许 description、items 和 settings。想提高输出质量，就要提前把第二步规划好。

用 schema 输出消除歧义

如果第一次尝试失败，重新检查 gws schema 里的准确方法签名和参数名，然后用这些字段重写请求。这是改进 gws-forms usage 最快的方法，因为它把你的假设替换成了 CLI 真正期望的结构。

用更小的操作逐步迭代

当表单改动很复杂时，把它拆成更小的动作：检查、创建、更新、验证。这样的工作流能减少批量更新中的错误，也更容易看出问题到底是输入有误、字段不受支持，还是你的意图与 Forms API 不匹配。