多设备内容发布系统任务后台使用文档API 文档

人工测试清单

人工测试清单

本清单用于在项目后台逐项验证服务器、手机旁的控制电脑、Android 手机和 Control Agent。先完成“当前可测”的连接检查，再进行平台操作验证。

当前状态和安全边界

  • 服务器 HTTPS 入口已配置为 https://x.jishengai.com。项目后端端口 8002 仍可直接通过 HTTP 访问；公网 Control Agent 必须使用 HTTPS 域名，不能使用明文 HTTP 发送 Agent Token。
  • 仓库中的 devices/phone01.yaml 是禁用模板，adb_serial 也不是实际手机序列号。尚未配置有效的 Agent 节点 Token 和真实设备映射时，Dashboard 不会显示手机在线。
  • 服务器不需要直接接 USB 手机。手机接到 Windows/Mac/Linux 控制电脑，由 Control Agent 主动连接服务器。
  • Android 平台 Publisher 仍缺少经过实机验证的 App 启动信息、控件选择器和发布结果识别。连接测试通过不代表已经具备真实发布能力。
  • 全程只使用自己拥有、正常登录且已授权的测试手机和账号。遇到登录过期、验证码、人脸或风控提示立即停止，保留截图并转人工处理；不得尝试绕过验证。

测试结果记录方式

每项记录以下信息：测试编号、日期时间、操作电脑系统、设备编号、结果（通过/失败/阻塞）、现象、截图或日志路径。可将结果发给项目维护者；不要附上密码、Token、验证码或完整手机号。

A. 现在可做的连接检查

T-01：服务器 HTTPS 入口

目的： 确认 Agent 有可安全访问的服务器地址。

前置条件： 已配置二级域名或 VPN HTTPS 地址，TLS 证书有效，并转发至项目服务端口 8002。

步骤：

  1. 在手机旁的控制电脑浏览 https://x.jishengai.com/health。
  2. 预期返回 JSON：{"status":"ok"}，浏览器不提示证书错误。
  3. 再访问 https://x.jishengai.com/dashboard，应直接显示任务后台，不弹账号密码框。
  4. 不要用公网 http://129.226.213.58:8002 作为 Agent 地址，也不要在没有 TLS 的情况下传送节点 Token。

通过标准： HTTPS 证书有效；/health 返回正常；/dashboard 无需登录即可访问。

当前状态： 已配置并检查通过；仍需在控制电脑上确认浏览器/API 可访问。

T-02：USB 调试授权与 ADB 识别

目的： 确认控制电脑能通过 USB 识别并操作这台授权手机。

前置条件： 手机已解锁；控制电脑安装 Android Platform Tools；使用可传数据的 USB 线。

步骤：

  1. 在手机启用开发者选项和 USB 调试。
  2. 用 USB 连接手机，在手机弹窗中人工确认“允许 USB 调试”。
  3. 在控制电脑终端运行：

```bash adb start-server adb devices -l ```

  1. 找到对应设备序列号；设备状态必须是 device。
  2. 可进一步运行 adb -s <设备序列号> shell getprop ro.product.model，检查返回的型号确实是这台手机。

通过标准： 设备稳定显示为 device，型号与实体手机一致。

异常处理： unauthorized 时解锁手机并在手机上确认授权；未列出设备时检查数据线、USB 口及系统驱动。不要把真实序列号公开发到群聊或提交到公开仓库。

当前状态： 需要人工在手机旁的控制电脑执行。

T-03：控制电脑 Appium 服务

目的： 验证 Appium 2 和 UiAutomator2 driver 可访问 Android 手机。

前置条件： T-02 通过；控制电脑已安装 Python、Java/Android SDK、Appium 2 和 UiAutomator2 driver。

步骤：

  1. 在控制电脑运行 appium --address 127.0.0.1 --port 4723。
  2. 另开终端访问 http://127.0.0.1:4723/status。
  3. 确认返回 JSON 表示服务已就绪。
  4. 使用 Appium Inspector 或本项目会话检查流程连接授权手机，确认能读取界面层级并保存一张测试截图；本项只读取界面，不点击发布。

通过标准： Appium status 正常，UiAutomator2 能建立和关闭会话，测试截图可打开。

当前状态： 需要人工在控制电脑和手机上执行；不同 Android 版本可能还需安装 SDK 组件。

T-04：Control Agent 心跳

目的： 确认控制电脑能安全连接中央服务，且服务器能收到设备状态。

前置条件： T-01 至 T-03 通过；服务器已有与控制电脑一致的节点 ID/Token 和设备配置；控制电脑本地设备配置指向实际序列号及本机 Appium 地址。

步骤：

  1. 服务器设备配置中为手机设置唯一 device_id，例如 phone01，并设 enabled: true、control_node: office01、支持的平台和账号别名。
  2. 服务器 .env 中将节点 ID 映射到独立随机令牌：AGENT_TOKENS_JSON='{"office01":"替换为安全随机令牌"}'。实际令牌不要贴进测试反馈或提交 Git。
  3. 控制电脑 .env 设置 PUBLISHER_MODE=android、AUTO_CONFIRM_PUBLISH=false、AGENT_NODE_ID=office01、AGENT_SERVER_URL=https://x.jishengai.com、AGENT_TOKEN=同一节点令牌。
  4. 确保控制电脑的设备 YAML 使用同一 device_id 和 control_node，并填写本机 adb_serial 与 appium_url: http://127.0.0.1:4723。
  5. 保持手机解锁、Appium 运行，在控制电脑启动 Agent：Linux/macOS 执行 scripts/run_agent.sh；Windows PowerShell 执行 scripts/run_agent.ps1。
  6. 等待最多一个心跳超时时间（默认 45 秒），刷新服务器 Dashboard。

通过标准： Dashboard 显示该 device_id 在线、ADB 状态为 device、Appium 状态为 online，且最后心跳时间持续更新。没有创建任务，也没有发布内容。

排查顺序： 查看 Agent 终端日志 → 核对 HTTPS 地址 → 核对节点 ID/令牌 → 核对两端 device_id/control_node → 检查 ADB 授权 → 检查 Appium /status。

当前状态： Mac 节点 mac01 的 HTTPS 鉴权与 ADB 心跳已验证，phone01 可见且解锁。Appium 尚未配置，因此平台发布任务仍不可运行；Agent 当前可因 Mac 端进程退出而显示离线。

T-05：设备离线状态

目的： 检查控制电脑或手机断开时后台能否显示离线。

前置条件： T-04 通过；当前没有运行中的发布任务。

步骤：

  1. 先停止控制电脑上的 Agent（不要拔除正在执行任务的设备）。
  2. 等待超过 Agent 心跳超时值（默认 45 秒），刷新 Dashboard。
  3. 重新启动 Agent，等待心跳恢复。

通过标准： 心跳过期后设备显示离线；Agent 重启后状态恢复在线。

当前状态： T-04 通过后可测。

B. 素材传输检查

T-06：服务器素材可下载和手机端可见

目的： 验证服务器路径、Agent 下载和 ADB 推送的权限链路。

前置条件： T-04 通过；使用不含敏感信息的测试图片；素材位于服务器 MEDIA_ROOT 内；仅对已授权测试设备执行。Control Agent 支持 transfer_only: true 素材测试任务，该模式不需要 Appium，不启动平台 App，也不会发布。

步骤：

  1. 确认服务器素材可读。当前测试图片绝对路径：/home/makemoney/ai-social-publisher/media/incoming/phone01_transfer_test.png。
  2. 确认 Dashboard 显示 phone01 在线；无需安装或启动 Appium。
  3. 向 POST https://x.jishengai.com/jobs 提交以下 JSON。该网址无需账号密码；请求使用 HTTPS。

```json { "platform": "transfer_test", "device_id": "phone01", "content_type": "image_post", "media_files": ["/home/makemoney/ai-social-publisher/media/incoming/phone01_transfer_test.png"], "title": "phone01 ADB 素材传输验证", "transfer_only": true } ```

  1. Dashboard 状态应依次由 PENDING 进入执行状态，并最终显示 素材传输测试通过（API 状态名 TRANSFER_TEST_PASSED）。任务详情会列出手机上的唯一文件名。
  2. 在 Mac 终端检查文件：

```bash adb -s <Mac上显示的设备序列号> shell ls -l /sdcard/DCIM/AI_PUBLISH/ ```

  1. 手机上打开文件管理器/相册，确认测试图片可见、可打开。确认后可人工删除这张测试图片。

通过标准： Agent 报告 TRANSFER_TEST_PASSED，手机端文件非空且可打开；测试期间未打开平台 App，也没有发布。

当前状态： 2026-09-27 已通过。服务器任务 1 状态为 TRANSFER_TEST_PASSED，Agent 在 vivo V2324A 上完成测试图片 ADB 推送与非空校验；用户确认图片已到手机。测试未启动平台 App、未发布内容。平台 Appium 流程仍未验证。

C. 平台发布测试（目前阻塞）

T-07：自动打开平台并准备草稿

目的： 在授权测试账号上验证平台专属页面操作。

当前阻塞： Douyin、小红书、视频号的 App 包名/启动 Activity、页面选择器、素材选择和表单填充仍是未实测骨架。现阶段即使 T-04 在线，真实 Android Publisher 也会在未实现步骤停止，不能据此判定发布链路通过。

解除阻塞后步骤： 使用 Appium Inspector 检查已登录测试账号的页面；按项目约定更新 selectors/<platform>.yaml；验证启动 App、进入发布页、选择测试素材、填写标题/正文/标签、设置封面。全过程保持 AUTO_CONFIRM_PUBLISH=false，核对设备画面和服务器截图。

通过标准： 任务进入 WAITING_CONFIRM，手机停在最终发布操作之前，后台保存的截图显示账号、素材和文案均正确。

禁止事项： 不测试也不尝试绕过验证码、人脸、登录验证或风控；遇到这些情况停止并转人工。

T-08：人工确认与结果回传

当前阻塞： 必须先完成 T-07，并明确授权使用测试账号发布一条测试内容后才可执行。本项目默认不自动确认，也不能把 Mock 的 SUCCESS 当成真实发布成功。

解除阻塞后步骤： 操作员检查待确认任务与截图；点击“确认发布”；人工在平台页面核对是否确实发布；检查服务器任务状态、结果截图及 Agent 最终状态是否一致。

通过标准： 仅在平台端实际确认成功后记录成功；如果页面结果不确定，使用 NEEDS_HUMAN，不得自动再次点击发布。

D. 扩展测试

T-09：7 台设备并行心跳和隔离

目的： 验证同一控制电脑最多管理 7 台设备且同设备任务互斥。

前置条件： 至少两台、最终七台授权 Android 手机及有效 USB 连接；每台有唯一 device_id，每台账号/平台映射经过核对。

步骤： 先同时启动多个设备心跳，检查 Dashboard 所有设备状态；后续仅使用 Mock 或不触发发布点击的安全测试任务验证不同设备可并发、同一设备不可重复认领。不得用七台设备同时发布公开内容作为首次并发测试。

通过标准： 各设备心跳独立更新；同一 device_id 同时最多关联一个活动任务。

当前状态： 需有多台实体手机；Mock 并发另由自动化测试覆盖。

测试反馈模板


测试编号：T-__
日期时间：
控制电脑系统：Windows / macOS / Linux
设备编号：
结果：通过 / 失败 / 阻塞
实际现象：
错误提示（请先移除 Token、密码、手机号等敏感信息）：
截图或日志文件名：