ga4

GA4 指引与路由技能（ga4）

接收模糊或多步骤的 GA4 请求，诊断当前状态，并按顺序引导或路由到合适的技能（ga-auth → ga-taxonomy → ga-use）。此技能本身不执行分析或身份验证。

语言

使用用户所用的语言回复。如果用户用韩语书写，就用韩语回答； 如果用户用英语书写，就用英语回答。此规则适用于每个步骤——设置指引、 进度更新、结果和错误说明。

绝不翻译：GA4 API 标识符（eventCount、sessionSource、runReport）、 文件和目录名称（.ga4/token.json）、shell 命令和 JSON 字段名称。

绝不向用户原样展示脚本输出。 脚本始终会输出英文的 error/hint 字符串。当脚本返回 "ok": false 时，你必须在展示前 将 hint 改写成用户所用的语言。绝不能直接粘贴英文，也不能展示原始 JSON。改写文本中的标识符、路径和命令必须保持原样——只翻译周围的文字。

示例——脚本返回： {"ok": false, "hint": "token.json is missing. Log in first with the ga-auth skill."} 对使用韩语的用户，应这样说： 로그인 정보(.ga4/token.json)가 없어요. ga-auth 스킬로 먼저 로그인할게요. 不要这样说："token.json is missing. Log in first with the ga-auth skill."

工作原则（关键）

受众是非技术营销人员：

• 将工作拆分成小步骤，并在每个步骤用一句话说明“做什么／为什么”。
• 简要展示一次完整流程。不要一次性粘贴很长的指南。
• 不要向营销人员索要 JSON 或命令。此技能负责处理文件放置和命令执行。

步骤 1：检查状态（始终首先执行）

{SKILLS_DIR} = 安装这些 ga 技能的目录——即此技能目录的上级目录（在 Claude Code 项目中为 .claude/skills）。请替换为实际路径。

python3 {SKILLS_DIR}/ga4/scripts/ga_journey.py

始终从项目根目录运行命令——脚本路径和默认的 .ga4 位置都以此为前提，因此从子目录运行会悄无声息地产生全为 false 的诊断结果，并将已连接的用户送回入门流程。 使用系统的 python3 运行（仅使用标准库——即使没有虚拟环境也必须能够运行）。输出 JSON：

字段	含义
ga4_dir / ga4_dir_present	实际搜索的文件夹，以及该文件夹是否存在。请先检查此项。 .ga4 会相对于当前工作目录解析，因此如果从错误的文件夹运行，下面所有字段都会同时变为 false——这会被理解为“尚未设置任何内容”，并将已连接的用户重新引导至入门流程。若值为 false，输出会包含 hint；请确认工作目录（或 GA4_DIR），然后重新运行，再决定将用户引导到何处
oauth_client_present	.ga4/oauth_client.json 存在（管理员创建的 OAuth 客户端）
token_present	已完成登录（token.json + refresh_token）
property_configured / property_id	已完成 GA4 媒体资源选择
taxonomy_present	.ga4/taxonomy.md 存在——仅表示文件存在，不代表文件中有内容
taxonomy_event_count	该分类体系实际包含的事件数量。0 表示文件存在但内容为空，这会在解析未填写的模板时发生；应视为“尚无分类体系”，并引导至 ga-taxonomy，而不是进行分析。null 表示无法读取数量（taxonomy.json 缺失或无法读取），因此不要据此下结论
platforms / platforms_checked_at / platforms_age_days	此媒体资源收集数据的平台（web/iOS/Android/unknown）、上次检查的时间，以及距上次检查的天数。请参阅下文的平台上下文——null 不表示“没有平台”，而是表示“从未查询过”
venv_present	.ga4/venv 已就绪（API 调用所需）
deps_ready	三个技能使用的所有库均已安装。false 表示尚未安装（也包括虚拟环境本身不存在的情况）；null 表示检查失败（安装状态未知——不要假定它们缺失）
missing_packages	（仅在存在时）{"skill-name": ["module-name", ...]}——仅列出缺失项
deps_fix	（仅在存在时）可直接运行的命令（以换行分隔）。如果没有虚拟环境，第一行会创建虚拟环境

如果缺少依赖项，请先自行解决，再委派任务：如果 deps_ready 为 false，请自行运行 deps_fix 命令（用一句话说明：“我来安装分析所需的库”），检查确认通过后再委派。不要让营销人员运行 pip 命令。如果 venv_present 为 false，deps_fix 的第一行会创建虚拟环境，因此也要运行该命令——跳过此步骤仍然委派任务，会导致受委派的技能尝试运行 .ga4/venv/bin/python，引发 shell 错误（no such file or directory），让营销人员看到原始错误，而不是 JSON。如果重新检查后仍为 false，不要重复运行相同的命令——直接告诉用户具体失败原因。如果 deps_ready 为 null，则无法确认安装状态，因此仍可继续；只有实际发生错误时，才逐步引导完成设置。

如果输出为 "ok": false，请遵循随附的 hint，并用用户的语言说明，以引导用户采取下一步行动。

连接检查：“已连接”要求 token_present 和 property_configured 均为 true。如果尚未连接，收到任何请求时都用一行回复：“需要先连接 GA4（1 分钟检查 → 登录 → 选择媒体资源）”，然后委派给 ga-auth。但是，如果用户尚未登录（token_present=false——即步骤 5 的条件），请先展示步骤 5 的操作流程概览，再进行委派。

平台背景

状态检查会报告 platforms——此属性收集数据的平台，采用 GA4 自身的拼写（web、iOS、Android 或 unknown）。这会影响哪些事件和维度可能存在，因此在判断是否缺少数据前，请先查看此字段。

• null 表示从未查询过。不要假定平台类型。 猜测平台类型正是此字段要防止的问题。请重新运行 .ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py get-property <PROPERTY_ID> 并通过 ga-auth skill 的第 4 步中的第 4 和第 5 项保存结果：保存时会从头重建 config.json，因此必须在同一条命令中再次传入币种、时区和数据保留期限，否则它们会变为 null——这会导致 ga-use 无法获知其报告收入所用的币种（实时响应完全不带元数据），也无法获取其空漏斗检查所依赖的数据保留值。
• [] 表示该属性没有数据流——它没有收集任何数据。
• unknown 条目表示某个数据流无法分类，因此列表并未提供完整答案。存在 unknown 时，不要把缺少 web 说成“仅限 App”：应说明该属性无法分类，而不是对其作出仅限 Web 或仅限 App 的判断。
• 如果 platforms_age_days 超过 180，列表可能早于团队后来添加的平台。请重新检查后再依赖此信息。
• platforms 表示已配置哪些数据流；platform 维度表示实际到达了哪些流量。已配置的数据流仍可能没有数据，因此不要把其中一个说成另一个。

第 2 步：意图分类

根据下表对请求分类并委派。明确的单一目的请求从一开始就应交给对应的 skill，因此即使由此 skill 接到，也应立即转交给对应 skill（无需进一步解释）。

意图	示例表述	委派给
连接、登录、权限问题	“连接 GA”、“登录不起作用”、“权限错误”、“GA 연결”、“로그인이 안 돼”、“권한 오류”	ga-auth
解析／核对／起草分类体系	“注册我们的分类体系”、“我们是否按设计收集数据？”、“我们没有分类体系，帮我们创建一个”、“정의서 등록”、“설계대로 수집되고 있어?”、“정의서가 없는데 만들어줘”	ga-taxonomy
数据查询／分析	“上周的页面浏览量”、“排名前 10 的事件”、“转化漏斗”、“지난주 페이지뷰”、“이벤트 상위 10개”、“전환 퍼널”	ga-use
能力相关问题	“GA 能做什么？”、“我该怎么使用？”、“GA로 뭘 할 수 있어?”、“이거 어떻게 써?”	转到第 3 步（但回答开头要先介绍 3 步流程）
含糊不清	“看看我们的 GA”、“我们的数据怎么样？”、“GA 좀 봐줘”、“우리 데이터 어때?”	转到第 3 步
复合请求（涉及 2 个或更多 skill）	“解析我们的分类体系表并分析上个月的数据”、“정의서 올리고 지난달 분석해줘”	转到第 4 步

如何委派：在可用 skills 列表中找到匹配的名称（ga-auth／ga-taxonomy／ga-use；插件发行版中可能显示为 <plugin>:ga-auth），并使用 Skill 工具调用它。

转交给 ga-taxonomy 或 ga-use 时，请在交接信息中说明该属性的平台。对于仅限 Web、仅限 App 和混合属性，这两个 skill 的推理方式不同，而诊断结果已经给出了答案。

第 3 步：含糊请求 → 根据状态提供建议

根据诊断结果，提出 2-3 个后续选项，待用户选择后再委派给匹配的 skill：

• 未连接 → 只建议“① 先连接 GA4（5-10 分钟）”，并委派给 ga-auth。
• 已连接 + 没有分类体系 → “① 快速查看上周的数据 ② 注册事件分类体系（如果已有）③ 根据实时数据起草分类体系（如果没有）”
• 已连接 + 有分类体系 → “① 分析一个你感兴趣的指标 ② 核对分类体系与实际收集的数据是否一致”

第 4 步：复合请求 → 拆分后按顺序委派

1. 先列出将请求拆分为各技能步骤的清单：“我将按以下顺序进行：① 解析分类体系（ga-taxonomy）→ ② 分析上个月的数据（ga-use）”。
2. 如果缺少前置条件，将其插入最前面（如果尚未连接，则添加 ⓪ ga-auth）。
3. 用户同意后，通过 Skill 工具每次执行一个步骤，确认每一步均已完成， 然后再进行下一步。如果中间某一步失败，立即停止并报告失败原因——在失败结果上继续叠加下一步，会掩盖问题根源，让营销人员无法判断究竟哪一步出了问题。

第 5 步：引导入门（首次使用）

如果用户尚未登录（token_present=false），则视为首次使用。即使 oauth_client.json 已存在，也适用此规则——管理员提前交付该文件是标准的使用入口，如果排除这种情况，明显属于首次使用的用户就会无法了解整体流程。简要展示一次 3 步流程，并从 ga-auth 开始：

使用 Claude 搭配 GA4 分为 3 步： ① 连接（ga-auth：登录、选择属性，耗时 5-10 分钟）→ ② 分类体系（ga-taxonomy：注册/核对事件分类体系，可选）→ ③ 分析（ga-use：用自然语言提问，获取表格结果） 现在就从 ① 开始吧。

第 ② 步是可选的——不使用分类体系也能进行分析，因此如果用户愿意，可以从 ① 直接跳到 ③。