tiktok-scripts/.github/copilot-instructions.md

Copilot 工作指令 — tiktok-scripts

自动加载的精简规则。完整上下文见 docs/AI_CONTEXT.md（改代码前请读对应章节）。

这是什么

给 TikTok 做自动化的 AutoX 项目，三层：

层	目录	产物	备注
界面（UI 模式）	tiktok-app/src/	dist/tiktok-app.js	19 模块
引擎（无界面）	tiktok-auto/src/	dist/tiktok-auto.js	18 业务模块 + main 入口；两个 task：video / id
独立脚本	根目录 tiktok_stats.js 等	不构建	PC Node 跑

构建 = 单文件拼接（AutoX 只能下发一整段脚本，不支持 require）。

构建与自检（改完必跑）

NODE="C:/Users/61554/.workbuddy/binaries/node/versions/22.22.2-6/node.exe"  # 或直接用 node

cd tiktok-auto && $NODE tools/build.js && $NODE tools/pc-selftest-id.js   # 期望 68 项通过
cd tiktok-app  && $NODE tools/build.js && $NODE tools/smoke.js && $NODE tools/audit-values.js
                                                                          # 期望 414 项通过 + AUDIT_CLEAN

硬规则（违反会静默出问题）

1. 新增模块前查重名函数：for f in src/*.js; do grep -o '^function [a-zA-Z_]*' "$f"; done | sort | uniq -d 单文件拼接下同名 function 会静默互相覆盖。
2. 默认值只在 tiktok-app/src/store.js 的 FIELDS 定义，别处禁止硬编码。
3. 输入框只走 W.inlineField / W.numberField，不要自己造 EditText。
4. 等待一律用 wait.waitFor，禁止 sleep()；判据必须是「新内容真的出现了」，不要用 settle() 判"点完是否成功"。
5. "ui"; 只能是入口文件 main.js 的第一行。
6. UI 模式下禁止阻塞式 dialogs.*（会静默返回 undefined），用项目自绘的 Dialog.*。
7. 模块之间不在加载时取彼此引用，一律在函数体内按名字取（TikTokAuto.xxx.yyy）。
8. 平台怪癖只写在 tiktok-auto/src/layout.js，不要散落到业务代码里。

高频坑（都是「不报错，只是结果错」）

坑	正解
app.launchPackage() 会把已在前台的 App 重置到首页，毁掉用户准备好的页面	先判 foregroundPackage() === pkg，是就什么都不做
settle() 会提前返回（骨架先出、行后加载，签名看起来没变）	等「行数 > 0」这类新内容出现的判据
数字先渲染成占位的 0	连续两次读到一致才采信；三组全 0 再等 1.5 秒复核
点列表行用 node.click() 会落在容器中心（可能是 Follow 按钮，误触会把用户关注掉）	按坐标点行左侧 30%
两种用户列表页的行结构不同（粉丝列表 txt_desc / 搜索用户 tv_username）	profile.listRows() 必须按当前页面分派
抓取阶段的「够了/到点了」不能用来终止收尾工作	收尾阶段只继承「用户叫停」和它自己的时长预算
在入口做全局 ensureFeed 会破坏「当前屏幕」类取材	各取材源自己保证前置状态；screen 源不动页面
http.get 在这个 AutoX 版本是坏的（OkHttp 冲突）	用 Java HttpURLConnection，并区分 getErrorStream()
engines.execScriptFile 的 arguments 到了子脚本变成对象	按 argv[i] 取，别当数组
子脚本看不到父脚本的全局变量	只能走文件通信（见 docs/AI_CONTEXT.md 2.3）
UI 回调里的异常不报错、不弹窗、不结束脚本	回调内部必须自己 try/catch 并留痕
build.js 写时间戳，每次 md5 都不同	不要用 md5 判断是否需要推送，只在推送后双向核对

完整坑库（约 40 条，分 6 组）见 docs/AI_CONTEXT.md 第 6 节。

不要做的事

• ❌ 不要引入登录态/Cookie 抓取——已验证对抓取零贡献，相关代码已删
• ❌ 不要试图给提取加"视频量门槛"——TikTok 用户页不显示视频数
• ❌ 不要试图判断账号所属国家——用户页没有这个信息
• ❌ 不要用 MCP 下发长脚本（120 秒上限会截断），用 am start 启动
• ❌ 不要把「已知局限」当 bug 修（见 docs/AI_CONTEXT.md 第 9 节）

交付要求

必须做：

1. 跑完上面对应的自检命令
2. 断言失败时先判断是回归还是断言该更新（例如新增一个基础设施计时器会让"计时器数量"断言从 1 变 2）
3. 涉及真机行为的改动必须真机验证——PC 自检只能验结构，验不了页面上真正发生了什么

报告时讲清三件事：改了什么 / 怎么验证的 / 没解决什么。

文档索引

文件	内容
docs/AI_CONTEXT.md	★ 完整上下文：架构、坑库、标准改法、实测锚点、排障
tiktok-app/README.md	界面：屏幕路由、控件约定、悬浮球实现
tiktok-auto/README.md	引擎：视频链路 + ID 提取链路（第 3.5 节）
PLAN_id_extract.md / REQ_id_extract_v2.md	ID 提取的历史方案（已实施）