# 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）。

## 构建与自检（改完必跑）

```bash
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 && $NODE tools/pc-selftest-bridge.js
                                                                          # 期望 114 项 + BRIDGE_SELFTEST_PASS
cd tiktok-app  && $NODE tools/build.js && $NODE tools/smoke.js && $NODE tools/audit-values.js
                                                                          # 期望 526 项通过 + AUDIT_CLEAN
cd tiktok-app  && $NODE tools/protocol-check.js                            # 期望 PROTOCOL_CLEAN（动过 protocol.js 就跑）
```

★ 顺序不能反：`smoke.js` / `audit-values.js` require 的是 **dist**，改了 `src/` 不 build 照样全绿。

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

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 提取的历史方案（已实施） |