Skip to content

Q&A 与经验总述

本目录整理 Workflow Builder 在真实业务构建、评估和增量运行中出现过的常见问题。条目优先提供可验证方法，不把一次偶发现象包装为通用规律。排障时先找到与现象最接近的文档，再按“确认方法”收集证据。

分类

文档 主要问题
安装与环境问题 UCAgent 路径、虚拟环境、代理、依赖和本地配置
运行与阶段失败 TUI、历史、Checker、引用、连续重试和阶段卡住
评估审批与增量修复 报告遗漏、审批、候选、空转、部署和闭环
控制台与端口 端口占用、退出、筛选、编辑和版本删除
性能、上下文与稳定性 长阶段、连续压缩、流式中断、浏览器 lock
工作流设计质量 形式主义、设计计划、工具/Checker/docs 和路径契约

排障证据优先级

  1. 确定性命令的输入、输出和返回码。
  2. Checker 的完整描述、参数和源码分支。
  3. 目标文件内容、哈希、时间戳和结构化报告。
  4. TUI 的工具调用与模型返回。
  5. 对网络、模型或业务复杂度的推测。

只有第五类证据时，不应立即修改大量规则。先设计可以区分不同原因的小实验。

记录新经验

新增条目必须包含：现象、影响、可能原因、确认方法、处理步骤和预防措施。已确认原因应注明证据；尚未复现或只有相关性的内容标记为“待验证”。业务专用细节放在示例中，不提升为所有工作流的强制规则。

标准问题记录模板

1
2
3
4
5
6
7
8
## 问题标题
**现象**：可直接观察的输出、次数和时间。
**影响**：阻断、错误产物、性能或维护影响。
**状态**：已确认 / 高概率 / 待验证。
**可能原因**：按证据强弱排序。
**确认方法**：命令、文件、字段和预期差异。
**处理步骤**：从最小、可逆动作开始。
**预防措施**：应修改的规则、测试或文档。

记录返回码时保存命令和 cwd；记录文件时保存相对路径、mtime 或哈希；记录 TUI 时保存阶段和失败次数。缺少这些上下文，同一句错误在不同工作区可能代表不同原因。

严重程度与公共经验

先处理无法启动、无限循环、破坏正式文件或虚假完成，其次是核心需求偏离和关键工具不可用，然后才是边界和体验。一次业务问题先写实现计划；跨业务复现或代码已证明通用缺陷后再进入公共 FAQ，并增加确定性回归。