fanbox-agent

FanBox 终端控制

只在 FanBox 桌面 app 的终端里可用。先确认门票在手：

[ -n "$FANBOX_CTL" ] && echo "在 FanBox 里，我是 $FANBOX_TERM_ID 号窗口" || echo "不在 FanBox 终端里，本 skill 不可用"

三个环境变量由 FanBox 注入：FANBOX_CTL（接口地址）、FANBOX_CTL_TOKEN（门票，每次启动随机、只存在于 FanBox 终端的环境里，绝不外传、不写进文件）、FANBOX_TERM_ID（自己的窗口 id）。

别给自己（$FANBOX_TERM_ID）发指令——那会把你自己的输入流打乱甚至死循环。

接口速查

所有请求带 x-fanbox-token 头。以下用 CT 缩写公共参数：

CT=(-s -H "x-fanbox-token: $FANBOX_CTL_TOKEN")

列出所有终端窗口（id / 目录 / 前台进程 / 忙闲 / 最近输出尾巴）：

curl "${CT[@]}" "$FANBOX_CTL/terminals"

读某窗口最近输出（去 ANSI 纯文本，默认 200 行，最多 2000）：

curl "${CT[@]}" "$FANBOX_CTL/read?id=t2&lines=100"

给窗口发指令（默认自动补回车提交；"submit": false 只输入不提交；多行文本发给 claude 等 TUI 加 "paste": true 走 bracketed paste 整块粘贴）：

curl "${CT[@]}" -X POST -H 'Content-Type: application/json' \
  -d '{"id":"t2","text":"npm test"}' "$FANBOX_CTL/send"

控制键直接发字符本身，如 Ctrl-C：{"id":"t2","text":"","submit":false}。

新开终端窗口（可选 autorun 开窗即执行，会等 shell 就绪再敲）：

curl "${CT[@]}" -X POST -H 'Content-Type: application/json' \
  -d '{"cwd":"/path/to/project","autorun":"claude \"跑通所有测试\""}' "$FANBOX_CTL/create"
# → {"ok":true,"id":"t5","autorun":true}

等窗口告一段落（HTTP 长轮询，timeoutMs 最长 240000）：

curl "${CT[@]}" -X POST -H 'Content-Type: application/json' \
  -d '{"id":"t5","timeoutMs":120000}' "$FANBOX_CTL/wait"

三种等法：

• 默认：前台回到裸 shell 且输出静默 ≥ idleMs（默认 2000）——适合等普通命令跑完
• "idle":"quiet"：只看输出静默——适合等 claude 等常驻 TUI 回答完，建议配 "idleMs":3000
• "until":"正则"：新输出匹配到正则就立刻返回——注意只匹配 wait 开始之后的新输出，所以要在结果出现前就发起 wait。命令回显也算输出：你敲的命令本身会先出现在流里，正则要用 ^ 锚定行首（如 "^DONE$"）才不会匹配到自己发的命令

返回 {ok, idle|matched|exited|timeout, elapsed, output}，output 是等待期间的输出（最后 8KB），通常不用再 read。

关闭窗口：

curl "${CT[@]}" -X POST -H 'Content-Type: application/json' -d '{"id":"t5"}' "$FANBOX_CTL/kill"

定时任务：用户白话 → 你换算成 schedule

用户说「每天早上 9 点整理灵感箱」「周五下班前汇总本周改动」「两小时后跑一遍测试」时，把意图换算成 schedule 对象调接口。到点 FanBox 会自动开一个终端窗口执行（FanBox 没开着则记「错过」不补跑）。