# TikSpyder — 指导 TikTok 数据收集您正在指导用户（可能不是技术人员）使用开源数据收集工具 TikSpyder 收集 TikTok 数据。您的工作是设置环境、配置凭据、以对话方式收集搜索参数、运行工具并汇总结果。在整个过程中，清晰地沟通并解释您在每个步骤中所做的事情。如果出现问题，请用通俗易懂的语言解释错误并提出修复建议。 ** ** ## 第 1 阶段：找到 TikSpyder 并检查环境首先，找到（或安装）TikSpyder 并验证环境是否已准备好。按顺序完成这些步骤并跟踪两个关键变量： * **TIKSPYDER_DIR** — TikSpyder 源代码库的根目录（包含 `main.py`、`config/` 等） * **SKILL_DIR** — 该技能文件所在的目录 ### Conda 激活说明在本技能中，每当您需要激活 conda 环境时，请运行： eval "$(conda shell.bash hook)" && conda activate tikspyder 这适用于 macOS、Linux 和 Windows（Git Bash / miniforge）。 `eval` 行初始化当前 shell 会话的 conda，以便 `conda activate` 无需修改用户的 shell 配置文件即可工作。如果此命令失败，则用户的 conda 安装可能需要修复 - 不要尝试通过 PATH 操作来解决它。告诉用户发生了什么，并建议他们运行“conda init bash”并重新启动终端。 ### 1.0 检查缓存环境（快速路径）成功运行后，技能会将环境详细信息保存到技能目录中的“.tikspyder-env.json”中。如果此文件存在，请阅读它 - 它包含跳过大部分阶段 1 所需的所有内容：对于 .claude/skills/tikspyder 中的候选人“$HOME/.claude/skills/tikspyder”；做 if [ -f "$candidate/.tikspyder-env.json" ];那么猫“$candidate/.tikspyder-env.json” 打破菲完成如果文件存在并且包含有效数据，则直接使用缓存的值： * 从缓存数据中设置SKILL_DIR、TIKSPYDER_DIR、env_type和ffmpeg状态 * 使用缓存的`env_type`激活环境：如果是conda，则使用标准的conda激活命令；如果是 venv，则获取激活脚本 * 进行快速健全性检查：验证 TIKSPYDER_DIR 仍然存在并且“tikspyder --help”在激活后有效 * 如果健全性检查通过，则跳至 **阶段 1.7**（显示摘要，但您可以简短，因为用户之前已经看过它 - 只需确认并继续） * 如果健全性检查失败（例如，目录被移动或 env 被删除），则删除缓存文件并进入完整的阶段 1 这可以节省重复运行的大量时间——无需搜索环境，也无需列出 conda env。 ### 1.1 找到技能目录技能目录包含此 SKILL.md 文件。在标准位置搜索它：对于 .claude/skills/tikspyder 中的候选人“$HOME/.claude/skills/tikspyder”；做 if [ -f "$candidate/SKILL.md" ];那么 echo "SKILL_DIR=$候选人" 打破菲完成将其存储为 SKILL_DIR 以供以后使用。 ### 1.2 检查 tikspyder 是否已经安装按顺序尝试这些检查。停在第一个有效的地方。 **步骤 A — 检查当前环境：** 点显示 tikspyder 2>&1 如果找到，请提取“Location：”并验证“main.py”是否存在。相应地设置 TIKSPYDER_DIR。 **步骤 B — 检查名为“tikspyder”的 conda/mamba 环境：** conda 环境列表 2>/dev/null | grep tikspyder 如果存在 `tikspyder` 环境，请激活它（使用上面的 conda 模式）并再次运行 `pip show tikspyder`。如果找到，请使用该环境执行所有后续命令。 **步骤 C — 使用 tikspyder 检查现有的 venv：** 在用户可能已克隆并安装 tikspyder 的常见位置查找 venv：对于“$SKILL_DIR/tik-spyder”中的候选人“$HOME/tik-spyder”“./tik-spyder”；做对于“.venv”中的 venv_dir “venv”；做 activate_script="$candidate/$venv_dir/bin/activate" # 在 Windows (Git Bash) 上，激活脚本位于 Scripts/ [！ -f "$activate_script" ] && activate_script="$candidate/$venv_dir/Scripts/activate" 如果[-f“$activate_script”];那么 echo "在 $candidate/$venv_dir 找到 venv" 休息2 菲完成完成如果找到，请使用“source "$activate_script"”激活 venv，然后运行“pip show tikspyder”。如果安装了 tikspyder，请将 TIKSPYDER_DIR 设置为该候选目录，并使用此 venv 执行所有后续命令。 **步骤 D — 检查存储库是否已克隆到技能目录中（没有环境）：** ls "$SKILL_DIR/tik-spyder/main.py" 2>/dev/null 如果找到，请设置“TIKSPYDER_DIR=$SKILL_DIR/tik-spyder”。该环境将在阶段 1.5 中创建。 ### 1.3 如果需要的话下载并安装如果上述任何检查都没有找到 TikSpyder，请从 GitHub 下载官方存储库到技能目录中： cd“$SKILL_DIR” git 克隆 https://github.com/estebanpdl/tik-spyder.git 然后设置`TIKSPYDER_DIR=$SKILL_DIR/tik-spyder`。 ### 1.4 Python 版本 python --版本 2>&1 || python3 --版本 2>&1 TikSpyder 需要 Python 3.11 或更高版本。如果版本太旧，请告诉用户并停止。 ### 1.5 创建环境并安装（仅当1.2中未找到tikspyder时）如果 tikspyder 已安装（在步骤 A、B 或 C 中找到），请完全跳过此步骤。否则，创建环境并安装。首先检查conda/mamba是否可用： conda --版本 2>/dev/null ||曼巴 --版本 2>/dev/null **如果 conda/mamba 可用**，创建一个专用环境，激活它（使用 conda 模式），并使用 TIKSPYDER_DIR 内的 `pip install -e .` 从克隆存储库安装 TikSpyder。 **如果 conda/mamba 不可用**，请使用 Python 内置的 venv： cd“$TIKSPYDER_DIR” python -m venv .venv 激活 — 路径因平台而异： * **Windows (Git Bash):** `源 "$TIKSPYDER_DIR/.venv/Scripts/activate"` * **macOS / Linux:** `源 "$TIKSPYDER_DIR/.venv/bin/activate"` 然后在 TIKSPYDER_DIR 中使用 `pip install -e .` 进行安装。无论创建哪种环境类型，都验证它是否有效： tikspyder --帮助告诉用户设置了哪种环境类型（conda 或 venv），以便他们知道以供将来参考。 ### 1.6 检查 ffmpeg ffmpeg -版本 2>&1 |头-1 音频提取和关键帧提取需要ffmpeg。如果丢失，请清楚地告诉用户他们将失去什么并询问是否继续： * “未安装 ffmpeg。没有它，TikSpyder 仍然可以下载视频并收集元数据，但音频提取和关键帧提取将被跳过。您可以从安装它。您想不使用 ffmpeg 继续，还是先安装它？” 如果用户想在不使用 ffmpeg 的情况下继续，那很好 - 只需记住第 4 阶段的这一点，这样您就不会因输出中的“没有这样的文件或目录：'ffmpeg'”错误而感到惊讶（它们是预期的且无害的）。 ### 1.7 摘要和准备情况检查（在继续之前先停在这里）在进入第 2 阶段之前，提供准备情况报告并等待用户确认。在用户同意之前不要继续。这可以防止浪费 API 积分或在损坏的环境中运行命令。显示类似：环境准备： -Python：3.12（好的） - TikSpyder：已安装 v0.1.0（conda env：tikspyder） - ffmpeg：未安装（音频提取和关键帧将被跳过）准备好继续 API 密钥设置了吗？如果缺少任何关键要求（Python 太旧、tikspyder 无法安装），请在此停止并帮助用户修复它。如果仅缺少 ffmpeg，用户可以选择继续 - 但他们必须明确确认。 ** ** ## 第 2 阶段：API 密钥配置 TikSpyder 使用两个外部 API： * **SerpAPI** — 支持基于 Google 的 TikTok 搜索（Google 搜索结果 + Google 图片缩略图） * **Apify** — 支持直接 TikTok 个人资料和主题标签数据收集 **重要提示：** TikSpyder 在所有模式下运行 SerpAPI 调用 - 即使是 `--user` 和 `--tag` 模式也会在 Apify 步骤之前触发 Google 搜索和 Google Images 调用。如果没有有效的 SerpAPI 密钥，这些调用将失败并出现 401 错误。 Apify 步骤仍然有效，但数据收集将不完整。为了获得最佳结果，无论用户计划使用哪种搜索模式，都请配置这两个键。 ### 2.1 检查现有密钥使用读取工具读取“$TIKSPYDER_DIR/config/config.ini”处的配置文件。检查“api_key”和“apify_token”是否包含真实凭证。 **如果出现以下情况，密钥无效：** * 为空或空格 * 包含单词“your”（例如“your_serp_api_key”、“your_apify_token”） * 字面意思是“”或“” * 少于 20 个字符（真正的 API 密钥更长） **安全规则：** * 切勿向用户打印、显示或回显 API 密钥 * 报告状态时，请说“SerpAPI 密钥：已配置”或“Apify 令牌：未配置”——从不显示实际值 * 将密钥写入配置文件时，直接使用写入工具 - 不要在 bash 中使用 echo/cat，因为密钥会出现在命令中 ### 2.2 询问丢失的钥匙如果任一密钥无效，请询问用户。立即询问所有丢失的钥匙 - 不要只询问一个，然后在执行过程中发现另一个丢失。解释一下每个 API 的用途： *“**SerpAPI 密钥** - 这可以让 TikSpyder 在 Google 中搜索 TikTok 内容。您可以在获取一个（他们有免费套餐）。” * “**Apify 令牌** — 这可以让 TikSpyder 直接收集 TikTok 个人资料和主题标签。您可以在获取一个（他们有免费套餐）。用户个人资料和主题标签搜索所需。” 如果用户只能提供一个密钥，那也没关系——解释一下什么可以用，什么不能用： * 仅 SerpAPI：关键字搜索完全有效；用户/主题标签模式将失败 * 仅 Apify：用户/主题标签收集有效，但 Google 搜索/图像步骤将显示 401 错误（通过 Apify 数据收集仍然成功，只是结果不完整） ### 2.3 保存密钥使用以下确切格式将配置文件写入“$TIKSPYDER_DIR/config/config.ini”： [SerpAPI 密钥] api_key = [Apify代币] apify_token = 如果用户仅提供两者之一，则保留任何现有的有效密钥。 ** ** ## 第 3 阶段：收集搜索参数询问用户他们想要收集什么。使用 AskUserQuestion 使其成为对话式的。这是决策树： ### 3.1 搜索模式（必填）问：“你想搜索什么？” 模式| CLI 标志 |注释 ---|---|--- 关键词搜索 | `--q "术语"` |在 Google 中搜索与该字词匹配的 TikTok 结果用户简介 | `--用户用户名` |收集特定 TikTok 用户的视频（需要“--apify”）标签 | `--tag 标签` |收集具有特定主题标签的视频（需要“--apify”）如果用户选择用户或主题标签模式，则自动需要“--apify”标志——无需询问即可添加它。还要验证是否为所选模式配置了所需的 API 密钥。如果用户选择关键字搜索但 SerpAPI 密钥丢失，请返回到第 2 阶段。对于具有用户/主题标签模式的 Apify 也是如此。 ### 3.2 附加参数了解搜索模式后，询问这些选项。您不需要询问每一个问题 - 根据用户的目标进行判断。提出最相关的选项： **对于关键字搜索：** * 国家/地区（`--gl`，例如，`us`、`gb`、`mx`）—“Google 应该从哪个国家/地区进行搜索？” * 语言（`--hl`，例如，`en`、`es`、`fr`）—“什么语言？” * 日期范围（`--after` / `--before`，格式 YYYY-MM-DD）—“想要限制在特定日期范围内？” * 搜索深度（`--深度`，默认 3）—“相关内容搜索应该有多深？默认为 3 级。” **对于用户/主题标签搜索 (Apify)：** * 日期过滤器（`--oldest-post-date` / `--newest-post-date`，格式 YYYY-MM-DD） * 结果数（`--number-of-results`，默认 25） **对于所有模式：** * 下载视频？ (`--download`) — “您想下载实际的视频文件吗？” * 输出目录 (`--output`) — “我应该在哪里保存结果？默认在 `./tikspyder-data/` 中创建一个带时间戳的文件夹。” * 工作线程 (`--max-workers`) — 仅在用户看起来技术性强或询问速度时才提及。下载默认值为 5，关键帧默认为 3。 ### 3.3 日期同步（关键） TikSpyder 使用 **两个独立的日期过滤系统** 独立运行： * **SerpAPI 日期** (`--after` / `--before`) — 过滤 Google 搜索结果 * **Apify 日期** (`--oldest-post-date` / `--newest-post-date`) — 过滤 Apify 结果当用户指定任何日期范围时，您必须为两个系统设置相应的标志。否则，一个 API 返回过滤后的结果，而另一个 API 返回所有内容，混合日期过滤和未过滤的数据。 **映射：** 用户说 | SerpAPI 标志 |阿皮皮旗 ---|---|--- “[日期]之后”/“自[日期]”/“自[日期]”| `--[日期]之后` | `--最旧的发布日期 [日期]` “[日期]之前”/“直到[日期]”| `--[日期] 之前` | `--最新发布日期 [日期]` **示例：** 如果用户说“2026 年 1 月之后的视频”，则该命令需要两者： --2026-01-01 之后 --最旧的发布日期 2026-01-01 这适用于所有搜索模式——关键字、用户和主题标签。 ### 3.4 运行前确认在执行之前，向用户展示将要发生的情况的简单语言摘要：这是我要运行的： - 搜索：关键字“选举错误信息” - 国家：美国，语言：英语 - 日期范围：2025年1月1日之后 - 下载视频：是 - 输出：./tikspyder-data/1234567890/ 在继续之前要求确认。 ** ** ## 第 4 阶段：执行 ### 4.1 如果需要激活环境重新激活在第 1 阶段发现/创建的相同环境。如果使用 conda，请使用本文档顶部的 conda 激活模式。如果使用 venv，请获取激活脚本（Windows：`.venv/Scripts/activate`，macOS/Linux：`.venv/bin/activate`）。 ### 4.2 构建并运行命令根据收集的参数构建 tikspyder CLI 命令。始终先“cd”到 TIKSPYDER_DIR，以便正确找到配置文件。命令示例： # 使用日期过滤器进行关键字搜索 cd "$TIKSPYDER_DIR" && tikspyder --q "搜索词" --gl us --hl en \ --2025-01-01之后 --2025-06-01之前 --output ./data/ --download # 带有日期过滤器的用户个人资料（注意：BOTH --after AND --oldest-post-date） cd "$TIKSPYDER_DIR" && tikspyder --user 用户名 --apify \ --2025-01-01 之后 --oldest-post-date 2025-01-01 --output ./data/ # 带日期过滤器的标签 cd "$TIKSPYDER_DIR" && tikspyder --tag hashtag --apify \ --2025-01-01 之后 --oldest-post-date 2025-01-01 \ --结果数 50 --output ./data/ --download 如果需要，请记住在“cd”之前添加 conda 或 venv 激活。运行命令并让用户看到输出。请使用较长的超时时间（最多 10 分钟），因为数据收集可能需要一段时间，具体取决于搜索范围。 ### 4.3 错误处理即使数据已部分收集，该命令也可能会错误退出。在得出运行失败结论之前检查输出目录 - 部分成功是常见的。 **预期噪音（不是错误）：** 输出|说明 ---|--- `提取音频时出错：没有这样的文件或目录：'ffmpeg'` |未安装 ffmpeg — 仍会下载视频，仅跳过音频提取。如果用户在第 1 阶段选择不使用 ffmpeg 继续，则无害。 **需要采取措施的错误：** 错误 |可能的原因 |修复 ---|---|--- `ValueError：必须提供 --user、--q 或 --tag` |缺少搜索词 |询问他们想要搜索什么来自 serpapi.com 的“401 客户端错误：未经授权”| SerpAPI 密钥无效或仍然是占位符 |这不应该发生——这意味着第 2 阶段未能检测到无效密钥。询问用户正确的密钥，保存并重新运行。查看第 2.1 阶段验证规则以了解出了什么问题。 `sql_manager.py` 中的 `IndexError: 列表索引超出范围` | SerpAPI 没有返回任何数据，导致 SQL 数据库为空 |这是 SerpAPI 密钥错误的下游症状。与上面相同的修复。 `ApifyApiError：未找到用户或身份验证令牌无效` |错误的 Apify 令牌 |要求用户在检查他们的令牌带有 asyncio 的 `RuntimeError`事件循环冲突 |运行 `cd "$TIKSPYDER_DIR" && git pull` 以获取最新修复连接/超时错误 |网络问题 |建议检查互联网连接，或尝试较少的结果 ### 4.4 运行后总结命令完成后，检查输出目录并总结收集的内容：查找 <输出目录> -type f |头-50 ls -la <输出目录>/*.csv 2>/dev/null ls <输出目录>/downloaded_videos/ 2>/dev/null |厕所-l ls <输出目录>/keyframes/ 2>/dev/null |厕所-l du -sh <输出目录> 向用户报告： * 生成的 CSV 数据文件数量 * 下载的视频数量（如果适用） * 提取的关键帧数量（如果适用） * 输出目录的总大小 * 可在 Excel 或 Google Sheets 中打开的主 CSV 文件的路径 ### 4.5 保存环境缓存（运行成功后）成功运行后（收集数据，输出目录有文件），保存已解析的环境详细信息，以便下一个会话可以跳过第 1 阶段发现。在“$SKILL_DIR/.tikspyder-env.json”处写入 JSON 文件： { "tikspyder_dir": "/绝对/路径/到/tik-spyder", "skill_dir": "/绝对/路径/到/skill/目录", “env_type”：“康达”， "env_name": "tikspyder", “python_version”：“3.12.1”， “ffmpeg_available”：假， “api_keys_configured”：正确， “last_successful_run”：“2026-02-27” } * `env_type` 应该是 `"conda"` 或 `"venv"` * `env_name` 是 conda 环境名称（仅与 conda 相关） * 使用绝对路径，这样无论工作目录如何，缓存都可以工作 * 仅在确认成功运行后才写入此文件 - 绝不在出现错误后写入如果文件已存在，请更新它（路径或 ffmpeg 状态可能已更改）。 ** ** ## 第 5 阶段：Streamlit 应用程序（替代）如果用户表示他们更喜欢可视化界面，或者他们似乎对参数不确定并且可能会从 UI 中受益，则可以主动提出启动 Streamlit Web 应用程序。确保在启动之前配置环境和 API 密钥（阶段 1-2）。激活环境（conda或venv，与阶段4相同），然后运行： cd "$TIKSPYDER_DIR" && tikspyder --app 这将在“http://localhost:8501”启动本地 Web 服务器。告诉用户： *“我已经启动了 TikSpyder 网络界面。它应该在您的浏览器中打开 ” *“网络界面可让您配置搜索、设置下载选项并直观地跟踪进度” *“当你完成后，回来告诉我——我会停止服务器” Streamlit 应用程序作为阻塞进程运行。要在运行时保持对话继续进行，请使用“run_in_background”在后台启动它。当用户完成后，找到并停止监听端口 8501 的进程。 ** ** ## 快速参考：完整 CLI 标志旗帜|类型 |描述 ---|---|--- `--q` |字符串|搜索关键词/短语 `--用户` |字符串|抖音用户名 `--标签` |字符串| TikTok 标签 `--gl` |字符串|国家/地区代码（例如“us”） `--hl` |字符串|语言代码（例如“en”） `--cr` |字符串|多国家过滤器 `--lr` |字符串|多语言过滤器 `--安全` |字符串|成人内容过滤器：“活动”（默认）或“关闭” `--google-domain` |字符串| Google 域（默认：`google.com`） `--深度` |整数 |相关内容深度（默认：3） `--之前` |字符串|日期上限 (YYYY-MM-DD) `--之后` |字符串|日期下限 (YYYY-MM-DD) `--apify` |旗帜|启用 Apify 集成 `--最早的发布日期` |字符串| Apify：最早的发布日期 (YYYY-MM-DD) `--最新发布日期` |字符串| Apify：最新发布日期 (YYYY-MM-DD) `--结果数量` |整数 | Apify：最大结果（默认值：25） `-d, --download` |旗帜|下载视频文件 `-w, --max-workers` |整数 |下载线程数 `-o, --output` |字符串|输出目录路径 `--app` |旗帜|启动 Streamlit Web UI

蜱矛

包含技能