williamnie/sing-box-manager-gui/sing-box-manager

sing-box manager（sbm）Agent 操作

所有操作都通过 sbm ctl 完成。它是 Agent API 客户端，用 sbm ctl connect 保存的连接（局域网 HTTP、HTTPS 或本机回环）和 Bearer 令牌访问管理器。不需要 SSH，也不需要 sudo。

1. 连接

优先复用已保存的连接：直接执行 sbm ctl capabilities。它返回当前令牌的权限（scopes）、可修改的资源及字段、确认窗口的范围与保证说明。以它的返回为准，不要凭记忆假设。

如果提示找不到 sbm、没有已保存连接或令牌失效（退出码 4），让用户按下面的步骤接入，并明确告诉用户每一步在哪台设备上做：

1. 浏览器：打开管理界面（通常是 http://网关局域网IP:9090）→「Agent 接入」→ 创建令牌，勾选需要的权限。
2. Agent 电脑（就是你正在运行的这台电脑）：复制同一页面的「一键接入命令」到终端执行，形如 curl -fsSL 'http://网关IP:9090/agent/setup.sh' | sh。它会从管理器下载 sbm、安装本 Skill 并提示粘贴令牌。令牌由用户在终端里粘贴，不要让用户把令牌发给你，也不要替用户执行这条交互命令。
3. 用户完成后，新开 shell 执行 sbm ctl capabilities 确认。若仍找不到 sbm，试 ~/.local/bin/sbm。

如果管理页面只能通过 127.0.0.1 打开（管理器只监听本机），用户需要先在网关服务器上开启局域网访问（例如重新运行安装脚本并加 --lan-http <服务器局域网IP>），这属于管理员操作，你只做说明。

已验证的连接保存在 ~/.config/sbm/connection.json，包含令牌；不要读取或回显其内容。切换其他服务地址时不能复用已保存令牌，需要重新连接。

手动指定连接参数时，普通命令的全局参数写在子命令之前：

不要索要管理密码，也不要把令牌写进命令行参数、环境变量或日志。

2. 硬性规则

1. 先读后写。 任何修改前先跑 sbm ctl status，看 active_operation、config.pending、core.running。
2. 只用变更集修改。 所有写命令只创建并校验变更集，不改运行配置。真正生效需要 change apply，然后在确认窗口内验证，再 change confirm。
3. 应用后必须验证再确认。 验证手段：explain domain、connections、dns、logs。验证失败或拿不准时执行 change rollback，不要确认。
4. 不夹带别人的改动。 status 中 config.pending.exists=true 表示有人在界面保存了改动但尚未应用。默认情况下变更集无法应用（退出码 3）。应该把 sbm ctl diff 的内容告诉用户，用户同意后才用 --include-pending <digest> 重新创建。
5. 不要绕过限制。 网关启用/恢复、拓扑变更、影响 bypass 网段的设备变更、内核升级、root 策略、端口/路径/监听设置都不在 Agent API 范围内。需要时说明原因，建议用户在管理界面操作；只有用户为这类维护另行明确授权并提供相应权限时，才按用户的具体指示执行。不要自行用 SSH 改数据文件、sudo 或调用旧接口来绕过。
6. 区分三种证据。 saved 表示已保存；applied 表示已写入运行配置（内核运行时生效）；runtime 指实时连接或 DNS 记录，是真实流量证据。报告结论时说明依据的是哪一种。explain 中的 may_match_first 表示静态推断无法确定的规则，不要当成事实。
7. 确认窗口的保证有限。 管理器运行期间，到期未确认会自动回滚；管理器重启时会优先恢复。管理器停机或崩溃期间不保证准时回滚，所以对可能断网的改动要缩短窗口，并尽快验证。
8. 退出码驱动分支。 0 表示成功；1 用法错误；2 被服务端拒绝（参数或校验失败，修正后重试）；4 令牌无效或权限不足，告诉用户需要哪个权限；5 网络或服务端错误，可用相同的 --idempotency-key 重试。3 表示需要决策，按 code 分别处理：

• base_changed / candidate_changed / expired / imported_revision_changed：数据在此期间变了。若用户的意图没变、改动范围也没变，可重新读取状态后重建变更集，最多重试 2 次；如果新状态让改动的含义变了，就停下来说明。
• operation_pending：先 sbm ctl change list 查看。如果是你自己刚应用的变更，继续完成验证并确认或回滚；如果是别人的，等待并报告。
• pending_changes（他人保存但未应用的草案）、recovery_required、gateway_change_forbidden、revert_conflict，以及任何需要扩大改动范围的情况：停下来报告并询问用户。

3. 标准修改流程

sbm ctl status                                   # 无 active_operation，pending.exists=false
sbm ctl rule add --name 公司内网 --type domain_suffix --value corp.example --outbound DIRECT
# → 输出 data.id、changes、config_changes、warnings、apply_ready
sbm ctl change apply <id> --confirm-within 120   # state=pending_confirm
sbm ctl explain domain git.corp.example          # applied.outbound 应为 DIRECT
sbm ctl connections                              # 如有实时流量，核对 chains/rule
sbm ctl change confirm <id>                      # 或 sbm ctl change rollback <id>

要撤销一个已确认的变更，执行 sbm ctl change revert <id>。它会生成新的撤销变更集，同样需要 apply → 验证 → confirm。只有该变更之后没有任何其他修改时才能撤销（否则返回 revert_conflict，应改为新建反向变更）。只保留最近 20 个已确认变更的恢复数据。未确认的变更直接用 change rollback。

一次要改多项时，写一个 ops 文件，用 sbm ctl change create --file ops.json 一次提交，这样只应用一次、只确认一次。各资源的字段见 references/ops.md。

节点（手动添加或订阅拉取）只接受常见代理协议及其协议字段，禁止引用本地文件（*_path）、覆盖 type/tag/server 等保留键，以及 bind_interface/detour 等拨号字段；被拒时如实告诉用户原因，不要改写节点去绕过。

订阅 URL 和节点分享链接含凭据，只能从文件或 stdin 传入，例如 sbm ctl sub add --name 主订阅 --url-file -，然后通过 stdin 输入 URL。读取类输出会自动脱敏。

4. 排查

先读 references/troubleshoot.md。常用命令：

• sbm ctl explain domain <域名> [--source <设备IP>]：已保存与已应用配置分别命中哪条规则、DNS 查询记录、实时连接。
• sbm ctl explain client <IP>：设备策略、按来源匹配的规则、该设备最近的 DNS 查询和连接。
• sbm ctl logs --grep <关键字> --lines 500、sbm ctl dns --domain <域名>、sbm ctl proxies、sbm ctl delay <节点...>。
• sbm ctl rules：规则的实际生成顺序（自定义 → 预设组 → 导入 → final）。

领域概念（部署模式、设备策略、规则顺序、DNS 旁路）见 references/concepts.md。

5. 命令速查

只读（read 权限）：capabilities status diff versions rules get <资源> nodes [--country HK] proxies connections kernel gateway status|clients|plan explain domain|client logs dns audit change list|show <id>

运行态（runtime 权限，不改持久配置）：select <选择组> <节点>、delay <节点...>

变更（write 权限创建，deploy 权限应用、确认、回滚）：

• rule add|delete|enable|disable
• block add|remove <域名...>
• sub add|refresh|delete
• node add|delete
• op <action> <resource> [id] --value JSON | --value-file F
• change create --file F
• change apply|confirm|rollback <id>

完整用法：sbm ctl help。