# Tiktok Scripts

AutoX（Auto.js Pro）项目。**启动入口是「飞舟脚本」界面，界面就是控制台**——
打开项目先看到界面，在里面配置、点「开始运行」，界面**直接唤起执行引擎**去操作 TikTok。

## 启动入口

| 项 | 值 |
|---|---|
| 清单文件 | `project.json` |
| 入口字段 | `"main": "./main.js"` |
| 入口文件 | `main.js`（项目根目录） |
| 界面 | `tiktok-app/`（登录激活 → 选脚本 → 调参数 → 开始运行） |
| 执行引擎 | `tiktok-auto/`（打开 TikTok → 搜索关键词 → 随机观看 → 评论） |

`main.js` 是一个**薄入口**：只做「加载界面产物 + 失败时给出可操作的报错」，不含业务逻辑。

> **入口为什么在根目录**：AutoX 项目约定入口在根目录（设备上已有的 `task_manager` /
> `tk_login` / `biyun-tk-*` 项目都是根目录 `main.js`），这样「从哪启动」一眼可见，
> 也方便在这里做前置检查。

### ★ `"ui";` 必须在**入口文件**的第一行

AutoX 的 UI 模式由**入口脚本**的 `"ui";` 指令开启。写在被 `require` 的模块里是无效的
（那只是一句字符串语句）。所以：

- `main.js` 第一行是 `"ui";`；
- `tiktok-app/dist/tiktok-app.js` 自己第一行也有 `"ui";` —— 它只在**该产物被直接运行**
  （例如用 `RunIntentActivity` 打开它）时才起作用；从 `main.js` require 进来时，
  真正决定 UI 模式的是 `main.js` 的第一行。

已在真机实测：`main.js` → require 界面产物 → UI 模式开启、界面正常渲染。

## 怎么跑

```bash
# 改界面后必须重新构建（入口只是加载产物，不会自动编译）
node tiktok-app/tools/build.js

# 改互动逻辑后重建（与界面各建各的）
node tiktok-auto/tools/build.js
```

在手机上：让 AutoX 同步本项目 → 打开项目 → 运行（跑的是 `main.js` → **界面**）。

**日常使用就是：打开界面 → 选脚本 → 调参数 → 点「开始运行」。**
界面会写配置、唤起引擎，引擎去操作 TikTok；跑完界面自己切回前台并告诉你结果。

单独跑执行侧（不经过界面）仍然可用：

```bash
node tiktok-auto/tools/run.js --keyword fashion --videos 1
node tiktok-auto/tools/run.js --dry-run        # 不真发评论
node tiktok-auto/tools/run.js --self-test      # 设备端纯函数自检
```

开发期只想单独调界面（不经过入口）时，也可以直接运行构建产物：

```bash
adb shell "am start -n org.autojs.autoxjs.v7/org.autojs.autojs.external.open.RunIntentActivity \
  -a android.intent.action.VIEW -d file:///sdcard/Download/tiktok-app.js -t text/javascript"
```

> ⚠️ 常驻界面脚本**不要走 MCP 下发**：`command:run` 有 120s 上限，而界面不会 `__END__`，
> 必然超时。用上面的 `am start` 或人在 AutoX 里打开。

## 两边怎么衔接（已接通）

界面点「开始运行」做三件事，然后由**执行引擎**接手：

```
界面 ──写──▶ /sdcard/tiktok_app/engine-config.json   （映射后的引擎配置）
     ──起──▶ engines.execScriptFile(tiktok-auto 产物) （另一个 ScriptEngine）
     ──读──◀ /sdcard/tiktok_app/run-state.json       （进度 / 终态）
     ──写──▶ /sdcard/tiktok_app/stop.flag            （停止请求，内容是 runId）
```

外加一份 `run-config.json`：界面完整配置 + 本次生效的引擎配置 + 「哪些勾了但不会生效」，
**给人看、给事后追溯用**。

四个文件都在 `/sdcard/tiktok_app/` 下，都是纯文本 JSON —— 出问题直接 `cat` 就能复盘。

> 为什么走**文件**而不是内存：界面与引擎是两个独立的 ScriptEngine，各有各的全局作用域，
> 对象传不过去（实测确认）。详见 [`tiktok-app/README.md`](tiktok-app/README.md) 第 6 节。

**已知能力边界**：引擎目前实现的是「搜索 → 逐个看 → 评论」。
界面上 ID提取 / UID私信 / 养号三页的脚本**没有对应引擎** —— 点「开始运行」会被明确拦下
（弹窗说明哪个脚本没接入），不会静默跑一个不相关的东西。
视频功能页「执行操作」里的**关注 / 私信 / 点赞也尚未接入**：勾了会在启动时提示一次，
并记进 `run-config.json` 的 `engine.notes`。

## 改什么改哪里

| 想改 | 改这里 | 要重新构建吗 |
|---|---|---|
| 界面布局 / 页面 / 文案 | `tiktok-app/src/*.js` | **是**（`node tiktok-app/tools/build.js`） |
| 界面的配置项 / 默认值 | `tiktok-app/src/store.js` 的字段表 | **是** |
| 界面 ↔ 引擎的字段映射 | `tiktok-app/src/engine.js` | **是** |
| 互动流程与逻辑 | `tiktok-auto/src/*.js` | **是**（`node tiktok-auto/tools/build.js`） |
| 界面 ↔ 引擎的通道协议 | `tiktok-auto/src/bridge.js` | **是**（两侧都要重建） |
| 关键词 / 评论文案 / 观看时长 / 超时 | `tiktok-auto/config/tiktok-auto.config.json`，推到 `/sdcard/Download/tiktok-auto/config.json` | 否 |

两个子工程各自的详细说明（设计稿对照、稳定性设计、真机验证记录、排障）：

- 界面： [`tiktok-app/README.md`](tiktok-app/README.md)
- 互动： [`tiktok-auto/README.md`](tiktok-auto/README.md)

## 已知待办（未改动，供参考）

- **引擎能力边界**：关注 / 私信 / 点赞动作、ID提取 / UID私信 / 养号三页的脚本都还没实现。
  这些在界面上都会被如实告知，不会假装支持。
- `package.json` 里的 `"main": "main.js"` 是 npm 的字段，与 AutoX 入口无关，无需修改。
- `project.json` 的 `name` 已随入口改为 **飞舟脚本**（原来是「TikTok 自动互动」）；
  `packageName` 仍是占位值 `org.example.my_project`，`splashText` 仍是
  `Powered by Auto.js Pro`。要正式发布 APK 时建议改成自己的包名与文案
  （改包名会让已装的旧 APK 变成另一个应用）。
- `.autojs.sync.ignore` 目前只忽略 `/build`。本地 `node_modules/`（仅类型声明）与 `.git/`
  也会被同步，数量大时同步会变慢；如需要可自行加上 `/node_modules` 与 `/.git`。