# test_script 节点偶发输出叙述文字而非代码——问题记录（Planner + Validator 都会中招）

**日期**: 2026-08-07
**性质**: 问题记录 + 待调查,不是已确认根因的需求文档（区别于同目录下其他几份——那几份是已经定位到具体代码 bug 并修复过的,这份目前还只是"观察到的现象",根因未确定）。
**状态**: 根因已定位（见第 6 节）。用户决策（2026-08-07）：不再继续在提示词/重试反馈上打补丁，**先直接禁用 test_script/validator_test_script 节点**（Planner 的 `work_graph_plan._PROMPT_TEMPLATE` 不再要求这个节点，Validator 的 `e2e_pipeline._VALIDATOR_MANIFEST` 从 3 节点缩成 2 节点），后续如果真的需要再重新设计（见第 8 节的结构性修复方向：把"探索"和"最终作答"拆成两次独立调用）。`_NARRATION_RETRY_HINT`（第 7 节）代码仍保留在 `_test_script_verify_fn` 里,只是当前这条路径不会被触发——如果以后重新启用这个节点,这个缓解依然生效。**2026-08-08 更新（第四轮，与自规划 Work Graph 需求的交叉决策）**：`docs/todo/work-graph-self-planning-and-loop-back-requirements.md`（Planner 自规划节点集合 + 失败回路需求）上线后，test_script 会重新作为可选节点开放给 Planner 自由规划——用户明确决定**不等本文档的结构性修复**，narrative-output 问题可能因此重现，这是已知且被接受的风险。本文档记录的根因（第 6 节）的真正结构性修复，安排在**另一份尚未撰写、关于"给 Coder agent 加入 test_script 模块"的文档**里一起解决，不是本文档单独继续跟进的范围。**2026-08-07 更新（第二轮）：不只是 Validator 的问题——`911861fe` 这个纯后端任务在 Planner 自己的 `n_test_script` 节点上也复现了同一模式。累计 3 个任务、6 次到达 test_script 类节点，6 次全部复现（100%），横跨 Planner 和 Validator 两种场景。建议提高优先级，不要再靠重试撞运气。** **2026-08-07 更新（第三轮，根因排查）：这是 08-06 "Benchmark 叙述事故"（commit `07a0a27`）的同类复发——test_script 类节点当时已经同时拿到提示词纠偏和机械拦截网双重防护，仍然 6/6 复现。根因不是"self-hosting 词汇污染"这个泛泛的猜测，而是 test_script 提示词本身要求"先做工具探索再产出内容"，模型探索后的收尾话术天然是"汇报我做了/启动了什么"而不是切换成纯文本吐出模式；self-hosting 只是放大器，让叙述读起来更精确（因为探索对象就是 graphlemon 自己，词汇表精确对应），不是必要条件。BRD/PRD/SDD/Benchmark/test_dataset 这几个不需要先探索的纯组合型节点，自 08-06 后再未复现，与此吻合。**

## 1. 现象

`validate_implementation_with_own_graph()`（Validator 自己的 benchmark→test_dataset→test_script 验证图）里的 `validator_test_script` 节点,连续两次真实生产运行中都输出了**叙述性文字**而不是可执行代码,导致 `check_script_compiles()` 正确拦截（py_compile/node --check 都报语法错误）,`verify_fn` 判定失败,重试一次仍然失败,最终 `ConsistencyCheckFailedError`。

两次真实发生,内容形态高度相似,都是"在描述某个 Work Node/workflow 的执行情况",不是在写测试脚本本身：

- 任务 `3605272e`（2026-08-07 03:10 UTC 附近）：`"Launched the 'graphlemon-node-f9cefb87af4c492aac738b9736d41e4e' workflow (Work Node validator) in the background, run ID wf_93345ca8-8c6. It's running asynchronously — I'll report results once it completes; no further action is needed right now."`
- 任务 `bfd3ee82`（2026-08-07 03:13 UTC 附近）：`"The graphlemon Work Node (validator) workflow completed. It authored \`test_nav_project_context_benchmark.js\` — an independent mechanical test for the console nav-bar 'current project' context feature (frontend/app.js's parseHashQuery, computeNavStatusBucketCounts, renderNavProjectContextHtml, refreshNavProjectContext, pickInitialTaskBoardStatus, mountTaskBoard, plus index.html's #nav_project_context element and style.css's .nav-count-* rules). It loads the real app.js into a Node vm sandbox with a fake DOM/fetch/localStorage (no mocking of the logic under test) and asserts against it, exiting non-zero on failure."`
- 任务 `bfd3ee82`，**同一个任务重试后第三次复现**（2026-08-07 05:35 UTC 附近）：`"It produced a runnable Node.js test script (\`nav_project_context_benchmark.js\`) validating U-047/U-048 (console nav-bar 'current project' context). It loads the real \`frontend/app.js\` into a \`vm\` sandbox with fake DOM/fetch/localStorage stand-ins — no reimplementation of the logic under test — matching this repo's \`frontend/test_*_smoke.js\` convention."` ——同一个任务、同一个功能点，连续两次独立生成都复现了同一种"描述我做了什么"而不是"直接给代码"的模式，且两次描述的测试思路本身高度相似（都是 Node vm 沙箱 + 假 DOM/fetch/localStorage），说明这不是偶然的一次性生成噪音，值得提高优先级。
- 任务 `bfd3ee82`，**第四次复现**（2026-08-07 06:03 UTC）：`"Launched the graphlemon Work Node (validator) workflow in the background (Task ID: wrux6aaat, Run ID: wf_201fcc6d-59f). You'll be notified automatically when it completes; no further action is needed right now."` ——跟 `3605272e` 第一次的措辞几乎一字不差（"Launched ... workflow in the background ... You'll be notified ... no further action is needed"），进一步印证这是一种稳定的、可复现的措辞模式，不是随机生成噪音。
- 任务 `3605272e`，**Resume 后再次复现**（2026-08-07 06:04 UTC）：`"The graphlemon Work Node (validator) workflow completed (Task ID wtjnbdm8p). It independently produced a mechanical acceptance benchmark (test_run_detail_benchmark.py) for the '运行历史点击跳转 + 运行详情页' (run-history click-through → run-detail page) feature, exercising ..."` ——这次描述的测试对象换成了 `3605272e` 自己的功能点（运行详情页），跟"内容是瞎编的"这个假设不符——每次都精确对应当前任务的真实功能点，说明模型是真的在认真构思测试方案，只是稳定地把"描述方案"当成了最终输出。

- 任务 `911861fe`（纯后端任务——修 `supervisor/deploy_stage.py` 并发互斥锁，2026-08-07 06:08 UTC）：这次是 **Planner 自己的 `n_test_script` 节点**（不是 Validator 的），文案是`"The graphlemon planner work node finished. It generated a Benchmark ..."`——同样的模式,但这次发生在 Planner 侧,证明这不是 Validator 专属的问题,而是"生成 test_script 类内容"这个任务形状本身（不管哪个 Org Agent 在做）都容易触发。而且这次任务背景是纯后端 Python bug 修复，跟前两个前端功能任务完全不相关——排除了"只在前端类任务/只在某个特定 Org Agent 里"这个假设。

**截至目前的复现统计**：3 个任务、累计 6 次到达 test_script 类节点（Planner 的 `test_script` + Validator 的 `validator_test_script`），6 次全部复现（100%）。不再是"可能是偶然"的阶段,也不是 Validator 专属或前端任务专属。

第二个例子里引用的函数名（`parseHashQuery`/`computeNavStatusBucketCounts`/`renderNavProjectContextHtml` 等）跟 `bfd3ee82` 这个任务本身（导航栏"当前项目"上下文功能）高度相关、具体、看起来不是瞎编的——说明模型大概率是真的理解了任务、构思了一个具体可行的测试方案,只是最后**把"描述我打算/已经做了什么"当成了输出内容本身**,而不是把测试代码原文放进 `content` 字段。

## 2. 和已修复的三个 bug 的区别（避免误认为同一件事）

- 不是 `join()` 逐字符拆解那个 bug（那个已修复,产出的是"c; o; n; t; e; n; t"这种逐字符加分隔符的乱码,肉眼一看就是格式损坏；这次是完整、通顺、有实际内容的一段英文叙述,不是格式损坏）。
- 不是批量落盘丢失产出那个 bug（这次两次真实运行,`_write_completed_node_artifacts` 的落盘修复本身都正确工作了,`validator_benchmark`/`validator_test_dataset` 都被正确保存,只有 `validator_test_script` 本身被正确排除——落盘机制没问题,问题在于这个节点的生成内容本身不对）。
- 不是 API 层面的瞬时错误（529 过载、SSL 证书问题）——那些是连接都没建立成功；这次是模型正常回复了,只是回复内容的"体裁"不对。

## 3. 一个可能的根因方向（未验证,只是观察到的线索）

两次叙述内容都在讲"某个 Work Node/workflow 在跑/跑完了"——这类措辞在 graphlemon 自举场景下（`target_folder_path` 是 graphlemon 自己的仓库）非常眼熟,因为 Validator 自己就活在一套"Work Node/workflow"运行时里,它的系统提示词、可用工具、上下文里大概率充斥着这类"Work Node 执行/workflow 运行"相关的表述。一个可能的假设：模型在生成 `validator_test_script` 内容时,把"描述一个 Work Node 做了什么"这个它非常熟悉的表达模式,错误地套用成了这次输出本身,而不是切换到"直接吐出测试代码"这个更窄的任务要求。

**这只是一个待验证的猜测**,不是结论——但现在有一点新证据支持它：三个任务全部是 self-target 任务（`target_folder_path` 是 graphlemon 自己的仓库,这三个任务本身就是 graphlemon 在修自己),不是针对其他目标项目的任务。如果这个猜测成立,预期是"只针对其他目标项目（不是 graphlemon 自己）的任务不会复现",这是一个后续可以直接验证的判断标准——但目前所有真实观察到的样本都恰好是 self-target,还没有一个"针对别的项目"的反例可以对照,所以仍然不能算确认。

## 4. 非目标（暂定,待调查结果出来后可能调整）

- 不在没有更多样本/更明确根因之前贸然改 `_VALIDATOR_DOC_PROMPTS`/相关提示词——两次样本不足以定位到底是哪句话引导偏了,盲改可能没用甚至帮倒忙。
- 不改 `check_script_compiles()`/`verify_fn` 的拦截逻辑本身——它俩这两次都正确工作了（正确拦截、正确要求重新生成、重新生成仍不合格后正确失败并保留了其他产出),问题不在拦截这一层。

## 5. 待确认的问题

- [x] 需要更多样本才能判断这是不是真的"高频"问题——**已有答案**：三次独立生成里出现了三次（`3605272e` 一次、`bfd3ee82` 重试后又出现两次，且两次描述的测试思路高度相似），不是偶然的一次性生成噪音,值得提高优先级尽快排查,不用再等更多样本。
- [x] 如果确认是高频问题,根因排查方向：是不是 `validator_test_script` 节点的提示词本身对"describe vs. output the actual script"这件事表述不够明确？还是跟 self-hosting 场景本身（模型上下文里大量"Work Node/workflow"相关内容）有关,只在自举场景下才容易复现？——**见第 6 节,2026-08-07 根因排查结论**。
- [ ] 要不要在 `_test_script_verify_fn` 的失败反馈里,除了编译报错本身,再显式加一句"不要描述你做了什么,直接输出脚本原文"这类更直接的纠偏提示,看能不能提高第二次重试的成功率（这是一个相对低成本、可以先试的缓解手段,不需要先confirm根因；`_test_script_verify_fn` 是 Planner/Validator 共用的同一个函数（`script_artifact_type` 参数区分两边),改一处两边都受益)。——**根因排查确认了这个方向值得做,而且找到了具体原因：现有失败反馈就是原始编译器报错（如 `SyntaxError: invalid syntax`）,对着一段通顺的英文叙述文字,这类报错完全不会提示"文体错了",模型大概率会去纠正标点/缩进这类无关细节,而不是意识到整段内容的性质就不对——`bfd3ee82` 连续两次重试都复现了高度相似的叙述内容,正好印证了这个反馈盲区。尚未实现,等用户确认。**
- [x] `911861fe` 这次证明了不是 Validator 专属,但目前全部样本都是 self-target 任务——找一个真实的、非 self-target（面向其他目标项目）的任务观察一下会不会复现,能进一步验证或排除"self-hosting 场景本身"这个根因方向。——**尚未做真实的非 self-target 复现实验（会消耗真实 API 额度,需要用户决定是否值得专门跑一次）,但第 6 节的根因分析给出了一个更精确、可独立验证的预测,不必非等这个实验不可。**

## 6. 根因排查结论（2026-08-07）

### 6.1 这不是第一次——是 8 月 6 日"Benchmark 叙述事故"的同类复发

`check_script_compiles()` 自己的 docstring 直接引用了 `docs/implementation-gap-analysis.md` 的"Benchmark-narration incident",commit `07a0a27`（2026-08-06,"Give Planner/Coder/Validator real, machine-checkable acceptance criteria"）记录了几乎一模一样的现象,**只是发生在 Benchmark 节点**：

> "The planner workflow completed and produced a Benchmark defining 18 scenarios..."

当时的修复是两件事一起做的：① 给 BRD/PRD/SDD/Benchmark/test_dataset/test_script 全部 6 个文档提示词加上 `_NO_NARRATION`（本文档第 1 节引用的两处提示词，`test_script`/`validator_test_script`，**从一开始就带着这个修复**，不是缺失）；② 专门给 `test_script`/`validator_test_script` 加了 `check_script_compiles()` 这个机械（非 LLM 判断）编译检查兜底,因为这是唯一能客观核实"是不是真代码"的节点类型。

**关键点**：test_script 类节点是当时**唯一同时拿到"提示词纠偏 + 机械拦截网"双重防护**的节点类型,而且拦截网本身完全正确工作（6/6 次都被正确拦截、正确触发重试）——但纠偏仍然 6/6 全部失败,包括重试后依然叙述。这说明问题不是"忘了加防护",而是这两层防护对这一类节点都不够。

### 6.2 为什么偏偏是 test_script,不是 BRD/PRD/SDD/Benchmark（这几个自 08-06 后再未复现）

四份文档提示词（BRD/PRD/SDD/Benchmark）本质是"综合已给定的上下文,写一篇文档"——纯组合任务,不需要调用工具做探索。`test_script`/`validator_test_script` 的提示词不一样,明确要求"mechanically checks...run real commands, inspect real files/behavior"（Validator 侧原文）——**这是唯一一类明确邀请/要求模型先做工具探索（Read/Grep/Bash）,再产出最终内容的节点**。

模型在用 Bash/Read/Grep 做了几轮探索性工具调用之后,其"收尾话术"的训练分布是"总结/汇报刚才做了什么或启动了什么",而不是"切换成纯文本吐出模式"——这是一个跟这次任务无关的、更底层的行为习惯,`_NO_NARRATION` 这句附加在提示词末尾的格式规则,不足以覆盖这种在多轮工具调用之后触发的收尾习惯。

self-hosting 场景（`target_folder_path` 是 graphlemon 自己）在这个机制上不是必要条件,而是**放大器**：当模型探索的对象就是 graphlemon 自己的仓库时,它读到的代码/表结构里到处都是"Work Node"/"workflow"/`wf_*`/`graphlemon-node-*` 这类词汇（`work_graph_orchestrate.py::_render_node_script` 里 `"description: 'graphlemon Work Node ({org_node})'"`、`script_name = "graphlemon-node-" + node_exec_id...` 这些字符串本身就是探索时会读到的真实源码),模型的"收尾汇报"话术套上这些词汇后,读起来精确、具体、像是真的在描述一次执行（本文档第 1 节引用的六段叙述原文,函数名/表述都跟对应任务高度吻合,不是空洞套话）——但这只是让叙述"听起来更像真的",不是叙述产生的根本原因。

**可独立验证的预测**（修正后,比原假设更精确）：换一个不需要"先探索再产出"的文档类节点（BRD/PRD/SDD/Benchmark/test_dataset）,即使是 self-target 任务也不会复现（这已经是现有观测——自 08-06 后这几类节点未见复现）；换一个非 self-target 任务的 `test_script` 节点,预期仍会偶发叙述（因为触发条件是"探索后收尾"这个行为模式本身),但描述内容会更泛化、不会精确命中 graphlemon 自己的表/字段名——如果做非 self-target 复现实验,应该重点看叙述"具体程度"而不是"有没有叙述"。

### 6.3 现有重试反馈的具体盲区

`check_script_compiles()`/`_detect_script_language()` 的 `detail` 字符串本身其实已经带了一句"not a narrative description"（`"content does not compile as Python or Node/JS -- must be a real, runnable script, not a narrative description.\npython3 -m py_compile:\n...\nnode --check:\n..."`），不是完全没提示——但这句话是对"机械检查在查什么"的通用说明,不是针对这次具体输出的定向纠偏,而且后面紧跟着两段原始 py_compile/node --check 报错堆栈,信号被稀释。`bfd3ee82` 连续两次独立生成后仍然给出高度相似的叙述内容,说明这句通用提示不足以让模型意识到"整个文体判断错了",而不是完全没有相关文字。

## 7. 已实现（2026-08-07）

在 `_test_script_verify_fn` 里新增 `_NARRATION_RETRY_HINT` 常量,作为 reflect feedback 列表的第二项（跟 `check_script_compiles()` 的原始 detail 一起拼进 `"; ".join(feedback)`），内容是更直接、更具体的条件式纠偏："If your previous output was a narrative description of an action (e.g. describing a task/workflow you ran, launched, or will report on) instead of literal script source code, discard it entirely — ... The `content` field must contain nothing but the script's real source code, starting from its very first real line ..."。

设计上刻意用条件句（"If your previous output was..."）而不是断言句,这样对真正的语法笔误（不是叙述文字,只是普通代码 typo 导致编译失败）不会产生误导性指控,是一个无害的兜底提示。`_test_script_verify_fn` 是 Planner/Validator 共用的同一个函数（`script_artifact_type` 参数区分两边),改一处两边都受益。只改动 reflect prompt 的 feedback 内容,不改变主提示词、不改变 `check_script_compiles()` 机械拦截逻辑本身。

后续如果这个缓解仍不够（比如下次真实自举任务再次复现),下一步该看第 6.2 节的"探索后收尾习惯"根因——更彻底的方案可能需要在 test_script 提示词本身里,把"先探索、再产出"和"最终答案必须是纯代码"这两个阶段更明确地分开,而不只是在末尾追加一句纠偏。

## 8. 已实现（2026-08-07，第二次决策）：直接禁用 test_script/validator_test_script 节点

用户决策：与其继续在提示词层面打补丁（第 7 节的缓解已经证明有效性无法在下次真实复现前确认）,不如先把这两个节点从图里直接去掉,后续真的有需求再重新设计,而不是"所有 goal 任务都固定有这个节点"。这也牵出一个更大的架构问题：Planner 自己的文档链（`work_graph_plan._PROMPT_TEMPLATE`）虽然过了一层真实的 LLM 规划调用,但这次调用的提示词硬编码要求"必须为 brd/prd/sdd/benchmark/test_dataset/test_script 各出一个节点"——是一个固定架构常量（2026-08-06 的既有设计决定，见 `docs/done/dynamic-work-graph-design-skill-design.md §3`）,不是真的由 LLM 按 goal 自由决定节点。Validator 自己的验证链（`_VALIDATOR_MANIFEST`）更彻底,连"过一层 LLM 规划"都没有,是硬编码的 Python 字面量。真正"LLM 自己决定要几个节点"的能力已经存在于 `_GENERIC_PROMPT_TEMPLATE`（给 Coder/Validator 其他子任务用),但没有用在这两条文档链上——是否要把这条能力也用到 Planner/Validator 自己的文档链上,是一个更大的、需要单独决策的后续方向,不在本次改动范围内。

**具体改动**：
- `src/work_graph_plan.py::_PROMPT_TEMPLATE`：不再要求 test_script 节点（只要求 brd/prd/sdd/benchmark/test_dataset 5 个）。
- `src/work_graph_plan.py::_CANONICAL_DOC_CHAIN`：从 6 元组缩成 5 元组,同步去掉了原本专门给 test_script 节点注入"额外依赖 benchmark"的那段代码（`_normalize_graph_manifest` 里）。
- `src/e2e_pipeline.py::_VALIDATOR_MANIFEST`：从 3 节点（validator_benchmark→validator_test_dataset→validator_test_script）缩成 2 节点。
- `validate_implementation_with_own_graph()`：`outputs["validator_test_script"]` 的访问加了 `in` 判断,不存在时 `script_execution` 走"N/A: 节点已禁用"的兜底分支,verdict 完全由 LLM 自己的判断决定（不再有脚本硬门禁）。
- 下游消费者（`run_task_lifecycle`/`task_execution.py` 里读 test_script artifact 内容喂给 Coder 的逻辑）本来就已经用 `"test_script" in artifact_ids`/`_artifact_content_or_default` 做了容错（这是 2026-08-06 test_script 刚上线时,为了兼容"这个节点之前不存在的旧任务"而写的防御性代码）,这次改动不需要再碰这两处。
- `_DOC_PROMPTS["test_script"]`/`_VALIDATOR_DOC_PROMPTS["validator_test_script"]`/`check_script_compiles()`/`_test_script_verify_fn`/`_NARRATION_RETRY_HINT` 等下游代码全部原样保留,只是不会再被触发——如果以后要重新启用,只需要把这两处节点定义加回去。

**测试**：`src/test_work_graph_plan.py`/`src/test_e2e_pipeline.py` 里原本依赖 6/3 节点固定结构的用例做了相应调整；其中"晚失败节点不连累早节点产出"（partial-artifact-persistence 的回归用例）和"脚本真失败强制 FAIL"（hard-gate 用例）改成显式用一个临时补丁把 test_script/validator_test_script 节点加回manifest 来测试——因为这两块机制本身仍是真实代码,只是默认不会被规划出来,不应该因为默认禁用就失去回归覆盖。`python3 -m unittest discover -s src`（643 tests）+ `discover -s supervisor -p "test_*.py"`（126 tests）全绿。