hanafubuki-agent

安装

用 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 | bash

Windows 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-update
Invoke-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_64x86_64-unknown-linux-gnuhanafubuki-agent-<版本>-x86_64-unknown-linux-gnu.tar.gz
macOS Intelx86_64-apple-darwinhanafubuki-agent-<版本>-x86_64-apple-darwin.tar.gz
macOS Apple 芯片aarch64-apple-darwinhanafubuki-agent-<版本>-aarch64-apple-darwin.tar.gz
Windows x86_64x86_64-pc-windows-msvchanafubuki-agent-<版本>-x86_64-pc-windows-msvc.zip
Linux ARM64aarch64-unknown-linux-gnuhanafubuki-agent-<版本>-aarch64-unknown-linux-gnu.tar.gz
Windows ARM64aarch64-pc-windows-msvchanafubuki-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 即可。

卸载

  1. 删除可执行文件:cargo uninstall hanafubuki-agent-cli,或者直接删除下载的二进制。
  2. 如果不再需要配置和历史,删除配置目录和数据目录。hanafubuki-agent config path 会打印它们的位置,默认位置见数据目录。
  3. Agent 在系统密钥环中使用的服务名是 org.licyk.hanafubuki-agent.secrets,如果其中有条目,可以一并删除。

使用脚本安装时,也可删除 hanafubuki-agent-notices,并从 Shell 配置中移除带 # hanafubuki-agent 的 PATH 行(Windows 则移除用户 Path 中的安装目录)。

数据目录包含所有会话历史、记忆和安装的 Skill,删除后无法恢复。配置目录中的 providers.toml 和 mcp.toml 保存着 API 令牌等凭据。

本页目录