只成功一次，第二次复现不了
表面现象
第一次手动输入能跑出结果，但没有保存输入、模型名、配置和输出样例。
常见原因
工作流还没有外部化成可复现文件，Agent 只能依赖当前会话上下文。
- 1保存 sample-inputs.md
- 2固定输出字段
- 3记录模型名和命令
- 4连续跑 3 次再扩展
Gateway 沉默失败
表面现象
Telegram、飞书或企业微信群没有回复，用户不知道消息有没有进入 Hermes。
常见原因
允许用户、Chat ID、进程重启、环境变量或后台日志缺失。
- 1先用 CLI 跑同样输入
- 2测试最短 /status
- 3查看 Gateway 日志
- 4确认允许用户和重启方式
过早把流程做成 Skill
表面现象
Skill 触发后输出不稳定，或者把第一版错误流程长期复用。
常见原因
流程还没经过真实样例验证，输入、输出和失败处理没有定下来。
- 1先退回普通工作流
- 2收集 3 到 5 次样例
- 3补齐输入输出边界
- 4再写 SKILL.md
Memory 记住了错误或过期事实
表面现象
Agent 反复引用旧路径、旧规则、旧偏好，导致新任务判断偏差。
常见原因
把临时状态、一次性输入或过期项目规则写进了长期记忆。
- 1列出当前 Memory
- 2删除过期事实
- 3只保留稳定规则
- 4每周清理一次
权限给得太大
表面现象
还没验收就让 Agent 发送外部消息、修改数据、触发部署或操作客户系统。
常见原因
没有把只读、草稿、人工确认和生产写入权限分层。
- 1先改成只读任务
- 2输出草稿而非直接执行
- 3高风险动作二次确认
- 4记录触发人和日志
换电脑或换人后没人接得住
表面现象
过几天回来不知道怎么启动、配置在哪、上次成功到哪一步。
常见原因
缺少会话交接、最后成功时间、环境变量说明和已知问题记录。
- 1补 session-handoff.md
- 2记录最后验证命令
- 3写清配置位置
- 4列出下一步最佳动作
排错顺序
遇到失败先缩小范围
不要同时改模型、Prompt、Gateway、环境变量和模板。先回到最小 CLI 输入，再逐层打开 Provider、Memory、Skills、Gateway 和定时任务。
先 CLI，后 Gateway
先只读，后写入
先样例，后真实数据
先日志，后长期运行