voloo 使用说明

中文图文版 · 快速上手 · English guide

voloo 是一个由电脑控制的直流电源开关。把它接在独立直流电源和设备之间，再用 USB-C 数据线连接电脑，就能通过网页仪表盘、命令行、AI Agent 或本地 HTTP API 控制供电。

voloo 只切换你接入的电源，本身不是电源。 USB-C 负责控制，不负责给设备供电。本说明适用于 USB-C 连接的 voloo。

标称工作电压：3.3–28 V DC；最高建议电流：3 A。超过 3 A 可能损坏硬件。

快速查阅：安装体验 · 接线和参数 · 仪表盘 · AI Agent · 过压后的恢复方式 · 常见问题

先记住三件事

• OFF 不等于 0 V。 关断后，负载可能仍有残压。需要主动泄放时，使用 discharge，并以设备确认输出电压 ≤ 1 V 为完成条件。
• 无效读数不等于 0 V。 界面显示“—”或 unreadable，以及 JSON 中的 null，都表示当前没有有效测量值。
• 结果未知时先查状态。 遇到 unknown、断线或等待超时，先查询设备当前状态，不要盲目重发电源命令。等待超时也不表示设备动作已经取消。

1 安装和无硬件体验

支持 macOS 11 及以上、Linux、Windows 10/11。请先安装 Node.js 18 或更新版本，再在终端执行：

npm install -g @librezoo/voloo
voloo --version

安装后，命令名是 voloo。不想全局安装时，也可以用以下方式运行一次：

npx @librezoo/voloo ls

没有硬件也能先体验仪表盘：

voloo demo

demo 使用模拟设备，不扫描或控制真实硬件。退出演示不会切换真实设备的供电。

2 接线和上电

准备一根支持数据传输的 USB 线。只支持充电的线不能用于通信；电脑一端可以是 USB-A 或 USB-C。

图 1：产品图为 AI 辅助效果渲染，接口标注用于识别。接线以实物和外壳的正负极标记为准。

图示按 红线接正极＋、黑线接负极− 配线。线色只用于辅助识别，不能代替电源极性测量和实物端子标记；图中导线是连接示意。

按压式端子怎么接线和取线

橙色按压件用于开夹接线，不是供电开关；通断电在网页仪表盘、CLI 或 Agent 中操作。端子固定在 voloo 上，无需拧螺丝或拆下整个端子。

接线、换线或取线前，先确认断电。如设备有残压，先保持 USB 连接执行泄放并确认 VOUT ≤ 1 V；再关闭并断开外部电源、拔下 USB-C，确认输入与设备端无电后操作导线。

1. 处理线头： 未处理导线用剥线钳按厂家图纸剥线 11 mm，整理线芯，不留散丝；预制端头先确认与端子匹配。
2. 按住： 按住对应橙色按压件，方向朝电路板，使夹口打开。
3. 插入： 持续按住，把线插入相邻的绿色圆孔，让铜芯完全进入夹持区。不要插入橙色开口或绿色细槽。
4. 确认： 松开按压件，轻拉导线确认夹紧，孔外不露铜。

取线： 确认断电后，按住对应橙色件，再沿进线孔方向取出，不要直接硬拽或撬动按压件。

剥线长度依据 KEFA KF142V-5.08 厂家图纸（立创 C475134）。端子元件的其他额定参数不会提高 voloo 整机标称 3.3–28 V、最高建议 3 A 的范围。

电压 电流和功率边界

已测试工况为 3.3–28 V、3 A 恒流负载。不同线材、接线、外壳及环境条件仍需确认压降和温升；该工况不扩展为任意启动浪涌、感性回灌、全温或无限时长运行的保证。

图 2：标称工作范围与保护阈值分开看。3.3 V 是标称下界，不是固件欠压阈值；28 V 是标称上界，不是软件过压触发点。

以下为 3 A 恒流负载下的功率换算，便于按供电电压选择负载：

任何工作电压下，最高建议电流都为 3 A。 例如 12 V × 4 A = 48 W，虽然低于 84 W，但电流已超过 3 A，仍可能损坏硬件。不要根据 84 W 反推出低压下可以使用更大的电流。

请按负载需要将外部电源的限流值设置为不超过 3 A，必要时进一步降低。voloo 不提供主动限流，保险丝也不是精确限流器。

主动泄放用于已经断开外部供电的负载残压，不是给电池放电或吸收持续供电功率的电子负载。

上电前必须确认

1. 正负极接反会损坏硬件。 接线前确认电源极性，关闭电源输出后再按外壳 + / − 标记连接，不要只凭端子左右方向判断。
2. 不要用同一个适配器，同时给设备和 USB 操作电脑供电。 负载端使用独立电源 A，经 voloo 的 IN / OUT 给设备供电；操作电脑使用另一独立电源 B。同一多口适配器的不同输出口也不算独立电源。
3. 负载电流不要超过 3 A。 超过最高建议电流可能损坏硬件。接线前设置外部电源限流，并考虑启动瞬间的电流。

接线顺序

1. 电源还未连接 voloo 时，用万用表确认电源的正负极，再关闭电源输出。
2. 电源 A → IN / SOURCE，核对正负极；A 不与操作电脑共用适配器。
3. OUT / DUT → 设备。设备只从 OUT 取电，断开它自带 USB、电池、调试器 VCC / 3V3 等其他供电。
4. 电脑 USB → voloo USB-C，使用数据线。电脑由另一独立电源 B 供电；负载不从电脑 USB 取电。
5. 使用调试器或 USB 转串口时，只连接需要的 GND 和信号线，不接它们的供电输出。
6. 确认标称电压范围、极性、独立供电和电流限制均正确后，再打开独立电源。

图 3：负载与 USB 操作电脑分别使用独立电源。这里的“独立”指不同适配器或独立直流电源，不是同一适配器上的不同输出口。

设备同时接入其他供电可能造成 OUT 倒灌，使关断后设备仍有电，甚至损坏硬件或电脑 USB 口。

3 第一次连接

先列出设备，再读取当前状态：

voloo ls
voloo status

只有一台设备时，status 等读取命令可以不写设备名。连接多台设备时，请指定 voloo ls 列出的完整 UID 或唯一昵称。

可以给设备起一个好记的昵称，例如 bench-a。设置昵称要求输出已经完全关断且设备空闲；不要为了改名而在未确认负载用途时切断供电。

# 将下面的示例 UID 替换为 voloo ls 实际列出的完整 UID
voloo name 5E-11-D0-00-00-00-00-01 bench-a

昵称会保存在设备中，重新插拔后仍可使用。后文的 bench-a 都指你已经确认并命名的那台设备；也可以直接使用它的完整 UID。

4 用网页仪表盘控制

voloo ui

命令会打开本机浏览器。仪表盘列出连接的 voloo，显示输入电压 VIN、输出电压 VOUT、当前状态、最近的输出电压变化和需要处理的故障。界面语言可选择简体中文，外观可选择浅色、深色或跟随系统。

图 4：中文版仪表盘，使用 voloo demo 模拟设备截图。图中的 UID、电压与操作状态是演示数据，不是实物测试记录。

• 切换供电： 按住设备开关约 0.6 秒。短按只显示提示，松开后不切换。
• 查看详情： 点击设备，查看详细状态、泄放、断电重启、改名和锁定等操作。
• 锁定设备： 锁定期间，网页、终端、Agent 和 API 的供电及改名操作会被拒绝；明确解锁后恢复。
• 处理未知结果： 先重新读取状态，确认设备实际处于什么状态，再决定下一步。

图 5：设备详情操作区（模拟设备截图）。先核对设备名称和 UID，再长按需要执行的操作；结果未知时先“检查状态”，不要盲目重复。

不想自动打开浏览器时：

voloo ui --no-open

它会输出一次性登录链接，需在 60 秒内打开。这个链接仅用于本机访问，不要当作可以发给朋友的公开网页。

5 常用命令

所有改变供电或设备昵称的命令都必须明确指定设备，不能省略目标。

off 和 discharge 怎么选

off 只断开供电，适用于你只想关断、并且会自行确认负载残压的场景。discharge 会先关断再主动泄放，确认输出 ≤ 1 V 才报告完成，设备的泄放等待上限为 5 秒。

需要反复冷启动时，优先用 cycle：它默认先泄放，完成后再等待指定时间，最后重新上电。任一步失败都不会继续执行后面的上电操作。

cycle --no-discharge 会改为普通 OFF 后等待；它没有确认残压已降到 ≤ 1 V，不应把它当作泄放完成。

命令的结果怎么判断

命令执行后，voloo 会读取设备状态，再报告设备确认的结果。丢失回复时不会自动重发电源命令。

脚本可以添加 --json 读取结构化输出，并根据退出码决定下一步：

6 接入 AI Agent

voloo 提供本地 stdio MCP 服务；以下为不同客户端的配置示例，配置位置与权限设置依客户端版本而异。先完成 npm 安装，再按客户端选择接入方式。由客户端启动 voloo mcp，不需要另开一个终端让它一直运行。

Codex

安装了 Codex CLI 时，在终端执行：

codex mcp add voloo -- voloo mcp

也可以将以下条目合并到 ~/.codex/config.toml，保留文件中的其他设置：

[mcp_servers.voloo]
command = "voloo"
args = ["mcp"]

参见 Codex 官方 MCP 命令说明。

Claude Code

claude mcp add voloo -- voloo mcp

Cursor

将 voloo 条目合并到 ~/.cursor/mcp.json 的 mcpServers 中；已有其他 MCP 服务时不要覆盖它们：

{
  "mcpServers": {
    "voloo": {
      "type": "stdio",
      "command": "voloo",
      "args": ["mcp"]
    }
  }
}

参见 Cursor 官方 MCP 配置说明。

VS Code Copilot

新版 Copilot 可在项目根目录的 .mcp.json 中使用以下配置：

{
  "mcpServers": {
    "voloo": {
      "type": "stdio",
      "command": "voloo",
      "args": ["mcp"],
      "tools": ["*"]
    }
  }
}

配置位置和格式依客户端版本而异。请查看 VS Code 官方 MCP 配置说明，合并配置，不要直接覆盖已有文件。

其他本地 MCP 客户端

在客户端的 MCP 设置中选择本地 stdio 服务，填写：

如果客户端提示找不到 voloo，先在终端运行 voloo --version 确认安装成功；必要时将启动命令换成 voloo 可执行文件的完整路径。

接入后怎么用

先让 Agent 读取设备列表和状态，确认目标后再控制供电。例如：

列出连接的 voloo，告诉我每台设备的昵称、当前状态和故障。

确认 bench-a 是目标设备后：

把 bench-a 冷启动一次：泄放后等待 2 秒，再重新上电，并报告设备确认的结果。

Agent 可以使用以下工具：

如果只希望 Agent 查看设备，不允许它切换供电或改名，可在 voloo 的 ~/.voloo/config.toml 中合并以下设置：

[mcp]
read_only = true

这是 voloo 的设置，不是 Agent 的 MCP 配置。启用后，MCP 写入操作会被拒绝；需要临时阻止各客户端修改某台设备的供电或昵称时，可使用 voloo lock 设备名。

7 过压保护与恢复供电

有效 VIN 降到 30.0 V 以下时，过压保护锁定会自动解除；但输出仍保持关闭，不会自动恢复供电。

整个过程是：

1. 发生过压： 有效 VIN 测量值 > 30.5 V 时，固件关闭已有输出，并禁止新的开启操作。
2. 电压恢复： 有效 VIN < 30.0 V 时，固件自动解除过压保护锁定，不需要额外的复位或解锁命令。此时输出仍为 OFF。
3. 用户重新开启： 先确认输入已回到标称 3.3–28 V 范围，极性、供电方式与电流限制均正确，再在仪表盘长按“开启供电”、发送新的 voloo on bench-a 命令，或明确让 Agent 开启目标设备，才会重新接通输出。

这里不是要求按硬件按钮，而是必须重新发起一次开启操作。网页、CLI、脚本和 Agent 发送的新开启命令都可以；固件不会自行重新开启。

之前的 ON 状态和过压期间被拒绝的开启命令都不会自动恢复或重放。这样可以避免电源电压一恢复，负载就意外启动。

这里的过压保护锁定与 voloo lock / voloo unlock 的操作锁是两回事。不要用 voloo unlock 来“复位过压保护”；它不负责解除过压。若你另外设置了操作锁，则仍需按用途处理该操作锁。

VIN 无效或采样过期时也会禁止开启并关闭已有输出。过压关断不会自动开始主动泄放。保护依赖固件的有效 VIN 测量值，软件阈值不等同于硬件瞬态钳位；正常使用仍按 3.3–28 V 标称工作范围。

固件维护方法见 USB 固件说明。维护时只使用适用于目标设备的升级包，并保留身份核验和安全检查。

8 在脚本和程序中调用

最简单的方式是调用 CLI，并检查退出码。以下 Python 示例会在命令失败时停止，不会自动重试：

import subprocess

subprocess.run(
    ["voloo", "cycle", "bench-a", "--off-ms", "2000"],
    check=True,
)

需要结构化数据时，使用 voloo --json status bench-a 等命令。其他语言也可以调用同一个 CLI，无需重新实现设备协议。

也可以使用本机 HTTP API：

voloo api-info --json

它会提供当前 API 地址、访问令牌和接口说明位置。后台进程重启后，地址和令牌可能变化，程序应在启动时重新读取。

请求需要带 Authorization: Bearer 令牌。API 仅用于这台电脑，不是局域网服务；不要将令牌或本机登录链接发给其他人。详细 HTTP 示例见 英文说明。

9 常见问题

需要提供问题记录时：

voloo report

命令只在本机生成诊断文件，不会自动发送。发送给他人前，先打开文件确认内容适合分享。

10 后台进程和本地文件

CLI、仪表盘、MCP 和 HTTP API 共用一个本机后台进程来管理 USB 端口。它会按需启动；没有客户端使用时，默认空闲 10 分钟后退出。启动或停止后台进程都不会改变设备输出。

voloo daemon status
voloo daemon stop

默认配置保存在 ~/.voloo/config.toml，日志保存在 ~/.voloo/logs/，诊断报告保存在 ~/.voloo/reports/。设置 VOLOO_HOME 可以更换存放目录。

停止后台进程、关闭浏览器或拔下 USB 都不能代替明确的关断和状态确认。结束使用前，按负载需要执行关断或泄放，并确认结果。