运行与阶段失败¶
启动后没有自动执行¶
现象：TUI 打开但停在等待输入。
确认方法：检查实际命令是否来自 make run，以及 RUN_LOOP_ARGS 是否为空。监督模式需要 --loop --loop-msg；干预模式故意去掉这些参数。
处理：监督模式重新使用默认 make WS=... run。不要在同一会话手工输入 loop 后又启动第二个自动 Agent。
恢复了旧阶段¶
UCAgent 默认读取 .ucagent 历史。需要续跑时这是正确行为；需要独立全新评估时才应清理或禁用历史。擅自增加 --no-history 会丢失已经完成的阶段上下文。
第一阶段失败多次¶
常见原因：实现计划缺少强制章节、阶段块标记不合法、详细度不足、工具/Checker 计划只是改写用户原文，或者 Checker 对最小格式有隐藏要求。
确认方法：读取 Checker 完整消息和 Guide_Doc/stages/00... 中的最小可通过示例；比较生成文件的标题、标记、正文长度和要求项。不要只看到“字数”就补重复段落，缺少的通常是数据流、异常、测试或扩展分析。
预防：阶段 FAQ 明示严格规则，最小示例后说明正式正文必须更详细。
引用文件被误判未读¶
曾出现配置写 .//workflow/...、实际读取 workflow/...，字符串追踪没有规范化而误判。正确做法是生成路径时就消除重复斜杠，并在比较前规范化。reference_files 和 output_files 都应列具体文件，不列目录；不确定当前存在的文件不要提前引用。
阶段长时间卡住¶
先观察是否有新的工具调用、文件时间戳、Checker 结果或上下文压缩。如果 Agent 在生成一批文档时每写一个文件就重复运行全量 make check_docs，应改为先完成本批文件，再运行一次综合检查。独立工具可并行生成，但共享注册文件必须串行。
如果同一失败检查重复且状态没有变化，属于空转而不是“仍在努力”。应停止并定位状态机或任务描述。
TUI 突然消失¶
检查 tmux session 是否仍存在、命令返回码和终端最后输出。可能是用户中断、Make recipe 结束、远端异常未恢复或启动命令本来就是 CLI。不要根据“看不到界面”直接推断工作流崩溃。
Checker 报描述缺失¶
检查配置注册指向的真实类、类级 description、检查方法 docstring，并用 checker description 回归 import。配置可能注册另一个同名类，因此只看当前打开文件不够。修复中心 spec 或模板，同时增加回归，不只给历史产物临时加注释。
失败很多次但最终通过¶
若错误逐步减少，Agent可能在有效修复；若同一格式反复猜测，GuideDoc缺最小示例或错误消息不足；若产物正确却被路径字符串误判，是 Checker问题。失败次数本身不能直接归因于正文长度。
长阶段确认命令¶
有新文件和不同调用就继续观察；重复全文读取或全量检查应优化批次；停在模型节点并出现流异常时再检查上下文和服务链路。
修复后续跑¶
先运行相关确定性回归，停止旧进程，再用相同 WS启动并保留历史。只有阶段结构与旧历史不兼容或用户明确要求时才清历史。设置 WS 本身不会关闭 TUI；没有界面时检查是否用了 CLI、管道或非 TTY。