hanafubuki-agent

构建与测试

工具链、验证命令、cargo xtask 的各项检查、golden 测试与历史语料及其更新规则、快照测试、文档站点的命令和 CI。

工具链

  • Rust:rust-toolchain.toml 固定 1.99.0(带 rustfmt 和 clippy),工作区的 rust-version 也是 1.99。edition 保持 2021,rustfmt 使用默认配置。
  • Bun:根目录的 package.json 用 packageManager 固定 Bun 1.4.2,只用于文档站点(site/,根目录 Bun 工作区的唯一成员)。
  • 仓库工具是 xtask crate,以 cargo xtask <command> 运行。
git clone https://github.com/licyk/hanafubuki-agent
cd hanafubuki-agent
cargo build                      # 整个工作区
cargo run -p hanafubuki-agent-cli -- --help

验证命令

在仓库根目录运行,按变更的影响选择范围。下面五步就是 .github/workflows/ci.yml 在 Linux、Windows 和 macOS 上运行的步骤:

cargo fmt --all --check
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo xtask check
cargo test --workspace --all-features
  • 警告是错误。#[allow] 必须写明它的 reason。
  • 格式化、静态检查和测试彼此独立:检查不会格式化,测试不会格式化也不会运行静态检查。
  • 只改文档时检查 diff 和引用的路径即可,不需要构建和测试。
  • 在 Linux 上通过不代表 Windows 或 macOS 也通过;交接时如实说明运行了哪些命令、跳过了哪些。

cargo xtask 的检查

命令和参数通过 Clap 派生宏声明在 xtask/src/cli.rs 及发布模块中,帮助文本与参数校验由声明自动生成。使用 cargo xtask --help 查看命令列表,使用 cargo xtask <command> --help 查看对应选项。帮助以状态码 0 退出,参数错误为 2,任务执行失败为 1。新增命令或参数时修改声明,不再单独维护帮助字符串或手写参数解析。

cargo xtask check 依次运行下面每一项,每一项也可以单独运行:

命令检查什么
check-dependencies依赖方向与分层:不依赖任何 Hanafubuki crate;每个成员只依赖层表(xtask/src/dependencies.rs 的 LAYERS)允许的成员;插件规则(内核不依赖插件、插件不依赖内核/门面/其他插件、kardia 的位置等),见插件规则
check-source-layoutRust 模块与测试的布局:lib.rs 只有声明与重新导出、mod.rs 与 foo.rs 的用法、没有 #[path]、没有 glob 重新导出、生产文件中没有内联测试、快照放在 snapshots/ 中
check-module-size文件与函数大小,对照 architecture/module-size-policy.toml:生产文件 600 行代码、测试文件 900 行、生产函数 200 行(注释不计)
check-strict-decodingdeny_unknown_fields 只出现在 architecture/strict-decoding-policy.toml 列出的类型上(带类别与原因)
check-model-api-contexthanafubuki-agent-model-api 的生产源码不出现任何上下文段类型
check-path-boundaries路径只通过 hanafubuki-agent-foundation::paths 解析:不直接 fs::canonicalize,不渲染 system(),不直接比较解析后的 PathBuf;例外在 architecture/path-policy.toml 中审计
check-locks生产代码不使用 std::sync::Mutex 或 RwLock(任何导入形式);测试与测试支持可以
check-plugin-panics插件 crate(crates/plugin-*)、门面自己的插件(crates/agent/src/plugins)和压缩 crate(crates/compression)的生产源码中没有 .unwrap() 和 .expect(
check-notices派生自第三方代码的文件带有它们的署名标记,NOTICE 列出它们(architecture/notices-policy.toml),见许可证
check-config-referencecrates/config/src 声明的每个设置(SettingSpec::new("键", …),键是字符串字面量)在配置参考的 config.toml 表格中都有一行,两种语言都有

另外还有:

  • cargo xtask module-size-report [--top N]:列出最大的文件和函数。
  • cargo xtask version 与 cargo xtask tag:发布用,见发布。

测试

cargo test --workspace --all-features 运行全部测试。值得知道的几组:

测试内容
请求 golden(crates/agent/src/tests/golden.rs)固定模型收到的内容,见下文
流水线测试(crates/agent/src/tests/pipeline.rs)用脚本化的模型和 MCP 服务器驱动真实的内核和 Agent 自己的插件跑完整个轮次:提交顺序、取消、审批、超时、panic 等
内核契约(crates/kernel/tests/)loop_contract、compaction_contract、persistence_contract、contracts、session_title_contract
故障(plugin_faults.rs、restart.rs、plugin_host.rs 等,在门面的测试中)插件故障与自动重启、内核故障与 Agent 重启、插件宿主
命令行(crates/cli/tests/)exec 针对脚本化模型端到端运行一个轮次;管理命令
代码插件(crates/plugin-packages/tests/guests、crates/agent/tests/plugin_guests.rs、crates/agent/tests/plugin_crashes、crates/cli/tests/plugin_examples.rs)在沙箱中启动的访客(Linux;没有沙箱时跳过),已安装插件的每种失败的端到端测试(plugin_crashes:损坏的清单、MCP 服务器崩溃、失败的钩子、访客的 panic、卡住、abort、段错误、内存耗尽、被杀死、协议垃圾和超大帧、重启循环、plugins 行本身的 panic;每种之后都有一个正常完成的回合;其中访客的检查只在 Linux 上运行,每项检查都有 150 秒的看门狗),以及在所有平台上运行的 WebAssembly 访客(由 wat crate 汇编的文本格式模块),在 Agent 的 panic hook 下被隔离的 kardia-hmr guest-stderr 线程上的 panic(guests 把自身作为子进程再运行一次并安装这个 hook,未被隔离的 panic 会在那里中止进程),guests 的每项检查都有一个看门狗:运行超过 120 秒的检查会被终止,并输出它到达的步骤、最近的日志记录,在 macOS 上还有每个线程的调用栈(sample);构建并启动示例插件(Unix;WebAssembly 示例只在安装了 wasm32-unknown-unknown 目标时运行,CI 会安装它;Python 示例只在 HANAFUBUKI_AGENT_TEST_PYTHON 指定了一个带有使用 kardia-guest/2 的 pykardia 的解释器时运行,CI 不设置它)
终端界面(crates/tui)insta 快照测试

测试针对真实实现,尽量少用 mock,不在测试里复制业务逻辑。测试的位置规则(白盒测试在 src/<module>/tests.rs,公开 API 与跨 crate 契约在 crate 的 tests/,测试辅助的写法)见参与开发。

设置 HOSHIMI_COMPACTION_TEST_URL 为真实 Hoshimi Responses 的 /v1 地址、HOSHIMI_CONTEXT_TEST_IMAGE 为含 ComfyUI、InvokeAI 或 Stable Diffusion 的 Hanafubuki 截图路径,在 Hoshimi 已登录 qodercli-cn 后,可运行 cargo test -p hanafubuki-agent --lib live_hoshimi_reported_context_and_images_compact_at_threshold -- --ignored --nocapture。此默认忽略的测试使用 DeepSeek-Flash,实际发送有图和无图的长文本,验证图片识别,在约 512k tokens 时重启会话,再跨过 80% 阈值。它使用独立的 Agent 数据目录,输出 Provider 用量、本地估算和压缩结果,不属于常规离线测试。

忽略测试 live_hoshimi_small_context_tool_loop_does_not_compact_on_cumulative_usage 使用相同的 HOSHIMI_COMPACTION_TEST_URL,不需要图片。它通过 DeepSeek-Flash 连续调用 36 次 update_plan,每次请求约 190k token,在默认预算下跨过 640 万累计输入 token,并断言 1M 上下文窗口没有被压缩。使用 cargo test -p hanafubuki-agent --all-features --lib live_hoshimi_small_context_tool_loop_does_not_compact_on_cumulative_usage -- --ignored --nocapture 显式运行。

golden 测试与历史语料

请求 golden(fixture 在 crates/agent/src/tests/golden/)在 Agent 自己的插件上、用一个什么都不添加的宿主,固定模型收到的内容:默认与计划模式、一次工具往返及其展示事件、Skill 目录、工作区指令、记忆摘要、压缩后的请求、来自脚本化进程内服务器的 MCP 工具(直接与延迟、过长与冲突的名字)和一次 tool_search 往返。

历史语料是更早的构建录制的历史,必须一直能打开并继续:golden/history/ 是 Hanafubuki 的语料逐字节的副本;golden/history-reasoning/ 是加入推理条目时录制的第二份语料,它必须带着推理文本打开,并且不让推理文本进入下一个请求。

更新规则:

  • 模型能看到的变化会改变请求 golden。只在有意的变化之后重新生成,并审查 fixture 的 diff:

    HANAFUBUKI_AGENT_UPDATE_GOLDEN=1 cargo test -p hanafubuki-agent --lib golden

    在 PowerShell 中运行

    $env:HANAFUBUKI_AGENT_UPDATE_GOLDEN = "1"
    try { cargo test -p hanafubuki-agent --lib golden } finally { Remove-Item Env:HANAFUBUKI_AGENT_UPDATE_GOLDEN }
  • 历史语料只在有意的历史格式变化之后重新录制;否则它们的意义就是证明旧的历史仍能打开:

    HANAFUBUKI_AGENT_UPDATE_GOLDEN_HISTORY=1 cargo test -p hanafubuki-agent --lib tests::golden
  • 两个变量只看是否设置,不看值:设置成 0 也会重写 fixture。

  • Linux、macOS 和 Windows 可生成并校验同一套请求基线。快照用占位符表示操作系统、CPU 架构和临时目录,并统一使用正斜杠表示夹具路径。

  • Hanafubuki 在 hanafubuki-agent-integration 中保留了自己的 golden 和同一份历史语料(双生副本):这里模型可见的变化也会改变它们,历史格式变化要在两边都重新录制。

要通过真实 Hoshimi Responses 端点对比工具看图和粘贴图片,设置 HOSHIMI_VISION_TEST_URL 为 /v1 地址、HOSHIMI_VISION_TEST_IMAGE 为图片路径,再运行 cargo test -p hanafubuki-agent --lib live_hoshimi_view_image_and_paste_deliver_the_same_image -- --ignored --nocapture。它使用已登录的 qodercli-cn 账号的 DeepSeek-Flash,要求模型调用真实的 view_image 工具,再在独立会话中发送同一张图片附件。测试检查工具确实被调用且保存的图片摘要相同,并打印两次描述供对照原图;仅这些结构断言通过,并不能证明视觉识别正确。该测试需要显式联网运行,不属于常规测试。

要使用真实 Hoshimi 账号和已安装的 @modelcontextprotocol/server-filesystem 测试延迟发现,可运行下面的显式探针。它使用 DeepSeek-Flash、临时工作区与文件,以及 MCP 默认注册方式(延迟暴露)。测试在 Responses、Chat Completions、Anthropic Messages 中检查 tool_list → 普通 search_tools → MCP 读取,并核对实际返回的文件内容。Hoshimi 端点需要已有登录的 qodercli-cn 账号。

HOSHIMI_TOOL_TEST_URL=http://127.0.0.1:18779/v1 \
MCP_FILESYSTEM_ENTRY=/path/to/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js \
cargo test -p hanafubuki-agent --lib live_hoshimi_discovers -- --ignored --nocapture

也可以将 HOSHIMI_TOOL_TEST_PROTOCOL 设为 Responses、ChatCompletions 或 AnthropicMessages,只运行指定协议。

终端界面的快照

终端界面的渲染用 insta 做快照测试。已审核的 .snap 是纳入版本控制的测试基准,保留在测试旁边的 snapshots/ 目录中,不应作为构建产物删除或忽略。这个目录不是模块。

快照不匹配时测试仍然失败。.cargo/config.toml 将 INSTA_PENDING_DIR 设为工作区内的 target/insta/,临时快照在其中保留相对于源码的目录结构。.snap.new、二进制快照的 .snap.new.* 附属文件和内联快照的 .pending-snap 都被忽略,也包括旧运行在源码旁留下的文件。显式设置环境变量可以覆盖这个输出位置。

安装 cargo-insta 后,从仓库根目录执行 INSTA_PENDING_DIR=target/insta cargo insta review --include-ignored --include-hidden 逐个审查(PowerShell 先设置 $env:INSTA_PENDING_DIR = 'target/insta',再执行相同的 cargo insta review 命令)。接受后会写回源码目录中的基准。也可以用 INSTA_UPDATE=always cargo test -p hanafubuki-agent-tui 直接更新基准,然后审查 diff;只接受有意的变化。不再需要未审核结果时,可以删除临时目录,其中不存放测试基准。

欢迎形象素材

欢迎形象内嵌的 crates/tui/assets/welcome/atlas.png 和 atlas.json 是生成文件,不应手工修改。先准备包含 imagegen 底图 base.png、眨眼关键帧 blink.png(均为 1254×1254)和 prompts.json 的审计目录,然后运行:

cargo xtask welcome-assets --source /path/to/audit
# 可选:--output /path/to/atlas(默认:crates/tui/assets/welcome)

原生 Rust 生成器(xtask/src/welcome/)无需 Python 或外部图片工具。它在审计目录保留全部 96 张彩色帧、八秒循环的 loop.gif、关键帧对照图、图集副本及输入和输出文件哈希(conversion.json)。仅替换眼睛区域可避免眨眼关键帧改变其他部位;归一化变形网格固定放平的手臂,并带动身体、头发和猫耳。眼睛坐标和裁剪区域针对当前 Hana 姿势;更换构图时需要更新 animation.rs 中的这些参数。运行时通过 Lanczos 滤波将带透明度的 256 色图集采样成彩色 2×4 盲文点阵,因此缩放不依赖某种终端字体的像素大小。素材是位图,并非 SVG 描摹。

运行 TUI 的 welcome 测试时,可将 HANAFUBUKI_AGENT_WELCOME_PREVIEW 或 HANAFUBUKI_AGENT_WELCOME_TUI_PREVIEW 设为输出 JSON 路径,分别导出渲染器的字符格或完整界面。将任一种导出转换为可缩放的彩色 SVG 进行视觉审核:

cargo xtask welcome-preview --input /path/to/cells.json --output /path/to/preview.svg

其他姿态的可复现源文件在 crates/tui/assets/welcome/sources/{left,sleep,read,corner}/。将某个源目录复制到审计目录,再运行同一个 welcome-assets --source /path/to/audit --output crates/tui/assets/welcome/<pose> 命令。pose.json 指定帧宽高及布局:horizontal 和 vertical 以 0(左/上)至 1(右/下)表示空闲区域内的比例位置,width_scale 调整终端显示比例,min_rows/max_rows 限制大小。生成器裁掉透明边距、固定下沿,接受任意尺寸的底图,从 base.png 生成呼吸和摆动循环,不要求原始姿态的眼睛坐标或眨眼关键帧;原来的居中姿态仍使用单独的眨眼关键帧。逐帧图片与审计产物保留在仓库外,主题目录只存图集与元数据。运行 TUI 的 every_theme_places 测试时,将 HANAFUBUKI_AGENT_WELCOME_THEMES_PREVIEW 设为已存在的目录,可导出五种实际布局,再逐个使用 welcome-preview 转成 SVG。

预览使用实际盲文点位和 RGB 颜色绘制,普通文字使用查看器的等宽字体。这是终端字符格的重建图,并非桌面截图。

文档站点

首页在浏览器中识别桌面平台:Windows 显示 PowerShell 命令,Linux/macOS 显示通过 Bash 运行 install.sh 的命令;未知或移动平台需要手动选择。/download 汇总两种脚本、发布压缩包与 SHA-256 文件、Cargo 和源码安装。它在浏览器中获取最新稳定版;API 不可用时,安装脚本和 GitHub Releases 链接仍可使用。静态输出检查要求生成 download/index.html 以及每个文档页。

站点在 site/:TanStack Start 上的 Fumadocs,预渲染为静态文件,为 GitHub Pages 构建在 /hanafubuki-agent/ 下。

bun install --frozen-lockfile
bun run site:dev          # http://127.0.0.1:3000
bun run site:check        # TypeScript 检查
bun run site:test         # vitest
VITE_BASE_PATH=/hanafubuki-agent/ bun run site:build
bun run site:preview
bun run format:site       # prettier 格式化 site/、package.json、.prettierrc.json
bun run format:check:site
  • 页面在 site/content/docs/:每页是 x.mdx(简体中文,默认)加 x.en.mdx(英文),frontmatter 有 title、description 和 icon(一个 lucide 图标名)。meta.json 与 meta.en.json 按同样的顺序列出同样的页面,i18n-content.test.ts 检查这两点。
  • prettier 格式化 MDX(表格、换行),不格式化 Markdown(.prettierignore 排除了 **/*.md)。
  • 构建之后检查每个页面都被预渲染了。
  • patches/ 中有 @tanstack/start-static-server-functions 的一个 Bun 补丁:它从源站根目录取预渲染的结果,补丁加上 Vite 的 base。升级这个包时要重新生成补丁(bun patch),否则在 base 下的首次加载仍然正常,但站内导航会失败。
  • 页面中的依赖片段写成 hanafubuki-agent = "0.10" 这样的形式,cargo xtask version 会在用户写的要求变化时更新它们。

CI

工作流何时运行做什么
ci.yml推送到 main、拉取请求、手动、被发布工作流调用;只改 Markdown、许可证文件或站点时不运行在 ubuntu、windows、macos 上运行上面的五个验证步骤(测试带 --no-fail-fast),每个作业最多运行 60 分钟;新的推送取消同一 ref 上旧的运行
site.yml推送到 main 或拉取请求,且改动了 site/、patches/、根目录的 Bun 文件或这个工作流bun install --frozen-lockfile、format:check:site、site:check、site:test、site:build,构建结果作为制品保留
release.ymlv* 标签,或手动运行发布 crate、构建二进制、创建 GitHub release,见发布

在 Windows 上,测试运行时 TEMP 和 TMP 指向作业自己在 runner.temp 下创建的目录,位于运行器的本地磁盘(D:)上,并像用户配置文件中的临时目录一样直接授予用户本身写权限(D: 只通过 Administrators 授予写权限,而沙箱的非提升令牌没有 Administrators):在系统盘上,Agent 的持久化写入每次刷盘最多要几秒,使轮次、取消和测试的等待超出了各自的期限。

CI 的验证只覆盖它实际运行的平台和命令;本地不要声称与 CI 等价,除非按当前的工作流复现了它。

Linux 构建内置 bubblewrap 需要 C 编译器、pkg-config 和 libcap 开发包(Debian/Ubuntu:libcap-dev)。只验证原生沙箱可运行 cargo test -p hanafubuki-agent-sandbox。Windows 提升账户测试须显式设置 HANAFUBUKI_TEST_ELEVATED_SANDBOX=1:它会执行 UAC 初始化并创建本地账户和防火墙规则,因此 CI 使用一次性 runner。Linux 命名空间测试要求宿主允许非特权用户命名空间;CI 与 Codex 一样启用该能力。

安装脚本测试

node tests/installers/run.mjs 使用本地 HTTP 发布夹具和 rustc 构建的原生可执行文件,运行真实的下载、校验、替换及 PATH 代码。测试覆盖指定/最新版本、空格与 Unicode 路径、重复安装、校验失败时保留旧程序,以及 PATH 修改的幂等性。Windows 同时运行 Windows PowerShell 5.1 和 PowerShell 7,用临时注册表键隔离真实用户 Path。Linux/macOS 同时运行 Bash 和 pwsh,并隔离 Shell 和 PowerShell 配置文件。Windows 上可传入 --bash C:\msys64\usr\bin\bash.exe,在受限 PATH 下测试真实 MSYS2 包装器;Windows x64 安装 CI 已启用此项。通过 --binary PATH --target TRIPLE 可测试已有构建,发布流程使用此模式。ci.yml 调用可复用的 installers.yml,覆盖三个系统及 Linux、Windows ARM64。测试需要 Node、Rust 和 PowerShell 7,不安装网站依赖。

本页目录