gtm-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GTM Agent

Trigger

触发条件

Apply this skill when a request concerns getting GTM Agent deployed, connected, checked, or upgraded for an organization.

当请求涉及为某个组织部署、连接、检查或升级 GTM Agent 时，应用此技能。

Scope

范围

One deployment is: a private copy of the agent template

eliasstravik/gtm-agent

as the repository

gtm-agent-<slug>

, deployed as the Vercel project

gtm-agent-<slug>

; a Slack connector

slack/gtm-agent-<slug>

installed in the organization's Slack; the workspace repository

gtm-<slug>

(empty until the agent's first save, save for the workflow runtime); and, when workflows are enabled, an existing Vercel project

gtm-<slug>-workflows

connected to that repository's

workflows/

folder with its existing database and machine transport. The scripts in

scripts/

use the GitHub and Vercel CLIs;

references/setup.md

lists what setup creates and what must already exist. Connections setup uses the existing protected workflow project through shared setup. Connection names come from the Vercel Secret Note or local label, following Connections naming. The agent remains optional for that setup. The workspace's contents belong to the other gtm skills.

一次部署包括：agent 模板

eliasstravik/gtm-agent

的一个私有副本，作为仓库

gtm-agent-<slug>

，并部署为 Vercel 项目

gtm-agent-<slug>

；一个安装到组织 Slack 中的 Slack 连接器

slack/gtm-agent-<slug>

；工作区仓库

gtm-<slug>

（在 agent 首次保存之前为空，仅除工作流运行时外）；以及当工作流启用时，一个已存在的 Vercel 项目

gtm-<slug>-workflows

，连接到该仓库的

workflows/

文件夹，并带有其现有数据库和机器传输。

scripts/

中的脚本使用 GitHub 和 Vercel CLI；

references/setup.md

列出了设置会创建什么以及哪些必须已经存在。连接设置通过 shared setup 使用现有受保护的工作流项目。连接名称来自 Vercel Secret Note 或本地标签，遵循 Connections naming。在该设置中，agent 仍然是可选的。工作区的内容属于其他 gtm 技能。

Inputs

输入

The request; the organization's workspace slug (the contract's slug rule; from an existing

~/.gtm/<slug>/

when one exists); the Vercel team slug (

vercel teams ls

; ask when more than one); the GitHub owner (the signed-in user unless the request names an organization); optionally a Slack channel id (

C0…

, at the bottom of a channel's About tab) for workflow notifications;

references/setup.md

请求；组织的 workspace slug（遵循 contract 的 slug 规则；如果存在

~/.gtm/<slug>/

，则来自该目录）；Vercel team slug（

vercel teams ls

；如果有多个则询问）；GitHub 所有者（除非请求中指定了组织，否则为当前登录用户）；可选地，用于工作流通知的 Slack 频道 ID（

C0…

，位于频道 About 选项卡底部）；

references/setup.md

。

Roles

角色

The user has the GitHub and Vercel CLIs signed in on this computer, authorizes the Slack install when required, either directly or through their authorized browser agent, adds the Neon database to the workflow project through Vercel's Neon integration (Production only, preview branching off) and accepts Neon's marketplace terms the first time a team uses it, invites the bot to a channel, and says the first sentence in Slack; the agent runs the scripts, relays exactly what the user must do, and reports the outcome.

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

Procedure

流程

Talk by the six rules in interaction; reproduce the dialogues. Before any job, confirm this computer can do it:

gh auth status

and

vercel whoami

both succeed, and

node --version

is 22 or newer. When they do not, or when this is the hosted agent itself (no

vercel

on PATH, or

GTM_RUN_SECRET

reads

host

), run nothing: say what is missing in one sentence and that a teammate runs

/gtm-agent

on a computer with both CLIs signed in.

Job	Do
Deploy	Ask for the Vercel team only when `vercel teams ls` shows more than one; ask for a channel id only when the user mentions workflow notifications. Say the one sentence of what will happen and that it takes about five minutes. Run `node scripts/setup.mjs --slug <slug> --team <team> [--github-owner <owner>] [--channel <id>]` from this skill's folder, streaming its output. When it prints the Slack address, relay it with the three things to do on that page (choose the workspace, configure the selected Slack profile using Slack configuration, Allow) and wait; the script continues by itself. Exit 2 names one human step: Slack installation, marketplace terms, project-scoped token setup, or signed-in setup verification: relay it, wait, run the same command again. Exit 0: close with the two Slack lines the script printed. Exit 1: report the failing line in plain words and offer Doctor.
Connect	The workflow project alone, for a deployment made before this skill or with `--no-workflows` : the same command with `--agent-project <name>` when the agent project has another name; the script skips what exists.
Doctor	`node scripts/doctor.mjs --slug <slug> --team <team> [--github-owner <owner>] [--agent-project <name>] [--workflow-project <name>] [--slack-connector <uid>]` ; report the failing lines in business terms with their fixes; run again with `--fix` when the user accepts the safe fixes (project settings, obsolete variables). For Slack changes, run `configure-slack.mjs --team <team> --connector <uid> --apply` , then follow Slack configuration to synchronize the provider manifest and reinstall. Pass a fresh `--slack-manifest <file.json>` to Doctor; it checks provider settings, installation freshness, and live token grants.
Upgrade	In the agent checkout ( `~/.gtm/.agents/<slug>/` , or the repository the user names): `git fetch template && git merge template/main` , preserve downstream customizations when merging, resolving routine conflicts within the authorized upgrade; ask only when intended behavior is ambiguous, `git push` ; the push deploys. Then Doctor. When the workflow runtime is behind, say so and hand off to gtm-workflow's Upgrade.

Names are fixed by the slug:

gtm-<slug>

(workspace repository),

gtm-agent-<slug>

(agent repository and project),

gtm-<slug>-workflows

(workflow project),

slack/gtm-agent-<slug>

(connector), the Neon database

gtm-<slug>

, connected to the workflow project only. A deployment made by hand before this skill keeps its names; pass them as overrides.

按照 interaction 中的六条规则进行对话；复现 the dialogues。在任何任务开始前，确认这台计算机能够执行：

gh auth status

和

vercel whoami

均成功，且

node --version

为 22 或更高。如果不满足，或者当前就是托管 agent 本身（PATH 中没有

vercel

，或

GTM_RUN_SECRET

读取为

host

），则不要运行任何命令：用一句话说明缺少什么，并说明需要由队友在一台两个 CLI 都已登录的计算机上运行

/gtm-agent

。

任务	操作
部署	仅当 `vercel teams ls` 显示多个团队时才询问 Vercel 团队；仅当用户提到工作流通知时才询问频道 ID。用一句话说明将要发生什么，以及大约需要五分钟。在此技能目录下运行 `node scripts/setup.mjs --slug <slug> --team <team> [--github-owner <owner>] [--channel <id>]` ，并流式输出其结果。当它打印出 Slack 地址时，将该地址和该页面上需要做的三件事（选择工作区、使用 Slack configuration 配置所选 Slack profile、点击 Allow）转达给用户，然后等待；脚本会自行继续。退出码 2 表示一个需要人工执行的步骤：Slack 安装、市场条款、项目级 token 设置或登录设置验证：转达该步骤，等待，然后重新运行相同命令。退出码 0：以脚本打印的两行 Slack 消息结束。退出码 1：用通俗语言报告失败行，并建议使用 Doctor。
连接	仅针对工作流项目，适用于在此技能之前部署或使用 `--no-workflows` 部署的情况：当 agent 项目名不同时，使用相同命令并加上 `--agent-project <name>` ；脚本会跳过已存在的部分。
Doctor	`node scripts/doctor.mjs --slug <slug> --team <team> [--github-owner <owner>] [--agent-project <name>] [--workflow-project <name>] [--slack-connector <uid>]` ；用业务语言报告失败行及其修复方式；当用户接受安全修复（项目设置、过时变量）时，使用 `--fix` 重新运行。对于 Slack 更改，运行 `configure-slack.mjs --team <team> --connector <uid> --apply` ，然后按照 Slack configuration 同步 provider manifest 并重新安装。为 Doctor 传入一个新的 `--slack-manifest <file.json>` ；它会检查 provider 设置、安装新鲜度和实时 token 授权。
升级	在 agent 的 checkout 中（ `~/.gtm/.agents/<slug>/` ，或用户指定的仓库）：执行 `git fetch template && git merge template/main` ，合并时保留下游自定义修改，解决授权升级范围内的常规冲突；仅在预期行为不明确时才询问； `git push` ；推送即部署。然后运行 Doctor。如果工作流运行时落后，请说明并移交给 gtm-workflow 的 Upgrade。

名称由 slug 固定：

gtm-<slug>

（工作区仓库）、

gtm-agent-<slug>

（agent 仓库和项目）、

gtm-<slug>-workflows

（工作流项目）、

slack/gtm-agent-<slug>

（连接器），Neon 数据库

gtm-<slug>

仅连接到工作流项目。在此技能之前手动完成的部署保留其原有名称；请通过覆盖参数传入。

Outputs

输出

A live agent answering in Slack, wired to its workspace repository and, unless declined, a live workflow project; the doctor's report; the two Slack lines: invite the app, then

@gtm-agent-<slug> set up our GTM workspace

一个在 Slack 中响应的在线 agent，连接到其工作区仓库，并且除非用户拒绝，还连接到一个在线工作流项目；doctor 的报告；两行 Slack 消息：邀请应用，然后

@gtm-agent-<slug> set up our GTM workspace

。

Exceptions

例外情况

Secrets never pass through the conversation: the scripts generate them and place them with

vercel env add

; the GitHub token is the CLI's own (

gh auth token

), which reaches every repository that user can write, and the user may replace

GTM_GITHUB_TOKEN

with a fine-grained token later. A Vercel Hobby account cannot hold a team: say that a Pro team is needed and stop. A GitHub organization that has not installed the Vercel GitHub app makes

vercel git connect

fail: name the install (Vercel → Settings → Git) and run again. A Vercel configuration update can leave Slack unchanged. Follow Slack configuration; Doctor must verify both sides and the installed token before reporting success. Requires

gtm-workspace

and

gtm-workflow

installed alongside this skill; when either is missing, say to install it with

npx skills add eliasstravik/gtm-skills -s <name> -y

(add

-g

when this skill lives in the global skills directory), then retry.

密钥绝不会通过对话传递：脚本会生成密钥并通过

vercel env add

放置；GitHub token 是 CLI 自身的（

gh auth token

），可访问该用户可写的所有仓库，用户之后可以将

GTM_GITHUB_TOKEN

替换为细粒度 token。Vercel Hobby 账户无法拥有团队：说明需要 Pro 团队并停止。未安装 Vercel GitHub app 的 GitHub 组织会导致

vercel git connect

失败：请说明安装位置（Vercel → Settings → Git）并重新运行。Vercel 配置更新可能不会改变 Slack。请遵循 Slack configuration；Doctor 必须在报告成功前验证两侧以及已安装的 token。需要在此技能旁边安装

gtm-workspace

和

gtm-workflow

；如果缺少其中任何一个，请说明使用

npx skills add eliasstravik/gtm-skills -s <name> -y

安装它（如果此技能位于全局 skills 目录中，则添加

-g

），然后重试。

Protected workflow viewer

受保护的工作流查看器

Setup stages an origin-scoped workflow bypass in the agent host, deploys that host, then enables native Vercel Authentication on All Deployments. The bypass and execution bearer never enter model-visible exports or user links. Doctor preserves protection and reports missing machine access or mismatched share-project trust. Existing signed intake senders need their own verified gate transport while preserving application signature checks; only pass

--intake-protection-verified

after checking each sender.

One public sharing project uses the workspace repository's

workflows/

root and

npm run build:share

. It has production-to-production Trusted Sources access to its own private project, only the fixed GET proxy, and no database, execution or provider credentials. Enable Share after deployment and access verification. See workflow viewer.

设置会在 agent 宿主中暂存一个 origin-scoped 的工作流绕过，部署该宿主，然后在所有部署上启用原生 Vercel Authentication。该绕过和执行 bearer 不会进入模型可见的导出或用户链接。Doctor 会保留保护，并报告缺失的机器访问或 share-project 信任不匹配。现有的已签名 intake 发送者需要它们自己的已验证 gate 传输，同时保留应用签名检查；只有在检查每个发送者后才能传入

--intake-protection-verified

。

一个公共共享项目使用工作区仓库的

workflows/

根目录和

npm run build:share

。它通过生产环境到生产环境的 Trusted Sources 访问自己的私有项目，仅使用固定的 GET 代理，并且没有数据库、执行或 provider 凭据。在部署和访问验证后启用 Share。参见 workflow viewer。

QC

Connections lives in the existing private workflow project. Verify its signed-in browser access after deployment; configuration alone is not readiness. Native account login, provider consent and Slack-specific actions may require the human.
No secret value appeared in the conversation or a reply.
Doctor ends with "All good." before the deployment is called done; every failing line was reported with its fix. Live smoke checks cover mentions, private channels, DMs, group-DM mentions, workflow replies, file downloads/uploads, and approvals; use an authorized test conversation.
The closing reply carries the two Slack lines and nothing about commits, builds, or checks.

连接配置位于现有私有工作流项目中。部署后验证其已登录的浏览器访问；仅配置并不等于就绪。原生账户登录、provider 同意和 Slack 特定操作可能需要人工参与。
对话或回复中不得出现任何密钥值。
在部署被认为完成之前，Doctor 必须以“All good.”结束；每个失败行都已报告并附带修复方式。实时冒烟检查涵盖提及、私密频道、私信、群组私信提及、工作流回复、文件下载/上传和审批；请使用经授权的测试对话。
结束回复包含两行 Slack 消息，不包含任何关于提交、构建或检查的内容。

References

参考

setup.md for what the scripts create, every variable, and the by-hand equivalent; interactions dialogues; from gtm-workspace: interaction, contract; from gtm-workflow: deploy.md.

setup.md：脚本创建的内容、每个变量以及手动操作对应的方式；interactions 对话；来自 gtm-workspace：interaction、contract；来自 gtm-workflow：deploy.md。