workhorse [ˈwɜrkhɔrs]
n. 驮马，做粗工者，重负荷机器
一款为极客设计和使用的持续集成工具，核心能力包括本地开发和远程构建。
你就安心写代码，编译的事情交给 牛马
从 0.3.0 开始，仓库内置 ./skills 目录，把 cargo-work 与 horsed 的常见任务整理为可复用的技能入口，方便团队协作和 AI 辅助执行。
推荐这样上手：
- 先看
skills/workhorse/SKILL.md，它会先把请求分流到客户端或服务端路径。 cargo work、远程构建、端口转发、产物同步等任务，走skills/workhorse-cargo-work/SKILL.md（再按需下钻到对应子 skill）。horsed首次部署、服务运维、服务端开发等任务，走skills/workhorse-horsed/SKILL.md（再按需下钻到 setup/ops/dev 子 skill）。
如果你在扩展工作流，请在新增或重命名 skill 后同步更新 AGENTS.md 的 Project Skills 列表，保持入口文档和实际目录一致。
- 统一入口：
AI_AGENT.md - 机器可读技能索引：
skills/index.json - 标准任务配方：
docs/agent-playbooks.md
- Linux
- MacOS
- Windows
你可以从 发布页面 下载二进制文件。
或者，你可以使用 cargo 安装：
cargo install --git https://github.com/uuhan/workhorse.git horsed
cargo install --git https://github.com/uuhan/workhorse.git cargo-work在终端中运行 horsed 命令，它会启动一个监听在 2222 端口的服务器。
# 在一个干净的目录中，存储所有文件。
horsed
# 然后会在当前目录生成两个文件：
# horsed.db3 - 数据库文件
# horsed.log - 日志文件第一次运行时，horsed 会启动一个 SETUP SERVER，并记录第一次使用的 SSH 公钥。你需要连接到 2223 端口成为服务器的 第一个用户。
ssh -p 2223 <YOUR NAME>@<THE HORSED SERVER>
# 例如： ssh -p 2223 uuhan@127.0.0.1之后，SETUP SERVER 会退出，你就可以开始使用 horsed 服务器了，当前目录下会生成一个 horsed.key 文件，它是服务器的私钥。
现在，horsed 服务器已经准备好接收来自客户端的连接。
horsed 支持参数 --dangerous, 目前只能在前台模式启用, 启用之后维护服务会常驻,
任意 连接到 2223 端口的客户端都能录入他的公钥信息, 请小心使用!
horsed -f --show-log --dangerous其他参数请参考 horsed --help 命令。
Workhorse 将普通的 <Action>@<The Horsed Server> 视为远程操作执行器。
当前支持的操作有：
- git：通过 SSH 协议作为远程 git 仓库使用
- cmd：在远程服务器上执行命令
- cargo：在远程服务器上执行 cargo 命令（build/check/clippy/test/run/doc 等）
- apply：接受 git 补丁并应用到工作树
- just：运行 justfile 中定义的 just 命令
- get：从远程服务器获取构建产物
- put：上传本地文件到远程工作目录
- scp：类似 scp，将文件从远程服务器复制到本地
- push/pull：推送或拉取代码到远程仓库
- ping：检查服务端连通性
- health：查看服务端健康信息（version/commit/os/shell/ulimit）
- logs：查看服务端日志
- job：查看远程任务并附加输出
- watch：监控文件变动并自动执行命令
- admin：管理员用户与公钥管理
- ssh：交互式 shell、本地(-L)、反向(-R)端口转发
Workhorse 设计支持两种客户端：
你可以使用常规的 ssh 命令连接到 horsed 服务器，它将像平常一样工作。SSH 客户端需要支持 SetEnv 命令来设置环境变量，OpenSSH 的最低版本应为 8.7（2021-08-20）或更高版本。
# 这将运行 `ls` 命令，并将输出返回到本地终端
ssh -p 2222 cmd@127.0.0.1 -- ls
# horsed.db3
# horsed.key
# horsed.log目前，Workhorse 客户端是一个 cargo 子命令，专为 Rust 项目构建。你可以远程运行几乎任何 cargo 命令，例如：
# 这将远程构建你的 Rust 项目，酷吧 :)
cargo work build --release你无需对项目进行更多配置，唯一需要做的是在当前的 git 仓库中添加一个名为 horsed 的远程目标：
git remote add horsed ssh://git@<THE HORSED SERVER>:2222/<YOUR NAME>/<YOUR REPO NAME>.git
# 例如： git remote add horsed ssh://git@127.0.0.1:2222/uuhan/workhorse.git
# 推荐将 horsed 仓库远程添加到你的 origin 远程。
# 然后，每次你推送到 origin，它也会推送到 horsed 仓库。
git remote set-url --add origin ssh://git@127.0.0.1:2222/uuhan/workhorse.git然后你可以远程运行任何 cargo 命令：
git push horsed
cargo work build
# 会有很多 cargo 输出...构建完成后，你可以从 horsed 服务器获取构建产物：
# 从 horsed 服务器获取文件
cargo work get target/debug/your-build-artifcat
# 文件将显示在当前目录，路径为：
# target/debug/your-build-artifcat你还可以获取整个目录：
# 从 horsed 服务器获取目录
cargo work get target
# 目录将显示在当前目录，路径为：
# target.tar你也可以上传本地文件到远程工作目录：
# 上传本地文件到远程仓库工作目录
cargo work put ./target/release/horsed target/release/horsed你也可以执行任意的远程命令:
# 运行远程命令, -- 后面的内容将作为命令执行
cargo work -- scoop install vcpkg默认 Windows 系统使用 powershell.exe, 非 Windows 系统使用 bash 执行命令,
你也可以使用 --shell 来指定你喜欢的解释器:
# 使用 nushell 作为 shell
cargo work -s nu -- ls
# 也可以使用环境变量 `HORSED_SHELL` 指定 shell
export HORSED_SHELL=nu
cargo work lscargo-work 也支持显式传入机器地址:
cargo work --repo ssh://git@127.0.0.1:2222/uuhan/workhorse.git -- pacman install zig
cargo work build --repo ssh://git@127.0.0.1:2222/uuhan/workhorse.git --release你也可以为 git 仓库配置多个 remote:
git remote add horsed-win http://git@127.0.0.1:2222/uuhan/workhorse.git
git remote add horsed-linux http://git@127.0.0.1:2222/uuhan/workhorse.git
git remote add horsed-macos http://git@127.0.0.1:2222/uuhan/workhorse.git
# 然后通过传递 --remote 来指定远程仓库
cargo work build --remote horsed-win
cargo work build --remote horsed-linux
cargo work build --remote horsed-macoscargo work 提供简单的 ssh 连接功能:
# 这将在服务端开启一个 tty 并且启动用户提供的交互 shell
cargo work ssh bash
# 如果不提供 shell, 默认使用 bash (unix) 或者 powershell (windows)
cargo work ssh你也可以进行正向, 反向端口转发:
# 正向转发本地 3000 端口到远程机器，所有本地请求会去往服务器
cargo work ssh -L 3000:127.0.0.1:3000
# 或者使用标准的 ssh 工具, 实现上保证 ssh 协议兼容性
ssh -L 3000:127.0.0.1:3000# 反向转发服务器 3000 端口到本地，所有对服务器的请求会来到本地
cargo work ssh -R 3000:127.0.0.1:3000
# 或者使用标准的 ssh 工具，实现上保证 ssh 协议兼容性
ssh -R 3000:127.0.0.1:3000同时 cargo work 指令也支持反向 HTTP 代理, 这在有时候会比较有用:
# -x, --enable-proxy 会在 `horsed` 端启用一个随机端口的反向代理,
# 连接到你当前的 ALL_PROXY 的代理, 在执行命令的时候会使用这个代理
cargo work build -x
all_proxy=socks5://127.0.0.1:1080 cargo work -x -- curl -v https://google.com
# 你也可以手动指定代理地址
cargo work build --all-proxy=socks5://127.0.0.1:1080你可以通过以下方式查看服务端日志:
cargo work logs
# 像下面这样可以持续获取 `horsed` 的日志
cargo work logs -f你可以检查服务端健康状态：
cargo work health
# 如果默认日志级别较高，看不到输出时可用：
RUST_LOG=info cargo work health
# 排障时可附加 trace 流：
RUST_LOG=info WH_DEBUG=1 cargo work health
# 机器可读输出（推荐给 AI Agent）：
cargo work health --json管理员可以使用 admin 子命令管理用户和公钥：
# 用户管理
cargo work admin users list
cargo work admin users add <name> [admin|user]
cargo work admin users enable <name>
cargo work admin users disable <name>
cargo work admin users role <name> <admin|user>
cargo work admin users delete <name>
# 公钥管理
cargo work admin keys list [user]
cargo work admin keys add <user> <alg> <key> [comment]
cargo work admin keys enable <alg> <key>
cargo work admin keys disable <alg> <key>
cargo work admin keys delete <alg> <key># 1) 更新本地客户端
just install-work
# 2) 同步代码并远程构建安装
git push horsed main
HORSED_SHELL=/bin/bash cargo work just install-horsed
# 3) 重启远程 horsed 服务
HORSED_SHELL=/bin/bash cargo work -- systemctl --user restart horsed# 1) 更新本地客户端
just install-work
# 2) 一键远程部署（构建 + 自动重启）
git push horsed main
HORSED_SHELL=powershell.exe cargo work just deploy-horseddeploy-horsed 会在远程执行 cargo build --release，然后通过延迟脚本自动完成 停止旧进程→拷贝二进制→启动新进程，无需手动操作。
- 如果服务端没有
nu，不要设置HORSED_SHELL=nu，请使用/bin/bash或/bin/sh（Linux），或powershell.exe（Windows）。 - 构建基线来自服务端仓库分支，发布前建议确保
horsed远程分支已同步（git push horsed main）。
更多的帮助信息可以通过查看帮助获取:
cargo work --help
cargo work <SUBCOMMAND> --help