米喜这阵子一直在收拾打卡/日报 Agent 这个项目的烂摊子。v1.0 版本从联调通过到正式投入日常使用，前后跑了大概六周时间，表面上功能是齐全的——定时打卡、日报自动生成、摘要推送、异常提醒，该有的都有了。但真正用起来才发现，问题远比比想象的多。
这个项目本质上是一个基于大模型工具调用能力的自动化 Agent，核心链路是：定时触发 -> 读取工作记录/沟通记录/代码提交 -> 调用大模型生成日报草稿 -> 推送到群聊 -> 人工确认归档。从架构上讲并不复杂，属于典型的"工作流编排 + LLM 工具调用"模式。但越简单的链路，越容易在细节上翻车。这六周里我陆续记下了二十多个问题点，筛掉一些偶发的、影响面小的，最后整理出一份 Bug 可改清单，按影响范围和修复成本排了优先级，准备在 v1.1 里集中处理。这篇文章就把整份清单的思路、拆解过程和修复方案完整记录下来，给正在做类似 Agent 项目的朋友一个参考。如果你也在维护自己的自动化工具，尤其是涉及定时任务、大模型输出解析、多 Agent 协作这些环节的，这份清单里的很多坑你早晚也会踩到。
1. 项目整体设计与 Bug 来源分析
1.1 v1.0 的核心架构和运行链路
先简单交代一下这个项目的技术底座。打卡/日报 Agent 采用的是"调度器 + 工作流 + 工具调用"的分层设计，底层跑在 Python 3.11 上，调度用的 APScheduler，工作流编排用的自研状态机，LLM 接入的是通用大模型 API，工具层封装了 Git 提交记录读取、文档检索、IM 消息发送、日历查询等接口。
整个执行链路是这样的：每天早上 9 点 30 分，调度器触发"早间打卡"任务，Agent 会拉取前一个工作日的代码提交、会议纪要、即时通讯消息等数据源，由大模型归纳成一段工作摘要，推送到团队群；每天晚上 18 点，触发"日报生成"任务，同样拉取当天的数据，生成结构化日报，交给用户确认后归档。
从技术角度看，v1.0 的重点不在算法也不在模型调优，而在于如何把大模型的能力稳定地嵌入到既有工作流里。整个项目的核心难点有三块：一是多数据源的采集与清洗，二是大模型输出的稳定性控制，三是状态流转的异常兜底。Bug 也主要集中在后两块——模型输出不稳定会引发解析错误，状态机流转设计不严谨会在边界条件下出现死锁或空转。
1.2 Bug 清单的来源和筛选方法
这份 Bug 清单不是凭空想出来的。我花了大概两周时间，做了三件事来收集和归类问题：
第一，全面复盘了六周内的所有运行日志。重点排查了报错堆栈、任务中断记录和异常推送记录，筛选出重复出现的错误模式。日志是最好的老师，很多偶发问题如果不通过日志回溯，根本不可能定位到根因。
第二，找了团队里实际的日活用户做了访谈。有人反馈"日报里经常出现昨天的内容"，有人说"打卡提醒有时候收不到"，还有人抱怨"Agent 生成的摘要和我实际做的工作对不上"。用户反馈往往没有技术细节，但能指出问题的表象，顺着表象去反查代码，往往能发现隐藏很深的逻辑缺陷。
第三，把 v1.0 里所有硬编码的阈值、超时时间、重试次数全部列了出来，逐个推演边界场景。很多 Bug 不是逻辑写错了，而是参数设计不合理——比如超时设置太短，大模型响应稍慢就触发重试，重试又导致任务堆积，最后整个工作流卡死。
筛选原则就两条：可复现性和影响面。只修能稳定复现、并且对用户有明显影响的问题。那些偶发一次、无法稳定复现的问题，先记录在案，不进入 v1.1 的修复清单。这不代表放任不管，而是避免在问题定位不清楚的情况下盲目改动代码，引入新的回归。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心 Bug 分类拆解与修复优先级划分
2.1 按影响维度把 Bug 分成四个象限
二十多个问题点如果一个个平铺开来处理，很容易迷失重点。我把它们按"影响频率"和"影响严重度"两个维度分成了四个象限：
第一象限是高频且严重的问题，这类必须第一时间修复。比如定时任务偶发跳过、日报内容出现串线、核心链路抛异常后静默失败——这些问题直接影响用户对工具的信任度，一天不修，团队就一天不敢真正依赖这个 Agent。
第二象限是高频但不太严重的问题，比如日报格式偶尔乱掉、摘要措辞不够精准、推送消息偶尔重复。这些问题不影响主流程跑通，但会持续消耗用户体验，属于"体验债"，需要在迭代窗口内一并处理。
第三象限是低频但严重的问题，比如极端情况下状态机死锁导致任务队列阻塞、并发触发时数据竞争导致日报内容张冠李戴。这类问题不常见，但一旦发生，修复成本极高，而且往往伴随着数据正确性问题，需要从架构层面去加固。
第四象限是低频且不严重的问题，属于优化项。比如特定环境下重试机制不生效、日志打印等级混乱导致排查困难等。这些不着急，顺手能改就改，不强行排期。
象限分析做完之后，v1.1 的修复范围就很清晰了：集中处理第一和第二象限的问题，针对第三象限做防御性重构，第四象限选择性处理。
2.2 优先级排序的具体方法论与判断依据
排优先级的时候，我参考了一个很朴素的原则：** 先保证正确性，再保证可用性，最后才考虑体验优化。** 数据正确性是一切自动化工具的生命线。日报内容错了，比日报没生成更可怕——没生成用户知道自己手动补，生成错了用户可能直接照着错的内容汇报工作，那问题就大了。
所以我把"日报内容串线"、"打卡记录时间错乱"、"时区边界处理不当"这类数据正确性相关的问题，全部列为 P0 级别。修复方案确定后第一时间进开发。
P1 级别是"任务静默失败"、"重试风暴导致接口限流"这类可用性问题。它们不直接产生错误数据，但会让任务链路的可靠性大打折扣。一个定时任务如果 10 次里有 2 次不触发，用户就会觉得这个工具"不太靠谱"，信任感一旦崩塌就很难重建。
P2 级别是格式、措辞、重复推送等体验问题。修复成本不高，但需要反复调试，放到功能迭代的间隙处理。
优先级排完之后，我又做了一轮"修复成本预估"。每个 Bug 都标注了预计改动范围、涉及模块、测试成本，然后按照"投入产出