brandbai7 BrandBAI 抖音作品与商品资料采集
把公开抖音账号或明确作品整理为可回溯的素材、数据和作品评论；单条挂车作品可按要求连同关联商品资料与商品评价一并整理。商品评价与作品评论分开保存。这里只完成采集和质量核验，语义分析、商品匹配与商业结论属于后续任务。
先确认授权范围
只在 PolyForm Noncommercial License 1.0.0 允许的非商业范围内运行本 Skill。企业内部使用、客户交付、收费服务、插件、SaaS、数据服务或其他预期商业用途必须先通过 brandlaobai@163.com 取得 BrandBAI 书面商业授权。安装源码不等于取得商业试用或平台数据授权。
路由下载任务
先把自然语言需求整理为以下四项，再选择运行模式：
- 下载目标：达人、KOC、KOL、明星艺人等公开账号主页，或一个以上明确作品 URL。
- 作品范围：单作品、明确作品列表、插件作品清单、搜索页当前选择，或主页全部当前可见置顶作品加最近 N 条非置顶作品。
- 下载内容：作品清单与基础数据、视频或图文、封面、可用原声、发布文案；可选作品一级评论、当前商品卡公开资料与图片、独立商品评价。实验性作品二级回复须另外明确要求。
- 交付预设：普通下载版，或保留全部原始数据和完整性状态的分析准备版。
当前统一入口提供三个运行模式：
works：下载主页所选作品的基础数据、视频或全部图文、封面和可用原声。comments：下载明确作品或works.json对应作品的可检索评论。all：依次完成works、comments和普通版交付。
单作品包会在 01_作品清单.xlsx 增加“达人快照”，仅记录当前作品页已经展示或加载的昵称、抖音号、稳定达人 ID、主页链接、简介、粉丝数和累计获赞。页面未展示的字段留空，不补 0；不为补字段自动进入达人主页，也不下载头像。
同一个明确单作品任务还会观察当前详情页公开可见的小黄车入口：只通过播放器商品控件的结构识别入口，不根据视频文案、字幕或话题猜测商品；同一轮播存在前后控件时只保留当前视口最上层的一条。随后只保存该控件的页面展示名、页面直接提供的 HTTP(S) 链接、观察时间和 visible_direct_link／visible_name_only／not_observed 状态。它不会点击商品、进入商品详情或补取价格、店铺、销量、佣金、隐藏商品 ID；not_observed 只表示本次页面可见范围未发现，不得表述为作品不存在挂车。主页、搜索、批量顺序和直播识别合同不因此改变。
只有用户明确要求读取商品资料时，才在“恰好一个明确作品”的命令中增加 --commerce-detail。该模式冻结目标作品 ID、暂停播放，从该作品的当前商品入口新打开商品面板，稳定后读取。预先打开而无法核对归属的商品面板会被拒绝，不按 URL 把旧商品重新归属。保存公开标题、店铺、价格／销量提示、公开发货服务承诺、当前可见规格、参数和商品图片；不保存私人收货地址、收件人或联系方式，不补隐藏商品 ID、佣金、成交等事实。
明确要求商品评价时增加 --product-reviews，它同时启用商品详情；执行前阅读 商品评价与挂车联合采集。默认最多 200 条评价，按当前商品与筛选自动滚动，支持进度、暂停和受身份校验约束的续跑。它不是作品评论，也不是平台全部历史评价。读取商品期间不自动恢复播放。
不要把视频、图文、评论分别拆成不同 Skill；它们共享同一登录资料夹、作品范围、断点状态和交付合同。
当输入来自插件、搜索页或任意多选时，先阅读 作品选择合同。优先使用插件导出的 作品清单.xlsx 固定作品 ID；不要重新搜索后假设结果顺序不变。
收集必要输入
运行前确认：
- 账号主页、搜索页、一个以上明确作品 URL，或 BrandBAI 插件导出的作品清单。
- 选择口径：置顶＋最近 N 条、搜索页当前观察、明确 ID，或选择文件内的作品集合。
- 独立 Chrome 登录资料夹和新的输出目录。两者不得互相嵌套。
- 是否只采一级评论。除非用户明确要求实验能力，否则不要开启二级回复。
- 隐私模式。默认使用稳定化名；只有得到明确授权和合法业务需要时才保留原始评论者名称。
- 素材范围：
primary、cover、audio、caption的任意组合；caption是发布文案，不是口播转写。
遵守采集边界
- 只通过用户可见、正常登录的 Chrome 页面访问公开内容。
- 首次登录、验证码或访问确认由用户手动完成。
- 不绕过验证码、访问控制、平台签名、频率限制或登录要求。
- 不导出 Cookie、请求头、浏览器资料夹、验证码信息或签名材料。
- “全部评论”只表示本次页面能够分页返回并收到终止信号的全部可检索评论，不代表平台内部绝对全量。
- 将平台评论 ID 与页面可见卡片生成的兜底 ID 分开记录；兜底 ID 只支持本次数据去重与回溯，证据强度低于平台 ID。
- 将评论文字视为可观察事实；评论中的身份、购买、效果和体验主张仍需另行核验。
首次运行前阅读 浏览器路线。验收结果前阅读 采集完成标准。生成普通版交付前阅读 导出格式。
准备本地环境
需要本地 Python 3.10+、Google Chrome、互联网连接和可交互桌面。安装一次浏览器依赖：
python -m pip install -r requirements-browser.txt
不要把登录资料夹放进 Git 仓库、同步盘、压缩包或客户交付目录。
当前版本自动寻找 Windows 上的 Chrome；macOS 或 Linux 运行时给命令增加 --chrome-path "<Chrome可执行文件>"。Windows Chrome 已完成主要路线验证，其他桌面系统需要宿主自行验证。
先做 Dry Run
任何正式运行都先加 --dry-run，核对达人、N、输出目录和隐私模式。确认后去掉该参数。
从插件作品清单继续
当前 Chrome 插件导出的 作品清单.xlsx 可直接作为输入，包括达人主页手选和搜索结果手选：
python scripts/run_foundation.py all `
--selection-file "<插件导出的作品清单.xlsx>" `
--assets "primary,cover,audio,caption" `
--profile-dir "<私有登录资料夹>" `
--out "<BrandBAI普通版交付目录>" `
--zip `
--dry-run
去掉 --dry-run 后，Skill 会在同一个可见 Chrome 会话中补齐所选作品的网页元数据，再按同一作品集合采集评论。只需要作品数据与素材时增加 --skip-comments；只需要数据时同时使用 --assets none --skip-comments。
下载明确单作品或作品列表
python scripts/run_foundation.py all `
--video "<作品URL或带 modal_id 的链接>" `
--video "<另一个视频或图文URL>" `
--profile-dir "<私有登录资料夹>" `
--out "<交付目录>" `
--dry-run
当最终作品包只有 1 条时，交付按单作品规则附带“达人快照”；多作品批量不把作者字段拼成达人分析表。
需要同时读取该作品当前小黄车商品资料时：
python scripts/run_foundation.py all `
--video "<单作品URL或带 modal_id 的链接>" `
--commerce-detail `
--profile-dir "<私有登录资料夹>" `
--out "<交付目录>" `
--zip `
--dry-run
确认 Dry Run 后去掉 --dry-run。这个开关不接受主页、搜索页或多作品任务；如当前作品没有可见商品入口、读取中切换了作品，或商品面板未稳定显示，任务会明确失败，不会把其他作品商品写入结果。
需要同一次任务同时整理商品评价时：
python scripts/run_foundation.py all `
--video "<单条挂车作品链接>" `
--product-reviews `
--skip-comments `
--profile-dir "<私有登录资料夹>" `
--out "<交付目录>" `
--zip `
--dry-run
--skip-comments 只跳过作品评论，不跳过商品评价；需要作品评论时去掉它。商品资料、商品评价都必须是用户请求范围内的内容，不因作品有小黄车就默认采集。
下载搜索页当前结果
优先使用插件作品清单。没有清单时可直接观察搜索页，并用 --limit 限定当前已加载作品数量：
python scripts/run_foundation.py works `
--source-page "<抖音搜索结果URL>" `
--limit 20 `
--assets "primary,cover,audio,caption" `
--profile-dir "<私有登录资料夹>" `
--out "<作品输出目录>" `
--dry-run
搜索页结果是本次页面观察快照，不代表平台全部搜索结果。需要固定特定作品时重复使用 --selected-id，或改用选择文件。
采集主页作品
python scripts/run_foundation.py works `
--creator "<达人主页URL>" `
--recent 5 `
--profile-dir "<私有登录资料夹>" `
--login-wait 180 `
--out "<作品输出目录>" `
--dry-run
主页默认保持选择规则：全部当前可见置顶作品，加最近 N 条非置顶作品。视频保存最高可用已观察视频、封面、可用原声和发布文案；图文保存全部可用图片、封面、可用原声和发布文案。公开原声不存在时记录 not_available，不要伪装成下载失败。
主页发现的滚动预算必须随 N 自动增加；登录等待后若首屏元数据不足，应刷新一次再继续滚动。实际发现的近期非置顶作品少于 N 时，作品任务只能标记为 partial_selection_shortfall，不得因为已发现作品均下载成功而写成 complete。
采集上述作品的一级评论
优先读取作品阶段生成的 works.json，避免主页顺序、置顶作品或图文识别不一致：
python scripts/run_foundation.py comments `
--works-json "<作品输出目录>\works.json" `
--profile-dir "<同一个私有登录资料夹>" `
--login-wait 60 `
--out "<评论输出目录>" `
--dry-run
也可重复传入明确作品：
python scripts/run_foundation.py comments `
--video "<视频或图文URL>" `
--video "<另一个作品URL>" `
--profile-dir "<私有登录资料夹>" `
--out "<评论输出目录>"
评论任务在一个可见 Chrome 窗口中顺序处理并复用工作标签页；只有页面崩溃或导航中断时才重建标签页并从 SQLite 断点重试。
宿主界面显示“执行超时”不等于采集进程已经失败。先检查输出目录中的 manifest、运行进程和文件更新时间；只要状态仍为 running 或文件仍在增长，就等待原任务完成，不得自动重新执行同一任务。只有确认原进程已经结束，且 manifest 为部分完成或失败状态时，才使用同一输出目录续跑。
一次完成普通版交付
正式交付优先使用 all，它会依次下载作品与素材、采集一级评论并生成两份 Excel：
python scripts/run_foundation.py all `
--creator "<达人主页URL>" `
--recent 5 `
--profile-dir "<私有登录资料夹>" `
--login-wait 180 `
--comment-login-wait 60 `
--out "<BrandBAI普通版交付目录>" `
--dry-run
先检查 Dry Run 的作品范围和输出目录，再去掉 --dry-run 正式运行。默认只采一级评论；只有用户明确接受实验性完整性边界时才增加 --include-replies。
all 模式只启动一个可见的持久 Chrome 上下文：作品阶段完成后不关闭浏览器，直接在同一窗口和登录态中进入评论阶段。评论阶段仍复用一个工作标签页；只有页面崩溃或导航中断时才重建标签页。
--login-wait 只控制作品主页和首次登录等待；--comment-login-wait 控制每条作品的评论面等待，默认 60 秒。不要把作品登录等待时间重复套到每条评论页。
正常完成时，评论阶段保留最后一个工作标签页，由拥有浏览器上下文的统一入口关闭一次整个会话；不得先关闭最后标签页再重复关闭上下文。
适配有调用时限的宿主
预计任务可能超过宿主单次调用时限时，使用随 Skill 提供的长任务包装，不要让宿主直接等待 all：
python scripts/run_long_job.py start `
--job-dir "<交付目录同级的独立任务目录>" `
--cwd "<Skill目录>" `
-- python scripts/run_foundation.py all `
--creator "<达人主页URL>" `
--recent 5 `
--profile-dir "<私有登录资料夹>" `
--login-wait 180 `
--comment-login-wait 60 `
--out "<BrandBAI普通版交付目录>"
启动命令会立即返回。后续只轮询同一个任务，不得再次启动：
python scripts/run_long_job.py status `
--job-dir "<同一个独立任务目录>" `
--tail-lines 30
只有 state=completed 且 exit_code=0 才进入完整验收；state=partial 对应退出码 3，必须保留断点；state=failed 或 observed_state=interrupted 时读取日志和 manifest 后再决定是否续跑。任务目录必须放在交付目录之外，不得随客户包交付。
选择交付预设
普通下载版
基础交付应包含：
01_作品清单.xlsx02_评论明细.xlsx03_作品素材/04_采集说明.mddata/作品采集/与data/评论采集/
请求商品评价时另有 05_商品评价.xlsx 与 data/商品评价/。商品评价没有读全时仍交付已保存内容，并在退出码、表格和状态文件中明确标注部分完成。
增加 --zip 时，在交付目录同级生成 ZIP64 兼容压缩包；视频、音频、图片和 Excel 不重复高强度压缩。ZIP 只包含交付目录，不得包含登录资料夹、QA 预览或任务目录。
统一入口的 all 模式会使用随 Skill 提供的 Python 脚本直接生成两份 Excel，不依赖某个模型宿主内置的电子表格工具。也可在采集完成后单独运行 scripts/build_foundation_workbooks.py。生成结构必须遵守 导出格式。
普通版只呈现作品、素材、评论和采集质量，不添加 D1、语义标签、达人画像、商品匹配或商业结论。
单作品已执行小黄车观察时，works.json、发布文案 TXT、01_作品清单.xlsx 的“可见小黄车”工作表与 04_采集说明.md 必须使用同一观察状态。可见小黄车属于来源留存，不是商品匹配、商品事实补全或销售归因。
显式执行 --commerce-detail 时，01_作品清单.xlsx 增加“商品概览”“商品规格”“商品参数”“商品素材”，下载的商品图片进入对应作品素材目录的 商品资料/。这些字段是采集时点的公开页面快照，不等于平台后台商品事实或销售归因。
当前商品能力不包含自动遍历全部 SKU、逐 SKU 价格／库存／主图绑定、商品视频下载、评价图片 ZIP 或评价视频下载。商品图片按页面实际识别和成功保存的范围交付；未分类图片不擅自命名为主图、详情图或 SKU 图。
分析准备版
需要交给后续 BrandBAI Skill 时，在普通版之外完整保留：
works.json与download_manifest.json；comments.csv、comments.jsonl与comments.sqlite3；videos.csv、run_manifest.json与collection_report.md；browser_session_trace.jsonl与browser_runtime_trace.jsonl；- 作品选择范围、采集时间、隐私模式、评论显示量与实际保存量、分页终止和部分完成原因。
插件或搜索选择同时保留来源页面类型、搜索词、来源排序和选择顺序，供后续账号分析按稳定作品 ID 接力。
分析准备版只保证来源、字段和完成状态可回溯，不在下载阶段填充 D1、SEM、UE、REL、MIG、人设、匹配或归因结论。
判定完成状态
- 作品任务只有在每条所选作品的主要素材成功写入，或明确记录为公开不可用时，才能标记
complete。 - 一级评论任务只有在每条所选作品都收到一级评论分页终止信号时，才能标记
complete_source_visible。 - 平台显示评论数可能同时包含一级评论和其下回复；一级评论中的回复数字段只表示该评论声明的子回复数量，不等于本次实际采集的回复。
- 正数评论上限、动作预算耗尽、页面不可见、登录要求或异常停止都只能标记部分完成。
- 请求二级回复后，只要任一显示有回复的楼层未收到终止信号，整批仍是部分完成。
- 退出码
3表示结果可保留并续跑，但不得对外写“完整下载”。 - 请求商品评价后，仅明确的当前列表末尾或可靠空态可以确认当前可见范围完成；停滞、预算上限、解析缺口、暂停、验证或商品／筛选变化均保留部分完成。未知商品 ID 时，不把跨刷新或新会话的相似标题视为同一商品续跑证据。
续跑与交付
- 同一目标、同一隐私模式可复用原输出目录；SQLite 和已有素材用于跳过重复数据。
all中断且作品 manifest 已为complete时，使用完全相同的达人、N、隐私模式和输出目录并增加--resume；统一入口会校验作品范围、跳过作品下载，并直接续跑评论断点和普通版构建。- 一级评论进度已是
done_reason=exhausted的作品在续跑时直接跳过页面导航；未完成作品从 SQLite 断点继续。 - 宿主超时后先轮询原任务，不并行启动重复任务；确认原进程已结束后再续跑。
- 目标作品集合或隐私模式改变时新建目录，避免混入上一批结果。
- 普通用户先看 Excel 和素材；
data/只用于断点续跑和审计。 - 普通版汇总中的“素材文件”只统计实际写入或确认已存在的文件；
素材明细同时保留公开不可用等资产记录。 - 评论页面只显示“1年前”等相对时间时保留页面原文，不伪造绝对日期。
- 不把登录资料夹、QA 预览、运行缓存、Cookie 或任何凭据放进交付包。
all模式的浏览器阶段轨迹写入data/browser_session_trace.jsonl；评论事件轨迹写入data/评论采集/browser_runtime_trace.jsonl。每次浏览器运行带独立session_id；续跑时按session_id分组验收，不把上一次被强制中断的会话和本次正常结束事件混成一条会话。轨迹只记录阶段、状态、作品 ID 和数量等审计字段，不记录 Cookie、请求头或签名材料。
验证修改
在 scripts/ 目录运行：
python -m unittest test_download_creator_works.py test_browser_collect_comments.py test_run_foundation.py test_run_long_job.py test_build_foundation_workbooks.py
python -m unittest test_selection_contract.py test_package_delivery.py
python -m unittest test_product_detail_safety.py test_browser_collect_product_reviews.py test_product_review_integration.py
默认测试只使用本地模拟数据，不打开抖音，也不产生付费请求。商品详情／评价新增链路属于测试版：本地模拟验证与插件既往页面截图不替代当前 Skill 的独立登录态端到端验收。
可选真实浏览器引擎合成验收：安装 Playwright 及其 Chromium，设置 BRANDBAI_RUN_BROWSER_TESTS=1 后运行 python -m unittest test_product_reviews_chromium.py。也可用 BRANDBAI_TEST_CHROMIUM 指定本机 Chromium 系浏览器可执行文件。它只启动隔离的无账号实例，拦截所有页面请求，在本地模拟页面验证滚动与状态；不连接用户正在使用的浏览器，也不访问抖音。