完整使用总述¶

本目录描述 Workflow Builder 从准备业务需求到交付、评估和长期增量维护的完整方法。QuickStart 适合第一次照着执行，本目录则解释每个目录和状态文件为什么存在、谁可以修改、失败后如何恢复。

使用生命周期¶

用户创建业务根目录和 input/，编写需求及样例。
Workflow Builder 将公共 wfgen/、Guide_Doc/ 和业务输入复制到构建工作区。
主工作流生成设计文件和 workflow/ 产物，并执行静态验收。
用户检查生成工作流的环境、文档、示例和 make check。
评估工作流独立产生 findings，用户在控制台审批或提出建议。
增量工作流按 run id 建立候选、部署修复、保存旧版本并回归。
用户重新运行相关评估，关闭旧问题或继续下一轮。

文档导航¶

输入契约：构建需求、样例和专业知识。
输出与工作区结构：设计、产物、报告、临时文件和历史。
工作流构建完整使用：监督与干预、续跑和验收。
评估与审批完整使用：报告、严重程度和审批。
增量修复与版本管理：候选、部署、恢复和闭环。
提示词使用方法：如何先加载协作协议，再使用短指令。
提示词：可直接交给协作 Agent 阅读的完整协议。

两层工作流¶

构建工作区中的 config.yaml 属于 Workflow Builder；生成到 workflow/config.yaml 的文件属于业务工作流。运行命令前先执行 pwd，确认当前目标：

# 生成或评估业务工作流
cd ~/FDocB/UCAgent/examples/workflow_builder
make WS=/业务根/workspace run

# 运行已经生成的业务工作流
cd /业务根/workspace/workflow
make run TARGET=example

多数路径错误、TUI 行为差异和错误历史恢复都来自混淆这两个层级。

权限和责任¶

用户拥有 input/、res/、审批和建议。
构建 Agent 可写 wfgen/、workflow/ 和 tmp/ 中当前任务允许区域。
评估 Agent 只读 workflow/，通过结构化工具写 eval/。
增量 Agent 只处理批准范围，通过候选和部署器修改 workflow/。
控制台通过后端 API 编辑结构化字段，不能任意写文件。

任何“为了让检查通过而绕开责任边界”的行为都属于失败，即使最终命令返回 0。

生命周期状态与退出条件¶

构建流程只有在中心设计、公开产物和静态验收一致后结束；评估流程只有在本责任域强制 check 有证据并写入报告后结束；增量流程只有在全部批准项有映射、正式回归通过并保存历史后结束。TUI显示“阶段完成”只是其中一层信号。

用户主动停止时应保留当前工作区、实现计划和报告。再次启动前先决定续用历史还是全新运行，不要同时清 .ucagent、wfgen/ 和 eval/。这些目录代表不同状态：历史可以重建执行上下文，设计是业务决策，评估是长期审计。

常用命令矩阵¶

目标	交互形态	自动 loop	是否修改 `workflow/`
`run`	TUI	是	构建时写入
`run_cli`	CLI	由 CLI 流程执行	构建时写入
`run_eval_*`	TUI	是	否
`run_inc`	TUI	是	通过部署器修改
`eval-ui`	浏览器	不适用	仅结构编辑或恢复时修改

配置优先级¶

从高到低为：Make 命令行赋值、当前 Make 进程显式变量、本地 .workflow_builder/local.mk、Makefile 默认值。使用 make configure-show 查看保存值，使用 make -n WS=... run 可以在不启动 Agent时检查展开命令。同一个 Builder 可以管理多个业务工作区，本地默认值不是硬绑定。

长期项目应为每次构建记录业务根、输入 revision、开始结束时间和产物 revision；评估使用 report run id；增量使用 inc run/change id。关键修改通过结构化记录追踪，终端截图只作辅助证据。