Skip to content

工作流构建完整使用

启动前

1
2
3
4
5
cd ~/FDocB/UCAgent/examples/workflow_builder
make configure-check
make help
test -f <business-root>/input/guide.md
test -d <business-root>/input/test_input

确认没有另一个进程正在同一工作区运行构建或增量流程。不同业务应使用不同的 WS 和 tmux session，避免 MCP 端口、历史和产物互相污染。

tmux 监督策略

监督策略让 UCAgent 内部 Agent 自动 loop。用户或外部 Agent 观察 TUI，连续失败时检查原因，只修改母工作流中真正有问题的规则，然后重启或续跑。入口：

1
make WS=<business-root>/workspace run

默认 RUN_LOOP_ARGS 包含 --loop --loop-msg。判断阶段是否仍在工作时，应结合 TUI 工具调用、目标文件时间戳和阶段失败计数，不能只看已经等待了多少分钟。

tmux 干预策略

干预策略不让内部 Agent 自动执行，而由外部 Agent 通过 MCP 获取 RoleInfo 和任务、完成当前阶段。入口：

1
make WS=<business-root>/workspace run RUN_LOOP_ARGS=

干预者仍必须遵循阶段任务和 Checker，不能绕过流程直接替整个业务工作流生成所有文件。适合定位难以从 TUI 理解的阶段失败，不适合长期代替工作流运行。

历史与续跑

默认运行保留 .ucagent 历史，因此停止后可以从现有阶段继续。只有明确需要全新评估或用户要求无历史运行时才使用相应参数或清理状态。不要在用户希望续跑时擅自添加 --no-history。

如果需求或中心 spec 已发生破坏性变化，旧阶段历史可能不再可信，应先备份报告和计划，再清理工作区重建，而不是让 Agent 在互相矛盾的上下文中继续。

失败诊断顺序

  1. 读取当前阶段名、失败次数和完整 Checker 消息。
  2. 查看实现计划对应阶段的“问题与处理”。
  3. 比较 reference/output 文件是否存在、是否为具体文件、路径是否规范化。
  4. 检查 Agent 是否误解格式、反复运行同一命令或读取过多无关文档。
  5. 确认是母规则问题后，修改公共源而不是只修工作区副本。
  6. 运行相关确定性回归，再从当前阶段续跑。

网络流式异常与业务 Checker 失败必须分开。incomplete chunked read 表示模型响应流没有完整结束，但频繁在大上下文阶段出现时也应检查一次请求是否过大、代理和服务端限制，不能简单认定唯一原因。

完成验收

主流程结束后检查设计和产物映射、工具和 Checker 注册、文档、环境、示例以及：

1
2
3
4
cd <business-root>/workspace/workflow
python setup.py --check
make check
make check_example

如果命令失败，构建不能算成功。不要由监督者手工修产物后宣称工作流本身已经通过测试；需要修正母工作流并用新运行验证。

环境启动方式

持久化方式适合重复使用：运行根 python setup.py，Make 自动加载本地值。临时方式适合一次实验：当前 shell 执行 ucagent_env、proxy_on 并在命令行传 WS。tmux 新 session 不一定继承 shell function，因此应检查实际 Python、代理和 Token。

监督频率和干预阈值

正常阶段每两分钟查看阶段、失败数、最近调用和产物变化。一次失败通常让 Agent自修；连续三次同根因可开始定向检查；五次以上或长时间无状态变化属于明显异常。阈值不是机械终止条件，长转换可以合理，但必须有工具或文件证据。

干预前保存 TUI 最后输出和任务。MCP接管时先 RoleInfo，只完成当前阶段并接受同一 Checker验收。修母规则后默认续用历史，除非用户明确要求全新运行。

质量与恢复

审查实现计划是否比用户需求更具体、workflow build spec 是否闭合、开发者文档是否引用真实业务源码、config 是否完成 placeholder 和引用自审。速度不是质量证据。

停止时先让当前命令响应 SIGINT，再退出 TUI。模型流异常若自动 retry，可以继续观察；进程退出后保留 .ucagent 重启。恢复时先确认 saved stage index，不应自动加 --no-history。