gtm-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GTM workflow

GTM工作流

Trigger

触发条件

Apply this Lifecycle SOP to a saved GTM workflow from creation through updates, runs, inspection, deployment, and deletion.

本生命周期SOP适用于已保存的GTM工作流从创建、更新、运行、检查、部署到删除的全流程。

Scope

范围

Own workflow code, result tables, migrations, dry runs, runs, diagrams, and deployment metadata inside the root

workflows/

project.

gtm-workspace

gtm-icp

, and

gtm-persona

own their respective artifacts.

Contract

Field	Public contract
Reads	The request, accepted workspace context, supplied rows, workflow files, and environment-held credentials
Writes	Workflow code, result tables, migrations, schedules, and deployment metadata
Outputs	A verified saved workflow, run result, inspection, diagram, deployment, or deletion
Approval	One plain-language card covers creation, save, hosted deployment, one-row test, and small fixes; later runs and checkpoints each get one card
Persists	Prepared local commits and approved pushes, plus workflow rows and cost records
Handoff	Workspace, ICP, and persona lifecycle changes go to their owning skills

负责根目录

workflows/

项目内的工作流代码、结果表、数据迁移、试运行、正式运行、流程图及部署元数据。

gtm-workspace

、

gtm-icp

和

gtm-persona

模块各自负责其对应的产出物。

核心约定

字段	对外约定
读取内容	请求、已接受的工作区上下文、提供的行数据、工作流文件以及环境中存储的凭证
写入内容	工作流代码、结果表、数据迁移、调度规则及部署元数据
输出内容	经验证的已保存工作流、运行结果、检查报告、流程图、部署结果或删除结果
审批规则	一张简明易懂的卡片涵盖创建、保存、托管部署、单行测试及小修复；后续的运行和检查点各对应一张审批卡
持久化内容	已准备的本地提交和已批准的推送，以及工作流行数据和成本记录
交接规则	工作区、ICP和persona生命周期的变更交由其对应的负责技能处理

Inputs

输入项

Use the request, resolved organization context, relevant accepted ICP and persona files, supplied rows, current workflow project, environment-held credentials, and accepted cost limits.

使用请求、已解析的组织上下文、相关的已接受ICP和persona文件、提供的行数据、当前工作流项目、环境中存储的凭证以及已确认的成本限制。

Roles

角色职责

The agent authors and verifies the work. The user approves one card covering saved changes, hosted deployment, the one-row test, stated external effects, and stated test cost; later full runs and user-chosen checkpoints each receive one approval.

Agent负责编写和验证工作内容。用户通过一张卡片审批已保存的变更、托管部署、单行测试、声明的外部影响以及声明的测试成本；后续的完整运行和用户选择的检查点各需一次审批。

Procedure

操作流程

Resolve the GTM workspace and requested lifecycle action. Ask one unnumbered question only when a result-changing fact cannot be inferred.
For create, copy
```
templates/
```
from this installed skill into the workspace's root
```
workflows/
```
project when absent, rename
```
gitignore
```
and
```
vercelignore
```
with leading dots, copy
```
.env.example
```
to
```
.env
```
, and write
```
GTM_HOST=<claude|codex>
```
for the host you run in. Workflow files live at
```
workflows/workflows/<slug>.ts
```
. Read the library, SDK choices, and the interaction standard. Read deployment only for deploy work and local use only for open/local work.
Draft workflow code, its table, a one-row input, and the author-written
```
Diagram:
```
header. A schedule request also writes the matching
```
vercel.json
```
cron entry. Run
```
npm run db:generate
```
,
```
npm run gtm -- verify <slug> --input data/test-1-row.json
```
,
```
git add <changed workflow, table, and migration paths>
```
, and
```
git commit -qm "<plain summary>"
```
silently.
```
data/
```
is ignored on purpose: the test input stays local and the card names it. Use
```
git commit --amend
```
after feedback when the prior commit was not pushed; after a push, a fix is a new commit.
Post one plan card stating what it does, reads, saves, where it runs, one-row test cost, possible data removal, and any missing key. Its last line is
```
Saving and testing. Back in a few minutes.
```
Invoke the matching command with that card as its approval summary: hosted,
```
git push && npm run gtm -- run <slug> --url https://<production-host> --input data/test-1-row.json --wait-live --background
```
, which returns at once and starts the test in the background after the deploy is live; local,
```
npm run gtm -- run <slug> --input data/test-1-row.json
```
, which starts the local server itself when needed.
After approval, collect hosted results with
```
watch_url
```
on
```
/api/runs/latest?workflow=<slug>&head=<pushed commit>
```
until a run appears, then on
```
/api/runs/<runKey>
```
until it finishes; at a keyboard use
```
npm run gtm -- runs get <id> --wait 600
```
. A failed run carries its plain reason in
```
error
```
; show it. Fix small failures and retry the identical approved step up to twice. Present a fresh card when cost, external effects, saved tables, command, or summary changes.
On success say
```
Built and tested. Ready to run whenever you want.
```
and provide the picture plus Diagram, Runs, and Data links. A later full run gets one short card and one real
```
run
```
command. Cancel asks
```
What would you like me to change?
```
; revise from free text and re-ask at the same step.
For update, inspect, or delete, preserve the same one-card boundary: verify and commit silently, then request approval for the first effectful command. Name deletion and data-removing SQL on the card. Use expand-then-contract for renames while a run may be waiting.

The command classifier allows local reads, checks, verification, dry runs, ordinary writes inside the checkout or scratch, and local commits. It asks for real runs, approval/cancellation, deploy commands, pushes, forced adds, paths outside those roots, and every unknown command. A chain takes its most restrictive classification; one approval request may be active at a time.

解析GTM工作区和请求的生命周期操作。仅当无法推断出会影响结果的事实时，才提出一个无编号的问题。
创建工作流时，若工作区根目录的
```
workflows/
```
项目中不存在模板，则将本已安装技能的
```
templates/
```
目录复制到该项目中，将
```
gitignore
```
和
```
vercelignore
```
重命名为带前导点的格式，将
```
.env.example
```
复制为
```
.env
```
，并根据你运行的主机写入
```
GTM_HOST=<claude|codex>
```
。工作流文件存放在
```
workflows/workflows/<slug>.ts
```
路径下。请阅读函数库、SDK选型指南以及交互标准。仅在处理部署工作时阅读部署指南，仅在处理开放/本地工作时阅读本地使用指南。
起草工作流代码、对应的数据表、单行测试输入，以及编写者标注的
```
Diagram:
```
头部。如果是调度请求，还需在
```
vercel.json
```
中写入对应的cron条目。静默执行以下命令：
```
npm run db:generate
```
、
```
npm run gtm -- verify <slug> --input data/test-1-row.json
```
、
```
git add <changed workflow, table, and migration paths>
```
以及
```
git commit -qm "<plain summary>"
```
。
```
data/
```
目录被故意忽略：测试输入仅保存在本地，审批卡中会提及该文件。若之前的提交尚未推送，收到反馈后使用
```
git commit --amend
```
修改；若已推送，则修复内容需作为新的提交。
发布一张计划卡片，说明工作流的功能、读取内容、保存内容、运行环境、单行测试成本、可能的数据删除操作以及所有缺失的密钥。卡片的最后一行为
```
保存并测试中，几分钟后回来。
```
。以该卡片作为审批摘要调用对应的命令：托管环境下执行
```
git push && npm run gtm -- run <slug> --url https://<production-host> --input data/test-1-row.json --wait-live --background
```
，该命令会立即返回，并在部署上线后在后台启动测试；本地环境下执行
```
npm run gtm -- run <slug> --input data/test-1-row.json
```
，该命令会在需要时自行启动本地服务器。
审批通过后，通过
```
watch_url
```
轮询
```
/api/runs/latest?workflow=<slug>&head=<pushed commit>
```
接口，直到出现运行记录，再轮询
```
/api/runs/<runKey>
```
接口直到运行完成；在终端操作时可使用
```
npm run gtm -- runs get <id> --wait 600
```
命令。运行失败时，
```
error
```
字段会包含简明的失败原因；请展示该原因。对于小故障，可修复后重试同一已审批步骤，最多重试两次。若成本、外部影响、保存的数据表、命令或摘要发生变化，则需提交新的审批卡片。
运行成功后输出
```
已构建并测试完成，随时可以运行。
```
，并提供流程图以及Diagram、Runs和Data页面的链接。后续的完整运行对应一张简短审批卡和一条实际的
```
run
```
命令。用户取消时询问
```
你希望我修改什么？
```
；根据自由文本修改后，在同一步骤重新请求审批。
对于更新、检查或删除操作，保持同样的单卡审批规则：先静默验证并提交，然后为第一个产生实际影响的命令请求审批。在卡片上注明删除操作以及会移除数据的SQL语句。当可能有运行任务在等待时，重命名操作采用「先扩展后收缩」的策略。

命令分类器允许执行本地读取、检查、验证、试运行、工作目录或临时目录内的普通写入，以及本地提交操作。对于正式运行、审批/取消、部署命令、代码推送、强制添加、根目录外的路径操作，以及所有未知命令，它都会请求审批。命令链采用最严格的分类规则；同一时间只能有一个活跃的审批请求。

Outputs

输出项

Produce a verified saved workflow or the requested run, inspection, deployment, or deletion result, with owned rows and cost records tied to its run.

生成经验证的已保存工作流，或所请求的运行、检查、部署、删除结果，并附带与运行关联的所属行数据和成本记录。

Exceptions

异常处理

When the Claude Code hook is missing, say

Run command-permission.mjs --install-claude-code, then restart Claude Code.

and use the interaction standard's numbered approval fallback for this session. Under

GTM_SANDBOX=1

, every run must use the literal hosted URL; the bot never runs the workflow in its sandbox. Claude Code runs

agentStage()

locally with a budget cap and MCP-only tools; Codex cannot cap spend and returns the refusal sentence, so Codex users add an AI key for agentic stages.

如果缺少Claude Code钩子，输出

请运行command-permission.mjs --install-claude-code，然后重启Claude Code。

，并在本次会话中使用交互标准的编号审批备用方案。在

GTM_SANDBOX=1

环境下，所有运行必须使用明确的托管URL；机器人永远不会在其沙箱中运行工作流。Claude Code会在本地运行

agentStage()

，带有预算上限且仅使用MCP工具；Codex无法限制支出，会返回拒绝语句，因此Codex用户需要为Agent阶段添加AI密钥。

QC

质量控制

```
gtm verify
```
passes before the card; the card reflects its cost, migration, and missing-key facts.
Paid calls, including
```
agentStage()
```
, use an explicit
```
step
```
matching a
```
[step: name]
```
Diagram node.
```
agentStage()
```
costs use
```
[cost: up to $X/row]
```
matching
```
maxUsd
```
.
Secrets remain in environment variables.
```
.env*
```
,
```
data/
```
,
```
.workflow-data/
```
,
```
.gtm-local.json
```
, and
```
node_modules/
```
remain untracked.
Each file write stays inside the checkout or scratch and preserves user-owned workflow/table/provider files during
```
gtm upgrade
```
.
User-facing text follows the interaction standard and contains no raw commands or JSON inside approval cards.

提交审批卡前必须通过
```
gtm verify
```
校验；卡片需体现成本、数据迁移及缺失密钥的相关信息。
付费调用（包括
```
agentStage()
```
）需使用与
```
[step: name]
```
流程图节点匹配的明确
```
step
```
参数。
```
agentStage()
```
的成本使用与
```
maxUsd
```
匹配的
```
[cost: up to $X/row]
```
格式标注。
密钥仅存储在环境变量中。
```
.env*
```
、
```
data/
```
、
```
.workflow-data/
```
、
```
.gtm-local.json
```
和
```
node_modules/
```
均不纳入版本控制。
所有文件写入操作均限制在工作目录或临时目录内，执行
```
gtm upgrade
```
时会保留用户拥有的工作流/数据表/提供商文件。
面向用户的文本遵循交互标准，审批卡中不包含原始命令或JSON内容。

References

参考文档

Library contract
SDK choices
Deployment
Local use
Shared interaction standard

函数库约定
SDK选型指南
部署指南
本地使用指南
通用交互标准