ads-start

引导式入门向导

你正在运行首次使用／重新进入向导，该向导会生成并维护 ~/.claude-ads/profile.json。这是新用户的规范入口，也是用户重新编辑已保存上下文的唯一位置。向导不会自动调用其他 /ads 命令——结束时会建议下一条命令，然后退出。

核心规则

1. 一次只问一个问题。 每个步骤使用一个包含 2–4 个选项的 AskUserQuestion 区块，然后通过 python3 scripts/profile.py set <dot.path> <value> 将答案写入配置文件，再询问下一个问题。必须能够恢复未完成的流程。
2. 逐步验证。 设置 OAuth／MCP 时，一次说明一个步骤，等待用户回复“完成”，运行验证调用并诊断错误。每个平台最多重试 3 次，之后提供“跳过，稍后再回来”选项。
3. 绝不在配置文件中存储机密。 Token、API 密钥、刷新 Token 仅存放在环境变量中。配置文件记录 api_key_present: true/false，绝不记录其值。
4. 向导结束时不执行操作。 以纯文本建议下一条命令，切勿执行该命令。

子命令路由

读取用户的参数（如果有）：

参数	行为
（无）	阶段 A — 检测首次运行还是重新进入。
status	运行 python3 scripts/profile.py get，打印 5 行摘要，然后退出。
edit	跳过阶段 A 欢迎内容，跳转到阶段 A.4 的编辑选择器。
reset	使用 AskUserQuestion 确认 → 调用 python3 scripts/profile.py reset --yes → 从阶段 A 重新开始。

---

阶段 A — 检测首次运行还是重新进入

A.1 运行 python3 scripts/profile.py get 并获取退出码。

• 退出码 2（无配置文件）→ 首次运行：打印下方欢迎横幅，然后前往阶段 B。
• 退出码 0（配置文件存在）→ 重新进入：打印 5 行摘要（行业、支出区间、活跃平台、上次命令），然后前往 A.4。

A.2 首次运行欢迎内容（按用户语言原样打印）：

Welcome to claude-ads. I'll walk you through 4 quick steps:

  1. Tell me about your business (~1 min)
  2. Connect Meta / Google / TikTok — one at a time, step by step (~2-10 min each)
  3. Optional: Zernio for publishing creatives, Meta for Developers
  4. Pick your first action

Nothing leaves your machine. Tokens go to env vars, not the profile.
You can re-run /ads start edit anytime to change settings, or /ads start reset
to start over.

A.3 首次运行：运行 python3 scripts/profile.py init 并继续前往阶段 B。

A.4 重新进入时的编辑选择器 — AskUserQuestion：

“你想更改什么？”

• Business context — 重新运行阶段 B。
• Meta connection — 仅针对 Meta 重新运行阶段 C。
• Google connection — 仅针对 Google 重新运行阶段 C。
• TikTok connection — 仅针对 TikTok 重新运行阶段 C。
• Zernio publishing — 重新运行阶段 D 的 Zernio 区块。

（AskUserQuestion 会添加“其他”选项——将其视为取消。）

完成所选编辑后，通过 python3 scripts/profile.py set last_command_at $(date -u +%FT%TZ) 写入 last_command_at，并以一行“已保存。”确认信息退出。

---

阶段 B — 业务上下文（首次运行或 edit context）

连续执行四个 AskUserQuestion 区块。每个答案都要立即保存。

B.1 行业 — AskUserQuestion（单选）

选项：Ecommerce · Local service · Real estate · Healthcare · Finance · Agency / multiple clients · Other。

映射为配置文件值：ecommerce、local-service、real-estate、 healthcare、finance、agency、other。

然后：python3 scripts/profile.py set context.industry <value>。

B.2 月广告支出 — AskUserQuestion（单选）

选项：Under $500/mo · $500–$2,000/mo · $2,000–$10,000/mo · $10,000+/mo。（用户可以选择“其他”并输入确切金额——将其转换为数字。）

将区间映射为美元中值：250、1250、6000、25000。如果用户提供了确切数字，则使用该数字。

然后：python3 scripts/profile.py set context.monthly_spend_usd <number>。

B.3 主要目标 — AskUserQuestion（单选）

选项：Sales / revenue · Leads / signups · App installs · Phone calls · Brand awareness。

映射为 sales、leads、app-installs、calls、brand。

然后：python3 scripts/profile.py set context.primary_goal <value>。

B.4 活跃平台 — AskUserQuestion（multiSelect: true）

“你目前在哪些平台投放广告（或计划投放）？”

选项：Meta (Facebook + Instagram) · Google Ads (incl. YouTube) · TikTok Ads。

至少选择 1 项。映射为 ["meta","google","tiktok"] 的子集。

然后运行：python3 scripts/profile.py set context.active_platforms '<json>'。

---

阶段 C — 逐个平台连接向导

对 context.active_platforms 中的每个平台（按 Meta → Google → TikTok 的顺序，仅限在 B.4 中选择的平台）运行以下循环。

C.1 选择层级 — AskUserQuestion（单选）

“你想如何连接 <PLATFORM>？”

选项	保存为 connections.<p>.tier	备注
MCP server (recommended)	Meta 使用 mcp_claude_ai · Google 使用 mcp_cohnen · TikTok 使用 mcp_adsmcp	层级 1。最快。
Direct API (free, OAuth once)	direct_api	层级 2。完全掌控。
Manual exports for now	manual	层级 3。始终可用，无需设置。
Skip — set this up later	skipped	暂不配置。

如果选择 manual 或 skipped：写入层级，将 connected_at 写为当前时间，跳过 C.2-C.4，继续下一个平台。

C.2 加载平台设置指南

阅读相关参考文件：

平台	参考文件
Meta	ads/references/setup-meta.md
Google	ads/references/setup-google.md
TikTok	ads/references/setup-tiktok.md

每个文件包含 A 节（MCP）、B 节（Direct API）、C 节（Manual）。跳转到与用户所选层级对应的 章节。在该章节中，按顺序引导用户完成各步骤。

C.3 逐步验证式引导

对于所选章节中的每个步骤：

1. 逐字显示步骤内容：其目标、“Do this”下的确切 URL/操作，以及用户“Expect to see”的内容。
2. AskUserQuestion → “第 N 步完成了吗？”，选项：
   • Done — next step
   • Hit an error
   • Cancel and skip this platform
3. 选择 Done：继续下一步。
4. 选择 Hit an error：阅读该步骤的“On error”分支，并请用户 描述他们看到的内容。根据参考文件建议最可能的修复方法。 重试该步骤。最多尝试 3 次 → 提供跳过选项。
5. 选择 Cancel：设置 connections.<p>.tier = "skipped"，然后继续下一个 平台。

完成最后一步后，运行验证调用：

平台	层级 A（MCP）验证	层级 B（Direct API）验证
Meta	调用 mcp__claude_ai_Facebook__ads_get_ad_accounts	python3 scripts/api/meta_fetch.py --account-id <id> --what account
Google	调用 mcp__cohnen_google_ads__list_customers（如果可用）— 否则请用户粘贴 customer_id	python3 scripts/api/google_fetch.py --customer-id <id> --what account
TikTok	通过 MCP 工具列出广告主 — 否则请用户粘贴 advertiser_id	python3 scripts/api/tiktok_fetch.py --advertiser-id <id> --what account

（如果此会话中没有 MCP 工具 — 例如，用户尚未在 claude.ai 上启用该工具 — 请改为让用户手动粘贴账户 ID，并跳过实时调用。记录 last_verified_at: null，以便 /ads 下次知道要重新验证。）

C.4 保存连接

验证成功后：

python3 scripts/profile.py set connections.<platform>.ad_account_id "<id>"
python3 scripts/profile.py set connections.<platform>.connected_at "$(date -u +%FT%TZ)"
python3 scripts/profile.py set connections.<platform>.last_verified_at "$(date -u +%FT%TZ)"

打印包含账户 ID 的 ✓ 确认信息。继续下一个平台。

---

阶段 D — 可选的账户创建引导

D.1 Meta for Developers（仅当 Meta 层级 == direct_api 时）

AskUserQuestion：

“你已经有 Meta for Developers 账户了吗？（使用直接 Meta API 路径必须拥有该账户。）”

选项：Yes — I have one · No — walk me through it · Skip。

选择 No 时：加载 ads/references/setup-meta-developers.md 并运行 逐步引导循环（与 C.3 的模式相同）。用户创建应用 并添加 Marketing API 产品后，返回 setup-meta.md 中 Direct API 章节的 C.3 第 1 步。

D.2 Zernio 发布（在阶段 C 结束时询问一次，无论套餐等级如何）

AskUserQuestion：

“你想启用 /ads publish，将生成的创意内容发布到 14 个以上的社交网络吗？Zernio 的免费套餐永久支持连接 2 个账户（无需信用卡）。”

选项：是 — 带我完成 Zernio 注册 · 以后再说 — 跳过 · 我已经有账户。

• 是：加载 ads/references/setup-zernio.md，运行步骤循环。成功后 写入 zernio.signed_up = true。如果用户表示已将 API 密钥保存到 ZERNIO_API_KEY，也写入 zernio.api_key_present = true。
• 我已经有账户：只需询问是否已导出 ZERNIO_API_KEY。 写入 zernio.signed_up = true，并相应设置 zernio.api_key_present。
• 跳过：保留默认值（false）。

---

阶段 E — 首次操作建议

打印一屏摘要：

✓ Profile saved to ~/.claude-ads/profile.json
✓ Connected:  <platform list with tier>
✓ Zernio:     <on / off>

然后运行 AskUserQuestion：

“你已完成设置。想先运行什么？”

选项（仅显示用户实际配置的选项）：

• /ads audit — 全平台完整审计（如果已连接 ≥2 个平台且套餐等级 ≠ 已跳过，推荐此选项）。
• /ads <single-platform> — 深入分析一个平台（从用户已连接的平台中单选）。
• /ads plan <industry> — 根据你的行业模板生成战略计划 （使用用户的 context.industry，若无则回退到 generic）。
• 直接退出 — 我想自行探索。

打印要输入的确切下一条命令（不要调用它）。示例：

太好了 — 下一步，请输入：/ads audit

最后执行：python3 scripts/profile.py set last_command "/ads start" && python3 scripts/profile.py set last_command_at "$(date -u +%FT%TZ)"。

---

状态模式（/ads start status）

运行 python3 scripts/profile.py get 并打印：

claude-ads profile
  Industry:           <context.industry or "—">
  Monthly spend:      ~$<context.monthly_spend_usd>/mo
  Goal:               <context.primary_goal>
  Active platforms:   <comma list>
  Meta:               <tier> · <ad_account_id or "—"> · last verified <relative time>
  Google:             <tier> · <ad_account_id or "—"> · last verified <relative time>
  TikTok:             <tier> · <ad_account_id or "—"> · last verified <relative time>
  Zernio:             <on/off> · API key <present/missing>
  Last command:       <last_command> (<relative time>)

退出，不再提示。

---

错误处理

• 如果 python3 scripts/profile.py 不可执行，则通过 python3 scripts/profile.py … 运行（这是默认方式）。
• 如果 ~/.claude-ads/ 为只读，打印该路径，并要求用户修复权限后重试。
• 如果 AskUserQuestion 返回“Other”且没有有用文本，则将该步骤视为取消。

输出约定

该向导不会生成报告文件。它只写入 ~/.claude-ads/profile.json 并输出面向用户的文字。其他 /ads 命令通过 python3 scripts/profile.py get 读取配置文件。