gws script +push 实战指南：用 Google Workspace CLI 将本地代码推送到 Apps Script 项目

gws script push 实战指南用 Google Workspace CLI 将本地代码推送到 Apps Script 项目【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli导读gws script push是 Google Workspace CLIgws内置的 Helper 命令用于把本地目录中的 Apps Script 源码文件.gs、.js、.html、appsscript.json整体上传到指定的 Apps Script 项目底层调用 Apps Script API 的projects.updateContent接口。本文以 skills/gws-script-push/SKILL.md 为骨架结合仓库源码 crates/google-workspace-cli/src/helpers/script.rs 讲解命令用法、文件过滤规则、底层调用链与安全边界读完即可在命令行或 AI Agent 工作流中安全地完成 Apps Script 项目的代码推送与更新。命令概览它是如何进入gws命令体系的gws的核心设计是schema-driven模式驱动绝大多数命令由 Google Discovery Service 的 REST 文档在运行时动态生成无需为每个 API 方法硬编码参数面。但对那些一次操作需要复杂编排或格式转换的场景gws提供了verb形式的 Helper 命令作为补充设计原则详见 crates/google-workspace-cli/src/helpers/README.md。script push正属于此类 Helper把递归扫描目录 → 逐文件转换格式 → 组装updateContent请求体这一串逻辑封装成单个命令。在 crates/google-workspace-cli/src/helpers/mod.rs 中可以看到它的注册方式——服务名script别名apps-script被映射到script::ScriptHelperscript | apps-script Some(Box::new(script::ScriptHelper)),因此以下两条命令完全等价gws script push --script SCRIPT_ID gws apps-script push --script SCRIPT_ID前置条件认证与全局 Flag在执行任何写操作前请先阅读共享参考文档 skills/gws-shared/SKILL.md若本地缺失可用gws generate-skills重新生成。其核心要点如下认证方式二选一# 浏览器交互式 OAuth推荐 gws auth login # 服务账号设置环境变量指向密钥文件 export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json常用全局 FlagFlag说明--format FORMAT输出格式json默认、table、yaml、csv--dry-run仅本地校验不实际调用 API--sanitize TEMPLATE通过 Model Armor 对响应内容做安全筛查安全规则绝不直接输出密钥/令牌执行写操作前必须先与用户确认破坏性操作优先使用--dry-run。命令语法与 Flagsgws script push --script IDFlag必填默认值说明--script✓—Script Project IDApps Script 项目 ID--dir—当前目录.存放脚本文件的目录这两个 Flag 的定义可以在源码 crates/google-workspace-cli/src/helpers/script.rs 中看到--script被标记为required(true)--dir可缺省。--dir缺省时实现中通过unwrap_or(.)回退到当前目录见 script.rs。支持的文件类型与自动过滤规则原文档 Tips 中给出的三条规则在源码process_file函数script.rs中有精确的对应实现本地扩展名映射到 API 的type映射后的name说明.gsSERVER_JS去掉.gs后缀的文件名服务端 JavaScript.jsSERVER_JS去掉.js后缀的文件名同上.htmlHTML去掉.html后缀的文件名HTML 模板appsscript.jsonJSONappsscript项目清单文件其他扩展名如.txt——被忽略不参与上传隐藏文件文件名以.开头——被跳过node_modules目录下的文件——被跳过含任意层级的子目录其中过滤逻辑的关键代码为// 跳过隐藏文件、node_modules、.git 等基础过滤 if filename.starts_with(.) || path.components().any(|c| c.as_os_str() node_modules) { return Ok(None); }注意两点细节目录扫描是递归的。visit_dirsscript.rs会遍历--dir下所有子目录因此src/下的utils.js同样会被收集并上传。appsscript.json是唯一被接受的 JSON 文件。其他任意.json文件如package.json、tsconfig.json都会被忽略这正是项目清单文件得以单独识别的原因。完整示例# 1. 将当前目录下的所有脚本推送到指定项目 gws script push --script SCRIPT_ID # 2. 从 ./src 目录推送典型项目布局src/ 下放源码 gws script push --script SCRIPT_ID --dir ./src # 3. 先做一次本地校验确认文件扫描与请求体构建无误不调用 API gws script push --script SCRIPT_ID --dir ./src --dry-run源码级原理一条完整的调用链script push的执行流程对应handle方法script.rs可分为六步参数解析与路径安全校验读取--script与--dir并调用validate::validate_safe_dir_path(dir_path)?校验目录。该校验函数定义在 crates/google-workspace/src/validate.rs会拒绝绝对路径、拒绝通过..逃逸到当前工作目录之外、拒绝包含控制字符的路径并安全地解析符号链接——这是面向 LLM Agent 调用场景的防注入设计该模块注释明确指出这些校验用于hardens inputs against adversarial or accidentally malformed values见 validate.rs。递归扫描与格式转换visit_dirs递归遍历目录process_file按上文规则将每个文件转换为{ name: ..., type: ..., source: ... }结构。若扫描后文件列表为空直接返回Validation错误No eligible files found in dirscript.rs。定位 API 方法从 Discovery 文档中查找projects资源下的updateContent方法script.rs并读取该方法声明的 OAuth scopes 用于申请令牌。组装请求体{ files: [ { name: code, type: SERVER_JS, source: function foo() {} }, { name: appsscript, type: JSON, source: { ... } } ] }认证通过auth::get_token(scopes)获取令牌仅在--dry-run模式下允许无令牌继续。执行请求调用executor::execute_method(...)script.rs。--dry-run时execute_method不会真正调用 API而是返回{ dry_run: true, ... }的校验信息见 crates/google-workspace-cli/src/executor.rs。底层 APIprojects.updateContent的语义push调用的是 Apps Script API 的projects.updateContent。根据 skills/gws-script/SKILL.md 中对该方法的行为描述更新后的内容会作为HEAD 版本存储并在触发器执行、脚本编辑器、插件预览模式、Web App 或 Apps Script API 开发模式中生效同时该方法会清空项目中所有既有文件。这正是原文档 Tips 中This replaces ALL files in the project的由来——push是全量替换语义而非增量合并。测试验证仓库为这一 Helper 提供了完整的单元测试script.rs可作为行为契约参考test_process_file_server_js验证.gs→SERVER_JS、文件名去后缀、源码内容原样保留test_process_file_html验证.html→HTMLtest_process_file_appsscript_json验证appsscript.json→{ name: appsscript, type: JSON }test_process_file_ignored验证普通.json、隐藏文件.hidden.gs、node_modules下的文件均被忽略test_visit_dirs验证递归扫描能同时收集根目录与子目录文件并排除无关类型。安全注意事项[!CAUTION]script push是写命令且为全量替换语义。执行前必须与用户确认切勿在未确认的情况下直接对线上项目执行。实操建议先 dry-run 后实推先用--dry-run确认扫描到的文件清单与请求体符合预期再执行真实推送确认项目 ID--script必须是目标 Apps Script 项目的 ID形如M1234abcd...推错项目会造成不可逆覆盖控制目录范围--dir默认取当前目录建议显式指定源码目录避免误扫入无关文件了解覆盖语义远端项目所有既有文件都会被本次上传的集合替换若本地缺少appsscript.json推送后项目清单将丢失可能影响项目配置。关联技能与延伸阅读skills/gws-shared/SKILL.md — 认证方式、全局 Flag 与安全规则skills/gws-script/SKILL.md — Apps Script 全部命令入口包含projects.create新建空项目、projects.getContent拉取项目内容、projects.updateContent等 Discovery 原生方法以及与push配套的projects.create→push建站流程命令源码crates/google-workspace-cli/src/helpers/script.rsHelper 设计规范crates/google-workspace-cli/src/helpers/README.md路径安全校验实现crates/google-workspace/src/validate.rs。结合projects.getContent拉取远端内容、本地修改后再用push推回即可形成一套完整的拉取—修改—推送Apps Script 迭代闭环适用于手工开发与 AI Agent 自动编码场景。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考