这是一个数字员工项目 harness 模板(FDE 交付 AI 项目的基础工程),从 dingtalk-opencode-agent(生产环境打磨 4.1+ 版本)提炼出 13 个可复用最佳实践,为新项目做基础。
三层目录架构(AI agent 修改代码前必须识别边界):
src/core/bin/core/tests/core/— @core harness 核心,不要改,bug fix 走 PR 贡献回 upstreamsrc/custom/bin/custom/tests/custom/— @custom FDE 在这里改,业务特定,不 merge 回 upstreamsrc/templates/— @template 纯净参考,FDE 的 diff 基线,不要改config/*.local.*— @config 真实凭据,被 .gitignore 忽略
详细派生 + 同步 + 贡献流程见 FORKING.md 和 CONTRIBUTING.md。
cp -r . /path/to/my-agent/
cd /path/to/my-agent/
cp config/config.example.json config/config.local.json
cp config/constants.sh config/constants.local.sh
# 编辑 *.local.* 填入真实身份/路径打开 src/custom/handler.py(初始复制自 src/templates/handler_template.py),按以下顺序修改:
-
改常量正则(顶部):
BUSINESS_MSG_RE/MSGID_RE— 匹配你自己业务消息的日志格式_RE_MEDIA_ID/_RE_FILE_ID— 匹配附件 ID 的格式
-
改
_classify_message:- 你的业务消息有几种类型?图片/文件/文本/语音/视频?调整分类逻辑
-
改
fetch_attachments+_fetch_image_entry+_fetch_file_entry:- 实现自己的附件下载逻辑(替换 dws CLI 调用为对应平台 SDK)
- 图片识别 prompt 在
core.agent_common._proxy_vision末句,按业务调整
-
改
render_prompt末句:- 默认是 "请基于上述消息内容回应用户。"
- 改成符合你业务场景的 prompt
-
回复怎么生成,不在 handler 里:
- handler 只负责「消息 → prompt」;生成交给能力调
core.brain.generate_reply(user, prompt, raw=True, ctx={"conv_id": ...}) - ctx 一定要带 conv_id:会话复用按 conv 粒度(
AGENT_SESSION_REUSE), 不带就退化成每次新建的无状态会话,多轮上下文丢失
- handler 只负责「消息 → prompt」;生成交给能力调
打开 src/custom/routes.py(不要改 src/core/event_watcher.py),在 hook 函数里注册自己的业务分发:
def route_reply(user, text, conv_type, raw_line):
# 文本回复路由:图片/语音/自定义指令/默认回复
if text == "[图片]":
threading.Thread(target=handle_image, args=(time.time(),), daemon=True).start()
elif match_business_line(raw_line):
mid, convs = match_business_line(raw_line)
threading.Thread(target=handle_business, args=(mid, convs), daemon=True).start()
else:
handle_reply(user, text)
def route_business_line(line):
# 默认已处理合并转发,按需扩展其他业务消息格式
...core/event_watcher.py 的 log_tail_thread / format_and_forward 会调用这些 hook:
route_reply(user, text, conv_type, raw_line)— 普通文本回复(已排除 /reboot)route_business_line(line)— 业务消息行route_sse_event(event, port, password)— SSE 事件(可选拦截,返回 False 走 core 默认转发)route_cleanup_state(event, cleanup_state, cleanup_lock)— spurious 多余轮次 cleanup 状态机(core 只做 TTL 兜底,状态机在 custom 实现)
core/agent_common.py 的 send_notification 默认用 dws CLI 发钉钉消息。如需替换为 Slack / 企业微信 / 飞书 / 邮件,在 src/custom/routes.py 里覆盖,或自定义通知函数。不要直接改 core。
cp bin/custom/agent-template.plist ~/Library/LaunchAgents/com.<your-org>.<your-agent>.plist
# 编辑 plist 中的 Label / ProgramArguments / StandardOutPath / PATH
launchctl load -w ~/Library/LaunchAgents/com.<your-org>.<your-agent>.plistbash tests/core/unit_test.sh # shell 单测(core,不改)
python3 tests/core/test_agent_common.py # Python 单测(core,不改)
bash tests/custom/e2e_test.sh # 端到端(需要真实链路)
bash tests/custom/test_event_freshness_watchdog.sh # 事件流看门狗单测(纯 mock,不碰网络)| 文件 | 层 | 关键函数 | 用途 |
|---|---|---|---|
bin/core/monitor.sh |
@core | cleanup_stale_state / start_all / run_forever |
守护循环 + 熔断 |
bin/core/healthcheck.sh |
@core | check_connect / check_serve_http / check_brain |
7 项健康检查 |
bin/core/lib.sh |
@core | verify_pid / acquire_lock / resolve_restart_mode / stop_components |
共享 shell 工具 + 服务控制助手 |
bin/core/start.sh |
@core | (脚本本身) | 启动服务(launchd/nohup) |
bin/core/stop.sh |
@core | (脚本本身) | 停止服务(launchd/nohup) |
bin/core/reboot.sh |
@core | (脚本本身) | /reboot 指令执行体(委托 stop + start) |
bin/custom/agent-template.plist |
@custom | (plist 本身) | launchd 配置模板 |
bin/custom/dws-connect.sh |
@custom | _run_consumers / _kill_subtree / _watchdog_cleanup |
dws event consume → bridge 管道 + 看门狗拉起 |
bin/custom/event_freshness_watchdog.sh |
@custom | _wd_check_once / _wd_count_newer / _wd_spawn_reboot |
事件流新鲜度看门狗(投递停滞检测 + 自愈,2026-09-18 事故) |
bin/custom/brain_watchdog.sh |
@custom | _bw_check_once / _bw_liveness_once / _bw_scan / _bw_restart_serve |
大脑 serve 连接看门狗(连接池毒化差分检测 + 主动探活 + 只重启 serve 自愈,2026-09-21 事故,第 5 组件;判定逻辑详见 docs/BRAIN_WATCHDOG_POLICY.md) |
src/core/agent_common.py |
@core | find_serve_credentials / serve_request / _proxy_vision / _clean_session_title |
共享 Python 工具 |
src/core/event_watcher.py |
@core | connect_sse / log_tail_thread / format_and_forward |
事件流主进程(调用 custom.routes 的 hook) |
src/custom/handler.py |
@custom | fetch_attachments / render_prompt / _lookup_senders_batch / match_business_line |
业务 handler(FDE 改这里) |
src/custom/routes.py |
@custom | route_reply / route_business_line / route_sse_event |
业务路由注册(FDE 改这里,不改 core) |
src/templates/handler_template.py |
@template | (同 custom/handler.py 的纯净版) | diff 基线,不要改 |
tests/core/test_agent_common.py |
@core | TestCleanSessionTitle / TestHandlerPools |
Python 单测 |
tests/core/unit_test.sh |
@core | (脚本本身,含 dws-connect 订阅选择) | shell 单测 |
tests/custom/test_dws_event_bridge.py |
@custom | TestToConnectLine(@我/群/单聊 convType 映射) |
Python 单测 |
tests/custom/test_ack_capability.py |
@custom | TestShouldAck / TestLifecycleWorker / TestDispatchReplySent(回执:已读+状态表情) |
Python 单测 |
tests/custom/test_subagent_watchdog.py |
@custom | TestFingerprintChildTracking / TestWatchdogE2E / TestSseSuppressCapability(Task 委派子会话保活,#125) |
Python 单测 |
tests/custom/test_brain_watchdog.sh |
@custom | (脚本本身,serve 毒化差分判定 + 防抖状态机) | shell 单测(纯 mock) |
tests/custom/e2e_test.sh |
@custom | (脚本本身) | 端到端测试(FDE 改这里) |
tests/custom/e2e_at_test.sh |
@custom | (脚本本身) | @我(AT) 订阅+处理 端到端测试 |
tests/custom/e2e_ack_test.sh |
@custom | (脚本本身) | 回执(已读+状态表情)端到端测试 |
tests/custom/e2e_forward_mixed.py |
@custom | (脚本本身) | 合并转发混合消息(2图+1文件+3文本)端到端测试 |
开发者手动控制服务、或远程通过 /reboot 聊天指令重启,有三个脚本:
-
bin/core/start.sh— 启动服务- launchd 模式:agent 已加载则
launchctl kickstart -k重启;否则bootstrap/load -w加载 - nohup 模式:
nohup monitor.sh --foreground后台运行 - 失败时退避重试一次,仍失败则告警 +
exit 1(让 launchd 拉起,双保险)
- launchd 模式:agent 已加载则
-
bin/core/stop.sh— 停止服务- launchd 模式:
launchctl bootout卸载 agent(优先)或unload,服务保持停止状态 - nohup 模式:
pkill -9 monitor.sh --foreground - 通用:
stop_components杀所有组件(TERM→KILL)+clean_runtime_state清状态文件
- launchd 模式:
-
bin/core/reboot.sh— 重启服务(/reboot指令执行体)- 委托模式:
sleep 1→stop.sh→sleep 2→start.sh - 由
src/core/event_watcher.py收到/reboot聊天指令时自动派生(脱离进程组)
- 委托模式:
模式选择:通过 REBOOT_RESTART_MODE 环境变量控制(config/constants.local.sh 配置)
nohup(默认)— 后台启动 monitor 进程(适合 Linux / 开发环境 / serve-less 配置)auto— 自动判定:launchd agent 已加载 →launchd模式;否则 →nohup模式launchd— 强制 launchd 模式(需提前配置好LAUNCHD_LABEL和LAUNCHD_PLIST)
用法示例:
# 启动服务(自动判定模式)
bash bin/core/start.sh
# 停止服务
bash bin/core/stop.sh
# 重启服务(等价于群里发 /reboot,但可手动调试)
bash bin/core/reboot.sh
# 强制 nohup 模式启动(跳过 launchd)
REBOOT_RESTART_MODE=nohup bash bin/core/start.shlaunchd/systemd 托管:生产环境推荐用 agent-template.plist(macOS)或 agent-template.service(Linux)托管 monitor.sh,supervisor 自动拉起崩溃进程。手动控制用 launchctl/systemctl:
# macOS
launchctl kickstart -k gui/$(id -u)/com.example.agent-connect # 重启
launchctl bootout gui/$(id -u)/com.example.agent-connect # 停止(卸载)
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/...plist # 启动(加载)
# Linux
systemctl --user restart dingtalk-agent.service # 重启
systemctl --user stop dingtalk-agent.service # 停止
systemctl --user start dingtalk-agent.service # 启动- 会话复用只按 conv_id,不按工作目录——一个目录下会有上百个 session,「最近活跃的那个」未必属于当前这场对话,按目录复用会串上下文。复用逻辑统一在
custom/brain.py(AGENT_SESSION_REUSE),能力侧只需在 ctx 里带上conv_id。例外:逐轮换模型(/flash,#117)的那一轮单开一次性 session,不进主会话——provider 的 prompt cache 按模型分桶,在长上下文的复用 session 里换模型反而更贵,详见 ARCHITECTURE.md 第 8 节;skill 用 Task 委派给flash-worker子代理(#123,opencode.json定义,model 取AGENT_OPENCODE_MODEL_FLASH)的轮次同理走独立 child session,用量由_collect_subagent_flash_usage记进 flash_* 统计,主轮 cache 不受影响 - 进程活着 + HTTP 200 ≠ 大脑活着——
check_serve/check_serve_http都不碰模型。2026-08-08 大脑与模型网关失联 16 分钟,这两项全程 OK、healthcheck 每 5 分钟报「健康」,任何请求都答不出来,只能靠人在钉钉里发现。故新增检查7check_brain:按opencode.log里新增的ok=False跨窗口累计(存.brain-fail.pending,仅探针通过清零)触发一次真实模型调用自检(阈值HEALTHCHECK_BRAIN_FAIL_THRESHOLD,默认 2 = 一条消息彻底失败的两行),健康时零请求零成本。必须累计:旧「单窗口条数 ≥3」在低频部署下一个窗口最多 2 条(http+cli 各 1),阈值永远凑不满——2026-09-17 网关间歇不可达 7 小时全程误报「健康」 - asked_ts buffer 设 5s——依赖服务写日志时刻 vs serve POST 时刻有微小偏差
- 轮询 do-while 风格(先调一次再判断)——保证至少调一次,避免常量 patch 为 0 时跳过整个循环
- patch.object 第三参数是
new不是return_value——指定 new 后不传 mock 给测试函数,测试函数不该有对应参数 - reply 不要被
_md的**...**包裹——避免 agent 返回## 标题时变成**## 标题**;直接把 reply 作为通知正文 - 空回复撤回受限——依赖服务触发 abort 后返回空 finalizer 被发到通知渠道时,event-watcher 无法用机器人身份撤回(钉钉 API "仅消息发送者可撤回" + 缺 processQueryKey)。需要依赖服务端配合过滤空回复。
- 不要改 core 改 routes——业务路由注册到
src/custom/routes.py,绝不改src/core/event_watcher.py。core 的路径在 upstream 和 fork 里必须一致才能干净 merge。 - dws 输出格式随版本会变,bridge 要兼容——
dws event consume -f ndjson的事件格式有两种:旧版嵌套(外层type=="event",事件体在data(二层 JSON 字符串).payload.body)、新版扁平(字段直接在事件顶层,type即事件类型名如user_im_message_receive_o2o,无data包裹)。dws_event_bridge.py两种都解析。故障特征极隐蔽:格式不匹配时 bridge 把每条事件都跳过(处理 0 条),进程/连接/healthcheck 全绿但数字员工完全不响应。诊断捷径:dws event consume ... | cat能看到原始数据、... | python3 dws_event_bridge.py却处理 0 条→ 就是格式不匹配。bridge 内置格式健康检查:收到 ≥3 条原始事件却解析 0 条时,在 connect-log + monitor.log 报⚠️ 格式健康告警。 for line in sys.stdin在管道下有 readahead 缓冲——低频事件流会卡在缓冲里不实时 yield,bridge 用iter(sys.stdin.readline, "")逐行读避免。- 杀
dws event consume必须连子树一起杀(#71)——consume 会派生dws event _bus子进程(真正持流连接的那个)。只kill <consumer>会把 _bus 甩成孤儿被 init 收养,它继续占着订阅消费消息;重启后新旧 _bus 抢投递,表象为「投递停滞/收不到消息」。约定:dws-connect.sh收尾用_kill_subtree(子在前)+ EXIT/TERM trap;stop.sh/monitor.sh stop_all杀完组件后调 custom 钩子stop_extra_cleanup(定义在bin/custom/start_funcs.sh),按DWS_PROFILE精确清扫进程树已断裂、COMP_PATTERNS 够不着的残留dws event进程。 - /reboot 必须用干净环境重启(#71)——
reboot.sh由老 event_watcher 派生,继承老 monitor 启动时的全部 env。若直接透传,config 里export VAR="${VAR:-新值}"风格的赋值会被继承的旧值压住——改完config/constants.local.sh后 /reboot 不生效(新 monitor / serve 仍带旧 env)。reboot.sh用env -i(仅保留 HOME/USER/PATH 等基本量)跑 stop.sh + start.sh,让 config 成为 env 的唯一来源,行为与「开新终端手工全停全起」一致。PATH 依赖constants.local.sh里export PATH="$PATH:$HOME/.local/bin:$HOME/.opencode/bin"补回 dws / opencode。 - macOS keychain 锁定会让
dws profile list返回空(#71)——e2e 冒烟的发送方自动探测会因此 SKIP,容易误判为"没登录"。解锁:security unlock-keychain ~/Library/Keychains/login.keychain-db;或显式E2E_SENDER_PROFILE="<corpId>:<真人userId>"绕过探测。start.sh启动时已做 keychain 预检并打印提示。 - e2e 冒烟别依赖硬编码免费模型(#71)——
opencode/deepseek-v4-flash-free等免费模型会失效/超时,未 source 配置时 e2e 会 HTTP 90s + CLI 90s = 180s 慢失败,易误判为链路问题。e2e_text_http_test.sh约定:未显式设AGENT_OPENCODE_MODEL时先 sourceconfig/constants.local.sh取真实可用模型,且起临时 serve 后轮询 /session 就绪探测(最多 30s)再发请求,不裸 sleep。 - 进程活着 + 连接活着 ≠ 流活着(2026-09-18 事故)——
dws event consume长连接静默失活时进程全活,healthcheck 27 轮全绿 2h15m 无告警无自愈:check_connect只verify_pid查进程存活;check_log_activity的 WARN 三重静默(不算硬失败 / 输出被 monitor 丢弃不进日志 / 无通知通道);check_brain只探测「调了但失败」,没消息进来 = 没失败记录 = 恒 OK。判定投递停滞的唯一确凿证据是 DWS 侧独立拉取交叉验证(服务端有新消息而本地没收到)。已由bin/custom/event_freshness_watchdog.sh(dws-connect 拉起的子进程)兜底:本地 inbound 超 45min → DWS 拉取过滤「自己发的 + msgId 已入站的」→ 确凿才告警 + reboot 自愈(防抖 30min / 上限 3 次,状态文件.event-stall.state)。诊断捷径:connect log 里最后一条「收到」与 DWS 拉到的最新消息时间戳错位 = 停滞实锤。另注意 bash 管道的 env 前缀陷阱:VAR=x cmd | python3的 VAR 只进 cmd 不进 python,过滤变量全空不报错、只是静默失效(单测能抓到)。 - Task 委派期间主会话指纹静止 ≠ 卡死(#125,2026-09-19 wx post 408 事故)——主模型把重活委派给 flash-worker 子代理(#123)后,子代理全程跑在独立 child session,主会话最后一条消息只剩一个静止的
tasktool part,_activity_fingerprint的四维指纹全不变 → 长委派(>900s 浏览器自动化)被活动感知超时误杀。修复:watchdog 发现 in-flight task part(state.status=pending/running)时从state.metadata.sessionId递归跟踪子会话指纹(限深 2 层,子会话活动拼进父指纹第 5 维;子会话指纹全取不到时按保活哲学视为仍在产出,MAX 兜底)。同时把子会话 sid 登记进 textreply 注册表 +sse_suppress能力按 parentID 吞掉子会话的 busy/idle SSE 业务通知——本部署AGENT_ROBOT_CODE是占位值,send-by-bot 通道 0 成功/30 失败(business error: success=false),不抑制就每次委派刷两条 FAIL,极易被误读成「兜底提示没发出去」(实际兜底走AGENT_REPLY_MODE=user通道,看reply user OK才是判据;send FAIL title=✅ 会话完成是 SSE 通知噪音)。 - 网关闪断会永久毒化常驻 serve 的连接池(2026-09-21 事故)——模型网关(内网 IP 走 VPN)凌晨闪断 2h+,恢复后 curl 直连 2.7ms、全新 CLI 进程 6s 出结果,但常驻 serve 仍持续
Cannot connect to API(Bun 复用池里的半开死连接,毫秒级快速失败),网络恢复后不会自愈。表象:每条消息「serve HTTP 失败→CLI 回退」;网关断期间 CLI 也失败 → 全发兜底提示;healthcheck 卡在check_brain真实探针重试。判定靠三路差分:网关 curl 直连(任何 HTTP 码含 401 = 通,零 token)× serve 探针 × 全新 CLI。零 token 自动检测的判据是 monitor.log 无条件标记的配对:brain opencode http err+CLI 回退成功(CLI 是全新进程,它能通 = 网关通 = serve 单侧故障实锤)。已由bin/custom/brain_watchdog.sh(第 5 组件)兜底:窗口内配对 ≥2 且新鲜 → 只重启 serve(保凭据,in-flight 走 CLI 兜底,不动订阅);双路全挂时按 L1 路由 × L2 真实推理两级差分定位故障层,仅「L1 通 + L2 通」(= 网关能出 token 而 serve 连不上)才重启,网关侧故障只告警不重启(重启无效,恢复后下一条消息自动触发自愈)。检测全部寄生在真实业务流量上,零 token 零额外模型请求。2026-10-01 追加:重启后必须验证(_bw_verify_serve,一次1+1=?真实推理探针,~70 token)——该次事故里 monitor 在网关故障窗口内重启 serve,新进程一出生就毒化(自启动起 35 次失败 / 0 次成功),而旧实现「重启即当成功」,额度照烧到 2/3 + 进 1800s 冷却 →serve_stale_wait只告警,02:56–03:25 共 29min 无自愈只能人工 reboot。现在验证通过 → 计数清零(额度归还)+ 发恢复告警;未通过 → 计入连续验证失败并走短退避 120s 继续试(不再静默 30min);无法验证(缺 python3/provider、401 凭据、端口未起)→ 保守退回旧的长冷却语义,绝不把探针自身故障当成「serve 仍毒化」。毒化的确凿特征(区别普通网络故障):serve.log 里stream→llm runtime selected→stream error间隔仅 1ms,且lsof -nP -p <serve-pid>显示根本没有到网关的 TCP 连接;客户端看到的 60s+ 全是 opencode 的 5 次退避重试。2026-10-05 追加:被动差分依赖业务流量,零流量 = 零证据 = 永不触发——该次事故网关故障窗口内用户发的/reboot(21:44)重启出 born-poisoned serve,22:40 网关恢复后 CLI 自愈、serve 永不自愈,之后零流量 →「失败证据陈旧 + L1 可达 → 视为已恢复」误判健康,毒化 serve 干挂 85min 等人工。已加主动探活_bw_liveness_once(路径 C,~70 token/次 ≈ 3.4k/天,BRAIN_SERVE_LIVENESS_INTERVAL=0关闭):看门狗启动 ~90s 后探一次(/reboot / healthcheck / launchd 重启全覆盖;新 serve = 新事故,先重置连续失败计数——否则旧计数会把新 serve 的自愈挡成 giveup)+ 此后每 1800s 周期探活(零流量收敛保证,网关恢复后最迟一个周期内自愈);动作语义与被动路径一致(L1 挂只告警、L1+L2 通 + serve 出不了 token 才重启 + 验证、探针不可用只记日志)。详见 docs/BRAIN_WATCHDOG_POLICY.md。 - 钉钉 markdown 渲染器只吃一个很窄的子集,标准 markdown 会「静默变形」甚至「静默丢内容」(2026-10-04 hugozhu 反馈「markdown 输出格式不好」)——
dws chat message send --text恒以 msgType=markdown 投递(--dry-run可验:dws 侧原样透传、不改一个字节),所有变形都发生在钉钉服务端。用「发探针消息 →dws chat message list-by-ids回读 content」的差分法实测出这套规则(探针 CmsgY8LI/UopkiDpuFRpCCxiUw==/ 探针 DmsgySyw+rkP3ys6tKT1ZPTtFQ==):- 单个
\n→ 整个丢弃(连空格都不留)⇒ 模型标准 markdown 的紧凑列表/多行段落糊成一整段,这就是「格式不好」的主因。\n\n(空行)与「行尾两空格 +\n」都会被规范成硬换行\n,渲染正确 ✅ - markdown 表格被整表丢弃(
| a | b |+| --- |三行发过去,回读 content 里只剩两个空行)⇒ 不是渲染丑,是数据丢失。同日早读 digest 修正版 4/4(msgN1TezpBz5jUfeZ/zrClAOQ==)的「花费结构」表格就在群里凭空消失 - 空行分隔的有序列表会被重编号:
1. / 2. / 3.→ 回读1. / 1. / 1.(每项被当成独立列表);1) / 2)括号式更糟,换行被吃掉连成一行。转义句点可解:1\. 丙→ 回读1. 丙,编号与换行都保住 ✅ - 无序列表
- a空行分隔可用;### 标题、---水平线、```代码围栏(含缩进)内容都活着 ✅;引用块> a\n> b会被并成一行 ━─=·这类字符画分隔线/项目符号不是 markdown 语法,只会糊成一片——早读 digest 最初的排版事故就是这个- 已落地两道防线:①
src/custom/replier.py::_normalize_md发送前统一改写(表格→逐行- **表头**: 值、有序标记转义、裸\n→空行、围栏内原样保留),可用AGENT_REPLY_MD_NORMALIZE=0关闭;②src/custom/brain.py::_SYSTEM_PROMPT直接把这套约束写进系统提示词,让模型一开始就不产出表格/字符画。单测tests/custom/test_reply_chunk.py::TestNormalizeMd - 注意改了 replier/brain 必须重启才生效(event_watcher 是常驻进程):本次 09:38 改完代码、进程还是 10-02 起的,群里发的仍是旧排版,容易误判「修了没用」
- 单个
- reboot.sh 派生链上的 opencode 进程无法建立出站连接(谱系归因拦截)(2026-10-06 事故,坑#17 的真凶之一)——
/reboot后由 reboot.sh(env -i+ 脱离进程组)派生的新 monitor 拉起的 serve,无论网关是否健康都连不上:Bun fetch 1ms 快速失败Cannot connect to API,lsof显示零到网关的 TCP 连接尝试(连 SYN 都没发);而同一时刻同一二进制:交互终端跑的opencode run正常(10/10)、手动起的 serve 正常(同 env、同 config、env -i复刻也正常)、reboot 链上 bash 跑的 curl L1/L2 探测也正常——被拦的只有「reboot 派生谱系 × opencode 二进制」这个组合(疑似 macOS 网络扩展按进程归因/responsible process + 签名校验过滤,curl 是 Apple 签名所以放行;系统统一日志无拒绝记录,机制未定位到系统层证据)。判定捷径:ps -o ppid= -p $(cat .serve.pid)一路向上追到 monitor,若根是 reboot.sh 谱系(而非交互终端/launchd)且 serve 零 TCP 出站 → 就是这个坑,别再怀疑网关/Bun 池。修复:从交互终端bash bin/core/start.sh重启全链(serve/connect/event_watcher/brain_watchdog 全部重挂到新 monitor 下,谱系即刻变好);坑#17 的 liveness 探针能检出此故障但修不了(看门狗自己也可能是坏谱系,重启出的 serve 依旧连不上 → 3 次后 giveup 等人工)。连锁小坑:monitor.sh 是set -euo pipefail,warmup 撞上「看门狗正在重启 serve」的窗口(serve 短暂不在)会直接静默退出(nohup 模式无 launchd 拉起 → 监控全丢),重启 monitor 前先确认 serve 健康;dws-connect.sh 收 TERM 后可能挂住不退出(trap 清理子树卡住),必要时kill -9主进程 +pkill -9 -f "dws event"清残留。
- shell 单测:
bash -n语法检查 + 函数级断言,不依赖网络/钉钉/serve - Python 单测:
unittest+patch.object(<module>, "<func>", return_value=...) - 业务 handler 测试:mock
core.brain.generate_reply验证 prompt 拼装 + ctx 带 conv_id,不测大脑内部 - e2e 通用范式:实际触发 + 监控日志 + DWS 独立拉群消息(两侧对照的双校验)
- 基础文本 e2e(最底层冒烟):以真人身份发一条纯文本、断言数字员工回复。这条不碰合并转发/serve,只验"收→大脑→发"闭环——最快定位链路断在哪。已脚本化:
bash tests/custom/e2e_text_reply_test.sh(opencode / Claude Code / Codex 通用;参数化身份不写死,SKIP 友好)。# 一键跑(自动探测真人发送方 + 唯一校验码 + V1-V4 双校验) bash tests/custom/e2e_text_reply_test.sh # 手动等价步骤(脚本内部就是这套): # 触发:用 --profile 切成真人身份(非数字员工自己,否则被 AGENT_SELF_NAMES 防回环过滤) dws chat message send --user "<数字员工 userId>" --text "[CODE] 37+5=?" --profile "<corpId>:<真人>" -y # 校验 A(agent 侧):agent-connect.log 有 "[connect] 收到 @<真人>: [CODE] …";monitor.log 有发送后的 "reply user OK" # 校验 B(DWS 侧独立拉取):从入站行取 convId,用 list --group 拉数字员工回复断言答案 # (注意:list-by-sender 实测不索引 o2o 私聊回复,o2o 校验须用 list --group <convId>) dws chat message list --group "<convId>" --time "<起始时刻>" --direction newer --profile "<corpId>:<真人>" -y
- 业务 e2e(合并转发路径):
dws chat message forward触发 → 监控日志 → 拉群校验,见tests/custom/e2e_test.sh。 - 合并转发混合消息 e2e(本地冒烟,无需真发):钉钉
combine-forward只能转发已存在 msgId、send --msg-type image又需预置 mediaId,故真造一条 2图+1文件+3文本的转发不可行。改用合成 fixture 驱动真实代码路径:真实list-by-ids结构 + 真实 serve+gemini 视觉识别本地图 + 真实摘要发送人解析 + 真实 brain,只 stub 转发源/媒体下载/发送三处 I/O。断言 6 条全在、类型都解析对、发送人从外层摘要对齐、图片走 serve+gemini(非_proxy_vision)、回复带ctx.conv_id进主 session。见tests/custom/e2e_forward_mixed.py(serve 在跑即真识别图片)。 - 文本回复 HTTP e2e(本地冒烟,无需钉钉):起临时 serve → 直接调
brain.generate_reply("u","1+1")断言回复 +opencode.log有transport=http,见tests/custom/e2e_text_http_test.sh。 - flash-worker 子代理委派 e2e(本地冒烟,无需钉钉,#123):起临时 serve(env 带
AGENT_OPENCODE_MODEL_FLASH,flash-worker 才有独立模型)→ 调brain.generate_reply_ex要求主模型用 Task 委派 flash-worker → 断言 child session 里 flash 模型有真实用量、flash_*统计已记账且主会话rounds=1(委派不进主会话窗口)。未配置 FLASH / 与主模型同值则 SKIP。见tests/custom/e2e_flash_subagent_test.sh。 - @我(AT) 订阅 e2e:验证
user_im_message_receive_at订阅 → bridge(convType=2) → inbound → 能力分发全链,末段 LIVE 用dws event consume ...receive_at --duration抓[event] ready证明真实建联(只读不发消息,无 dws/未登录则 SKIP)。见tests/custom/e2e_at_test.sh。开启订阅:config/constants.local.sh设DWS_EVENT_AT=1。 - 坑#1:
dws chat message list --group对某些群报openCid or cid is required(list_conversation_message_v2的权限/参数怪癖);群聊场景可回退list-by-sender(按发送者拉)。但 o2o 私聊回复实测list-by-sender索引不到——私聊校验必须用list --group <o2o-convId>(convId 从 connect log 入站行convId=…取)。e2e_text_reply_test.sh的 V4 即如此。 - 坑#2:实时订阅(connect 日志)不回显当前登录用户自己发的消息——数字员工的回复不会出现在它自己的接收流里,别把"connect 日志没看到回复"误判为没发出去;用校验 B 的 DWS 拉取确认。
- 坑#3:
dws event订阅偶发投递停滞——dws event consume子进程还活着(healthcheck 只查进程存活会误判"健康"),但连接静默失活、消息迟迟不进 connect log,只延到下次重启。跑基础文本 e2e 时若 V2 超时未见入站,先bash bin/core/reboot.sh重建订阅再跑。常态兜底见「常见坑#15」:event_freshness_watchdog.sh已自动检测(DWS 交叉验证)+ 告警 + 自愈。 - 所有能力共走同一条后端路:文本回复、合并转发、图片、文件都调
core.brain.generate_reply(ctx={"conv_id": ...})→brain._brain_opencode→ serve HTTPPOST /session/{id}/message(优先,复用常驻进程省冷启动,实测 ~3x),serve 不可用时自动回退opencode runCLI。因为共享同一个 conv 的 session,转发完再追问能接上上下文。都依赖 serve 常驻(start_serve见bin/custom/start_funcs.sh)。 AGENT_DEBUG=1→ opencode 调用单独记opencode.log(统一调试总开关,原AGENT_SERVE_DEBUG已并入):每次 opencode 调用记一条摘要(transport=http|cli/ model / 耗时 / prompt+reply 长度 / reply 预览 / 成败),并把每个 serve 请求/响应的完整 body(含发给模型的 prompt 与模型返回)写到同一文件,长 body(图片 data_url 等)自动截断头尾。想确认"回复到底走 HTTP 还是 CLI 回退"或"到底发了什么 prompt / serve 返回了什么"都看这个文件。错误恒记(不受开关影响)。路径可用AGENT_OPENCODE_LOG覆盖。
- 基础文本 e2e(最底层冒烟):以真人身份发一条纯文本、断言数字员工回复。这条不碰合并转发/serve,只验"收→大脑→发"闭环——最快定位链路断在哪。已脚本化:
数字员工收到自动化事件推送(监控告警、数据推送、安全封禁等)时,按 docs/EVENT_HANDLING_POLICY.md 执行分类过滤与升级策略。核心:默认静默,SSH 封禁永久忽略,监控连续 ≥6h 升级,价格异常波动(≥5%)立即告警。
判定前必须先读状态文件续算(历史上三次「跟踪断档」都源于跳过这一步、用「单次未达 6h」当理由):
- 监控告警(watchdog 重启 / 代理失败 / exit-node 重置等)→ 读 docs/alert_state.md,按「同设备+同服务」既有跟踪行与冷却线续算;冷却已过 → 下次报警即升级。
- 行情数据推送(黄金 / BTC / 股价)→ 读 docs/price_state.md 取上次基线算环比,并把本次数值追加回该表(黄金用「国内 元/克」、BTC 用「美元/枚」,推送自带的人民币折算不可作阈值判据)。
用户(hugozhu)发送「存入notes」时,把最近一条消息的内容(链接则抓取正文、文本则原文)存入钉钉知识库 wiki,而不是本地/第三方 notepad:
- 目标空间:
hugozhu的知识库(workspaceId=r98znONN9JrLXLxn),notes文件夹(nodeId=XPwkYGxZV3eG6jaAF9OD1E168AgozOKL) - 必须用 hugozhu 本人 profile
dinga626d60c1128d449:0420506555(数字员工 profile 无该 wiki 权限) - 流程:抓取正文 → 清洗(去微信/网页噪声)→
dws doc create --workspace r98znONN9JrLXLxn --folder XPwkYGxZV3eG6jaAF9OD1E168AgozOKL --name "<标题>" --content-file <tmp.md>→dws doc read回读验证 → 回复 docUrl
回答公众号人群/流量/选题相关问题、或为公众号写内容前,先读 docs/wechat-mp-audience-profile.md(2026-08-31 快照:人群属性 + 地域 + 流量来源结构 + 内容策略含义)。数据过期时重新抓取公众号后台数据并更新该文件。
- 不要改
src/core/bin/core/tests/core/下的任何文件——bug fix 走 PR 贡献回 upstream(见 CONTRIBUTING.md) - 不要用
pgrep -f检测进程(会误匹配 send-by-bot 转发进程)——用verify_pid - 不要在能力里自己找/建 session——调
generate_reply(ctx={"conv_id": ...}),复用交给custom/brain.py - 不要用
flock(macOS 不可用)——用shlock或文件存在性判断 - 不要用
tee -a file >&2(launchd 已重定向 stderr 到同一文件,会双写)——log()只写 stderr - 不要把真实凭据写入
config/config.example.json或config/constants.sh——只填*.local.*(已 gitignore)