帮助中心 · 执行客户端

客户端安装与使用指南

服务端只负责任务调度与记录,真正执行命令的是执行机上的 task_client。本文覆盖 Windows 与 Linux 执行机的下载、一键安装、首次配置、核心操作、故障排查与卸载。

适用版本 v1.0.0Windows / Linux 一键安装约 3 分钟完成首次接入
下载客户端
1

先认识客户端

一个客户端进程同时只执行一条任务;空闲时每 10 秒拉取,执行期仍每 10 秒心跳。 超过 30 秒没有心跳,服务端判定离线并回收其运行中的任务。

浏览器任务 / 客户端 / 设置
↓ HTTP 同源
服务端 API任务调度 · 状态机 · 用量 · /downloads
↓ 注册 / 心跳 / 认领 / 结果(AK/SK 签名)
执行机 · task_client子进程 shell=False
↓ argv
AI CLIcodebuddy / hermes
浏览器任务 / 客户端 / 设置Web UI服务端 API任务调度 · 状态机 · 用量/api/* · /downloads/*MySQL任务 / 消息 / 客户端 / 用量执行机task_client注册 / 心跳 / 拉取 / 上报AI CLIcodebuddy / hermes子进程 shell=FalseHTTP 同源页面 / 接口AK/SK 签名认领 / 心跳 / 结果argv
10s
空闲拉取间隔
10s
心跳间隔
30s
无心跳判定离线
1
单进程并发任务数
最短路径:执行机已装好 Python 与 AI CLI 时,跑第 4 节的一条一键命令 → 在启动目录的 .env 填入 AK/SK → 运行 task-client, 页面「客户端」显示在线即可。
2

系统最低配置要求

客户端本身很轻,主要资源消耗来自任务调用的 AI CLI 和项目构建。下表是执行机的最低要求与推荐配置。

项目最低要求推荐说明
操作系统Windows 10 / 11(x64)、Linux x86_64同左两种系统均提供一键安装脚本;macOS 可按源码方式运行,但未单独验证。
Python3.103.13wheel 声明 requires-python ≥ 3.10;当前实测版本为 3.13。
CPU2 核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 CLIcodebuddy 或 hermes 已安装并登录使用专用低权限账号必须对运行客户端的账号可见;Windows 不接受 .cmd/.bat,需 .exe 或同名 .ps1。
脚本环境Windows:PowerShell 5.1+;Linux:Bash + curlWindows: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-Json
3

下载渠道说明

本项目不提供 exe / msi 安装包或应用商店分发。客户端以 Python wheel 或源码目录交付, 下载后按第 4 节一键安装,或按第 5 节分步安装。

服务端内置下载 · 推荐
task_client-1.0.0-py3-none-any.whl
版本 v1.0.0约 32 KBPython 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 | bash
Windows(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.sh
PowerShell
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_URLhttps://worker.aiho.net/downloads 脚本内默认值;页面上的一键命令已自动改用当前访问地址 https://worker.aiho.net/downloads
TASK_CLIENT_HOMELinux $HOME/task-client
Windows %LOCALAPPDATA%\task-client
安装目录;venv、.env 与身份文件都放在这里
TASK_CLIENT_PYTHON自动探测显式指定 Python 解释器;Windows 默认优先用 py -3
PIP_INDEX_URLPyPI国内可设为清华镜像;升级时脚本不会重装已有依赖
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 | bash
PowerShell(自定义示例)
$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。

独立目录 D:/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 venv
3

安装客户端

安装 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.whl
4

验证安装

能输出版本号 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=1234
6

首次初始化配置

顺序是:注册账号 → 创建 AK/SK → 写客户端配置 → 启动 → 在页面确认在线 → 建一个任务验证闭环。

1

注册并登录服务端

浏览器打开服务端地址,首次使用切到「注册」。系统第一个账号会自动接管升级前遗留的无归属任务, 后续账号的数据彼此隔离。

2

创建 AK/SK

进入「个人中心 → 开放接口密钥」创建一对密钥。Secret Key 只显示一次,立即保存;泄露后在同一个页面撤销。

3

写客户端配置

在启动目录新建 .env。最小配置只有三项;其余按需填写。

.env
# 必填
SERVER_URL=http://127.0.0.1:8000
ACCESS_KEY=AK...
SECRET_KEY=...

# 可选
CLIENT_NAME=build-node-1
DEFAULT_WORKDIR=D:/code/your-project
LOG_LEVEL=INFO

源码方式可执行 Copy-Item client/.env.example client/.env 后再编辑。

常用配置项
变量必填说明
SERVER_URL是服务端地址。同机填 http://127.0.0.1:8000;跨机填内网地址。
ACCESS_KEY是在「个人中心 → 开放接口密钥」创建,通常以 AK 开头。
SECRET_KEY是创建时只显示一次,丢失只能重建;泄露后立即撤销。
CLIENT_NAME否客户端展示名称,默认使用主机名。
DEFAULT_WORKDIR否任务未指定工作路径时使用,默认是客户端启动目录。
STATE_FILE否客户端身份文件,默认是启动目录下的 .client_state.json。
POLL_INTERVAL否空闲拉取间隔,默认 10 秒;注册成功后由服务端下发覆盖。
HEARTBEAT_INTERVAL否心跳间隔,默认 10 秒;注册成功后由服务端下发覆盖。
LOG_LEVEL否日志级别,默认 INFO;排查问题时可临时改为 DEBUG。
配置文件查找顺序:环境变量 TASK_CLIENT_ENV_FILE → 启动目录 .env → 源码目录 client/.env。需要把配置放到别处时,启动前设置 $env:TASK_CLIENT_ENV_FILE = "D:/config/task-client.env"。
4

启动并确认在线

前台启动客户端,日志出现「注册成功」后,页面「客户端」应显示在线。 也可以用健康检查接口确认 clients_online 大于 0。

PowerShell
Invoke-RestMethod http://127.0.0.1:8000/api/health | ConvertTo-Json
5

创建第一个任务验证闭环

进入「任务 → 新建任务」,填写提示词,工作路径指向执行机上一个真实目录,超时先用默认 14400 秒。创建后观察状态从 pending → running → success。

安全边界:AK/SK 等同于执行凭据,只放在执行机的 .env,不要提交、 截图或共享;客户端用哪个账号运行,任务命令就拥有该账号的权限。
7

核心功能操作指引

下面是日常使用频率最高的操作与规则。所有数据按账号隔离,越权访问按 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
仍然无法定位时,按顺序确认三件事:服务端 /api/health 是否正常、 客户端日志是否「注册成功」、同一账号下 Get-Command codebuddy 是否可用。
9

卸载步骤说明

卸载只影响执行机上的客户端,不会删除服务端的任务、消息与用量数据。 顺序建议:停进程 → 撤销密钥 → 删除配置与身份 → 删除虚拟环境。

1

停止客户端

前台运行按 Ctrl+C;后台或 wheel 方式按进程结束。

PowerShell(wheel)
Get-Process task-client -ErrorAction SilentlyContinue | Stop-Process -Force
2

撤销 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/venv
4

删除程序与安装包

wheel 方式删除整个安装目录即可;源码方式删除 client/venv。 如果曾全局安装过包,再执行 python -m pip uninstall task-client。

5

检查开机自启

本项目默认不写注册表、不创建计划任务。如果你手工加过「任务计划程序」或服务, 在对应的系统设置中删除即可。

卸载前确认没有排队中或执行中的任务;强制结束客户端会让运行中的任务在 30 秒后被服务端判定 worker_lost。如需保留任务历史,请勿删除服务端数据库。
还需要帮助? 在「客户端」页确认节点在线,或在「接口文档」页调试开放接口。