Skip to content

Latest commit

 

History

History
265 lines (212 loc) · 34.5 KB

AGENTS.md

File metadata and controls

265 lines (212 loc) · 34.5 KB

AGENTS.md — 给 agent 看的项目说明

项目用途

这是一个数字员工项目 harness 模板(FDE 交付 AI 项目的基础工程),从 dingtalk-opencode-agent(生产环境打磨 4.1+ 版本)提炼出 13 个可复用最佳实践,为新项目做基础。

三层目录架构(AI agent 修改代码前必须识别边界):

  • src/core/ bin/core/ tests/core/ — @core harness 核心,不要改,bug fix 走 PR 贡献回 upstream
  • src/custom/ bin/custom/ tests/custom/ — @custom FDE 在这里改,业务特定,不 merge 回 upstream
  • src/templates/ — @template 纯净参考,FDE 的 diff 基线,不要改
  • config/*.local.* — @config 真实凭据,被 .gitignore 忽略

详细派生 + 同步 + 贡献流程见 FORKING.md 和 CONTRIBUTING.md。

如何基于本 harness 启动新项目

Step 1: 复制 + 配置

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.* 填入真实身份/路径

Step 2: 实现业务 handler

打开 src/custom/handler.py(初始复制自 src/templates/handler_template.py),按以下顺序修改:

  1. 改常量正则(顶部):

    • BUSINESS_MSG_RE / MSGID_RE — 匹配你自己业务消息的日志格式
    • _RE_MEDIA_ID / _RE_FILE_ID — 匹配附件 ID 的格式
  2. 改 _classify_message:

    • 你的业务消息有几种类型?图片/文件/文本/语音/视频?调整分类逻辑
  3. 改 fetch_attachments + _fetch_image_entry + _fetch_file_entry:

    • 实现自己的附件下载逻辑(替换 dws CLI 调用为对应平台 SDK)
    • 图片识别 prompt 在 core.agent_common._proxy_vision 末句,按业务调整
  4. 改 render_prompt 末句:

    • 默认是 "请基于上述消息内容回应用户。"
    • 改成符合你业务场景的 prompt
  5. 回复怎么生成,不在 handler 里:

    • handler 只负责「消息 → prompt」;生成交给能力调 core.brain.generate_reply(user, prompt, raw=True, ctx={"conv_id": ...})
    • ctx 一定要带 conv_id:会话复用按 conv 粒度(AGENT_SESSION_REUSE), 不带就退化成每次新建的无状态会话,多轮上下文丢失

Step 3: 注册业务路由

打开 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 实现)

Step 4: 替换通知后端(可选)

core/agent_common.py 的 send_notification 默认用 dws CLI 发钉钉消息。如需替换为 Slack / 企业微信 / 飞书 / 邮件,在 src/custom/routes.py 里覆盖,或自定义通知函数。不要直接改 core。

Step 5: 装 launchd agent

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>.plist

Step 6: 跑测试

bash 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 拉起,双保险)
  • bin/core/stop.sh — 停止服务

    • launchd 模式:launchctl bootout 卸载 agent(优先)或 unload,服务保持停止状态
    • nohup 模式:pkill -9 monitor.sh --foreground
    • 通用:stop_components 杀所有组件(TERM→KILL)+ clean_runtime_state 清状态文件
  • 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.sh

launchd/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     # 启动

常见坑

  1. 会话复用只按 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 不受影响
  2. 进程活着 + HTTP 200 ≠ 大脑活着——check_serve/check_serve_http 都不碰模型。2026-08-08 大脑与模型网关失联 16 分钟,这两项全程 OK、healthcheck 每 5 分钟报「健康」,任何请求都答不出来,只能靠人在钉钉里发现。故新增检查7 check_brain:按 opencode.log 里新增的 ok=False 跨窗口累计(存 .brain-fail.pending,仅探针通过清零)触发一次真实模型调用自检(阈值 HEALTHCHECK_BRAIN_FAIL_THRESHOLD,默认 2 = 一条消息彻底失败的两行),健康时零请求零成本。必须累计:旧「单窗口条数 ≥3」在低频部署下一个窗口最多 2 条(http+cli 各 1),阈值永远凑不满——2026-09-17 网关间歇不可达 7 小时全程误报「健康」
  3. asked_ts buffer 设 5s——依赖服务写日志时刻 vs serve POST 时刻有微小偏差
  4. 轮询 do-while 风格(先调一次再判断)——保证至少调一次,避免常量 patch 为 0 时跳过整个循环
  5. patch.object 第三参数是 new 不是 return_value——指定 new 后不传 mock 给测试函数,测试函数不该有对应参数
  6. reply 不要被 _md 的 **...** 包裹——避免 agent 返回 ## 标题 时变成 **## 标题**;直接把 reply 作为通知正文
  7. 空回复撤回受限——依赖服务触发 abort 后返回空 finalizer 被发到通知渠道时,event-watcher 无法用机器人身份撤回(钉钉 API "仅消息发送者可撤回" + 缺 processQueryKey)。需要依赖服务端配合过滤空回复。
  8. 不要改 core 改 routes——业务路由注册到 src/custom/routes.py,绝不改 src/core/event_watcher.py。core 的路径在 upstream 和 fork 里必须一致才能干净 merge。
  9. 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 报 ⚠️ 格式健康告警。
  10. for line in sys.stdin 在管道下有 readahead 缓冲——低频事件流会卡在缓冲里不实时 yield,bridge 用 iter(sys.stdin.readline, "") 逐行读避免。
  11. 杀 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 进程。
  12. /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。
  13. macOS keychain 锁定会让 dws profile list 返回空(#71)——e2e 冒烟的发送方自动探测会因此 SKIP,容易误判为"没登录"。解锁:security unlock-keychain ~/Library/Keychains/login.keychain-db;或显式 E2E_SENDER_PROFILE="<corpId>:<真人userId>" 绕过探测。start.sh 启动时已做 keychain 预检并打印提示。
  14. e2e 冒烟别依赖硬编码免费模型(#71)——opencode/deepseek-v4-flash-free 等免费模型会失效/超时,未 source 配置时 e2e 会 HTTP 90s + CLI 90s = 180s 慢失败,易误判为链路问题。e2e_text_http_test.sh 约定:未显式设 AGENT_OPENCODE_MODEL 时先 source config/constants.local.sh 取真实可用模型,且起临时 serve 后轮询 /session 就绪探测(最多 30s)再发请求,不裸 sleep。
  15. 进程活着 + 连接活着 ≠ 流活着(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,过滤变量全空不报错、只是静默失效(单测能抓到)。
  16. Task 委派期间主会话指纹静止 ≠ 卡死(#125,2026-09-19 wx post 408 事故)——主模型把重活委派给 flash-worker 子代理(#123)后,子代理全程跑在独立 child session,主会话最后一条消息只剩一个静止的 task tool 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 通知噪音)。
  17. 网关闪断会永久毒化常驻 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。
  18. 钉钉 markdown 渲染器只吃一个很窄的子集,标准 markdown 会「静默变形」甚至「静默丢内容」(2026-10-04 hugozhu 反馈「markdown 输出格式不好」)——dws chat message send --text 恒以 msgType=markdown 投递(--dry-run 可验:dws 侧原样透传、不改一个字节),所有变形都发生在钉钉服务端。用「发探针消息 → dws chat message list-by-ids 回读 content」的差分法实测出这套规则(探针 C msgY8LI/UopkiDpuFRpCCxiUw== / 探针 D msgySyw+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 起的,群里发的仍是旧排版,容易误判「修了没用」
  19. 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 HTTP POST /session/{id}/message(优先,复用常驻进程省冷启动,实测 ~3x),serve 不可用时自动回退 opencode run CLI。因为共享同一个 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 覆盖。

事件消息处理

数字员工收到自动化事件推送(监控告警、数据推送、安全封禁等)时,按 docs/EVENT_HANDLING_POLICY.md 执行分类过滤与升级策略。核心:默认静默,SSH 封禁永久忽略,监控连续 ≥6h 升级,价格异常波动(≥5%)立即告警。

判定前必须先读状态文件续算(历史上三次「跟踪断档」都源于跳过这一步、用「单次未达 6h」当理由):

  • 监控告警(watchdog 重启 / 代理失败 / exit-node 重置等)→ 读 docs/alert_state.md,按「同设备+同服务」既有跟踪行与冷却线续算;冷却已过 → 下次报警即升级。
  • 行情数据推送(黄金 / BTC / 股价)→ 读 docs/price_state.md 取上次基线算环比,并把本次数值追加回该表(黄金用「国内 元/克」、BTC 用「美元/枚」,推送自带的人民币折算不可作阈值判据)。

指令约定:「存入notes」

用户(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

公众号画像(Agent 记忆)

回答公众号人群/流量/选题相关问题、或为公众号写内容前,先读 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)