湖仓写任务报 CommitFailed，最常见的处理是调高重试次数。这对一部分并发 append 有效，对 overwrite、delete 或 compaction 却可能掩盖真正的语义冲突。更麻烦的是提交超时：客户端认为失败，Catalog 可能已经成功切换了元数据。

诊断并发写入，不能只看异常类名。我会把一次写拆成数据文件生成、基于某个 snapshot 规划变更、冲突校验、Catalog 原子提交和提交结果确认五段，先判断失败发生在哪一段，再决定复用文件、重新规划还是人工核对。

“模型没有返回结果”是一句症状，不是根因。我见过模型已经正常结束，网关漏了 terminal event；也见过前端展示了答案，服务端却没有持久化。只看其中一层，谁都能拿出一段日志证明自己没问题。

Agent 诊断需要的是可连接、可校验的证据链。它从用户实际看见的结果出发，关联到 Run、上下文、模型 Attempt、工具 Operation、流事件和最终存储，并明确哪一段是原始事实、哪一段是系统推断。

传统服务报错，值班同学通常先看接口、实例和依赖。Agent 出问题时，表面症状更混乱：用户说“一直转圈”，可能是模型仍在生成、工具卡住、SSE 丢了终态，也可能任务已经完成但结果没有持久化。

运行手册不能按团队组件来写成“模型篇、向量库篇、MCP 篇”。值班者首先拿到的是用户症状和一个时间点。我更愿意从结果状态出发，先确认影响与副作用，再沿 Run 的证据链定位归属。

知识摄取任务变绿，用户仍搜不到文档，通常不是“向量库偶尔没命中”这么简单。任务成功只说明代码走到了结束，没有证明源内容枚举完整、解析结果没截断、每个 chunk 都生成向量、索引切到了新版本，也没证明查询链路使用了这版索引。

我会沿六层做证据对账：枚举、抓取、解析、切块/embedding、发布、查询。每层都有输入输出不变量和 manifest。定位从第一个数量或版本不一致的层开始，不先调 top-k。

数据源页面显示“测试连接成功”，任务发布后仍然报表不存在、没有查询权限或连接中断，这种情况并不矛盾。测试连接通常只完成 JDBC 建连，最多证明当前网络、账号和密码能建立一个短连接。

同步任务要求更多：Reader 要执行真实 SQL，切分键需要能参与查询；Writer 要有目标表写入权限，preSql、postSql 还要通过语法检查。任务跑几个小时以后，连接空闲超时、游标、字符集和网络设备的行为也会出现。

DataX 在 2020 年底已经有两套不同深度的检查：DBUtil.testConnWithoutRetry() 和 Job 的 dryRun。把源码走一遍，就能知道页面上的绿色图标到底证明了什么。