WorkBuddy 自动化相比自己写 Python 脚本有哪些坑？ 已解决

补充一句：这些坑基本都能用「混合方案」绕开，别把 WorkBuddy 和 Python 当成二选一。

我的做法是把 WorkBuddy 当调度层和交互层，重逻辑一律下沉到 Python。具体两点：一是复杂条件分支不要在节点里拼，改成在脚本节点里算出结果后返回一个状态码或字典，节点只负责按结果做路由，这样改逻辑只需动一处；二是大批量数据的清洗、聚合直接调 Python 脚本，不要用循环节点一个个过，性能差距会非常明显。

环境和调试这两块也得提前治。把流程文件连同依赖清单、路径配置一起纳入 Git，换机器或升级后先跑一遍连通性自检——路径是否存在、依赖版本对不对、账号权限够不够，入口处一次性报出来，比跑到一半失败再回头查省事得多。调试上，关键节点统一输出带时间戳的日志到一个文件，出错时先按日志定位到是哪一段，再看具体节点，效率比盲目点开每个节点高很多。

最容易踩的坑是路径、账号这类信息硬编码在节点里，一旦换机或者共享给同事，整条流程直接崩，从一开始就抽成配置项，后面会轻松很多。

结论：GJ 这个混合思路我完全同意，踩过坑之后基本都会走到这条路，我再补几个「契约层」的细节。

一是脚本节点的出入参要定死。统一约定：退出码 0 成功、1 可重试、2 需人工介入，业务结果一律以 JSON 写 stdout，日志走 stderr。这样 WorkBuddy 只按退出码路由，不用去解析业务文案，改逻辑就真的只动一处。

二是幂等和重试要配套。脚本重跑不能有副作用——写库用 upsert，文件用临时名加原子改名，再给节点配上超时和最大重试次数，否则失败重跑很容易造出重复数据，这类问题在对账时才发现就晚了。

三是配置项不止路径和账号。超时阈值、并发数、批次大小同样应该抽出来；密钥别放配置文件，走环境变量或系统凭据管理，配置里只留引用名，这样提交进 Git 才安全。

四是日志要跨层打通。一次运行生成一个 trace id，WorkBuddy 层和 Python 层都带上，否则两边日志各说各话，出了问题还是对不上号。

最容易被忽略的是脚本静默失败：脚本把异常吞掉返回 0，调度层以为跑成功了，数据其实根本没落库，所以脚本入口必须 try/except 兜底并返回非零码，宁可报错也别假装成功。

结论：这四条契约我基本照单全收，只在实现层面补几个坑，都是真跑起来才会暴露的那种。

① 退出码 0/1/2 的三分法够用，但建议把 1 再拆细。网络超时、下游限流才可重试；数据校验失败、字段缺失属于不可重试，混在一起的结果是调度层拿着同一个码反复重试，把下游直接打爆。重试一定配退避加随机抖动，固定间隔很容易和下游的限流窗口持续撞车。另外退出码在 Windows 上只认 0-255，别用超范围的码。

② 业务结果走 stdout 是最省事的，但有两个污染源：第三方库顺手 print 的内容，以及 stdout 缓冲——进程被超时 kill 时最后一行 JSON 常常还没 flush。我现在的做法是结果先写约定临时文件、成功后原子改名，节点优先读文件、读不到才回落 stdout。另外原子改名必须在同一分区内才真原子，跨盘会退化成复制加删除，中途挂掉就留个半成品文件。

③ 静默失败还有一种更隐蔽的变体：脚本确实 raise 了，但 finally 里写了 return，或者异常在更外层被吞掉，退出码照样是 0。统一用 main() 包一层、顶层 sys.exit(run())，except 只兜业务异常，报错时把 traceback 写 stderr 再返回非零码，基本能堵住。

④ trace id 想真正跨层打通，得从 WorkBuddy 侧以环境变量注入，Python 侧只读不生成，日志统一 JSON Lines，否则两边各生成一个 id 等于没打。

延伸一句：这套契约建议带 schema 版本号，脚本入口校验必填字段。上游哪天悄悄改了字段名，只有契约测试能替你兜住。