安装
用 cargo 安装,下载发布的二进制文件,或从源码构建;以及升级和卸载。
hanafubuki-agent 是一个独立的可执行文件,没有额外的运行时依赖。可以用以下四种方式之一安装:
| 方式 | 适合 | 需要 |
|---|---|---|
| 一键安装脚本 | 为当前用户安装或更新 | Bash + curl,或 PowerShell |
cargo install | 已经安装了 Rust 工具链 | Rust 1.99 或更新版本 |
| 发布的二进制 | 不想安装 Rust,直接下载使用 | 支持的平台(见下表) |
| 从源码构建 | 想使用 main 分支上的最新代码 | Git 和 rustup |
下载页 汇总安装命令以及所有受支持平台的最新稳定版程序。首页根据浏览器平台选择安装命令,也可以手动切换平台。
一键安装
Linux/macOS,或 Windows 上的 MSYS2/Git Bash(需要 Bash 和 curl):
curl -fsSL https://raw.githubusercontent.com/licyk/hanafubuki-agent/main/install.sh | bashWindows PowerShell 5.1,或 Windows/Linux/macOS 上的 PowerShell 7(pwsh):
irm https://raw.githubusercontent.com/licyk/hanafubuki-agent/main/install.ps1 | iex脚本自动选择本机 x64 或 ARM64 归档,在替换已有程序前校验 SHA-256 和可执行文件的版本,并把许可证保留在旁边的 hanafubuki-agent-notices 目录。不需要管理员权限。Git Bash 和 MSYS2 可以使用 install.sh,即使 PATH 中没有 PowerShell,也会查找 Windows PowerShell 并安装原生 Windows 归档;安装目录同时接受 Windows 路径和 MSYS 路径。Linux/macOS 上的 install.ps1 使用 tar 和 chmod 安装对应的 Unix 归档。这里的 ARM 指 ARM64;不提供 32 位 ARM 或 musl Linux 归档。
Linux/macOS 默认安装到 ~/.local/bin,Windows 默认安装到 %LOCALAPPDATA%\hanafubuki-agent\bin。可通过 HANAFUBUKI_AGENT_INSTALL_DIR 或目录参数覆盖,参数优先。安装后打开新终端:Shell 脚本向 .zshrc(设置了 ZDOTDIR 时使用该目录)、.bashrc(macOS 上为 .bash_profile)或其他 Shell 的 .profile 添加 PATH;PowerShell 在 Windows 上更新用户 Path,在 Linux/macOS 上更新 $PROFILE.CurrentUserAllHosts。MSYS2/Git Bash 安装器还会配置自身 Shell 的配置文件,因为这些 Shell 不一定继承 Windows 用户 Path。在 Unix 上,PowerShell 安装器也会更新调用它的 PowerShell 会话的 PATH,不修改 Bash 或 Zsh 配置文件。不读取这些文件的 Shell 请跳过自动设置并自行配置 PATH。
如需检查脚本或指定参数,先下载再运行:
curl -fsSLO https://raw.githubusercontent.com/licyk/hanafubuki-agent/main/install.sh
bash install.sh --version 0.5.0 --architecture arm64 --install-dir "$HOME/.local/bin" --no-path-updateInvoke-WebRequest https://raw.githubusercontent.com/licyk/hanafubuki-agent/main/install.ps1 -OutFile install.ps1
pwsh -File ./install.ps1 -Version 0.5.0 -Architecture arm64 -NoPathUpdate| Shell 参数 | PowerShell 参数 | 含义 |
|---|---|---|
--version | -Version | 默认 latest,或带/不带 v 的版本号 |
--architecture | -Architecture | 默认 auto,也可选 x64 或 arm64 |
--install-dir | -InstallDir | 可执行文件所在目录 |
--no-path-update | -NoPathUpdate | 不修改 Shell 配置和用户 Path |
HANAFUBUKI_AGENT_RELEASE_BASE_URL 可覆盖 Bash 的发布下载地址;HANAFUBUKI_AGENT_RELEASE_API_URL 可覆盖 PowerShell 的发布 API(Windows Bash 包装器也使用它)。
再次运行脚本即可更新。Windows 上请先退出正在运行的 Agent,安装脚本不能替换被占用的可执行文件。已有配置和会话历史会保留。
用 cargo 安装
cargo install --locked hanafubuki-agent-cli这个 crate 提供的命令叫 hanafubuki-agent,安装在 ~/.cargo/bin(Windows 上是 %USERPROFILE%\.cargo\bin)。确认它在 PATH 中:
hanafubuki-agent --version构建需要 Rust 1.99 或更新版本。版本太旧时,先运行 rustup update stable。
下载发布的二进制
每个版本的 GitHub Releases 页面都提供六种平台与架构组合的压缩包,以及对应的 .sha256 校验文件:
| 平台 | 目标 | 文件 |
|---|---|---|
| Linux x86_64 | x86_64-unknown-linux-gnu | hanafubuki-agent-<版本>-x86_64-unknown-linux-gnu.tar.gz |
| macOS Intel | x86_64-apple-darwin | hanafubuki-agent-<版本>-x86_64-apple-darwin.tar.gz |
| macOS Apple 芯片 | aarch64-apple-darwin | hanafubuki-agent-<版本>-aarch64-apple-darwin.tar.gz |
| Windows x86_64 | x86_64-pc-windows-msvc | hanafubuki-agent-<版本>-x86_64-pc-windows-msvc.zip |
| Linux ARM64 | aarch64-unknown-linux-gnu | hanafubuki-agent-<版本>-aarch64-unknown-linux-gnu.tar.gz |
| Windows ARM64 | aarch64-pc-windows-msvc | hanafubuki-agent-<版本>-aarch64-pc-windows-msvc.zip |
压缩包里是一个同名目录,包含可执行文件、LICENSE、NOTICE 和 THIRD-PARTY-LICENSES.txt。Linux 版本需要 glibc 2.35 或更新版本(Ubuntu 22.04、Debian 12 及更新的发行版)。
下载并校验
把压缩包和它的 .sha256 文件下载到同一个目录,然后校验:
sha256sum -c hanafubuki-agent-<版本>-x86_64-unknown-linux-gnu.tar.gz.sha256校验通过时,sha256sum 和 shasum 会输出 OK。
解压并放入 PATH
tar xzf hanafubuki-agent-<版本>-<目标>.tar.gz
install -m 755 hanafubuki-agent-<版本>-<目标>/hanafubuki-agent ~/.local/bin/~/.local/bin 只是一个例子,任何在 PATH 中的目录都可以。
确认可以运行
hanafubuki-agent --version从源码构建
git clone https://github.com/licyk/hanafubuki-agent.git
cd hanafubuki-agent
cargo install --path crates/cli仓库中的 rust-toolchain.toml 固定了工具链版本(1.99.0),rustup 会在第一次构建时自动安装它。只想构建而不安装时,使用 cargo build --release -p hanafubuki-agent-cli,可执行文件在 target/release/hanafubuki-agent。
平台说明
MCP 服务器的 OAuth 令牌保存在系统密钥环中,Linux 上通过 Secret Service 访问(GNOME Keyring、KWallet 等都提供它)。没有桌面环境的服务器或容器通常没有 Secret Service:这时 hanafubuki-agent doctor 的 keyring 一项会显示 FAIL,但其他功能不受影响:Provider 令牌和 MCP 凭据都保存在配置文件中,不使用密钥环。
配置和数据目录遵循 $XDG_CONFIG_HOME 和 $XDG_DATA_HOME。
更新
hanafubuki-agent update 按安装方式更新运行它的可执行文件;hanafubuki-agent update --check 只说明是否有更新的发布版本,以及 update 会做什么(update)。终端界面也会检查是否有更新的版本,在底栏显示它,并在下一次启动时提出替你运行 update(更新)。
| 安装方式 | hanafubuki-agent update |
|---|---|
| 发布的二进制 | 下载最新发布版本中本平台的归档,校验大小和 SHA-256 摘要,确认其中的可执行文件能在本机运行,然后把它放到位 |
cargo install | 在 Linux 和 macOS 上替你运行 cargo install --locked hanafubuki-agent-cli。在 Windows 上,请在没有 Agent 从该可执行文件运行时,从另一个终端自己运行它:那里正在运行的可执行文件不能被替换 |
| 从源码构建 | 不做任何事:更新检出的源码并重新构建 |
手动更新发布的二进制和安装时一样:下载新的归档,核对校验和,替换可执行文件。在 Windows 上,请先退出所有从它运行的 Agent,或者先把正在运行的可执行文件重命名到一旁,再把新文件放到原来的位置。
正在运行的 Agent 保持原来的版本直到重启,下次启动运行新版本。请尽快重启它们:它们的沙箱命令已经会启动新的可执行文件。配置文件和历史记录会被新版本直接读取:新版本能容忍它不认识的字段,也不会删除它无法使用的数据。
在 Windows 上,update 会把正在运行的可执行文件重命名为新文件旁边的 hanafubuki-agent.exe.NUMBER.outdated,没有进程再运行它之后,下一次更新或终端界面的下一次启动会删除它。如果更新恰好在两次重命名之间被中断(两者相隔只有几毫秒),就不会有 hanafubuki-agent.exe:把最新的 .outdated 文件改回 hanafubuki-agent.exe 即可。
卸载
- 删除可执行文件:
cargo uninstall hanafubuki-agent-cli,或者直接删除下载的二进制。 - 如果不再需要配置和历史,删除配置目录和数据目录。
hanafubuki-agent config path会打印它们的位置,默认位置见数据目录。 - Agent 在系统密钥环中使用的服务名是
org.licyk.hanafubuki-agent.secrets,如果其中有条目,可以一并删除。
使用脚本安装时,也可删除 hanafubuki-agent-notices,并从 Shell 配置中移除带 # hanafubuki-agent 的 PATH 行(Windows 则移除用户 Path 中的安装目录)。
数据目录包含所有会话历史、记忆和安装的 Skill,删除后无法恢复。配置目录中的 providers.toml 和
mcp.toml 保存着 API 令牌等凭据。