launchd agent (com.example.agent-connect)
└── monitor.sh --foreground (守护进程,KeepAlive={SuccessfulExit:false} + RunAtLoad=true)
├── cleanup_stale_state: 启动时清理失效的 PID 文件
├── start_all: 拉起 3 个组件(nohup+disown,脱离进程树独立存活;已有同种进程则跳过)
│ ├── connect 进程(你的数字员工核心连接,如 dws dev connect / 自定义 bridge)
│ ├── serve-watcher.sh(监控 connect 日志,发首次启动通知)
│ └── event-watcher.py(SSE 事件流监听 + log-tail 业务路由 + 状态机 cleanup)
├── warmup: 触发依赖服务首次启动 + 提取凭据(pid/port/pwd → .serve.* 文件)
└── 主循环:每 CHECK_INTERVAL 秒 → healthcheck.sh
├── 健康 → 重置失败计数 + 兜底拉起 watchers(30 分钟内自愈)
└── 不健康 → 累加失败计数;未达熔断阈值 → 全量重启
└── 连续 MAX_FAILURES 次失败 → 熔断:notify_alert + exit 0
(exit 0 → launchd 不再拉起,等人工;
崩溃 exit 非零 / SIGTERM cleanup exit 1 → launchd 自动恢复)
healthcheck.sh (monitor 调用) — 7 项检查(5 硬 + 2 告警)
├── 检查1: connect 进程存活(PID 文件 + kill -0 + cmdline 签名,硬失败)
├── 检查2: 日志活跃度(35 分钟内有活动,仅告警)
├── 检查3: 日志尾部致命错误(grep FATAL/panic,硬失败)
├── 检查4: event-watcher 进程活跃(仅告警)
├── 检查5: serve 进程存活(PID + kill -0,硬失败)
└── 检查6: serve HTTP /session 响应(凭据自刷新,硬失败)
└── 检查7: 大脑真实自检(失败计数超阈值才真发一次模型调用,硬失败)
event-watcher.py (3 个独立线程 + 主线程)
├── 主线程: connect_sse() — 无限重试 + 退避(3s→30s)连 opencode serve /event
│ └── 收到 SSE 事件 → format_and_forward() → send_notification
├── log_tail_thread: tail connect 日志
│ ├── 解析 "[connect] 收到 @user: text (convType=...)" 行
│ ├── 跨行格式状态机 + 线程安全 dedup
│ ├── 路由到业务 handler(handle_reply / handle_image / handle_forward)
│ ├── /reboot 指令 → 派生 reboot.sh + os._exit(0)
│ └── 撤回空回复(监听 "agent 已生成回复" + "普通消息已发送" → recall)
└── 状态机 cleanup_state: 处理 spurious 多余轮次
├── awaiting_spurious → 等多余消息出现(原轮次事件正常放行)
├── cleaning → DELETE + abort 多余 user/assistant 消息
└── idle 时比较 deleted_user vs expected_count,未达标重置 awaiting_spurious
agent_common.py — 共享 Python 工具(被 event-watcher + handler 共用)
├── 常量(ROBOT_CODE/USER_ID/PROFILE/PROXY_URL/VISION_MODEL)
├── log / send_notification / _md
├── _run_cli (dws CLI 包装)
├── find_serve_credentials (进程表 + 环境变量提取)
├── serve_request (opencode serve HTTP 唯一出口:凭据 + Basic auth + 调试日志)
├── _clean_session_title (session title 归一:折行 + 限长)
└── _proxy_vision (多模态识别,逐字提取原文不总结)
注:会话的建/删/复用**不在这里**——那是后端策略,由 custom/brain.py 按 conv 维护
(见最佳实践 8)。core 只提供凭据发现与 HTTP 出口。
handler.py — 业务 handler(FDE 在 src/custom/handler.py 改造,模板在 src/templates/handler_template.py)
├── match_business_line (log-tail 调用,跨行检测 + 线程安全 dedup)
├── fetch_attachments (I/O 阶段:图片下载+vision / 文件下载+读正文)
├── render_prompt (纯函数零 I/O,单测无需 mock)
├── _lookup_senders_batch (一次 list-by-ids 批量反查 N 个 sender)
└── _fetch_senders (补齐缺失 sender,DingTalk summary 不完整时兜底)
注:只管「消息 → prompt」;生成回复由能力调 core.brain.generate_reply
文件: bin/core/monitor.sh + bin/custom/agent-template.plist
关键设计:
KeepAlive={SuccessfulExit:false}— exit 0 不拉起(等人工),崩溃/被杀会拉起RunAtLoad=true— 开机/登录自启ThrottleInterval=10— 10 秒内不重复拉起(防崩溃循环)- 连续
MAX_FAILURES次失败 → 熔断:发告警 + exit 0 - SIGTERM/SIGINT → cleanup exit 1(非零让 launchd 拉起,覆盖系统重启场景)
文件: bin/core/healthcheck.sh
关键设计:
- 硬失败(进程死、HTTP 无响应)→ 不健康,触发全量重启
- 仅告警(日志活跃度、非关键子组件)→ 不健康,记日志但不触发重启
- 输出 JSON:
{healthy, message, checks: {...}} - serve 凭据失效时从进程表 + 日志刷新
文件: bin/core/lib.sh
关键设计:
- PID 文件 + kill -0 检测进程存活
- cmdline 签名校验防 PID 复用(进程死了,新进程复用同 PID)
- pgrep -fi ^锚定兜底(PID 文件丢失时仍能检测,^锚定排除 send-by-bot 转发进程)
- 抽到 lib.sh 共享给 monitor + healthcheck,消除两处逻辑漂移
文件: bin/core/monitor.sh
关键设计:
- 启动时对每个组件 PID 文件做失效检测(PID 死/被复用 → 删除)
- start_* 前 is_running 检查,已有则跳过(避免重复拉起两个 watcher 并行)
- 主循环健康通过后兜底拉起 watchers(30 分钟内自愈)
文件: src/core/event_watcher.py 的 connect_sse()
关键设计:
- 无限重试 + 退避(
MIN_RECONNECT_INTERVAL→MAX_RECONNECT_INTERVAL,3s→30s) - serve 未启动时等待而非退出(interval 累加但不超过 MAX)
- 端口变更自动切换(凭据每次实时从
find_serve_credentials()获取) - 启动顺序不再敏感——event-watcher 比 serve 先启动也能自动恢复
文件: src/core/event_watcher.py 的 log_tail_thread()
关键设计:
tail -F+ inode 检测轮转(文件 inode 变化或变小则重开)- 跨行格式检测状态机(行 1 含 msgtype,行 2 含 msgId → 用
_pending_cross_line暂存) - 线程安全 dedup(
_seen集合 +_state_lock)
文件: core src/core/event_watcher.py 提供 TTL 兜底 + route_cleanup_state hook;
状态机实现在 custom src/custom/routes.py(业务特定,FDE 可编辑)
关键设计:
- core 只负责 TTL 过期兜底防僵死(
CLEANUP_TTL=40s)+ 调用 hook - awaiting_spurious → 等多余消息出现(原轮次事件正常放行)
- cleaning → DELETE + abort 多余 user/assistant 消息
- 多选/连发场景下累积删除
expected_count条 - idle 时不立即 pop:比较
deleted_uservsexpected_count,未达标重置 awaiting_spurious
文件: src/custom/brain.py 的 _conv_sessions / _http_reuse()
关键设计:
- 粒度是 conv_id(DingTalk 的 openConversationId),不是工作目录——一个目录下会有 上百个 session,"最近活跃的那个"未必属于当前这场对话,按目录复用会串上下文
_conv_sessions是OrderedDict:TTL 过期(AGENT_SESSION_TTL)+ LRU 逐出 (AGENT_SESSION_MAX,被挤掉的会话连远端一起删)_conv_lock(conv_id)单会话串行,不同 conv 并行不受影响- 自愈两路:复用的 sid 404(serve 重启/GC)→ 重建一次重试;复用的 sid 回空 (疑似后端 stream-error 把回合 completed 成空)→ 丢弃 + 删远端 + 新建重试
- 重置关键词(
AGENT_SESSION_RESET_KEYWORDS)让用户主动开新话题 - 逐轮换模型的那一轮是例外,不进主会话(#117):消息带
/flash等触发词 → 本轮改用AGENT_OPENCODE_MODEL_FLASH,且单开一次性 session 跑完即删。原因是 provider 的 prompt cache 按模型分桶——2026-08-26 线上同一 session:主模型轮input=303 / cache_read=59,392,紧接的 flash 轮变成input=57,557 / cache_read=1,024, 59K 历史对新模型全量重编码,省下的单价全赔进去;而每条(new sid)都落在input 250~2,700 / cache_read≈19,456——全新 session 几乎免费,system+tools 前缀在 provider 侧跨 session 命中。代价是 flash 轮看不到前文(顺带修掉一个正确性问题:继承主 会话历史时 flash 会照抄上一轮答案)。判据是「≠ 默认模型」而非「== FLASH」,配成同值不分流。opencode.log每行的sess=reuse|oneshot用来事后区分两类轮次 _inflight登记在跑任务(conv_id → sid/title/started),供/cancel直接 abort 和/reboot通知展示"这一停会打断什么";经core.brain.register_inflight注册给 core- 所有能力共用这一套:文本回复、合并转发、图片、文件都调
core.brain.generate_reply(ctx={"conv_id": ...}),所以转发完再追问能接上上下文
文件: src/core/agent_common.py
关键设计:
find_serve_credentials— 优先读.serve.port/.serve.pwd,回退进程表扫描;带短 TTL 缓存serve_request— opencode serve HTTP 的唯一出口:凭据、Basic auth、可开关的 REQ/RESP 调试日志集中一处,避免模板在各处被拷贝出漂移
文件: src/templates/handler_template.py(FDE 复制到 src/custom/handler.py 改造)
关键设计:
fetch_attachments— I/O 集中(图片下载+vision / 文件下载+读正文)render_prompt— 纯函数零 I/O,单测无需 mockbuild_prompt兼容 wrapper 串联两者(保留旧 API)
文件: src/templates/handler_template.py(FDE 复制到 src/custom/handler.py 改造)
关键设计:
_lookup_senders_batch(msg_ids)— 一次 list-by-ids 批量反查 N 个 sender- 比 list --group 鲁棒(不依赖群权限)
- 比逐个查询快(一次调用取回所有缺失 msgId 的 sender)
- 轮询等待依赖服务转发完成:
POLL_MAX_SECONDS/POLL_INTERVAL可配置常量- 测试 patch 为 0 避免真实 sleep
- do-while 风格保证至少调一次
文件: tests/(core 测试在 tests/core/,custom 测试在 tests/custom/)
关键设计:
- shell 单测:
bash -n语法检查 + 函数级断言(不依赖网络/钉钉) - Python 单测:
unittest+patch.object(<module>, "<func>") - e2e 测试:实际触发 + 日志验证 +
dws chat message list验证消息流 - 测试 patch 轮询常量为 0 避免真实 sleep
文件: src/custom/handler.py 的 _fetch_senders()(模板版在 src/templates/handler_template.py)
关键设计:
- summary 行数 vs messages 数量不一致时,记 raw content 头 300 字符
- 便于排查外部 API 格式变化(如 DingTalk summary 从
sender:content格式改成 AI 总结性描述) - 失败/成功/命中分别记日志
- timestamp + 组件前缀
| 文件 | 用途 |
|---|---|
.connect.pid |
connect 进程 PID |
.serve.pid |
opencode serve 进程 PID |
.serve.port |
opencode serve 监听端口 |
.serve.pwd |
opencode serve 的 OPENCODE_SERVER_PASSWORD |
.watcher.pid |
serve-watcher 后台进程 PID |
.event-watcher.pid |
event-watcher 后台进程 PID |
/tmp/agent-monitor.lock |
monitor 守护进程单实例锁(含 PID) |
.next-check |
下次自检的 Unix 时间戳 |
.opencode-connect-status.json |
最近一次健康检查结果 |
均运行时文件,不提交 git。