1 先认识客户端 一个客户端进程同时只执行一条任务;空闲时每 10 秒拉取,执行期仍每 10 秒心跳。 超过 30 秒没有心跳,服务端判定离线并回收其运行中的任务。
浏览器 任务 / 客户端 / 设置
↓ HTTP 同源
服务端 API 任务调度 · 状态机 · 用量 · /downloads
↓ 注册 / 心跳 / 认领 / 结果(AK/SK 签名)
执行机 · task_client 子进程 shell=False
↓ argv
AI CLI codebuddy / hermes
浏览器 任务 / 客户端 / 设置 Web UI 服务端 API 任务调度 · 状态机 · 用量 /api/* · /downloads/* MySQL 任务 / 消息 / 客户端 / 用量 执行机 task_client 注册 / 心跳 / 拉取 / 上报 AI CLI codebuddy / hermes 子进程 shell=False HTTP 同源 页面 / 接口 AK/SK 签名 认领 / 心跳 / 结果 argv 最短路径: 执行机已装好 Python 与 AI CLI 时,跑第 4 节的一条一键命令 → 在启动目录的 .env 填入 AK/SK → 运行 task-client, 页面「客户端」显示在线即可。
2 系统最低配置要求 客户端本身很轻,主要资源消耗来自任务调用的 AI CLI 和项目构建。下表是执行机的最低要求与推荐配置。
项目 最低要求 推荐 说明 操作系统 Windows 10 / 11(x64)、Linux x86_64 同左 两种系统均提供一键安装脚本;macOS 可按源码方式运行,但未单独验证。 Python 3.10 3.13 wheel 声明 requires-python ≥ 3.10;当前实测版本为 3.13。 CPU 2 核 4 核及以上 客户端空闲几乎不占 CPU;编译、测试类任务由 AI CLI 与项目本身消耗。 内存 2 GB 可用 4 GB 及以上 实测客户端空闲常驻约 45 MB(不含 AI CLI 子进程与项目构建)。 磁盘 300 MB 可用 1 GB 以上 虚拟环境与依赖约百 MB;任务工作目录、构建产物与输出另计。 网络 可访问 SERVER_URL 内网 / VPN 服务端默认只监听 127.0.0.1;跨机部署需调整监听并限制来源。 AI CLI codebuddy 或 hermes 已安装并登录 使用专用低权限账号 必须对运行客户端的账号可见;Windows 不接受 .cmd/.bat,需 .exe 或同名 .ps1。 脚本环境 Windows:PowerShell 5.1+;Linux:Bash + curl Windows:PowerShell 7.x 仅一键安装脚本需要;wheel 安装后直接运行 task-client 不受限制。
AI CLI 必须先登录。 客户端以运行账号的身份执行子进程,CLI 的登录态就是该账号的权限。 建议使用专用低权限账号,并在同一账号下先手动跑一次 codebuddy -p "你好" 确认可用。
安装前自查
PowerShell 复制
python --version
Get-Command codebuddy
Invoke-RestMethod http://127.0.0.1:8000/api/health | ConvertTo-Json3 下载渠道说明 本项目不提供 exe / msi 安装包或应用商店分发。客户端以 Python wheel 或源码目录交付, 下载后按第 4 节一键安装,或按第 5 节分步安装。
服务端内置下载 · 推荐
task_client-1.0.0-py3-none-any.whl
版本 v1.0.0 约 32 KB Python wheel(py3-none-any)
文件由服务端静态托管在 /downloads/ 下,执行机能访问服务端即可下载。 文件名中的版本号以实际构建产物为准。
固定地址(latest): task_client-latest-py3-none-any.whl 永远指向最新版本,URL 不随版本号变化,适合写进脚本或文档。浏览器点「下载 latest」会自动 重命名为 task_client-1.0.0-py3-none-any.whl;/downloads/latest.txt 是给一键脚本用的指针文件,内容就是当前版本 wheel 的文件名。 注意: latest 不是合法版本号,直接对固定名副本执行 pip install 会被 pip 拒绝,请用第 4 节的一键脚本,或按 latest.txt 重命名后再安装。
命令行下载
PowerShell 复制
New-Item -ItemType Directory -Force D:/task-client | Out-Null
Invoke-WebRequest -Uri "https://worker.aiho.net/downloads/task_client-1.0.0-py3-none-any.whl" -OutFile "D:/task-client/task_client-1.0.0-py3-none-any.whl"Bash(Linux / macOS) 复制
curl -fsSL "https://worker.aiho.net/downloads/task_client-1.0.0-py3-none-any.whl" -o "task_client-1.0.0-py3-none-any.whl"推荐 服务端内置下载 服务端构建时已把 wheel、latest 固定名副本与一键安装脚本发布到静态目录,执行机能访问服务端即可直接下载。
适用:执行机与服务器同机或同内网
源码 源码目录运行 复制整个 client/ 目录或 clone 仓库,在目标机创建虚拟环境并安装 requirements。
适用:开发调试、内网拷贝、需要改客户端
离线 离线介质拷贝 在联网机下载 wheel 或打包 client/ 目录,用 U 盘或共享盘复制到执行机。
适用:执行机无法访问外网
从源码构建 wheel
需要自行分发时,在任意一台有 Python 环境的机器上构建。构建产物是纯 Python wheel, 可复制到同版本 Python 3.10+ 的机器使用。
PowerShell 复制
cd D:/code/task_engine/client
python -m pip install build
python -m build --wheel --outdir dist离线安装
wheel 不内置第三方依赖。执行机不能访问 PyPI 时,先在联网机把 wheel 与依赖一起下载,再整体拷贝。
PowerShell 复制
# 联网机:下载 wheel 与全部依赖
python -m pip download -r client/requirements.txt -d ./offline-pkgs
# 离线执行机:从本地目录安装
python -m pip install --no-index --find-links ./offline-pkgs ./task_client-1.0.0-py3-none-any.whl 服务端部署脚本 deploy/deploy-build-client.sh 会在构建时自动生成 wheel、 task_client-latest-py3-none-any.whl、latest.txt 与两个一键安装脚本, 清理旧版本并发布到 backend/app/static/downloads/,无需手工拷贝。
4 一键安装(推荐) 服务端已把安装脚本与 wheel 一起发布。执行机装好 Python 3.10+ 后,复制下面一条命令即可完成 下载、建虚拟环境、安装并生成 .env 模板;重复执行即为升级, 已有配置与客户端身份不会被覆盖。
Linux(Bash)
Bash 复制
curl -fsSL https://worker.aiho.net/downloads/install-linux.sh | bashWindows(PowerShell 5.1+)
PowerShell 复制
irm https://worker.aiho.net/downloads/install-windows.ps1 | iex想先审阅脚本再运行
Bash 复制
curl -fsSL https://worker.aiho.net/downloads/install-linux.sh -o install-linux.sh
less install-linux.sh
bash install-linux.shPowerShell 复制
irm https://worker.aiho.net/downloads/install-windows.ps1 -OutFile install-windows.ps1
notepad .\install-windows.ps1
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1可覆盖的环境变量
变量 默认值 说明 TASK_CLIENT_BASE_URL https://worker.aiho.net/downloads 脚本内默认值;页面上的一键命令已自动改用当前访问地址 https://worker.aiho.net/downloads TASK_CLIENT_HOME Linux $HOME/task-client Windows %LOCALAPPDATA%\task-client 安装目录;venv、.env 与身份文件都放在这里 TASK_CLIENT_PYTHON 自动探测 显式指定 Python 解释器;Windows 默认优先用 py -3 PIP_INDEX_URL PyPI 国内可设为清华镜像;升级时脚本不会重装已有依赖
Bash(自定义示例) 复制
# 自定义安装目录、下载地址与 pip 镜像(export 后管道里的 bash 才能继承)
export TASK_CLIENT_HOME=/opt/task-client
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
curl -fsSL https://worker.aiho.net/downloads/install-linux.sh | bashPowerShell(自定义示例) 复制
$env:TASK_CLIENT_HOME = "D:\task-client"
$env:PIP_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
irm https://worker.aiho.net/downloads/install-windows.ps1 | iex 脚本先读 /downloads/latest.txt 拿到当前版本 wheel 的真实文件名,再交给 pip 安装,因此版本升级后 URL 与脚本都不用改。默认安装目录分别是 $HOME/task-client 与 %LOCALAPPDATA%\task-client; 安装完成按提示填写 AK/SK 后运行对应目录下的 task-client 即可。
安全提示: 以上一键命令通过 HTTP 明文下载并直接执行远程脚本,等价于把执行机的 控制权交给该下载地址。请仅在可信任的内网/服务器使用,生产环境建议改 HTTPS, 或采用上面的「下载后审阅再运行」;同时确认 /downloads/latest.txt 返回的是 wheel 文件名而不是 HTML 页面。
5 分步安装向导 Linux 执行机建议直接用第 4 节的一键脚本。下面以 Windows + PowerShell 为例, 选择 wheel 安装(执行机推荐)或源码安装(开发推荐),命令会随选择切换; Linux 需把解释器换成 venv/bin/python、启动器换成 venv/bin/task-client。
① 获取安装包 → ② 创建虚拟环境 → ③ 安装依赖 → ④ 写入配置 → ⑤ 启动验证
1 获取安装包 wheel 方式从第 3 节下载;源码方式把仓库放到执行机,例如 D:/code/task_engine。
PowerShell 复制
New-Item -ItemType Directory -Force D:/task-client | Out-Null
Invoke-WebRequest -Uri "https://worker.aiho.net/downloads/task_client-1.0.0-py3-none-any.whl" -OutFile "D:/task-client/task_client-1.0.0-py3-none-any.whl"2 创建虚拟环境 使用独立虚拟环境,避免污染系统 Python。wheel 方式建议单独建目录,便于升级与卸载。
PowerShell 复制
cd D:/task-client
python -m venv venv3 安装客户端 安装 wheel 及其依赖。 国内网络可在 pip 命令后追加 -i https://pypi.tuna.tsinghua.edu.cn/simple。
PowerShell 复制
cd D:/task-client
./venv/Scripts/python.exe -m pip install --upgrade pip
./venv/Scripts/python.exe -m pip install D:/task-client/task_client-1.0.0-py3-none-any.whl4 验证安装 能输出版本号 1.0.0 即表示包已正确安装。
PowerShell 复制
cd D:/task-client
./venv/Scripts/python.exe -c "import task_client; print(task_client.__version__)"5 写入首次配置 在启动目录 创建 .env:wheel 方式是 D:/task-client/.env,源码方式是 client/.env。 必填项与服务端地址见第 6 节。
6 启动客户端 首次建议前台运行,直接观察注册与拉取日志;确认在线后再改为后台或计划任务。
PowerShell 复制
cd D:/task-client
./venv/Scripts/task-client.exe启动成功的日志
日志样例 复制
客户端启动 client_id=... server=http://127.0.0.1:8000 name=...
注册成功 name=... poll=10.0s heartbeat=10.0s offline=30s
开始任务 task_id=12 message_id=34 model=deepseek-v4.1-flash workdir=...
结果已上报 task_id=12
任务结束 task_id=12 exit_code=0 duration_ms=12347 核心功能操作指引 下面是日常使用频率最高的操作与规则。所有数据按账号隔离,越权访问按 id 一律返回 404。
常用操作速查
我想… 操作路径 新建任务 任务 → 新建任务 查看对话 / 继续追问 任务详情 → 对话 停止执行中的任务 任务列表或详情 → 停止 批量重试失败任务 勾选 failed / cancelled → 批量重试 批量删除任务 勾选任务 → 批量删除(running 会跳过) 查看在线节点 顶部导航 → 客户端 创建 AK/SK 个人中心 → 开放接口密钥 配置完成通知 设置 → 任务完成通知 保存常用工作路径 设置 → 常用工作路径 查看用量与成本 个人中心 → 用量与成本 调试开放接口 顶部导航 → 接口文档
任务字段
字段 必填 说明 任务提示词 是 交给 AI 执行的内容,最多 200,000 字符。 Agent 否 执行 CLI,默认 codebuddy,也可选 hermes。 期望模型 否 auto(不指定,用 CLI 默认)、default(Agent 默认)、pool(按策略调度)或具体模型名。 任务工作路径 否 执行机本地路径;留空使用客户端 DEFAULT_WORKDIR。 指定客户端 否 留空进入共享池;填写 client_id 后只允许该节点认领。 任务参数 否 参数名以 - 或 -- 开头;--model、--session-id 等系统参数由客户端拼装,禁止手填。 超时(秒) 否 默认 14400 秒,范围 5 ~ 86400。
任务状态流转
pending 新建 → running 执行中 → success 成功
failed 失败 cancelled 已取消 → 手动重试回到 pending
超时 / 客户端离线 → 自动重试(默认 2 次,退避 30s、60s)→ pending
多轮对话 打开任务详情 →「对话」发送新消息。首轮建立会话,续轮自动使用 --resume 继承上下文;上一轮未结束时输入框禁用,接口返回 409。
停止、重试与删除 pending 可立即取消;running 先标记取消请求,客户端每 2 秒轮询并终止进程树。 failed / cancelled 可批量重试;running 任务不能删除,但可以停止。
客户端管理 「客户端」页 10 秒刷新一次,展示在线状态、最近心跳、CPU/内存、运行任务数。 可创建分组并在表格中直接调整归属;多开时每个实例必须使用不同 STATE_FILE。
模型池与熔断 auto 不指定模型,default 用 Agent 默认模型, pool 按优先级或权重调度。连续失败 3 次默认熔断 4 小时, 可在「模型」页手动解除;熔断只影响 pool。
用量与通知 「个人中心 → 用量与成本」按日、模型、任务汇总 token 与费用; 「设置」可配置飞书、企业微信或通用 Webhook,仅在任务进入终态时发送。
常用工作路径 「设置 → 常用工作路径」保存后,新建任务时可直接选择。路径是执行机本地路径, 服务端只做格式校验,是否存在由客户端执行前校验。
需要程序化创建任务或查询结果时,使用「接口文档」页的 AK/SK 签名生成器与代码示例; Web 登录态使用 Authorization: Bearer <token>。
8 常见问题排查 FAQ 先看客户端日志,再看任务详情的 error_code、stdout 与 stderr。 源码方式日志在 logs/client.out.log 与 logs/client.err.log; wheel 方式前台运行时直接看控制台。
查看客户端日志(源码方式) 复制
Get-Content logs/client.out.log -Tail 50
Get-Content logs/client.err.log -Tail 50现象: 进程打印 ValidationError,还没注册就结束。
原因: 启动目录没有 .env,或缺少 SERVER_URL / ACCESS_KEY / SECRET_KEY。
处理: 在启动目录创建 .env 并补齐三项。wheel 方式读取启动目录的 .env,不是 client/.env;也可用环境变量 TASK_CLIENT_ENV_FILE 指定路径。
现象: 注册请求被服务端拒绝,客户端退出或反复重试。
原因: AK/SK 错误、密钥已撤销,或本机时间与服务器相差超过 300 秒。
处理: 到「个人中心 → 开放接口密钥」重新创建并更新 .env;校对系统时间。401/403 不会无限重试。
现象: 健康状态没有在线节点,任务无人认领。
原因: 客户端未启动、注册失败、网络不通,或 SERVER_URL 写错。
处理: 前台启动看日志;用 Invoke-RestMethod 访问 /api/health;确认服务端地址、端口与防火墙。
现象: 任务 pending,客户端空闲。
原因: 任务指定了其他客户端,或任务属于另一个账号。
处理: 检查任务「指定客户端」;共享池任务任何在线节点都能认领;确认当前账号下能看到该任务。
现象: 客户端上报可执行文件未找到。
原因: 运行客户端的账号 PATH 中没有 codebuddy/hermes,或 CLI 未安装。
处理: 用同一账号执行 Get-Command codebuddy;安装并登录后重启客户端继承新 PATH。Windows 不接受 .cmd/.bat,需 .exe 或同名 .ps1。
现象: 进程没有启动,直接上报路径无效。
原因: 任务工作路径不存在、不是目录,或 DEFAULT_WORKDIR 指向不存在的目录。
处理: 修正任务工作路径或客户端 DEFAULT_WORKDIR。路径是执行机本地路径,服务端只做格式校验。
现象: 状态长时间不变,进程也未退出。
原因: 客户端被强杀或断网,CLI 卡死,取消标志无人消费。
处理: 等待 30 秒离线回收;客户端恢复后会按取消标志落 cancelled;必要时缩短任务超时。
现象: 任务失败后停在 failed,没有回到 pending。
原因: 错误码不在白名单、已达最大重试次数,或 AUTO_RETRY_MAX=0。
处理: 默认仅 timeout / worker_lost 自动重试 2 次,退避 30s / 60s;检查服务端 .env 与任务详情里的 retry_count。
现象: 客户端列表出现重复节点,任务互相抢占。
原因: 多个实例共用同一个 .client_state.json,或复制了身份文件。
处理: 每个实例使用不同启动目录,或显式配置不同 STATE_FILE;身份文件不要跨机器复制。
现象: 任务详情 stdout 中间出现省略标记,或中文显示异常。
原因: 输出超过 MAX_OUTPUT_CHARS 保留头尾,或 CLI 输出编码不是 UTF-8。
处理: 默认上限 200,000 字符,可按需调大;客户端按 UTF-8 → GBK → replace 解码,尽量让 CLI 输出 UTF-8。
现象: 注册超时或连接被拒绝。
原因: 服务端默认只监听 127.0.0.1,其他机器无法访问。
处理: 优先同机部署或走内网 / VPN;确需监听内网时改为内网 IP:8000,并限制防火墙来源,不要直接暴露公网。
现象: 「客户端」页的版本号没有变化。
原因: 旧进程仍在运行,或 wheel 没有重新安装。
处理: 停止旧客户端 → 安装新 wheel → 重新启动。版本号来自客户端包版本与 CLIENT_VERSION。
现象: 脚本提示 latest.txt 内容异常,或提示下载内容不是 wheel。
原因: 下载目录缺少发布产物;服务端 SPA 兜底对不存在的路径返回 index.html 且 HTTP 200,看起来像下载成功。
处理: 在服务器重新执行 deploy/deploy-build-client.sh 发布 wheel、latest.txt 与两个安装脚本;确认 /downloads/latest.txt 返回的是 wheel 文件名而不是 HTML。
现象: 对 task_client-latest-py3-none-any.whl 执行 pip install 时提示 invalid version。
原因: latest 不是合法的 PEP 440 版本号;固定名副本只是下载别名,不是可直接安装的 wheel 名。
处理: 用一键脚本安装(它会读 latest.txt 拿到真实文件名),或把下载的文件重命名为 latest.txt 中的内容后再 pip install。
仍然无法定位时,按顺序确认三件事:服务端 /api/health 是否正常、 客户端日志是否「注册成功」、同一账号下 Get-Command codebuddy 是否可用。
9 卸载步骤说明 卸载只影响执行机上的客户端,不会删除服务端的任务、消息与用量数据。 顺序建议:停进程 → 撤销密钥 → 删除配置与身份 → 删除虚拟环境。
1 停止客户端 前台运行按 Ctrl+C;后台或 wheel 方式按进程结束。
PowerShell(wheel) 复制
Get-Process task-client -ErrorAction SilentlyContinue | Stop-Process -Force2 撤销 AK/SK 在「个人中心 → 开放接口密钥」撤销该执行机使用的密钥,撤销后旧凭据立即失效。 如果还要重装同一节点,可保留密钥并跳过这一步。
3 删除配置与客户端身份 删除 .env 与 .client_state.json。删除身份后再次启动会以新 client_id 注册;旧节点记录会保留在「客户端」列表中并显示离线。
PowerShell(wheel) 复制
Remove-Item D:/task-client/.env -ErrorAction SilentlyContinue
Remove-Item D:/task-client/.client_state.json -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force D:/task-client/venv4 删除程序与安装包 wheel 方式删除整个安装目录即可;源码方式删除 client/venv。 如果曾全局安装过包,再执行 python -m pip uninstall task-client。
5 检查开机自启 本项目默认不写注册表、不创建计划任务。如果你手工加过「任务计划程序」或服务, 在对应的系统设置中删除即可。
卸载前确认没有排队中或执行中的任务;强制结束客户端会让运行中的任务在 30 秒后被服务端判定 worker_lost。如需保留任务历史,请勿删除服务端数据库。