快速开始

默认面向 Agent:装好 CLI 与 Skill,让 Agent 管本机。人工需要看面板时,再用 Cloudflare Tunnel 把本机服务映射到域名。推荐版本 v0.3.7。

Agent 路径:安装 CLI + Skill → 启动服务 → 用 JSON / Skill / MCP 操作。Web 面板可选。

一键复制给 Agent 的 Prompt

粘贴到当前对话,让 Agent 自行安装、启动并用 CLI / Skill 接管本机。不要改 Prompt 里的安全约束。

请在这台 Linux 主机(x86_64 或 ARM64)安装并启用 Bot VM Ops,让你之后用它的 CLI / Skill 管理本机,而不是随便猜 shell。

约束:
- 服务默认只绑定 127.0.0.1;CLI 只连本机。
- 不要打印、粘贴或请求 token / tunnel-token 文件内容。
- 改文件前确认路径在已授权根内;不要扩权、不要执行任意 shell 当替代品。
- 指标 unavailable 不要当成 0。

步骤:
1) 安装最新 CLI,并把 bot-vm-ops Skill 装到当前 Agent 的 skills(Codex 示例用 --agent codex;若你是别的 Agent,改成对应值):
set -eu
install_dir="$(mktemp -d)"
trap 'rm -rf "$install_dir"' EXIT
curl --fail --show-error --location --proto '=https' --proto-redir '=https' \
  https://github.com/fenfenxu/bot-vm-ops/releases/latest/download/install.sh \
  -o "$install_dir/install.sh"
sh "$install_dir/install.sh" --bin-dir "$HOME/.local/bin"
command -v bot-vm-ops || export PATH="$HOME/.local/bin:$PATH"
bot-vm-ops --version
npx skills add fenfenxu/bot-vm-ops --skill bot-vm-ops --agent codex --global --yes

若工作区在 /workspace/bot-vm-ops(Grok 等),改用:
cd /workspace/bot-vm-ops && ./install-bin.sh
并把二进制路径记为 /workspace/bot-vm-ops/bin/bot-vm-ops。

2) 若服务未在跑,启动它(后台常驻按平台能力处理;不要输出 token):
# 默认用户安装
bot-vm-ops serve
# 或 Grok 工作区
mkdir -p /workspace/bot-vm-ops/data
/workspace/bot-vm-ops/bin/bot-vm-ops serve \
  --token-file /workspace/bot-vm-ops/data/token \
  --file-root /workspace

3) 探活并做一次只读检查:
bot-vm-ops health --json
bot-vm-ops system current --json
bot-vm-ops bots list --json

4) 之后凡是监控、进程、Bot、历史、授权目录文件,优先用 bot-vm-ops … --json 或已安装的 bot-vm-ops Skill;需要 MCP 时再用 bot-vm-ops mcp。
5) 若用户还要在外网浏览器看 Web 面板,再按产品站「Cloudflare Tunnel」说明映射到本机 9876,并用 serve --web-origin https://确切域名;不要把端口裸暴露到公网。

完成后用一两句话汇报:CLI 版本、服务是否 healthy、Skill 是否已装,以及下一步你可以帮用户做什么。
命令拆解(可选对照)

安装 CLI 和 Skill

Linux x86_64 / ARM64。需要 curl、Node.js/npm。

$ sh install.sh --bin-dir "$HOME/.local/bin"
$ npx skills add fenfenxu/bot-vm-ops --skill bot-vm-ops --agent codex --global --yes

启动本机服务

默认 127.0.0.1:9876。不要把 token 内容贴进对话。

$ bot-vm-ops serve

探活

$ bot-vm-ops health --json
$ bot-vm-ops system current --json

可选:给人开 Web(Cloudflare Tunnel)

公网域名指到 http://127.0.0.1:9876,并用 --web-origin。详见下方 Tunnel 一节。

用 Cloudflare Tunnel 做域名访问

解决「服务已起来,但只能本机看」的问题。服务继续听 127.0.0.1;公网只走 Cloudflare 边缘到 Tunnel。

1. 账号与域名

注册 Cloudflare,把域名 DNS 交由 Cloudflare 代理(橙云)。没有自有域名时,先用 Cloudflare 文档中的试用 / 快速隧道方案验证连通,再生产环境再绑正式域名。

2. 创建 Tunnel

Dashboard → Zero Trust → Tunnels。创建后得到安装命令或 token。把 token 写到本机文件(如 data/tunnel-token),权限 600;进程用 cloudflared tunnel run --token-file … 常驻。

3. 主机名映射

Public Hostname 指到 http://127.0.0.1:9876(或你改过的本机端口)。DNS CNAME 一般由 Tunnel 自动写入。

4. 对齐 Origin

serve --web-origin https://你的域名 必须与浏览器 Origin 完全一致,否则会话 / CSRF 会失败。改域名或协议后需重启服务。

# 示意:token 文件勿泄露;路径按你的机器调整
$ cloudflared tunnel --no-autoupdate run --token-file "$HOME/.config/bot-vm-ops/tunnel-token"
$ bot-vm-ops serve --web-origin https://ops.example.com

产品站本身在 ops.droplink.cloud。你自己的面板域名请另建 Tunnel 主机名,不要覆盖别人的映射。

接下来怎么用

装完只是开始。按角色继续:人看 Web,Agent 走 Skill / CLI / MCP。

查看 Web 面板

登录后从侧栏进入:实时监控、历史趋势、进程、Bot、授权目录文件、审计。文件与危险操作有二次确认;不可读指标会标 unavailable,不会假装成 0。

  • 本机:http://127.0.0.1:9876
  • 远程:你的 Tunnel HTTPS 域名 + 匹配的 --web-origin
  • Token:配置目录中的文件,勿提交仓库

使用 Skills

仓库 skills/bot-vm-ops/ 教 Agent 何时调用 CLI、如何探活、如何有界读日志与改文件。

# 只装 Skill(CLI 已存在时)
$ npx skills add fenfenxu/bot-vm-ops --skill bot-vm-ops --agent codex --global --yes

说明见 SKILL.md。Agent 应先 health --json,再查系统 / Bot;改文件前确认路径在已授权根内。

CLI 与 MCP

JSON 写 stdout、日志写 stderr。常用只读命令:

$ bot-vm-ops doctor --json
$ bot-vm-ops processes list --sort memory --limit 20 --json
$ bot-vm-ops bots diagnose <id> --from <ms> --to <ms> --json
$ bot-vm-ops mcp

MCP 复用本机凭据与边界,适合已接 MCP 的 Agent 运行时。

分发细节: docs/distribution.md · 设计: design.md