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

Control Agent（Mac/手机控制端）

下载当前 Mac Control Agent 项目包（不含服务器 .env、节点 Token、SQLite 数据库及运行日志）。

Control Agent：Mac 手机控制端

Control Agent 运行在手机旁边的 Mac 上。手机通过 USB 接 Mac，由 Mac 本地 ADB 控制；Agent 主动通过 HTTPS 连接服务器、领取指定任务、下载服务器素材并回传心跳、状态和截图。服务器不需要直接连接手机，也不需要开放 ADB 端口。

当前 Mac 安装包

浏览器可从项目使用说明页点击“下载 Mac Control Agent 项目包”，也可直接下载：

https://x.jishengai.com/downloads/ai-social-publisher-mac-agent-2026-09-27.tar.gz

这是完整项目源码包，含 Python 依赖清单、安装脚本、Mac Agent 配置模板和启动脚本。运行 scripts/install_mac_agent.sh 会创建项目虚拟环境并通过 pip 安装依赖，因此安装时 Mac 需要访问 Python 包源。安装包不含服务器 .env、节点 Token、SQLite 数据库、运行日志或虚拟环境。

素材传输受单文件 5 GiB、单任务合计 8 GiB、每任务 20 个文件的默认限制约束。Mac Agent 会在成功、失败、取消或传输测试通过满 168 小时后清理该任务的本地下载素材；NEEDS_HUMAN 的缓存、截图、日志、数据库和服务器源素材会保留。

远程 UI 自动化任务默认有 900 秒执行时限（AGENT_JOB_TIMEOUT_SECONDS），超时后最多等待 5 秒协作停止（AGENT_CANCEL_GRACE_SECONDS）。Agent 会将任务报为 NEEDS_HUMAN，并在本机持久化隔离该设备；Agent 重启后仍不会给该手机分配新任务。已下发到 Appium 的当前操作无法被 Python 强行撤销，超时后需人工检查手机及平台状态。确认安全后，在 Mac 项目根目录执行以下命令解除隔离：


.venv/bin/python scripts/release_agent_device.py phone01 --confirm-manual-inspection

解除前务必人工确认当前页面、登录状态和是否已发生发布；不要只为恢复队列而直接清除隔离。

Mac 安装

要求 macOS、Python 3.11+、Android Platform Tools。此处进行 transfer_only 素材传输测试时无需 Node、Java 或 Appium。若缺少依赖，可使用 Homebrew 安装：


brew install python@3.12 android-platform-tools age

下载并解压项目包后：


tar -xzf ai-social-publisher-mac-agent-2026-09-27.tar.gz
cd ai-social-publisher
./scripts/install_mac_agent.sh
cp deploy/agent/macos/phone01.yaml.example devices/phone01.yaml
adb devices -l

手机需要保持解锁，并由操作员在手机上确认 USB 调试授权。adb devices -l 中目标设备状态必须为 device，不能是 unauthorized 或 offline。

编辑 devices/phone01.yaml，把 REPLACE_WITH_MAC_ADB_SERIAL 替换为 Mac 上显示的真实 USB 序列号。device_id 保持 phone01，control_node 保持 mac01。

节点配置与凭证

.env 中需要设置：


PUBLISHER_MODE=android
AUTO_CONFIRM_PUBLISH=false
AGENT_NODE_ID=mac01
AGENT_SERVER_URL=https://x.jishengai.com
AGENT_TOKEN=由服务器加密交付的节点令牌
DEVICE_CONFIG_DIR=devices
AGENT_POLL_SECONDS=2
AGENT_WORK_DIR=./agent-data

服务器 Token 不应放入项目包、Git、命令行参数或 launchd plist。推荐在 Mac 生成 age 密钥，将公钥交给服务器管理员；管理员用该公钥加密 agent-mac01.env 后交付。Mac 用私钥解密：


mkdir -p ~/.config/age
chmod 700 ~/.config/age
age-keygen -o ~/.config/age/keys.txt
chmod 600 ~/.config/age/keys.txt
age-keygen -y ~/.config/age/keys.txt
age -d -i ~/.config/age/keys.txt agent-mac01.env.age > .env
chmod 600 .env

只把 age-keygen -y 输出的 age1... 公钥交给管理员；私钥和解密后的 .env 留在 Mac。服务端设备 phone01 的 control_node 必须与 AGENT_NODE_ID 相同，节点 ID 与令牌映射也必须一致。

启动与状态确认


./scripts/start_mac_agent.sh

启动后访问 https://x.jishengai.com/dashboard，确认 phone01 心跳在线。前台启动的终端关闭后 Agent 会退出。需要后台登录自启动时，按 deploy/agent/macos/README.md 安装 launchd LaunchAgent；launchd 需要用户登录会话，不会绕过 USB 授权或锁屏验证。

仅测试 ADB 素材传输

使用传输测试任务时必须设置 transfer_only: true。该执行分支只从服务器下载任务素材、用 ADB 推送到手机、检查目标文件存在，然后返回 TRANSFER_TEST_PASSED。它不启动平台 App、不创建 Appium session、不点击发布按钮。

服务器测试图片：

/home/makemoney/ai-social-publisher/media/incoming/phone01_transfer_test.png

创建测试任务示例：


{
  "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
}

通过 POST https://x.jishengai.com/jobs 创建任务。成功后在 Mac 验证：


adb -s <vivo的ADB序列号> shell ls -l /sdcard/DCIM/AI_PUBLISH/

测试图采用唯一任务文件名推送。完成后可在手机相册或文件管理器中人工删除。

故障排查

  • 设备显示 agent_offline：检查 Mac Agent 进程、HTTPS 连通性、AGENT_NODE_ID 和 Token 配置。
  • adb unauthorized：解锁手机并人工接受 USB 调试授权；不要尝试自动化绕过。
  • Agent 在线但没有领取任务：核对 device_id、control_node、启用状态及任务计划时间。
  • 素材下载失败：确保素材绝对路径位于服务器 MEDIA_ROOT 中且服务可读。
  • 查看 Agent 运行日志：前台终端输出，或 launchd 的 logs/agent.stdout.log 和 logs/agent.stderr.log。

遇到验证码、人脸、登录失效、风控或结果不确定时停止操作并由人工处理。不要对这些状态自动重试。