gtm-agent

GTM Agent

触发条件

当请求涉及为某个组织部署、连接、检查或升级 GTM Agent，或者在创建任何内容之前询问是否可行以及需要什么时，应用此技能。

范围

一次部署包括：将 Agent 模板 eliasstravik/gtm-agent 私有复制为仓库 gtm-agent-<slug>，并部署为 Vercel 项目 gtm-agent-<slug>；在组织的 Slack 中安装 Slack 连接器 slack/gtm-agent-<slug>；工作区仓库 gtm-<slug>；以及在启用工作流时，由 gtm-workflow 的共享设置 --deploy 上线的工作流项目 gtm-<slug>（项目、Neon、共享项目、密钥、首次推送 workflows/），并将其连接到此 Agent；Agent 设置会在最后一步完成此连接。scripts/ 中的脚本使用 GitHub 和 Vercel CLI；references/setup.md 列出了设置会创建的内容。连接名称取自 Vercel Secret Note 或本地标签，并遵循连接命名。此 Agent 对该设置仍是可选的。工作区内容属于其他 gtm 技能。

输入

请求；组织的工作区 slug（遵循约定中的 slug 规则；如果已有 ~/.gtm/<slug>/，则从中获取）；Vercel 团队 slug（vercel teams ls；如果有多个，请询问）；GitHub 所有者（默认为当前登录用户，除非请求中指定了组织）；可选的 Slack 频道 ID（C0…，位于频道「关于」标签页底部），用于工作流通知；references/setup.md。

角色

用户已在此计算机上登录 GitHub 和 Vercel CLI；在需要时直接或通过其授权的浏览器 Agent 授权安装 Slack；通过 Vercel 的 Neon 集成将 Neon 数据库添加到工作流项目（仅限 Production，关闭预览分支）；团队首次使用时接受 Neon 的 Marketplace 条款；邀请机器人加入频道，并在 Slack 中发送第一句话。Agent 运行脚本，准确转达用户必须执行的操作，并报告结果。

流程

在对话中首次使用 gtm 技能时，会按 更新 中的说明检查一次是否有更新版本。按照 交互 中的六条规则沟通；复现对话示例。开始任何工作前，先确认这台电脑能够执行：gh auth status 和 vercel whoami 均成功，且 node --version 为 22 或更高版本。若条件不满足，或当前运行环境是托管 Agent 本身（PATH 中没有 vercel，或 GTM_AGENT_HOSTED 为 1），则不要运行任何命令：用一句话说明缺少什么，并告知团队成员应在已登录这两个 CLI 的电脑上运行 /gtm-agent。

工作	操作
就绪情况	用户只询问能否进行设置、需要什么或费用多少时。不要创建任何内容。运行上述只读检查和 vercel teams ls，然后说明已就绪的内容、缺少的内容、设置将创建的内容、需要用户执行的步骤（参见 references/setup.md），并说明 Vercel 团队必须使用 Pro 套餐。提供 Deploy 选项。
部署	仅当 vercel teams ls 显示多个团队时，才询问要使用哪个 Vercel 团队；仅当用户提及工作流通知时，才询问频道 ID。用一句话说明将要执行的操作，并说明大约需要五分钟。从此技能所在文件夹运行 node scripts/setup.mjs --slug <slug> --team <team> [--github-owner <owner>] [--channel <id>]，并实时输出结果。脚本打印出 Slack 地址时，将其转发给用户，并说明需要在该页面完成以下三件事：选择工作区、按照 Slack 配置配置所选 Slack 个人资料、点击 Allow；然后等待，脚本会自动继续。退出码为 2 时，会指出一项需要用户执行的步骤（细粒度 GitHub 令牌、安装 Slack、允许 Vercel 的 GitHub 应用访问新仓库，或团队首次添加 Neon 时接受 Neon 条款）：转达该步骤并等待，然后再次运行相同命令。退出码为 0 时，用脚本打印的两条 Slack 信息结束。退出码为 1 时，用通俗语言说明失败的那一行，并提供 Doctor 选项。
诊断	运行 node scripts/doctor.mjs --slug <slug> --team <team> [--github-owner <owner>] [--agent-project <name>] [--workflow-project <name>] [--slack-connector <uid>]；用业务术语说明失败的行及其修复方法；所有 workflow-project 修复都应使用 gtm-workflow 的 setup --deploy，并传入 --agent-project，以修复缺失的内容；--fix 会关闭 Agent 项目的预览部署。对于 Slack 变更，运行 configure-slack.mjs --team <team> --connector <uid> --apply，然后按照 Slack 配置同步提供方清单并重新安装。向 Doctor 传入新的 --slack-manifest <file.json>；它会检查提供方设置、安装是否为最新版本，以及有效令牌授权。
升级	在 Agent 检出目录（~/.gtm/.agents/<slug>/，或用户指定的仓库）中：运行 git fetch template && git merge template/main，合并时保留下游自定义内容，并在授权的升级范围内解决常规冲突；仅当预期行为不明确时才询问，然后运行 git push；推送会触发部署。接着运行 Doctor。如果工作流运行时版本落后，说明这一点并交由 gtm-workflow 的 Upgrade 处理。Doctor 中的“Agent runs the latest GTM Skills release”一行会说明何时需要升级；托管 Agent 也会在 Slack 中提示（更新）。

名称由 slug 固定：gtm-<slug>（工作区仓库）、gtm-agent-<slug>（Agent 仓库和项目）、gtm-<slug>（工作流项目，名称与仓库相同）、gtm-<slug>-share（公开分享和 webhook 中继项目）、slack/gtm-agent-<slug>（连接器）、Neon 数据库 gtm-<slug>，仅连接到工作流项目。若在使用此技能之前手动完成了部署，则保留原有名称；将其作为覆盖值传入。

输出

一个在 Slack 中实时应答的 Agent，已连接到其工作区代码库；如果未拒绝，还会连接到一个实时工作流项目；医生的报告；两条 Slack 消息：邀请应用，然后发送 @gtm-agent-<slug> set up our GTM workspace。

异常情况

密钥绝不会经过对话：脚本会生成密钥，并通过 vercel env add 添加；Agent 主机只会在针对工作区代码库的 Git 请求中添加 GTM_GITHUB_TOKEN，且该令牌是仅限该代码库的细粒度令牌（Contents 读写）。设置过程绝不会使用 CLI 自身的登录信息；如果没有令牌，会以退出码 2 停止并说明如何创建令牌；再次运行时，会从用户自己的终端中的 GTM_GITHUB_TOKEN 获取令牌，并拒绝任何非细粒度令牌（github_pat_…）。Vercel Hobby 帐户无法拥有团队：说明需要 Pro 团队，然后停止。尚未安装 Vercel GitHub 应用的 GitHub 组织会导致 vercel git connect 失败：说明安装位置（Vercel → Settings → Git），然后再次运行。Vercel 配置更新可能不会更改 Slack。请遵循 Slack 配置；Doctor 必须验证两端和已安装的令牌，然后才能报告成功。需要同时安装 gtm-workspace 和 gtm-workflow；如果缺少其中任意一个，请说明应使用 npx skills add eliasstravik/gtm-skills -s <name> -y 安装（如果此技能位于全局技能目录中，则添加 -g），然后重试。

受保护的工作流查看器

每次部署时，工作流项目都受 Vercel Authentication 保护。Agent 使用该项目唯一的自动化绕过密钥（应用将其识别为 VERCEL_AUTOMATION_BYPASS_SECRET）访问工作流；gtm-workflow 的设置会将其存储为 Agent 上的 GTM_WORKFLOW_BYPASS_SECRET；该绕过密钥绝不会进入模型可见的导出内容或用户链接。工作流项目只保留一个绕过密钥（Doctor 会标记多余的密钥），因此 Agent 保存的副本是仅限 Agent 的路由所接受的密钥；如需替换，请在 Agent 上删除 GTM_WORKFLOW_BYPASS_SECRET，然后再次运行该设置。Webhook 发送方会向共享项目的中继发送请求（https://gtm-<slug>-share.vercel.app/api/intake/<workflow>），中继会使用其 OIDC 身份转发已签名事件；绝不要向发送方提供绕过密钥。请参阅工作流查看器。

质量检查

• Connections 位于现有的私有工作流项目中。部署后验证已登录浏览器能否访问；仅有配置并不代表已就绪。原生帐户登录、提供方授权和 Slack 特定操作可能需要人工完成。
• 对话或回复中没有出现任何密钥值。
• 在判定部署完成之前，Doctor 会以“All good.”结束；每个失败项都已报告并附上修复方法。实时冒烟测试涵盖提及、私有频道、私信、群组私信中的提及、工作流回复、文件下载／上传和审批；请使用已授权的测试对话。
• 最后的回复只包含两条 Slack 消息，不提及提交、构建或检查。

参考资料

setup.md 介绍脚本创建的内容、所有变量以及手动操作的对应方式；交互对话；来自 gtm-workspace：交互、契约；来自 gtm-workflow：deploy.md。