moonbox-agent
v0.1.0
Published
Moonlight Treasure Box (moonbox) — Siming Cave Dwelling node agent: a connector installed on the user's machine, with outbound WSS connecting back to the Daofu platform, remotely driving local Harness (encapsulating pi, which can control the local desktop
Readme
月光宝盒 agent(moonbox)
部署在局域网 Linux / macOS / Windows 机器上的轻量守护进程:主动向道否平台发起 出站 WSS 长连接,接收任务指令(建任务/续聊/取消/审批)、驱动本机 Harness (zcode / opencode / dsh / pi / qwen-code)并把进度事件回传平台。模型 API Key 与 会话数据全部留在本机,平台只转发指令与事件。
安装与注册
前置:目标机 Node.js ≥ 20;本机已安装至少一个受支持的 harness(zcode --version /
opencode --version / dsh --version 可用;agent 启动时自动探测并上报能力)。
moonbox 只装连接器:不安装任何 harness CLI 与模型 SDK,模型 API Key 留在本机。
npm 全局安装(推荐,三平台通用)——发布包为单一 moonbox-agent(bin 命令
moonbox),运行时仅依赖 ws/zod,不携带 harness SDK:
npm i -g moonbox-agent # 或 npm i -g moonbox-agent-0.1.0.tgz
# 可选:需要 pi / qwen-code 这类 SDK 型 harness 时,显式安装其 SDK(与 moonbox 同层)
npm i -g @earendil-works/pi-coding-agent @qwen-code/sdk
moonbox --enroll <一次性令牌> --server https://<平台地址> [--name 书房-Mac-mini]
moonbox # 常驻运行Linux 也可用脚本一步安装/更新(在本仓库执行,构建 → 打包 → 传输 → 装 systemd 服务 → 重启;更新不触碰注册状态):
pnpm agent:install # 本机
pnpm agent:install -- [email protected] # 远端洞府(ssh 可达,装 /opt 需 sudo)安装完成后只需一次注册(见下);此后升级重复执行同一命令即可。
手动方式(macOS/Windows 或自定义部署):
# 在本仓库构建(或把 apps/agent 拷到目标机器构建)
pnpm --filter moonbox-agent build
# 1. 平台 Web「司命」页生成一次性注册令牌(24h 有效)
# 2. 在洞府机器上注册(只需一次)
node apps/agent/dist/index.js \
--enroll <一次性令牌> \
--server https://<平台地址> \
--name 书房-Mac-mini
# 3. 常驻运行
node apps/agent/dist/index.js状态保存在 ~/.siming-agent/state.json(SIMING_AGENT_HOME 可改);删除该文件
并在平台删除洞府即解绑。未确认的事件与审批请求镜像到同目录 outbox.json
(原子写,上限 2000 条,超限最旧优先丢弃),agent 重启后自动重放。
环境变量
| 变量 | 说明 |
|---|---|
| SIMING_AGENT_HOME | 状态目录(默认 ~/.siming-agent) |
| SIMING_WORKSPACES | 工作区白名单:冒号/逗号分隔的授权根目录(支持 ~ 展开),如 ~/projects:/srv/work;未配置不限制。白名单外的任务指令直接拒绝(/srv/work-evil 这类前缀碰撞路径同样拒绝) |
| SIMING_DSH_PROVIDER | dsh 路由 provider(默认 deepseek-official) |
| SIMING_DSH_MODEL | dsh 路由 model(默认 deepseek-chat) |
| SIMING_DSH_DENY_TOOLS | dsh 工具黑名单(逗号分隔;dsh 对未知工具名会使 prompt 失败,配置前先核对工具名) |
| MOONBOX_DESKTOP_KEY | 桌面操控密钥:与平台(daofor 侧同名 env)配同一值后,pi 任务可申请操控本机桌面(截图/点击/输入/按键/滚动);未配置或不匹配即拒绝(fail-closed)。hello 帧据此外报 desktop 能力 |
系统服务(开机自启)
Linux 用 pnpm agent:install 时自动创建并管理 systemd 单元(moonbox.service,
运行用户 = ssh 登录用户,EnvironmentFile=-/etc/moonbox.env 可选配置落点——
即上表环境变量可写进该文件)。手动部署参考以下模板:
Linux (systemd) — /etc/systemd/system/moonbox.service:
[Unit]
Description=Moonbox — Daofor Siming Node Agent
After=network-online.target
[Service]
ExecStart=/usr/bin/node /opt/moonbox/dist/index.js
Restart=always
RestartSec=5
User=youruser
[Install]
WantedBy=multi-user.targetmacOS (launchd) — ~/Library/LaunchAgents/com.moonbox.agent.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>com.moonbox.agent</string>
<key>ProgramArguments</key><array>
<string>/usr/local/bin/node</string><string>/opt/moonbox/dist/index.js</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
</dict></plist>Windows — 以任务计划程序(开机触发)或 node dist\index.js 配 NSSM 注册为服务。
行为说明
- 心跳 30s(覆盖 nginx 300s 读超时);断线指数退避重连(1s→60s)。
- 事件按 (taskId, seq) 缓冲,收到平台确认后裁剪;重连后未确认事件全部重放 (平台幂等去重)。seq 以毫秒时间戳为基准,agent 重启后不会与历史事件撞号; 缓冲同时落盘(去抖 500ms、退出即写),进程重启后继续重放。
- 审批:zcode 的
interaction/requestPermission反向请求转发平台裁定; 断线期间 harness 每 1s 重发同 requestId 的请求,平台按既有决策自动补答。 opencode 的permission.asked事件转发平台裁定,回复映射 allow→once、 deny→reject(会话存在期逐次询问,不放大授权面)。 - opencode:每任务 spawn
opencode serve --hostname 127.0.0.1 --port 0(仅本机回环、免密),指令走 REST(prompt_async异步发话)、进度走GET /eventSSE;mode 映射 build/edit→buildagent、plan→planagent、 yolo→会话级全放行 ruleset。文件改动经session.diff事件上送, 平台任务详情以 diff 视图渲染。 - dsh:每任务 spawn
dsh --profile sdk(stdio JSON-RPC 2.0),session/prompt未知 sessionId 懒建会话(续聊/恢复即复用同一 id)。无远端审批回调:permission:'allow'自动放行(SIMING_DSH_DENY_TOOLS可收紧),任务日志 标注「自动放行模式」。 - 工作区白名单:设置
SIMING_WORKSPACES后,平台下发的任务只允许落在授权 根目录内,越界指令直接拒绝并回执错误。 - 依赖出站 443(WSS);无需在局域网开放任何入站端口。
与平台的契约
WSS 帧 schema 与注册接口见 @moonbox/contract(本仓库 packages/contract,
daofor 侧 packages/shared/src/siming.ts 的同步副本)。协议版本
SIMING_PROTOCOL_VERSION 在 hello 帧 v 字段协商,不兼容变更需两侧同步升版。
