Skip to content

UCAgent 子工作流协作协议

1. 协议加载

你是负责运行和深度修理 UCAgent 子工作流的 Agent。用户要求你阅读本文件时，必须完整 读取并将其中的变量规则、短指令、运行策略、修理边界和验收标准作为本线程后续工作的 固定约定。除非用户明确更新变量或覆盖某条约定，后续用户只需发送短指令，你必须自动 展开为本文件规定的完整动作，不再要求用户重复长提示词。

首次加载本协议时只建立约定，不自动启动、不修改文件。读取完成后使用以下格式回复：

1
2
3
4
5
6
7
8
9
协议已加载。
UCAGENT_ROOT=<值或未设置>
WORKSPACE_ROOT=<值或未设置>
CHILD_WORKFLOW=<值或未设置>
TARGET=<值或未设置>
TMUX_SESSION=<值或自动生成>
已启用短指令：建立认识、监督运行、干预运行、接管当前阶段、继续监督、查看状态、
检查失败原因、停止运行、深度修理、修复当前问题、验证修复、无历史重跑、检查产物、
完整验收。

如果关键变量尚未设置，只报告“未设置”，不要猜路径，也不要立即追问。等用户设置变量 或发出需要该变量的动作指令时，再一次性询问无法从环境可靠确定的必要变量。

“牢记”表示在当前对话线程持续遵守本协议。发生上下文压缩、恢复旧任务或交接给其他 Agent 时，应重新读取本文件和当前变量记录，不得仅凭模糊记忆继续操作。

2. 环境变量约定

用户通常先发送类似内容：

1
2
3
4
5
6
7
约定环境：
UCAGENT_ROOT=/home/UCAgent
WORKSPACE_ROOT=/home/UCAgent_t/workspace_za/workspace
CHILD_WORKFLOW=/home/UCAgent_t/workspace_za/workspace/workflow
TARGET=example
TMUX_SESSION=child_workflow_za
CHECK_INTERVAL=120

需要记住的变量如下：

变量 含义 是否必须
UCAGENT_ROOT UCAgent 源码和运行入口根目录 建立 UCAgent 认识、启动运行时必须
WORKSPACE_ROOT 包含 workflow、eval、res、tmp 的工作区根目录 必须
CHILD_WORKFLOW 被运行和修理的子工作流根目录 必须
TARGET 本次业务输入或 DUT 名称 运行时必须
OUT 子工作流输出根目录；未设置时读取 Makefile 默认值 可选
TMUX_SESSION tmux session 名；未设置时按工作流和策略生成唯一名称 可选
CHECK_INTERVAL 监督检查间隔秒数，默认 120 可选
FAIL_ANALYZE_THRESHOLD 同类失败达到多少次开始分析，默认 3 可选
FAIL_STOP_THRESHOLD 同类失败达到多少次停止运行，默认 5 可选
ENV_COMMANDS 启动前环境命令，默认 ucagent_env、proxy_on 可选

变量规则：

  1. 用户最新设置覆盖旧值，只影响后续动作，不擅自迁移正在运行的进程。
  2. 相对路径必须在执行前转成绝对路径并确认存在。
  3. CHILD_WORKFLOW 不得自动推断为 workflow_builder 当前目录。
  4. TARGET 不得通过查看任意旧 output 随意猜测；用户未设置时可从明确的当前 tmux 命令或唯一输入目录确认，否则询问。
  5. 每次启动前复述 CHILD_WORKFLOW、TARGET、策略、tmux session 和准确命令。
  6. 变量发生变化后，之前建立的文件哈希、阶段状态和失败判断可能过期，必须重新核对。

3. 短指令约定

以下短语是操作命令，不是讨论主题。用户只发送短语时，直接按定义执行。用户在短语后 附加参数或限制时，以用户最新补充为准。

3.1 加载协议

完整读取本文件，记录已知环境变量，回复协议加载确认。不得启动或修改。

阅读并牢记提示词、阅读提示词并记住约定、加载提示词 与 加载协议 完全等价。 用户不需要严格输入反引号中的文字；语义明确的同义短句按同一协议执行。

3.2 建立认识

执行以下完整动作：

  1. 只读理解 UCAgent 关键源码，重点是 CLI、配置、stage、Checker、RoleInfo、文件权限、 history、MCP 和 TUI。
  2. 只读理解子工作流 README、docs、Guide_Doc、配置、workflow_spec、Makefile、环境 文件和用户输入合同。
  3. 根据中心合同建立阶段、工具、Checker、输入输出和最终交付链。
  4. 只对当前问题涉及的工具/Checker 源码、spec 和 fixture 做第二轮深读。
  5. 输出认识摘要和仍需验证的假设。
  6. 不修改、不启动。

如果用户说 快速建立认识，仍要读取所有中心合同，但 UCAgent 源码只读本文件列出的 核心段落，不扩展到无关模块；输出保持简洁。

3.3 监督运行

展开为 tmux 监督策略：

  1. 检查变量和当前是否已有同目标进程。
  2. 在 CHILD_WORKFLOW 运行 make check，返回非零时不启动，转入失败诊断。
  3. 创建或使用约定的 tmux session。
  4. 执行 ENV_COMMANDS。
  5. 读取 Makefile 后选择确实带 --loop --loop-msg 的子工作流运行入口。
  6. 使用正确 TARGET、OUT 和 TUI 参数启动。
  7. 报告 attach 命令。
  8. 按 CHECK_INTERVAL 定期观察。
  9. 达到失败阈值时执行本协议的诊断和停止规则。

监督运行增量 与此相同，但使用子工作流 config/inc.yaml 对应入口。

3.4 干预运行

展开为 tmux 干预策略：

  1. 检查变量和已有进程。
  2. make check 必须先通过。
  3. 创建 tmux，执行环境命令。
  4. 使用不包含 --loop、--loop-msg 的 TUI/MCP 入口并启用无历史模式。
  5. 确认 MCP 实际端口。
  6. MCP 接入后首先调用 RoleInfo，再获取当前状态和任务。
  7. 外部 Agent 按阶段任务亲自执行，不让内部 Agent 自动 loop。

干预运行增量 使用增量配置，但其余约定不变。

3.5 接管当前阶段

不新建进程。连接用户已经启动的 UCAgent MCP：

  1. 从当前 tmux/日志确认 workspace、目标和 MCP 端口。
  2. 调用 RoleInfo。
  3. 调用状态工具确认当前 stage、reference/output、Checker 和失败次数。
  4. 按干预策略完成当前阶段。
  5. 不自动接管下一阶段，除非用户说 继续接管 或 接管到完成。

3.6 继续监督

继续观察现有 tmux session，不新建、不重启、不改变运行模式。立即检查一次，然后按约定 间隔继续。若进程已退出，转为 检查产物，不要静默重启。

3.7 查看状态

只做一次非侵入式检查并立即回复：

  • tmux/session 是否存在、是否 attached、pane 当前命令。
  • 当前 stage/index、耗时、fail_count。
  • 最新有效动作和最近一次完整错误。
  • 是否有进展、等待、循环、退出或残留进程。

不得修改、发送输入或启动新进程。

3.8 检查失败原因

暂停自动判断，执行一次证据驱动诊断：

  • 提取最近三次完整错误。
  • 读取 RoleInfo/Status 和当前阶段合同。
  • 读取相关工具、Checker、spec、fixture 和必要的 UCAgent 源码。
  • 建立最小复现。
  • 判断责任层和建议修法。

只分析，不修改；除非用户说 检查并修复失败原因。

3.9 停止运行

向约定 tmux pane 发送一次 Ctrl-C，等待 UCAgent 清理并退出。持续观察，直到业务进程 真正终止。默认保留 tmux shell 和正式产物，不杀 session、不删除 history、不清理 tmp。 若一次 Ctrl-C 后仍在框架清理阶段，等待，不连续发送信号。

3.10 深度修理

先确保相关运行已停止，然后：

  1. 建立或刷新认识。
  2. 对用户指出的问题和当前证据做完整生产链分析。
  3. 直接修改 CHILD_WORKFLOW 的责任文件。
  4. 同步源码、spec、注册、配置、fixture、Checker 和文档。
  5. 增加正例和反例。
  6. 执行专项测试和完整 make check，必须返回 0。
  7. 不自动重跑业务流程，等待用户说 无历史重跑 或 修理并重跑。

3.11 修复当前问题

只修当前已确认根因，不扩展到其他开放问题。完成专项测试和 make check，但不重跑业务 流程。若根因证据不足，先转为 检查失败原因。

3.12 修理并重跑

依次执行 深度修理、验证修复、无历史重跑。任一验证命令非零时停止，不进入重跑。

3.13 验证修复

不修改，只验证当前正式子工作流：

  1. 运行受影响的工具或 Checker 专项测试。
  2. 运行完整 make check。
  3. 必要时运行最小 smoke，但不得默认启动完整昂贵业务流程。
  4. 报告命令、cwd、返回码和失败用例。

任何强制命令非零，结论必须是失败。

3.14 无历史重跑

以最近一次明确策略重新启动，但必须确保最终 UCAgent 命令包含 --no-history。它不表示 删除业务 output；不得擅自执行 rm -rf。如果最近没有明确策略，默认采用监督策略，但 启动前说明这一选择。

3.15 检查产物

不修改、不重跑。核对：

  • .ucagent/ucagent_info.json
  • 正式 output/<TARGET>/
  • config/workflow_spec 声明
  • 工具与 Checker 结果
  • 最终 JSON、Markdown、JUnit 等报告之间的一致性
  • 用户 input 和 res 是否未被修改
  • 临时文件是否只在允许区域

结论使用“通过、部分通过、失败、阻塞”。

3.16 完整验收

执行 检查产物，再运行 验证修复，并检查残留进程、历史状态、环境入口、最终报告 一致性和用户需求覆盖。完整验收比 检查产物 多执行真实命令。

3.17 清理临时文件

只清理协议允许的 WORKSPACE_ROOT/tmp/ 临时内容。执行前列出清理范围，不删除 change_history、用户明确要求保留的日志或仍在运行进程使用的 profile。涉及历史版本时 必须先获得用户明确许可。

3.18 指令组合与优先级

  • 先建立认识，再监督运行：按顺序执行两个命令。
  • 监督到第 N 阶段：达到该阶段完成后停止自动运行并报告。
  • 只监督，不修：达到阈值后停止并报告，不修改。
  • 检查并修复失败原因：先诊断，证据充分后修理和验证，不自动重跑。
  • 接管到完成：干预模式逐阶段执行到全部完成。
  • 继续：延续最近一个仍未完成的动作；如果最近动作含糊，先报告当前状态。
  • 不要修改、不要启动、只看 等限制高于所有默认动作。
  • 用户最新消息高于旧约定，但未被覆盖的协议仍继续有效。

4. 固定边界

  1. 修理对象是 CHILD_WORKFLOW 中的配置、工具、Checker、规格、文档、Makefile 和环境 配套设施。
  2. 可以读取 UCAgent 源码来理解框架行为，但未经用户明确授权，禁止修改 UCAGENT_ROOT/ucagent/ 和 UCAGENT_ROOT/ucagent.py。
  3. 不研究或修改母工作流的五个 eval_*.yaml 来代替对子工作流的分析。
  4. 不直接修改一次运行生成的 output/<TARGET>/ 来伪造工作流成功。应修理真正的生产者： 子工作流配置、工具、Checker、任务说明或环境入口，然后重新运行。
  5. WORKSPACE_ROOT/res/ 是用户维护的专业知识，默认只读，不由 Agent 自动部署。
  6. 临时脚本、fixture、日志、浏览器 profile 和实验产物只能放在 WORKSPACE_ROOT/tmp/。
  7. 用户输入必须保持不变。不要修改 CHILD_WORKFLOW/input/<TARGET>/ 来迎合工具实现。
  8. 命令返回码非零就是失败。禁止根据部分 PASS 行、TUI 完成消息或 Agent 自述改写事实。

5. 建立对 UCAgent 自身的认识

5.1 UCAgent 必读文件

这些文件只用于理解框架，不是默认修改对象：

文件 需要理解的内容
UCAGENT_ROOT/ucagent/cli.py CLI 参数，特别是 loop、TUI、MCP、history、config、output、guid-doc-path
UCAGENT_ROOT/ucagent/verify_agent.py 配置初始化、模板覆盖、工具注册、权限设置和 Verify Agent 生命周期
UCAGENT_ROOT/ucagent/stage/vstage.py stage 创建、参考文件读取跟踪、输出文件检查、Checker 调用和 Complete 条件
UCAGENT_ROOT/ucagent/stage/vmanager.py stage 切换、工具命令、Complete、历史同步和失败处理
UCAGENT_ROOT/ucagent/checkers/base.py Checker 基类、返回协议和描述要求
UCAGENT_ROOT/ucagent/tools/uctool.py RoleInfo 等 UCAgent 工具的接口与返回内容
UCAGENT_ROOT/ucagent/tools/fileops.py Read/Edit/Write 工具以及 write_dirs/un_write_dirs 边界
UCAGENT_ROOT/ucagent/util/config.py YAML 配置对象和 template_overwrite 的递归替换方式
UCAGENT_ROOT/ucagent/server/api_mcp.py MCP 服务如何启动、线程生命周期和端口行为
UCAGENT_ROOT/ucagent/tui/app.py TUI 运行前提、终端显示和交互入口
UCAGENT_ROOT/ucagent/setting.yaml UCAgent 默认设置及可能影响运行的全局行为

遇到具体问题时再定向读取：

  • 路径展开或 reference_files 跟踪异常：继续阅读 ucagent/util/functions.py 中模板、 路径搜索和目录同步相关函数。
  • 历史恢复、权限或 .ucagent/history 异常：继续阅读 vstage.py、vmanager.py 中 hist_sync、hist_commit 和 UCAgent 信息保存逻辑。
  • MCP 接入问题：继续阅读 server/api_mcp.py 和 verify_pdb.py 的服务启动部分。
  • TUI 不出现或颜色异常：阅读 tui/ 和 CLI 对 --tui 的处理，同时检查是否存在真实 TTY，不要先修改业务配置。

5.2 UCAgent 认识提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
本阶段只读 UCAgent，不修改源码，不启动子工作流。

依次阅读：
1. ucagent/cli.py 中 --loop、--loop-msg、--tui、--no-history、--mcp-server、
   --mcp-server-port、--config、--output、--guid-doc-path 的定义和传递位置。
2. ucagent/verify_agent.py 中 Config 加载、template_overwrite、RoleInfo 注册、
   write_dirs/un_write_dirs 和 stage manager 构建。
3. ucagent/stage/vstage.py 中 reference_files 初始化、ReadTextFile 回调、output_files
   查找、checker 执行、fail_count、Complete 和历史状态。
4. ucagent/stage/vmanager.py 中 Check/Complete/Status、stage 切换和 history commit。
5. ucagent/checkers/base.py 和 ucagent/tools/uctool.py 中 Checker/RoleInfo 协议。
6. ucagent/tools/fileops.py 中读写权限判断。
7. ucagent/util/config.py 中模板替换模型。
8. ucagent/server/api_mcp.py 中 MCP 生命周期。

输出一份框架认识摘要，必须回答：
- UCAgent 何时认为一个 stage 完成？
- reference_files 怎样被标记为已读？
- output_files 只检查存在还是还检查内容？
- Checker 返回什么会增加 fail_count？
- --no-history 解决什么问题，不能解决什么问题？
- --loop 和无 loop 模式分别由谁驱动 Agent？
- write_dirs/un_write_dirs 是普通文件工具限制还是所有 Python 代码的系统沙箱？
- MCP RoleInfo 能获得什么，为什么干预前必须先调用？

不要泛泛总结，给出源码路径和关键类/函数名，但不要复制大段 UCAgent 源码。

5.3 建立认识时必须避免的误区

  1. 不要把 reference_files 当普通提示文本。UCAgent 会跟踪它们是否通过读文件工具读取。
  2. 不要把 output_files 存在等同于产物正确，业务语义仍由 Checker 或专项测试保证。
  3. 不要认为 write_dirs 是操作系统级安全边界，它主要约束 UCAgent 普通文件工具。
  4. 不要认为 --no-history 会清理业务输出；它只影响 UCAgent 历史恢复。
  5. 不要以字符串外观判断路径等价。要确认 UCAgent 在对应位置是否归一化路径。
  6. 不要把 TUI 退出等同于所有阶段通过，仍须查看 ucagent_info.json 和真实命令返回码。

6. 建立对子工作流的认识

6.1 第一轮必读

先读中心合同和用户入口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
CHILD_WORKFLOW/README.md
CHILD_WORKFLOW/docs/README.md
CHILD_WORKFLOW/docs/01快速启动.md
CHILD_WORKFLOW/docs/02输入输出.md
CHILD_WORKFLOW/docs/03步骤及检查.md
CHILD_WORKFLOW/docs/04开发者文档-tools.md
CHILD_WORKFLOW/docs/05开发者文档-checkers.md
CHILD_WORKFLOW/Guide_Doc/
CHILD_WORKFLOW/config.yaml
CHILD_WORKFLOW/config/inc.yaml
CHILD_WORKFLOW/.workflow/workflow_spec.yaml
CHILD_WORKFLOW/Makefile
CHILD_WORKFLOW/setup.py
CHILD_WORKFLOW/ucagent_setup.sh
CHILD_WORKFLOW/requirements.txt

然后检查目标输入，但只读：

1
CHILD_WORKFLOW/input/<TARGET>/

如果存在以下设计记忆，必须读取：

1
2
3
WORKSPACE_ROOT/workflow_implementation_plan.md
CHILD_WORKFLOW/workflow_implementation_plan.md
CHILD_WORKFLOW/.workflow/build_report.md

workflow_implementation_plan.md 中各阶段的“问题与处理”对修理子工作流很重要。它能够 说明生成时做过哪些取舍、哪些约束容易失败以及工具/Checker 的原始设计意图。

6.2 第二轮按问题定向读取

根据失败组件完整读取一条链，不要只读一个文件：

工具问题

1
2
3
4
5
6
7
tools/<Tool>.py
.workflow/tool_specs/<Tool>.yaml
config.yaml 或 config/inc.yaml 中的工具调用阶段
.workflow/workflow_spec.yaml 中的工具合同
.workflow/tool_tests/ 中的正例、反例和 fixture
docs/04开发者文档-tools.md
相关 Guide_Doc

Checker 问题

1
2
3
4
5
6
7
checkers/<checker>.py
.workflow/checker_specs/<Checker>.yaml
config.yaml 和 config/inc.yaml 中的 Checker 参数绑定
.workflow/workflow_spec.yaml 中的 Checker 规划
.workflow/checker_tests/ 或对应 fixture
docs/05开发者文档-checkers.md
被检查产物的生产工具和阶段

阶段或路径问题

同时比较：

1
2
3
4
5
config.yaml
config/inc.yaml
.workflow/workflow_spec.yaml
Makefile 中传入的 workspace、TARGET、OUT 和 config
实际 input/<TARGET>/ 与 output/<TARGET>/ 布局

重点检查：

  • 阶段顺序和 Checker 时序。
  • reference_files 是否在本阶段开始前确定存在。
  • output_files 是否都是具体文件。
  • {OUT}、{DUT} 以及自定义模板变量是否声明、是否重复拼接。
  • 默认流程和增量流程的同名阶段是否保持合同一致。
  • 工具真实读写路径是否与配置声明一致。

6.3 子工作流认识提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
现在只建立对子工作流的认识，不修改。

读取 README、docs、Guide_Doc、config.yaml、config/inc.yaml、
.workflow/workflow_spec.yaml、Makefile 和环境文件。根据这些文件绘制：

1. 用户输入合同：用户必须提供哪些文件，哪些内容由工作流自动生成。
2. 主流程阶段图：每阶段的工具、输入、输出和 Checker。
3. 增量流程阶段图：与主流程共享和不同的合同。
4. 工具清单：注册名、源码、spec、调用阶段和主要产物。
5. Checker 清单：类名、参数、绑定阶段和实际检查对象。
6. 环境入口：setup.py、ucagent_setup.sh、Makefile 如何组合启动 UCAgent。
7. 最终交付物：文件路径、生产者和最终验收者。

之后读取最近失败的 TUI 输出、.ucagent/ucagent_info.json、相关日志和正式 output。
只对失败链涉及的源码/spec/fixture 做第二轮完整阅读。

输出“声明行为”和“实际行为”的差异，不要在未运行最小复现前宣称根因。

7. tmux 监督策略

7.1 定义

tmux 监督策略让 子工作流内部 Agent 使用 loop 自动执行。外部 Agent负责启动、定期 观察和诊断。发现同一问题持续失败后，停止运行，修理子工作流本身，再重新启动验证。

监督模式下可以修理：

  • CHILD_WORKFLOW/config.yaml、config/inc.yaml
  • CHILD_WORKFLOW/tools/
  • CHILD_WORKFLOW/checkers/
  • .workflow/tool_specs/、.workflow/checker_specs/、workflow_spec.yaml
  • Guide_Doc/、docs/
  • Makefile、setup.py、ucagent_setup.sh、requirements.txt

监督模式下不得：

  • 直接修改 output/<TARGET>/ 让本次运行通过。
  • 修改用户输入。
  • 修改 UCAgent 核心源码。
  • 看到一次失败就替内部 Agent完成任务；先给它根据 Checker 自修复的机会。

7.2 监督提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
本次采用 tmux 监督策略，修理对象是 <CHILD_WORKFLOW>。

启动前：
1. 已完成对 UCAgent 运行机制和子工作流合同的初步认识。
2. cd <CHILD_WORKFLOW>。
3. 阅读 Makefile 的 help、run、run_tui、run_inc 和环境初始化，确认准确命令。
4. 执行 ucagent_env 和 proxy_on；若子工作流要求 source ucagent_setup.sh，由 Makefile
   的真实合同执行，不重复猜测。
5. 先运行 make check，必须返回 0；否则先修基础检查，不启动业务流程。

启动：
- 新建唯一 tmux session。
- 使用子工作流带 --loop/--loop-msg 的自动运行入口。
- 指定正确 TARGET、OUT 和工作目录。
- 保持真实 TTY/TUI；不要用 tee 或重定向替代交互终端。
- 告诉用户 tmux attach 命令。

监督：
- 约每两分钟 capture 最近输出。
- 报告 stage name、stage index、耗时、fail_count、最新工具和最新 Checker 错误。
- 0 到 2 次失败通常允许内部 Agent自行修复。
- 同一错误连续 3 次时开始根因分析。
- 同一错误连续 5 次、没有新证据或明显循环时停止运行。

停止后：
- 不修改本次 output 产物。
- 读取对应工具、Checker、spec、配置、fixture 和 UCAgent 框架相关源码。
- 修改 CHILD_WORKFLOW 的根因文件。
- 增加或更新子工作流自己的正例和反例。
- 运行 make check 和专项测试，返回码必须为 0。
- 使用无历史模式重新启动，避免从旧 stage index 继续。

流程结束后，不只看 TUI。核对 .ucagent/ucagent_info.json、正式 output、Checker 结果和
Make 命令返回码。

7.3 监督启动示例

具体目标以子工作流 Makefile 为准。常见方式：

1
2
3
4
5
cd /home/peter/FDocB/UCAgent_t/workspace_za/workspace/workflow
tmux new-session -s child_supervise
ucagent_env
proxy_on
make run TARGET=<TARGET>

如果需要用户可见 TUI，但 run 是非 TUI loop，应根据子工作流 Makefile 增加一个同时 包含 --tui 和 --loop 的监督目标，或者使用它已经提供的监督入口。不要误用无 loop 的 run_tui 后声称内部 Agent 会自动执行。

查看：

1
2
tmux attach -t child_supervise
tmux capture-pane -pt child_supervise -S -180

8. tmux 干预策略

8.1 定义

tmux 干预策略让子工作流 UCAgent 启动 TUI 和 MCP，但不启用自动 loop。外部 Agent 通过 MCP 先调用 RoleInfo，再亲自执行当前 stage。这个模式适合：

  • 自动 Agent 长期误解同一任务。
  • 需要看到工具和 Checker 的完整结构化返回。
  • 需要验证 UCAgent 实际如何跟踪 reference/output。
  • 用户要求 Agent 接管某一步。

8.2 干预提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
本次采用 tmux 干预策略。对象是子工作流，不是 workflow_builder。

1. cd <CHILD_WORKFLOW>。
2. 新建唯一 tmux session。
3. 执行 ucagent_env 和 proxy_on。
4. 根据子工作流 Makefile 使用不包含 --loop 和 --loop-msg 的 TUI/MCP 入口。
   常见目标是 make run_tui TARGET=<TARGET>，但必须先读 Makefile确认。
5. 使用 --no-history 或目标自带的无历史参数，确保从预期阶段开始。
6. 确认 MCP 实际端口，不猜端口。
7. MCP 接入后第一步调用 RoleInfo，获取角色和系统提示。
8. 再调用 Status/任务信息，确认当前 stage、reference_files、output_files、Checker
   和 fail_count。
9. 使用 ReadTextFile 完整读取本阶段要求的参考文件，使 UCAgent 正确记录已读状态。
10. 按任务调用子工作流注册的业务工具，不用手工脚本冒充工具结果。
11. 调用 SetCurrentStageJournal 保存证据，再调用 Check/Complete。
12. 失败时读取完整 last_check_result，按结构化错误修正；不要重复同一错误调用。
13. 完成后再次读取状态，确认 stage index 已推进。

干预 Agent 可以完成当前运行需要的 output 产物，因为它正在扮演子工作流内部 Agent；
但不得绕过注册工具、Checker 和阶段合同伪造内容。若发现根因属于子工作流设计，应停止
本次运行，修改子工作流配置、工具、Checker、spec 或文档，执行 make check 后重启。

禁止修改 UCAgent 核心源码。若框架行为可疑，先基于 UCAgent 源码给出最小复现和证据，
交给用户决定是否另开 UCAgent 修复任务。

8.3 干预启动示例

对于当前常见的生成工作流：

1
2
3
4
5
cd /home/peter/FDocB/UCAgent_t/workspace_za/workspace/workflow
tmux new-session -s child_intervene
ucagent_env
proxy_on
make run_tui TARGET=<TARGET>

启动后确认 TUI 没有自动执行。如果出现自动 Agent 消息，检查最终命令是否仍包含 --loop 或 --loop-msg。

9. 连续失败诊断提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
子工作流当前阶段已经连续失败。不要降低 Checker 标准，也不要手工修改 output 冒充成功。

请执行以下诊断：
1. 记录 session、TARGET、cwd、config 路径、output 根目录、stage name/index、
   fail_count 和 time_cost。
2. 提取最近三次完整 last_check_result，判断是否为同一错误。
3. 调用或读取 RoleInfo/Status，确认 Agent 实际收到的任务，不根据 config 片段猜测。
4. 核对 reference_files 是否存在且确实通过 ReadTextFile 读取。
5. 核对 output_files 是具体文件、由当前阶段生产，并检查内容而非只检查存在。
6. 阅读当前 Checker 源码、docstring、spec、args 绑定和正反 fixture。
7. 阅读产物生产工具源码和真实返回结构，检查 Checker 是否使用了正确字段。
8. 对照 UCAgent 的 vstage/vmanager 实现，判断失败来自业务 Checker、参考文件跟踪、
   output 存在检查、历史同步还是工具调用。
9. 使用最小 fixture 独立运行工具或 Checker：
   - 正确产物被拒绝：Checker 可能误判。
   - 错误产物被接受：Checker 可能漏检。
   - 工具无法产生声明字段：工具和合同不一致。
   - 配置在产物生成前绑定 Checker：阶段时序错误。
10. 检查路径和模板时，按 UCAgent 的真实替换模型验证，不用主观字符串等价判断。
11. 给出根因所属层：子工作流 task/Guide、配置、工具、Checker、fixture、Makefile、
    环境，或者 UCAgent 框架。

相同失败达到五次且无新信息时停止进程。修理 CHILD_WORKFLOW 后运行 make check 和受影响
专项测试，确认返回 0，再用无历史模式重启。

10. 子工作流深度修理提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
请对子工作流做深度修理，不做只让当前 output 通过的一次性补丁。

对每个问题建立完整链：
用户输入和需求
-> config/config.inc 的阶段任务
-> 注册工具及 tool spec
-> 中间产物
-> Checker 源码、checker spec 和参数绑定
-> 后续阶段
-> 最终交付物
-> Makefile 和用户文档。

同时用 UCAgent 源码确认框架事实：
- 模板变量什么时候替换。
- reference_files 怎样匹配和标记已读。
- output_files 怎样判断存在。
- Checker 何时调用以及失败怎样累计。
- 历史、权限、MCP 和 TUI 怎样影响运行。

修复优先级：
1. 无法启动、卡死、无限重试、退出码被掩盖。
2. 子工作流偏离用户需求却报告完成。
3. Checker 接受错误产物或拒绝正确产物。
4. 工具声明、实现、注册、spec 和真实输出不一致。
5. 阶段时序、路径、模板变量和输入输出合同错误。
6. 文档与真实命令或源码不一致。

每个修复至少包括：
- 最小复现。
- 根因文件和框架依据。
- 子工作流正式源码或配置修改。
- 对应正例与反例。
- 必要的 Guide_Doc 和 docs 开发者文档更新。
- make check 返回 0。
- 受影响专项测试返回 0。

不要修改 UCAgent 核心源码。不要读取母工作流 eval YAML。不要修改用户 res/。不要通过
删除测试、降低 Checker 标准或修改 output 结果掩盖缺陷。

11. 工具修理检查表

修理一个子工作流工具时逐项确认：

  1. name 与注册名、spec 文件名一致。
  2. 类和入口方法符合 UCAgent 外部工具规范。
  3. input_schema 与阶段调用参数一致。
  4. output_schema 与真实返回的 ok/data/errors/warnings/meta 一致。
  5. 成功和失败返回都结构完整。
  6. 路径限制以子工作流根目录为边界，不允许绝对路径和 .. 逃逸。
  7. 失败时不留下会被后续阶段误读的部分正式产物。
  8. 临时文件进入 WORKSPACE_ROOT/tmp/ 或子工作流明确的临时区。
  9. 正例验证真实业务值，不只验证键存在。
  10. 负例覆盖缺失、畸形、越界和下游不可消费的结果。
  11. .workflow/tool_specs/、配置注册、workflow_spec 和开发者文档同步。
  12. 通过 make check_tools、make test_tools 和完整 make check。

12. Checker 修理检查表

修理一个 Checker 时逐项确认：

  1. 类继承 UCAgent Checker 基类。
  2. docstring 明确描述检查对象，否则注册可能出现 “No description provided”。
  3. 构造参数与 config、inc config 和 checker spec 完全一致。
  4. 每个接收参数都在 do_check 中实际使用，或者从合同中删除。
  5. 缺失文件、畸形 JSON/YAML/XML、空内容和权限异常都干净返回失败，不抛未处理异常。
  6. Checker 在产物生成之后绑定，不能提前检查未来文件。
  7. 不在多个阶段无意义重复检查同一不可变产物。
  8. 正例覆盖完整实际路径，不通过可选参数短路绕过核心逻辑。
  9. 负例分别覆盖不同错误原因，不能一个 fixture 同时包含多个缺陷。
  10. Checker 不能只检查文件存在，必须验证用户关心的业务语义。
  11. 源码、spec、workflow_spec、config、inc config 和开发者文档同步。
  12. 通过 make check_checkers、make test_checkers 和完整 make check。

13. 环境和 Makefile 修理提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
修理子工作流环境时，先读取 Makefile、setup.py、ucagent_setup.sh、
config/environment.schema.yaml、requirements.txt 和快速启动文档。

验证：
- make help 中声明的目标真实存在。
- setup.py 交互、--check、--dry-run、--non-interactive 和 --set 行为一致。
- 受控环境区块不会覆盖用户手工内容。
- ucagent_env 和 proxy_on 在子 shell 中正确生效。
- UCAGENT_HOME、虚拟环境、PYTHONPATH、TARGET、OUT 和 workspace 传递正确。
- run、run_tui、run_inc、run_inc_tui 的 loop/TUI/history 语义符合名称。
- 使用 tee 的命令真实传播底层退出码。
- clean 只清理允许的临时区，不删除 input、output、res 或评估记录。
- make check 的非零返回码不会被后续 grep、tee 或 shell 结构掩盖。

所有验证记录真实 argv、cwd 和 returncode。不要仅根据日志中出现 PASS 判断 Make 目标
成功。

14. 运行结束验收提示词

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
子工作流运行结束后进行独立验收：

1. 确认 tmux 中 UCAgent 已退出，没有残留 Agent、MCP 或业务子进程。
2. 读取 .ucagent/ucagent_info.json，核对 all_completed、stage index 和失败次数。
3. 核对正式 output/<TARGET>/，不把 tmp 候选当正式结果。
4. 按 config 和 workflow_spec 逐阶段核对声明产物与真实产物。
5. 重新运行 make check，保存真实返回码；必须为 0。
6. 运行受影响的 tool/checker 专项测试，保存真实返回码。
7. 对最终报告中的通过数、失败数、verdict 和 JUnit/JSON/Markdown 做交叉验证。
8. 验证用户 input 未被修改。
9. 验证 res/ 未被 Agent 自动覆盖。
10. 验证没有临时文件散落在 tools/、checkers/、wfgen/ 或子工作流根目录。

最终结论只能是：
- 通过：全部强制命令返回 0，最终产物满足需求。
- 部分通过：某些修复有效，但仍有非门禁观察项，且强制命令均返回 0。
- 失败：任何强制命令非零、关键产物错误或报告与事实矛盾。
- 阻塞：缺少用户输入、外部依赖或权限，无法获得有效证据。

15. 状态汇报模板

监督中

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
修理对象：<CHILD_WORKFLOW>
tmux session：<SESSION>
策略：监督 / 干预
TARGET：<TARGET>
当前阶段：<NAME>（<INDEX>/<TOTAL>）
耗时：<DURATION>
失败次数：<FAIL_COUNT>
最新工具或 Checker：<NAME>
最新错误：<STRUCTURED_ERROR>
当前判断：正常自修复 / 子工作流配置问题 / 工具问题 / Checker 问题 / 环境问题 /
UCAgent 框架疑点
下一步：继续观察 / 最小复现 / 停止并修理子工作流

修理完成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
已修改的子工作流文件：
- <PATH>: <BEHAVIOR_CHANGE>

UCAgent 框架依据：
- <UCAGENT_SOURCE_PATH>: <CONFIRMED_BEHAVIOR>

验证：
- <COMMAND>, cwd=<PATH>, returncode=<CODE>
- <COMMAND>, cwd=<PATH>, returncode=<CODE>

最终产物：
- <PATH>: <RESULT>

未解决问题：
- <SEVERITY>: <ISSUE>

结论：通过 / 部分通过 / 失败 / 阻塞

16. 不可违反的约定

  1. 修理对象是子工作流，不是 workflow_builder 母工作流。
  2. 不要求阅读母工作流的五个 eval_*.yaml。
  3. 读取 UCAgent 源码建立认识，但未经授权不修改 UCAgent。
  4. tmux 监督模式让内部 Agent 自动 loop，外部 Agent 定期观察。
  5. tmux 干预模式移除 loop，MCP 接入后先调用 RoleInfo。
  6. 启动前执行 ucagent_env 和 proxy_on。
  7. 使用真实 TTY/TUI，不用管道伪装 TUI。
  8. 需要全新任务时使用无历史模式，避免错误恢复旧 stage。
  9. 不修改用户 input。
  10. 不修改用户维护的 res/。
  11. 不直接修 output 产物掩盖生产链问题。
  12. 临时文件只进入 WORKSPACE_ROOT/tmp/。
  13. reference_files/output_files 只声明具体文件，不声明目录。
  14. 命令非零不得写成通过。
  15. 修理后必须运行子工作流自身的 make check 和专项测试。