last30days Skill 首次运行 NUX 设置向导：v3.0.0 历史快照、完整配置键位与当前实现解析

技术导读：last30days 是一个面向 AI Agent 的跨平台研究技能，当用户第一次运行 /last30days <topic> 时，Agent 必须先引导用户完成首次配置（安装工具、提取浏览器 Cookie、解锁 X/Twitter、可选接入 ScrapeCreators 等）。本文以仓库中的 docs/reference/old-nux-wizard-v3.0.0.md 历史快照为骨架，完整还原 v3.0.0 首次运行 NUX（New User eXperience）向导的双平台流程、全部 .env 配置键位与安全写入规则，并结合 SKILL.md 现行实现与 setup_wizard.py 源码，说明向导背后的判定逻辑、命令调用链与演进差异。读完你可复现整套 first-run 引导设计，也能按手册手工配置所有研究源。

---

一、文档定位：一份有"溯源价值"的历史快照

docs/reference/old-nux-wizard-v3.0.0.md 本身并不是普通的使用手册，而是一份从 SKILL.md 在 git commit 0a9ff16（v3.0.0，2026-04-08）处逐字捕获（Captured verbatim）的原文存档。它的存在目的有三，文档开头写得很清楚：

1. Provenance（溯源）：为"Matt 当年构建的首次运行向导"留下可核对的原始副本；
2. 作为恢复源头（source）：它是后来"恢复模态 NUX"的蓝本（当前 SKILL.md 中 Step 0 的 Claude Code Modal Flow 即为该快照的现代还原版本）；
3. 标注了与现行版本的关键差异：文档开头明确提示"live wizard in SKILL.md Step 0 uses the CURRENT source inventory (Digg, youtube_comments, SC backups) and omits Threads/Pinterest"——即当前向导的源清单已经更新（新增 Digg、YouTube 评论、ScrapeCreators 备份语义；移除了 Threads/Pinterest）。

也就是说，读这份文档 = 读 v3.0.0 时代 Agent 首次被用户调用时的完整行为规范。它是理解该项目"引导层（onboarding）如何收敛权限与凭据"的最佳入口，而非一个静态的配置说明。

---

二、Step 0 的核心设计原则：先向导、后研究、静默检测

v3.0.0 向导被命名为 Step 0: First-Run Setup Wizard，它最强调的规则是"ALWAYS execute Step 0 BEFORE Step 1, even if the user provided a topic"。

2.1 即使用户已给主题，向导也不可跳过

文档用 /last30days Mercer Island 举例：即便用户在命令中直接携带了研究主题，Agent 也必须先完成首次运行检测并展示向导，主题只是被"暂时保存"，向导结束后立刻开始研究。向导本身约耗时 10 秒且"一生只跑一次"（only runs once ever）。这一"topic 保留、研究延后"的语义在当前 SKILL.md 中演化成了更细的 RESEARCH CONTINUATION OVERRIDE（第 539 行起）：当用户拒绝对话式 Cookie 同意或选择 Skip 时，向导会先走无 Cookie 路径并立刻研究，把 ScrapeCreators 提供、源开关等可选步骤推迟到本次研究响应之后再继续——"Deferred is not dropped"，因为 SETUP_COMPLETE=true 已经写入，后续调用将跳过 Step 0。

2.2 静默的首次运行检测

首次运行的判定在 v3.0.0 中非常克制，文档明确要求 Agent：

• 仅检查 ~/.config/last30days/.env 是否存在（文件不存在 = first run）；
• 不得运行任何 Bash 命令或向用户展示命令输出；
• 若文件已存在且包含 SETUP_COMPLETE=true，则静默跳到 Step 1，不输出任何"Setup is complete"之类的状态消息。

当前实现把检测来源扩展得更多：env.py 的 is_setup_complete()（第 1318-1324 行）只判断 SETUP_COMPLETE 是否为真值；而 SKILL.md 第 543-546 行补充道：凭据可能存在于 process env、项目配置 .claude/last30days.env、全局配置 ~/.config/last30days/.env、macOS Keychain（last30days-<KEY>）、pass(1)、宿主自带 auth 中，因此".env 文件不存在"本身不再等同于 first run——只有当所有标记源与凭据源都为空时才算首次运行。底层 is_first_run() 的判定逻辑很简单：return not config.get("SETUP_COMPLETE")（setup_wizard.py 第 25-31 行）。

2.3 按能力分叉的两条流程

向导根据"Agent 会话是否具备 WebSearch / AskUserQuestion 交互能力"拆成两条完全不同的执行路径：

宿主类型	能力	走哪条流程
Claude Code	有 WebSearch + AskUserQuestion 模态框	Claude Code Setup Flow（模态驱动）
OpenClaw / Codex / raw CLI	无 WebSearch / 无可交互模态	OpenClaw / Non-WebSearch Setup Flow（JSON + 状态摘要）

从 SKILL.md 第 552-554 行可以看到，这一"平台分叉"被完整保留到今天，只是演进为 Claude Code Modal Flow 与 Non-Modal Prose Flow 两支，二者"做同样的工作"（同款 Cookie 提取、同款 CLI 安装、同款 ScrapeCreators 提供），差别仅在交互载体：模态框还是纯文本对话。

---

三、OpenClaw / Non-WebSearch 流程：JSON 探测 + 分级配置

这一支适合无浏览器弹窗、无模态 UI 的服务器场景。v3.0.0 文档给出的命令是：

python3 "${SKILL_ROOT}/scripts/last30days.py" setup --openclaw

3.1 先环境探测，再渲染状态摘要

Agent 运行上述命令后读取 JSON 输出，据此判断哪些已配置、哪些缺失，然后向用户展示一个带 ✅/❌ 的状态摘要：

👋 Welcome to /last30days!

Detected:
{✅ or ❌} yt-dlp (YouTube search)
{✅ or ❌} X/Twitter ({method} configured)
{✅ or ❌} ScrapeCreators (TikTok, Instagram, Reddit backup)
{✅ or ❌} Web search ({backend} configured)

在源码层面，这个 JSON 由 setup_wizard.py 的 run_openclaw_setup()（第 793 行起）产出。它探测的项目包括：

• yt_dlp：shutil.which("yt-dlp") 是否存在；
• node / python3：运行时可用性；
• digg_cli 与 digg_action：best-effort 安装 digg-pp-cli（Printing Press 库的 CLI）；
• keys：对一组键名逐一探测（SCRAPECREATORS_API_KEY、XAI_API_KEY、BRAVE_API_KEY 等），键名被归一化为短名（如 scrapecreators、xai）；
• x_method：X/Twitter 的可用认证方式，判定顺序是 XAI_API_KEY → xai、AUTH_TOKEN + CT0 → cookies，否则为 None。

值得注意：run_openclaw_setup() 是无 Cookie 的探测——注释明确写着 "no cookies, tool + key availability"，它只回答"哪些键在、哪些工具在"，把呈现与决策留给宿主模型。

3.2 按优先级补齐四个缺失项

文档随后定义了固定优先级，Agent 逐项询问/处理缺失的配置：

1. ScrapeCreators（未配置时）：话术要点是"增加 TikTok 和 Instagram 搜索（并在公共 Reddit 被限流时充当 Reddit 备份），10,000 次免费调用、无需信用卡、无返利无分成"。提供三个选项：
   • Option A — via GitHub（推荐）：若前面探测到 gh CLI，文案改为"通过 GitHub CLI 直接注册，约 2 秒、无需浏览器"；若没有 gh，则走设备流："我会把一个一次性代码复制到剪贴板并打开 GitHub 授权页"。随后执行 python3 "${SKILL_ROOT}/scripts/last30days.py" setup --github，解析 JSON：先试 PAT（依赖 gh 安装），失败则退回设备流。status 为 success 时把 SCRAPECREATORS_API_KEY={api_key} 写入 .env。
   • Option B — "I have a key"：接受粘贴，写入 .env。
   • Option C — Skip for now。
2. X/Twitter（未配置时）：话术列出三条解锁路径——FROM_BROWSER=auto（读浏览器 Cookie，免费）、XAI_API_KEY（无需浏览器，走 api.x.ai）、AUTH_TOKEN+CT0（手动 Cookie）。选项：A=填写 xAI API key（服务器场景推荐，持久、不过期），B=粘贴 AUTH_TOKEN + CT0，C=跳过。
3. YouTube（未发现 yt-dlp 时）：提示运行 pip install yt-dlp。
4. Web search（无 Brave/Exa/Serper key 时）：说明"Web 搜索 key 能带来更聪明的结果；Brave Search 免费额度为每月 2,000 次查询"。

完成上述配置后，向导最后写入 SETUP_COMPLETE=true 到 .env，再进入研究阶段。OpenClaw 支在写完后就跳到 "END OF FIRST-RUN WIZARD"，不重复模态流程。

---

四、Claude Code Setup Flow：六步模态引导

有交互模态的宿主（Claude Code）走的是更"产品化"的引导序列。v3.0.0 文档强制规定顺序：

(1) welcome text → (2) setup modal → (3) run setup if chosen → (4) optional ScrapeCreators modal → (5) topic picker

并且要求"必须从步骤 1 开始，不得跳到主题选择器或研究"。

4.1 Step 1：一次性欢迎文本

欢迎文本以普通消息（非引用块）展示一次，随后立即调用 AskUserQuestion，且欢迎语不得重复出现在弹窗内：

Welcome to /last30days!

I research any topic across Reddit, X, YouTube, and other sources - synthesizing what people are actually saying right now.

Auto setup gives you 5 core sources for free in 30 seconds:
- X/Twitter - reads your x.com browser cookies to authenticate (not saved to disk). Chrome on macOS will prompt for Keychain access.
- Reddit with comments - public JSON, no API key needed
- YouTube search + transcripts - installs yt-dlp (open source, 190K+ GitHub stars)
- Hacker News + Polymarket + GitHub (if `gh` CLI installed) - always on, zero config

Want TikTok and Instagram too? ScrapeCreators adds those (10,000 free calls). No kickbacks, no affiliation.

说明：欢迎文案中的 "190K+ GitHub stars" 与 "10,000 free calls" 是该项目向导内置的对外宣传口径（在 setup_wizard.py 的 _WELCOME_TEXT 常量中同样存在），此处仅作向导文本转述。

4.2 Step 2：三选一设置模态

AskUserQuestion 的问题与选项被严格限定：

• Question: "How would you like to set up?"
• Option 1: "Auto setup (~30 seconds) - scans browser cookies for X + installs yt-dlp for YouTube"
• Option 2: "Manual setup - show me what to configure"
• Option 3: "Skip for now - Reddit (with comments), HN, Polymarket, GitHub (if gh installed), Web"

4.3 选 Auto setup：先拿 Cookie 同意

v3.0.0 在此引入一个关键隐私护栏：在执行任何 Cookie 读取之前，必须先检查 ~/.config/last30days/.env 里是否已有 BROWSER_CONSENT=true；没有则再弹一次 AskUserQuestion，让用户明确选择是否允许扫描浏览器中的 x.com Cookie（强调"Cookie 实时读取、不落盘、macOS 的 Chrome 会触发一次 Keychain 授权"）。三个选项对应三种行为：

• "Yes, scan my cookies for X" → 正常跑 setup，结束后向 .env 追加 BROWSER_CONSENT=true；
• "Skip X, just set up YouTube" → 只装 yt-dlp，不做 Cookie 扫描；
• "I have an xAI API key instead" → 粘贴 XAI_API_KEY 写入 .env，再装 yt-dlp。

同意后执行（当前版本命令已随 SKILL_DIR 约定演进为以 skill 根目录为基准的调用）：

cd {SKILL_DIR} && python3 scripts/last30days.py setup

并向用户展示执行结果（找到了哪些 Cookie、是否装好 yt-dlp）。

4.4 ScrapeCreators 模态与 GitHub 双态授权

Auto setup 完成后，向导用纯文本展示一次、再弹一次模态来提供 ScrapeCreators。弹窗前先静默执行 which gh 判定 gh_available，据此改变选项描述：

• 若 gh 可用 → "Registers directly via GitHub CLI in ~2 seconds - no browser needed"；
• 若 gh 不可用 → "Copies a one-time code to your clipboard and opens GitHub to authorize"。

选中该选项后执行 cd {SKILL_DIR} && python3 scripts/last30days.py setup --github（v3.0.0 是带 5 分钟超时的单条命令）。文档给出了精确的结果文案矩阵：

status / method	话术要点
success + method=pat	"You're in! Registered via GitHub CLI - zero browser needed. 10,000 free calls…"
success + method=device + clipboard_ok=true	"You're in! (The authorization code was copied to your clipboard automatically.)…"
success + method=device + clipboard_ok=false	"You're in! 10,000 free calls…"
timeout / error	"GitHub auth didn't complete. No worries - you can sign up at scrapecreators.com instead or try again later."

这一 --github 单命令流程在源码侧对应 setup_wizard.py 的 run_github_auth()，其背后是完整的 GitHub Device Flow 实现（_DEVICE_BASE 指向 https://api.scrapecreators.com/v1/github/device）：run_device_auth() 请求 /device/code 拿到 device_code/user_code/verification_uri/interval，随后 poll_device_auth() 轮询授权，成功后 fetch_api_key() 换取 SCRAPECREATORS_API_KEY。源码甚至用正则 ^[0-9A-Z]{4}-[0-9A-Z]{4}$ 校验设备码，防止畸形或 key 形字符串被误标为设备码泄漏到 stdout/剪贴板。当前的 SKILL.md 第 606-616 行已把它升级为两命令流程：setup --github-start（前台，约 1-2 秒返回 code + JSON，复制到剪贴板）→ setup --github-poll（后台，5 分钟超时），并明确"成功时引擎自动持久化 key、API key 以掩码形式返回、永不回显原始值"——这与 setup_wizard.py mask_api_key()（第 633-641 行，输出形如 sc_…xxxx）以及 write_api_key() 的幂等写入语义完全对应。

4.5 源开关与首个研究主题

ScrapeCreators key 保存成功后（跳过则无此步），向导让用户选择开哪些源：

• "TikTok + Instagram (recommended)" → 追加 INCLUDE_SOURCES=tiktok,instagram；
• "Everything - TikTok, Instagram, Threads, Pinterest, YouTube comments" → 追加 INCLUDE_SOURCES=tiktok,instagram,threads,pinterest,youtube_comments；
• "Just the basics" → 不写 flag（ScrapeCreators 仅作 Reddit 备份）。

最后是 first research topic picker，提供 Claude Code vs Codex（技术对比）、Sam Altman（新闻人物）、Warriors Basketball（体育）、AI Legal Prompting Techniques（垂直/专业）、Type my own topic 五个例子；若用户在命令里已带主题（如 /last30days Mercer Island）则跳过此选择器直接研究。

---

五、Manual setup 手册：.env 完整键位清单

这是 v3.0.0 向导中信息密度最高、最值得按图索骥的部分。选 "Manual setup" 后 Agent 以纯文本展示完整配置手册。下表将手册中所有键位、来源与用途完整归档（键名与文案均取自原文档）：

X/Twitter（三选一，文档称"最重要"）

键	说明	备注
FROM_BROWSER=auto	搜索时读取 x.com 登录 Cookie 完成认证，免费	Cookie 每次实时读取、不落盘；macOS Chrome 首次会弹 Keychain；Firefox/Safari 不弹
XAI_API_KEY=xxx	无需浏览器访问，在 api.x.ai 申请	最适合服务器或无 Cookie 扫描意愿的场景
AUTH_TOKEN=xxx + CT0=xxx	手动粘贴 X Cookie	获取路径：x.com → F12 → Application → Cookies

Reddit（免费、开箱即用）

键	说明
（无）	Public JSON 即可取到帖子 + 带赞数的 top comments，无需配置
SCRAPECREATORS_API_KEY=xxx	可选：公共 Reddit 被限流时的备份源
OPENAI_API_KEY=xxx	可选：公共 Reddit 搜索找不到帖子时的兜底

YouTube（免费、开源）

命令/键	说明
brew install yt-dlp	安装后开启 YouTube 搜索与字幕/transcript

Bonus：TikTok/Instagram/Threads/Pinterest/YouTube 评论（ScrapeCreators）

键	说明
SCRAPECREATORS_API_KEY=xxx	10,000 次免费调用
INCLUDE_SOURCES=tiktok,instagram	开启最热门的两个；可追加 threads,pinterest,youtube_comments

GitHub Issues/PRs（免费、免 key）

条件	说明
安装 gh CLI（brew install gh）	GitHub 搜索自动启用，无需 API key

Perplexity Sonar Pro（经 OpenRouter 的 AI 合成研究）

键/flag	说明
OPENROUTER_API_KEY=xxx	把"带引用的 AI 合成研究"作为 Reddit/X/YouTube 之外的增量源加入
INCLUDE_SOURCES=perplexity	启用（可追加进已有列表，如 tiktok,instagram,perplexity）
--deep-research	对需要深挖的主题生成 50+ 引用的详尽报告
附带收益	若没有 Gemini/OpenAI/xAI key，它同时驱动规划与重排引擎

额度说明：上表中 "~$0.02/run"、"~$0.90/query"、"50+ citation"、"10,000 free calls"、"2,000 queries/month" 等均为向导内置话术给出的额度参考，来自 v3.0.0 文档原文，不代表当前服务的实时报价。

其他随时可加的源

键	说明
EXA_API_KEY=xxx	语义 Web 搜索，每月 1K 免费
BSKY_HANDLE=you.bsky.social + BSKY_APP_PASSWORD=xxx	Bluesky（免费 app password）
BRAVE_API_KEY=xxx	Brave Web 搜索

收尾标记

手册要求永远在文件最后加一行：SETUP_COMPLETE=true。

在源码里，真正落盘执行"追加不覆盖"逻辑的是 setup_wizard.py 的 write_setup_config()（第 531 行起）：它先读取已存在的 key 集合，仅当 SETUP_COMPLETE 缺失时才追加，且把 FROM_BROWSER 的持久化限定为"实际取到 Cookie 的那个浏览器"（避免持久化 auto 导致后续每次运行都去探测 Chrome、重复触发 Keychain 弹窗）；write_api_key()（第 587 行起）则保证同名 key 已存在时直接返回、绝不重复写入。两个函数都经由 _open_secret_append 以 0o600 权限追加写入（源码注释："the .env holds tokens and keys, so it must never be created world-readable"）。

"Open .env in editor" 选项

Manual setup 之后还有一个小模态 "How do you want to add your keys?"，三个选项分别是 "Open .env in my editor"（先建带注释模板的文件并打开编辑）、"Paste keys here"（粘贴 key 由 Agent 写入）、"I'll do it myself"（只告诉路径）。"editor" 分支要求 Agent 创建预填充模板的 .env。

---

六、.env 安全写入规则：CRITICAL 级别的四条铁律

v3.0.0 对写 .env 有绝不覆盖的强制要求（文档原话标注为 CRITICAL，适用于写入任何 key 之前）：

1. 先检查文件是否存在：test -f ~/.config/last30days/.env
2. 若存在，先 READ，然后只追加缺失的 key：使用 >>（双重重定向）
3. 绝不使用 >（单重重定向会摧毁既有内容）
4. 若不存在，先建目录与空文件：mkdir -p ~/.config/last30days && touch ~/.config/last30days/.env

这条约束的工程意义在源码中被进一步强化：除了 append-only，setup_wizard.py 还保证了 key 级幂等（已有同名 key 则不写）与 0o600 文件权限。从仓库测试看，这套契约是可验证的：tests/test_setup_wizard.py 与 tests/test_onboarding_contract.py 覆盖向导状态机与首次运行契约，另有 test_secret_hygiene.py、test_check_config_env_safety.py 等持续校验密钥卫生与配置安全。

---

七、命令分发在源码中的落点

向导中的 setup 命令最终都汇入 CLI 主入口 last30days.py：

• 第 2635-2641 行附近：topic.lower() == "setup" 时进入 setup 子命令逻辑，并按额外参数分派——--openclaw 走 run_openclaw_setup()（见第 3019-3021 行），--github / --device-auth / --github-start / --github-poll 分别走 run_github_auth() / run_full_device_auth() / run_github_start() / run_github_poll()；
• 无以上子 flag 时进入 run_auto_setup()（allow_browser_cookies 由是否带 --allow-browser-cookies 决定，第 3051-3054 行），完成后调用 write_setup_config() 写 SETUP_COMPLETE（第 3071 行），并向 stderr 输出 get_setup_status_text() 汇总；
• --preflight 则输出一份"安全的、人类可读的权限预检"（第 727-728、2974-2989 行），供 Non-Modal 流程在动浏览器/Cookie 之前向用户汇报"将要写什么、将调用什么可选命令"。

run_auto_setup() 内部（setup_wizard.py 第 64 行起）在拿到显式同意后才遍历 env.cookie_extraction_browsers() 所列浏览器，按域名规范逐源提取 Cookie，并把"找到 Cookie 的浏览器"回传给调用方；随后探测/安装 yt-dlp 与 Digg CLI，最终返回含 cookies_found、ytdlp_action、digg_action 等键的结构化结果。整个设计把"对话式同意"留给宿主模型（模型是唯一能问用户的主体），把"机械动作"下沉到非交互子进程——这也是 SKILL.md 第 541 行"You are the conversational driver"原则的由来。

---

八、从 v3.0.0 到当前：六步模态如何被"找回"

这份快照之所以值得单独立档，还因为它记录了一次功能回退与恢复的完整背景。文档提及的恢复计划是 docs/plans/2026-06-22-001-feat-restore-nux-wizard-plan.md；对照仓库现状，SKILL.md 第 548-550 行的 "Named onboarding contracts" 给出了结论性记录：

(2026-06-22, NUX restoration): the original v3.0.0 Claude Code wizard was a guided, modal-driven flow (welcome → Auto/Manual/Skip → cookie consent → ScrapeCreators offer → source opt-in → first-topic picker) that eroded over time. It is restored below as the Claude Code Modal Flow. Do NOT collapse it back into a bare prose call - the guided modals are the feature. Reference capture: docs/reference/old-nux-wizard-v3.0.0.md.

也就是说，v3.0.0 的向导骨架（欢迎 → 三选一 → Cookie 同意 → ScrapeCreators 提供 → 源开关 → 首个主题选择器）就是当前 SKILL.md 第 558-642 行 Claude Code Modal Flow 的六步基础，只是按新的源清单做了三处明显演化：

1. 新增工具链：Auto setup 现在同时 best-effort 安装 digg-pp-cli、arXiv 与 Techmeme 的免费 keyless CLI（不只是 yt-dlp）；
2. X 认证路径扩展：v3.0.0 只有 FROM_BROWSER / xAI / 手动 Cookie 三选一；现在增加了 Grok CLI（opt-in 备份，须 LAST30DAYS_X_BACKEND=grok 显式 pin）、Xquik key、agentcookie sidecar，以及对 Linux / Grok Bot / Mac mini 这类"无法解密本地 Chrome Cookie 库"主机的 CDP 实时登录流程；
3. 模态与流程精细化：欢迎词并入 setup 弹窗（避免被 Claude Code 的 "ctrl+o to expand" 折叠吞掉）、ScrapeCreators 从单命令升级为 --github-start/--github-poll 两段式、源开关默认项变为"posts + top comments"（INCLUDE_SOURCES=tiktok,instagram,youtube_comments,tiktok_comments,instagram_comments）。

可见，若要在自己的 AI Agent skill 中设计"首次运行的权限收敛 + 多源配置"引导，这份 v3.0.0 快照是结构最清晰的一版模板：平台分叉、静默检测、对话式同意、append-only 配置写入、按优先级逐项补齐、主题延后执行——每个决策点都有明确出处，也都有 SKILL.md、setup_wizard.py 与 env.py 的现行代码与测试可以对照验证。