spec_tight.md 27 KB
title: 实施规格书_飞舟脚本_2026-10-13
# 飞舟脚本 App · 实施规格书
配套设计文件：https://ardot.tencent.com/file/734917825641912\ 版本：2026-10-13 · 适用于把本设计交付给编码 AI / 开发执行\ **本文档是"可执行规格"，画布只是视觉参考。有冲突时以本文档为准。**
##
§0 怎么用这份文档
先填 §7 技术栈 —— 不填则 §3 的字段控件类型无法映射，开发只能猜。
§1 是页面边界（特别注意 C1–C5 是同一个页面）。
§2 是导航与状态机 —— 决定跳转与互斥，必须先实现。
§3 是字段清单，§4 是交互规则，§5 是必须替换的假数据。
§6 是设计令牌，直接落成主题变量。
§9 列出了已知的不一致与待确认项，开工前先过一遍。
## §1 页面清单（画板 → 页面/状态映射） 底栏只有 3 个 tab：
任务/记录/我的。 |编号 画板名 节点 ID 类型 归属|
A1 卡密登录 `16:257` 独立窗口（**无底栏**） 启动入口|
A2 卡密登录 · 校验中 `16:1491` A1 的**加载态** 同一页|
A3 卡密登录 · 校验失败 `16:288` A1 的**错误态** 同一页|
A4 权限引导弹窗 `30:738` 弹窗 叠在 **B1** 上|
B1 任务列表 `30:102` **一级页** 任务 tab · 默认落点|
B2 任务列表 · 运行中 `30:203` B1 的**运行态** 同一页|
C1 ID提取 `3:1` **二级页** 任务 › ID提取 · **首屏**|
C1r ID提取 · 运行中 `16:138` C1 的**运行态** 同一页|
C2 ID提取 · 脚本二三 `16:483` C1 的**第 2 屏（滚动位置）** 同一页|
C3 ID提取 · 脚本四 `16:589` C1 的**第 3 屏** 同一页|
C4 ID提取 · 功能设置 `16:706` C1 的**第 4 屏** 同一页|
C5 ID提取 · 功能设置（滚到底） `16:965` C1 的**底部** 同一页|
C6 UID私信 `3:534` 二级页 任务 › UID私信|
C7 UID私信 · 脚本一展开 `7:11` C6 的**展开态** 同一页|
C8 养号 `3:469` 二级页 任务 › 养号|
C9 视频功能 `3:629` 二级页 任务 › 视频功能|
D1 记录列表 `30:871` **一级页** 记录 tab|
D2 记录空态 `30:958` D1 的**空态** 同一页|
D3 运行详情 `30:1241` D1 的**二级页** 记录 › 单次运行|
E1 我的 `7:289` **一级页**（可滚动） 我的 tab|
E2 我的 · 解绑确认 `16:850` 弹窗 叠在 E1 上|
F1 ID提取 · 未选脚本 `16:23` 弹窗 叠在 C1 上|
F2 ID提取 · 权限拦截 `16:319` 弹窗 叠在 C1 上|
F3 切换任务确认 `30:1005` 弹窗 叠在 B2 上|
F4 ID提取 · 运行中卡密到期 `16:1360` 弹窗 叠在 C1r 上|
F5 脚本报错 `30:1119` C1r 的**报错态** + 弹窗 同一页### ⚠️ 最重要的一条 C1 / C1r / C2 / C3 / C4 / C5 是同一个「ID提取」页面的 6 个采样点，不是 6 个页面。\ ID提取 是一个可滚动的长页面：脚本选择（脚本一~四）→ 功能设置（14 项）。\ C2–C5 只是把它滚动到不同位置时的样子。 ###
实际需要实现的页面只有 5 个 + 3 个 tab
卡密登录（A1/A2/A3 三态）
任务列表（B1/B2 两态）
任务详情（4 种：ID提取 / UID私信 / 养号 / 视频功能）—— ID提取 最长，可滚动
运行记录（D1/D2 两态 + D3 详情）
我的（E1，可滚动）
## §2 导航与状态机 ### 2.1 启动与卡密
启动 → 读本地卡密 ├─ 无卡密 / 已过期 → A1 卡密登录 └─ 有效 → B1 任务列表 A1 ──点「登录激活」→ A2（按钮转「登录中…」+ 转圈，禁用防重复点） ├─ 校验失败 → A3（输入框变玫瑰色 + 下方红字提示，仍停在 A1） └─ 校验成功 → 检查权限 ├─ 缺权限 → A4 权限引导弹窗 └─ 权限齐 → B1### 2.2 一级 / 二级导航
B1 任务列表 ──点任务卡主体──→ 对应二级页（C1/C6/C8/C9） 二级页 ──点「← 返回」──→ B1 B1/B2/D1/D2/D3/E1 ──点底栏──→ 三个 tab 互切 D1 记录列表 ──点任一条目──→ D3 运行详情 D3 ──点「← 返回」──→ D1### 2.3 全局运行状态机（全局单跑）
空闲（idle） │ │ 发起运行（前置校验全通过） ▼ 运行中（running）────────────────────────────┐ │ │ ├─ 正常跑完 → 完成（success） │ ├─ 点「停止运行」 → 手动停止（stopped） │ 点别的任务「运行」 ├─ 卡密到期 → 弹 F4 → 回 A1 ├→ 弹 F3 确认 ├─ 脚本报错 → 弹 F5（可看日志） │ └「停止并开始」→ 停旧的，起新的 └─ 权限被关闭 → 归入「报错中断」 │ ──┘ 所有结束 → 回到「空闲」，并**写入 D1 一条记录**互斥规则：任何时刻只允许一个脚本在运行（跨任务也互斥）。 运行中，其他任务的「运行」按钮仍然可点，点击后弹 F3 确认，不做禁用。 运行中，不允许在同一运行中切脚本 —— 必须先停。 ### 2.4 全局运行条 位置：顶部，状态栏下方（
x=20, y=70, w=335, h=44） 显示条件：仅「运行中」时出现；空闲/完成时整条隐藏（不占高度） 内容：● {任务名} · 脚本X · 运行中+ 右侧等宽字体计时 报错态（F5）：整条变玫瑰红，文案脚本一 · 执行出错已停止，右侧已终止交互：点击整条 → 跳回运行中的那个任务的详情页 职责分工：运行条 = 状态与导航；页面底部 CTA = 启停控制。运行条上不放停止按钮 ### 2.5 运行前置校验顺序点「开始运行」时，按此顺序校验，任一步不过就拦截：
卡密有效？ → 否：不做提示，直接回 A1
无障碍 + 悬浮窗权限齐？ → 否：弹 F2
已选脚本？ → 否：弹 F1
已有脚本在运行？ → 是：弹 F3；否：直接启动
## §3 字段表 ### C1 ID提取 · 脚本选择 |
字段 控件 默认值 校验 / 备注|
脚本一 ~ 脚本四 **单选圆点** 脚本一 选中 同一时间仅可运行一个；页面内有说明「单选：同一时间仅可运行一个脚本」|
自定关注或粉丝页面提 ID 复选框 ✓ 脚本一展开项|
自定页面提 ID 复选框 ✗|
主播去重 复选框 ✓|
├ 去重模式 下拉 `ID 模式`|
└ 进入页面 下拉 `粉丝页`|
主播 ID 输入 `ID1#ID2#ID3` 多个用 `#` 分隔|
使用文本 ID 复选框 + 文件选择 ✗ 路径框**右对齐**；按钮「选择」|
底部提示 文案 `↓ 下方还有「功能设置」，向下滚动查看` 脚本二/三/四的展开内容见 C2、C3。### C2 ID提取 · 脚本二 / 脚本三（展开态） 脚本二 · 评论页提 ID |
字段 控件 默认|
自定评论页面提 ID 复选框 ✓|
提取评论的人的粉丝 ID 复选框 ✗脚本三 · 文本 UID 裂变提 ID |
字段 控件 默认|
文本 UID 裂变提 ID 复选框 ✗|
UID 博主去重 复选框 ✓|
进入页面 下拉 `关注页`|
裂变文本 输入 + 按钮 路径框右对齐 / 按钮「选择」当前脚本提示条：
当前脚本：自定评论页面提 ID（居中、浅色底） ### C3 ID提取 · 脚本四（展开态） |字段 控件 默认|
关键词视频提 ID 复选框 ✗|
关键词主播 输入 `关键词`|
关键词提取主播粉丝 ID 复选框 ✗|
关键词提取评论区 ID 复选框 ✗|
关键词提取评论的人的粉丝 ID 复选框 ✗### C4 ID提取 · 功能设置（14 项，C2/C3/C5 共用同一张卡） |
# 字段 控件 默认值 备注|
1 过滤私密账户 复选框 ✓|
2 过滤无头像账户 复选框 ✓|
3 提取区域 输入 + 按钮 `国家简码：JP#TW#US` / 按钮「含对应区域ID条款」 说明两行见下|
— （说明） 文案 `国家简码：如日本填 JP；台湾：TW，多国则用 # 隔开`|
— （说明） 文案 `如：JP#TW#CN#US，不填则匹配所有国家`|
4 语言区域 下拉 `通杀`|
5 昵称个签检测 下拉 `通杀`|
6 云端去重 复选框 + 输入 + 按钮 ✓ / `表名：字符` / 按钮「连通测试」|
7 AI 头像识别 复选框 ✓|
8 AI性别 下拉 `男`|
9 AI 年龄 > 输入 `20`|
10 关注量 **区间输入（双框）** `0` ~ `500000` 数字居中，框宽 56px|
11 粉丝量 区间输入 `0` ~ `500000`|
12 获赞量 区间输入 `0` ~ `500000`|
13 视频量 区间输入 `0` ~ `500000`|
14 提取符合 输入 + 后缀文案 `0` + `个 ID 后停止`### C6 UID私信 |
分组 字段 控件 默认|
脚本选择 脚本一 · 已提 UID 私信 单选 ✓|
脚本二 · 自己粉丝私信 单选 ✗|
功能设置 AI 性别 下拉 `男`|
关注数量 区间输入 `100` ~ `200`|
私信数量 区间输入 `20` ~ `30`|
休息时间（秒） 区间输入 `100` ~ `500`|
私信 / 评论设置 随机私信文本 文件选择 按钮「选择文件」|
随机评论文本 文件选择 按钮「选择文件」### C7 UID私信 · 脚本一（展开态） |
分组 字段 控件 默认|
脚本一（展开） UID 私信 复选框 ✓|
筛首视频日期 下拉 `7 天内`|
首视频点赞 / 首视频评论 开关 `都执行`|
已筛符合的 UID 文本 输入 + 按钮 路径框右对齐 / 按钮「选择」|
功能设置 进行关注 / 进行私信 开关 `开启`|
关注数量 区间输入 `100` ~ `200`|
私信数量 区间输入 `20` ~ `30`|
去重方式 下拉 `关注+私信去重`### C8 养号 |
分组 字段 控件 默认|
脚本选择 随机操作养号 单选（已选） ✓|
养号参数 浏览时长（分钟） 区间输入 `3` ~ `8`|
点赞概率 下拉 `30%`|
评论概率 下拉 `10%`|
关注概率 下拉 `15%`|
单次操作 区间输入 `10` ~ `30`|
底部提示 文案 — `随机浏览、点赞、评论模拟真实活跃度`### C9 视频功能 |
分组 字段 控件 默认|
脚本选择 关键词视频功能 单选（已选） ✓|
功能设置 关键词 输入 `搜索`|
主播区域 输入 `国家简码`|
停止个数 区间输入 `1` ~ `5`|
间隔时间（秒） 区间输入 `20` ~ `20`|
执行操作 4 个开关胶囊 关注 开 / 私信 开 / 点赞 关 / 评论 关|
私信 / 评论设置 随机私信内容 1-3 文件选择 按钮「选择文件」|
随机评论内容 1-3 文件选择 按钮「选择文件」### B1/B2 任务列表 |
字段 说明|
页面标题 `飞舟脚本` / 副标题 `TikTok 自动化脚本 · 选择任务`|
区标题 `任务` + 说明 `全局单跑：同一时间仅可运行一个脚本`|
任务卡 ×4 图标 · 任务名 · **状态徽标** · 当前脚本 · 上次运行 · 「运行」按钮状态徽标取值：
空闲（灰） /运行中（绿） /未配置（琥珀）\ 任务卡副文案： ID提取 →当前：脚本一 · 粉丝页提 ID/上次 10:24 · 提取 128 个 IDUID私信 →当前：脚本一 · 已提 UID 私信/上次 09:58 · 私信 30 人养号 →当前：随机操作养号/上次 09:12 · 运行 6 分钟视频功能 →当前：关键词视频功能/还未运行过### D1/D3 运行记录 |字段 说明|
D1 区标题 `运行记录` + `共 3 条 · 点任一条查看执行日志`|
记录条目 图标 · `{任务} · {脚本}` · **结果标签** · 时间行 · 结果行 · 右箭头|
**结果标签取值** `已完成`（绿） / `手动停止`（灰） / `报错中断`（玫瑰红）|
D3 摘要卡 任务名 · 结果标签 · `时间 · 耗时 · 结果量` · 结果文件名 + 「打开」「分享」|
D3 日志卡 标题「执行日志」+「复制」按钮 + 等宽字体日志行|
**日志级别配色** `INFO` 灰 / `WARN` 琥珀 / `ERROR` 玫瑰红### E1 我的 |
分组 字段 控件 值|
卡密 卡密状态 标签 `已登录`（绿）|
卡密到期时间 只读值 + 提醒标签 `2026-12-31 23:59` + `即将到期`（琥珀）|
解绑卡密 按钮 `解绑`（玫瑰色）|
应用 TikTok 客户端（未安装态） 标签 + 按钮 `未安装`（灰）+「下载」|
TikTok 客户端（已安装态） 标签 + 按钮 `已安装 v39.5.4`（绿）+「更新」|
关于 脚本版本 只读值 `2026.10.10`|
更新日志 按钮 `查看`|
检查更新 标签 `已是最新`（绿） ⚠️ 「应用」区两行是**互斥状态对照**，运行时按安装状态**只渲染一行**。### 弹窗文案（A4 / F1–F5 / E2） |
编号 标题 说明 按钮|
A4 `需要开启权限` `为正常执行脚本，请先授予以下权限` 权限 3 行（无障碍 已开启 / 悬浮窗 未开启 / **通知 未开启（可选）**）+「去授权」+「稍后再说」|
F1 `无法开始运行` `请先选择要运行的脚本` 「知道了」|
F2 `无法开始运行` `无障碍与悬浮窗权限未开启，脚本无法执行` 权限 3 行 +「去授权」+「稍后再说」|
F3 `{任务名}正在运行` `开始 {目标任务} 将先停止当前脚本（全局单跑）` 「取消」+「停止并开始」|
F4 `正在运行的脚本已停止` `卡密已到期，需重新登录后继续使用` + 小字 `确认后将返回卡密登录界面` **仅「确认」**|
F5 `脚本执行出错` `无障碍服务被关闭，脚本已停止运行` 「查看日志」+「知道了」|
E2 `确认解绑卡密？` `解绑后需重新输入卡密才能使用` / `正在运行的脚本将立即停止` 「取消」+「确认解绑」（玫瑰色） A4 与 F2 结构完全一致，仅标题/说明/权限初始状态不同，**可复用同一组件**。
## §4 交互规则清单 |
# 触发 行为|
1 启动且无有效卡密 **自动跳 A1**，不弹提示|
2 运行中卡密到期 弹 F4 → 点「确认」→ **自动回 A1**|
3 E1 点「解绑」 弹 E2 → 「确认解绑」→ **自动回 A1**|
4 点「开始运行」 按 §2.5 顺序校验，不过则拦截|
5 运行中点其他任务「运行」 弹 F3；「停止并开始」→ 先停旧再起新。**按钮不禁用**|
6 运行中切换任意页面 顶部运行条**始终可见**（它是全局组件）|
7 点运行条 跳回运行中的任务详情页|
8 脚本报错 运行条变红 + 弹 F5；点「查看日志」→ D3|
9 全局互斥 任何时刻仅一个脚本运行（跨任务）|
10 记录条目点击 进 D3|
11 「我的」页内容超出 **页面可滚动**（底部渐隐 + 右侧滚动指示条）|
12 ID提取 / 功能设置页内容超出 **可滚动**（同上）|
13 脚本卡点击 展开/收起配置项（箭头方向随之变化）|
14 二级页「← 返回」 回 B1|
15 所有运行结束 写一条 D1 记录（含结果分类）
## §5 占位值替换表（必须替换，否则会写死假数据） |
位置 当前占位值 需替换为|
E1 · 软件/脚本版本 `2026.10.10` 真实脚本版本号规则|
E1 · 卡密到期时间 `2026-12-31 23:59` 真实到期时间（来自卡密接口）|
E1 · TikTok 已安装版本 `v39.5.4` 真实适配版本 / 运行时读取|
C1 · 主播 ID 示例 `ID1#ID2#ID3` 真实示例或留空提示|
C4 · 提取区域 `JP#TW#US` / `JP#TW#CN#US` 真实默认值|
C4/C2/C3/C6/C7/C8/C9 · 所有区间值 `0~500000` / `100~200` / `20~30` / `100~500` / `3~8` / `10~30` / `1~5` / `20~20` 真实默认值与上下限|
C4 · AI 年龄 `20` 真实默认|
C4 · 提取符合 `0` 真实默认|
B1 · 任务卡「上次…」 `上次 10:24 · 提取 128 个 ID` 等 读取真实历史记录；无记录显示 `还未运行过`|
D1/D3 · 记录与日志 3 条示例 + 6 行日志 真实运行记录；日志为**脚本真实输出流**|
D3 · 结果文件名 `uid_20261013.txt` 真实产物文件名规则|
A1 · 卡密输入框示例 校验失败态里的 `TK9F-2A7C-8E10-4B55` 仅演示用，不要预填
## §6 设计令牌 ### 颜色 |
用途 值|
页面底色 `#030014`|
卡片底 `#FFFFFF` @ 4%（部分 6%）|
卡片描边 `#FFFFFF` @ 8%|
弹窗底 / 描边 `#17142B` / `#FFFFFF` @ 12%|
底栏底 `#0A0A17` @ 96%|
主色（渐变） `#2EA7FF` → `#9381FF`|
主色（单色） `#2EA7FF`（激活/链接 `#7CC7FF`）|
成功 / 运行中 `#13DDC4`|
警告 / 未配置 / 即将到期 `#F5C24B`|
危险 / 报错 / 解绑 `#FF5470`|
次要紫 `#9381FF`|
主文字 `#FFFFFF`|
正文文字 `#CFCCE6` / `#E6E4F5`|
次要文字 `#9A97B8` / `#8E8BA8`|
弱提示文字 `#6F6C8A`### 字体 |
用途 字体 / 字号|
中文 `Noto Sans SC`|
数字 / 设备号 / 日志 `JetBrains Mono`|
状态栏时间 `Inter`|
页面标题 22px / SemiBold|
二级页返回头标题 21px / SemiBold|
弹窗标题 18px / SemiBold|
区标题 / 任务卡标题 16px / 15px SemiBold|
设置名 / 正文 13px Regular|
标签 / 说明 / 提示 11–12px### 尺寸与圆角 |
元素 规格|
画板 375 × 812|
状态栏 高 62（**系统绘制，不要实现**）|
**全局运行条** `x=20, y=70, w=335, h=44`，圆角 12|
**返回头** 高 44，返回热区 44×44，圆角 —|
**底栏** 高 83 = 页签行 49 + 安全区 33|
底栏页签图标 22×22|
内容区（空闲） `y=62, h=595`|
内容区（运行中·有 CTA） `y=126, h=531`|
内容区（运行中·无 CTA） `y=126, h=591`|
主 CTA `x=20, w=335, h=48`，圆角 99|
卡片 圆角 16 / 14，内边距 14–16|
**区间输入框** 单框宽 **56**，数字**居中**|
文件路径输入框 内容**右对齐**|
底部渐隐 `y=577, h=80`|
滚动指示条 `x=367, w=3`，圆角 99### 触控标准 新组件（任务卡、记录条目、返回头、运行条）按 44pt 实现（如运行按钮 68×44、返回热区 44×44）。 ⚠️ 既有控件（设置行、胶囊）视觉仍是 26px —— 建议实现时视觉保持紧凑、热区用透明 padding 撑到 44px（§9 有记录）。 ### 图标 线性图标，
stroke-width1.6，圆角端点，viewBox 0 0 24 24。底栏三图标：任务=圆角方框+勾 / 记录=时钟 / 我的=人像。
## §7 技术栈（开工前必填） |
项 值|
运行形态 ☐ Android 原生（Compose / View） ☐ WebView + H5 ☐ AutoX.js `ui` 模块 ☐ 其他：\_\_\_\_|
目标 TikTok 版本 \_\_\_\_|
卡密校验接口 \_\_\_\_（地址 / 方法 / 请求体 / 返回结构 / 错误码）|
权限申请方式 无障碍：跳系统设置？悬浮窗：`ACTION_MANAGE_OVERLAY_PERMISSION`？|
脚本执行与日志回传 AutoX 事件/回调 结构 \_\_\_\_|
记录与配置的本地存储 \_\_\_\_（SQLite / JSON / MMKV）|
结果文件落点 \_\_\_\_（目录 / 命名规则 / 是否需上传）|
更新检查接口 \_\_\_\_（软件更新 / 脚本更新）|
TikTok 客户端下载源 \_\_\_\_
## §8 分批实施顺序（建议） |
批次 内容 验收|
**第 1 批 · 静态壳** A1–A4、B1/B2、C1–C9、D1–D3、E1/E2、F1–F5 的页面与导航 + §6 令牌 能点着走完全部页面，视觉对齐画布|
**第 2 批 · 状态与规则** §2.3 全局状态机、§2.5 前置校验、§4 全部 15 条交互、5 类弹窗触发 每种状态都能触发到；互斥不破|
**第 3 批 · 业务** 卡密校验（A2/A3）、真实权限申请、脚本执行 + 日志流、结果文件落点、记录持久化 真机跑通一个完整任务每批完成后先出静态预览确认，再进下一批。
## §9 已知不一致与待确认项（开工前先过一遍） |
# 问题 建议|
1 **C6 与 C7 的「功能设置」字段集不同**：C6 是 `AI 性别 / 关注数量 / 私信数量 / 休息时间`，C7 是 `进行关注·进行私信 / 关注数量 / 私信数量 / 去重方式` 同一页不应有两套，需**二选一统一**（我倾向以 C7 为准，C6 补上开关与去重方式）|
2 **C1–C5 未在画布上加分组标注** 本规格书 §1 已说明；画布如需标注可另补|
3 **触控目标**：既有控件视觉高 26px \ 实现时热区撑到 44；若要视觉也放大需重排版式|
4 **E1 / 多个二级页内容余量很小**（E1 空闲态约 548/595） 运行中加运行条后余量更紧；已加底部渐隐，实现时按**可滚动**处理|
5 **未激活页签旧色 `#7A7794` 对比度 4.4:1** 未达 WCAG AA 已统一改为 `#8E8BA8`（5.6:1），实现时用新值|
6 **B1 任务卡的「上次运行/结果量」需要数据来源** 依赖任务层提供统计字段，需在 §7 里明确|
7 **多脚本并行不支持**（设计上就是全局单跑） 若未来要支持队列，需重新设计状态机|
8 **D3 日志的长列表** 日志可能很长，需虚拟滚动；已设计「复制」按钮
## 附：Ardot 设计文件节点索引（供查证）
A1 16:257 A2 16:1491 A3 16:288 A4 30:738 B1 30:102 B2 30:203 C1 3:1 C1r 16:138 C2 16:483 C3 16:589 C4 16:706 C5 16:965 C6 3:534 C7 7:11 C8 3:469 C9 3:629 D1 30:871 D2 30:958 D3 30:1241 E1 7:289 E2 16:850 F1 16:23 F2 16:319 F3 30:1005 F4 16:1360 F5 30:1119 组件母版： 底栏 任务激活 30:45 / 记录激活 30:64 / 我的激活 30:81 返回头 ID提取 30:1 / UID私信 30:7 / 养号 30:18 / 视频功能 30:29KS_DOC_REVIEWS JZf9xTgLXBFgjXJ4dJWVsU 140585 https://www.workbuddy.cn/space/d/JZf9xTgLXBFgjXJ4dJWVsU