进阶配置

环境变量

变量	默认值	作用
BLUE_PUPPET_PORT	48291	本地 HTTP 服务端口，需与 Hook URL 一致
BLUE_PUPPET_FPS	30	渲染帧率，可设置 1 到 240
BLUE_PUPPET_3D_SPIN	未开启	设为 1 时，立体形象持续 360° 转圈

跟随与状态逻辑固定以约 60Hz 运行，BLUE_PUPPET_FPS 只调整渲染帧率。提高帧率会更顺滑，也会增加 CPU 开销。

PowerShell 示例

$env:BLUE_PUPPET_PORT = "49291"
$env:BLUE_PUPPET_FPS = "60"
$env:BLUE_PUPPET_3D_SPIN = "1"
.\target\release\blue-puppet.exe

端口变化后，使用托盘或宠物菜单中的 复制配置 获取匹配的新 Hook URL。

HTTP 接口

方法	路径	说明
POST	/state	接收 Hook 事件 JSON，必须包含非空 session_id
GET	/state	查询所有当前实例，返回 {"states": {session_id: state}}
GET	/health	健康检查，返回 {"ok": true}

未知路径返回 404。POST 缺少 session_id 时返回 400；停止监听期间，POST 仍返回成功，但响应包含 paused: true，事件不会进入界面。

健康检查

curl http://127.0.0.1:48291/health

手动发送事件

curl -X POST -H "Content-Type: application/json" \
  -d "{\"session_id\":\"demo-1\",\"hook_event_name\":\"UserPromptSubmit\",\"prompt\":\"帮我优化多会话渲染\"}" \
  http://127.0.0.1:48291/state

再发送完成事件：

curl -X POST -H "Content-Type: application/json" \
  -d "{\"session_id\":\"demo-1\",\"hook_event_name\":\"Stop\"}" \
  http://127.0.0.1:48291/state

中文编码

手动测试时，请使用能够正确处理 UTF-8 中文和 JSON 转义的工具。不同终端的单引号、双引号规则并不相同。

渲染与性能

蓝木偶使用 winit 管理窗口、tiny-skia 绘制，并在 Windows 上通过 UpdateLayeredWindow 合成逐像素透明内容。立体形象由内置软光栅管线生成，包括 Gouraud 着色、z-buffer 和 2× 超采样。

为降低持续动画的开销：

• 跟随和状态逻辑约 60Hz，渲染默认 30fps；
• 像素缓冲和 GDI 表面跨帧复用；
• 气泡与会话标题只在文字、字号或 DPI 变化时重绘；
• 多宠物由统一事件循环主动驱动，不依赖不稳定的系统重绘通知。

从源码执行测试

cargo test

测试覆盖渲染居中、倾斜对称、缓存图层一致性和后台任务识别等逻辑。仓库还包含默认忽略的图片 dump 与性能基准测试，可通过 cargo test -- --ignored 按需运行。