Nº12 · Operations toolkit · private repo运维工具集 · 私有仓库macOS supervision & monitoring · Oct 2026macOS 进程监督与监控 · 2026 年 10 月
Remote Commander Ops
Keeps a home Mac reachable from a phone through an AI chat client: launchd supervision, a safe installer, and a metadata-only monitor that says why remote access is down.让家里的 Mac 能通过手机上的 AI 聊天客户端随时被调用：launchd 监督、安全的安装器，以及只记元数据、能说清为什么断线的监控。
- Phone · AI chat client手机 · AI 聊天客户端
- Vendor relay厂商中继
- launchd · pinned runtimelaunchd · 锁定运行时
- Single instance?单实例？
- Monitor · class + alert监控 · 分类 + 告警
SECTION · REMOTE COMMANDER OPSDesign view · code private设计视图 · 代码私有
01Problem问题
The vendor's remote device is a long-running process that holds a rotating OAuth session. Started by hand it dies with the terminal; started twice it rotates the same refresh token and breaks the connection; supervised naively it restarts every 30 seconds forever after a logout. And a running process does not mean the relay connection is alive.厂商的远程设备是一个持有轮换 OAuth 会话的常驻进程。手动启动会随终端一起退出；启动两份会互相轮换同一个刷新令牌、弄断连接；简单交给监督器又会在登出后每 30 秒无限重启。而且进程活着并不代表中继连接还在。
02What I built我做了什么
- A pinned runtime under launchd. The launcher refuses to start a second supervised instance and waits while a terminal-launched one exists; matching the vendor process by its full command line fixed a real bug where a full-path
nodeor a path with spaces slipped past.锁定版本的运行时交给 launchd。启动脚本拒绝启动第二个托管实例，并在终端手动实例存在时等待；按完整命令行匹配厂商进程修复了一个真实 bug：完整路径的node或带空格的路径曾被漏判。 - An installer with
--check(read-only diff), idempotent--prepareand--activate --yesthat backs up, swaps and restores itself when launchd rejects the new job. Every path is tested against stubbedlaunchctl,psandplutil.安装器提供只读对比的--check、幂等的--prepare，以及会先备份、再替换、launchd 拒绝时自动回滚的--activate --yes。每条路径都用替身的launchctl、ps、plutil测试。 - A one-minute monitor classifies each tick as ok / process / auth / relay / network / unknown: it counts the supervised pid's established connections to the relay port, probes the network only when that connection is gone, and reads the session file's age against the vendor's 45-minute refresh. Three consecutive failures raise one alert; recovery raises one more. Notification ships off.每分钟一次的监控把每个时刻分为 ok / process / auth / relay / network / unknown：统计托管进程到中继端口的已建立连接，只在连接消失时探测网络，并按厂商 45 分钟的刷新节奏判断会话文件是否过期。连续三次失败只发一次告警，恢复再发一次；通知默认关闭。
- The same process matcher exists in awk (launcher) and Python (monitor); a parity test runs both over one fixture corpus and caught the one case where they disagreed.同一套进程匹配逻辑在 awk（启动脚本）和 Python（监控）里各有一份；一致性测试用同一组样例跑两边，抓到了唯一一处分歧。
03Architecture架构
04Measured测量结果
160
tests: 89 Python unit tests + 71 shell cases with stubbed launchctl, ps and plutil测试：89 个 Python 单元测试 + 71 个用替身 launchctl、ps、plutil 的 shell 用例
src · kais-commander-ops/tests (private)
6
health classes from metadata only仅凭元数据得出的健康分类
src · kais-commander-ops/scripts/healthcheck.py (private)
9 / 10
independent review findings fixed before merge; one rejected with evidence from the vendor source合并前修复的独立复审发现；一条依据厂商源码有理由地拒绝
src · kais-commander-ops PR #2 (private)
~40 d
health history kept at one record a minute每分钟一条记录可保留的历史
src · kais-commander-ops/scripts/healthcheck.py (private)
05Limits, stated plainly局限，直说
- One machine, one user. The relay is a third-party service; the monitor can tell a relay outage from a local one but cannot fix it.单机单用户。中继是第三方服务；监控能区分中继故障和本地故障，但无法修复中继。
- Reboot and crash drills are documented but not yet run; the 99.5% availability figure is a target, not a measurement.重启和崩溃演练已写明但尚未执行；99.5% 可用性是目标，不是测量结果。