iterate-operator

Imported from 564239493/operator-common-iterator-claude (.claude/skills/iterate-operator/SKILL.md). Install upstream with npx skills add 564239493/operator-common-iterator-claude --skill iterate-operator. Copyright stays with the author.

算子闭环迭代

参数：$ARGUMENTS

先读 docs/WORKFLOW.md 与 docs/ARTIFACT_CONTRACTS.md，然后严格执行：

阶段迁移硬守卫（强制）：所有阶段状态迁移一律运行 python scripts/flow_control.py advance --run-dir <run-dir>，由代码读取落盘产物、 按内置规则表裁决去向并落盘（TRANSIT=迁移 / HOLD=条件未满原地等待 / NOOP=终态 / NO_ROUTE=需人工，决策证据见 stdout 与 <iter>/transition_decision.json）。 禁止直调 run_state.py set-state 做阶段迁移（其兜底边校验会对非法边 exit 2， --force 仅限人工恢复逃生口）。set-constraint-check 子状态回写与 set-fields 字段回写不受影响。等待态的用户决定只能经 --user-decision approve|stop 转达， 模型不得代替用户决定。

1. 解析参数。算子文档支持绝对路径、项目相对路径和包含 .. 的外部相对路径。 operator-family=auto、test-framework=auto；未传 --prompt 时由 init_run.py 按文档类型选择并装配最新 ACLNN prompt 或隔离的 torch_npu prompt； torch_npu 是内部 family 名 hs 的显式 CLI 别名。 auto 仅对已有 TTK adapter 的六个重点算子选择 ttk；其余 torch_npu API 选择 constraints，只运行约束提取/补充/校验，不误入必然失败的用例生成。 max-iterations=5，constraint-check-rounds=3，case-count=10，mode=real， server-config=servers.json。constraint-check-rounds 是每个新约束版本的语义 check 最大轮数：首轮完整 EXTRACT 后执行，后续仅在 UPDATE_CONSTRAINTS 产生新版本后执行； 与 max-iterations 相互独立，check 通过提前结束。 human-checkpoint-round=3（0=禁用）；迭代到该轮仍以 constraint_extraction 失败时， 在下一轮开始前弹人工补充检查点（AskUserQuestion 四选一）。需 max-iterations > 该值 才有意义。

   --human-constraints-upload 默认关闭；开启时检查点为四选一（人工修复 / 人工补充 / 自动修复 / 立即停止）， 前 human_checkpoint_round 轮仍纯自动迭代，检查点之后每个失败轮都重新弹该四选一 （可逐轮切换）。 未开启human-constraints-upload时检查点退化为三选一（人工修复不可选）。详见下方「挂起、监听与唤醒」节。

   hs-scenario-mode=original；只有用户显式传入 --hs-scenario-mode planned 时，torch_npu + TTK 才启用 TND/BSND/ paged-attention 场景拆分和投影。该参数对 ACLNN/ATK 不生效。 --src 可选，指定算子源码目录（项目内或外部）；未提供时可用 python scripts/locate_operator_source.py --aclnn-name <算子名> 定位后再传。 省略 --src 则跳过源码分析，退回纯文档驱动流程。 --source-analysis-knowledge 默认关闭；显式传入时，仅对 ACLNN 自动提示词装配 启用 source_analysis 类知识，并继续要求 operator_name_eq 精准命中。不得与 --prompt 同用，也不得用于 torch_npu。

2. 调用 python scripts/init_run.py 创建 run（透传 --src、 --supplement-constraints、--source-analysis-knowledge、--operator-family、--test-framework、 --hs-scenario-mode、--constraint-check-rounds 等参数， --batch-dir 是目录批次内部参数不传）。该命令把外部文档只读复制到 run 的 inputs/ 目录， 后续 Agent 必须使用返回的 operator_doc_snapshot。若传入 --src，把算子 源码关键文件浅快照到 inputs/src_snapshot/，写入 run_state.operator_src_snapshot （为空则第 5 步跳过 source-analyst，退回纯文档驱动）。若传入 --supplement-constraints，只读复制到 inputs/supplement_constraints.md， 写入 run_state.supplement_constraints。 --human-constraints-upload 透传给 init_run.py，置 run_state.human_constraints_upload=true （默认缺省 false，现有路由行为不变；详见下方「挂起、监听与唤醒」节）。 --resume-run <run-dir> 不创建新 run，而是从已有 run 目录的 run_state.json 恢复： 纯文件驱动，不依赖聊天历史——读 state + current_iteration + iter 目录产物 判定从何处续跑（见下方「挂起、监听与唤醒」节恢复路径）。 如果提供了 --batch-dir，创建成功后必须立刻调用 python scripts/batch_state.py --batch-dir <batch-dir> attach-run --run-dir <run-dir>， 再进入 EXTRACT；这样会话中断时目录批次可以定位并恢复该 run。

3. full scope 若默认真实模式缺少服务器配置或配置字段不完整，立即停止并把命令返回的 message、server_config 和 errors 提示给用户。不得自动切换到 mock。 只有用户显式传入 --mode mock 才能执行 Mock。constraints-only 不执行远端， 不要求服务器配置。

4. 在主会话展示完整计划、可用 Agents、每阶段输入/输出和终止条件。

5. init_run.py 成功后 state 为 PLAN；主协调器必须继续推进到 EXTRACT，不能仅创建 run 后结束。 委派 constraint-extractor 之前，主协调器必须先运行 python scripts/flow_control.py advance --run-dir <run-dir> （推进器裁决 PLAN→EXTRACT 并落盘；run_state.json 一律经 scripts/run_state.py / scripts/flow_control.py 写入，禁止手动 Edit）。 extract-constraints 在写 constraints.json 前会校验 state 已是 EXTRACT，未推进会被拦截并 空跑一轮。该完整提取只发生在初始化首轮；执行反馈轮推进为 UPDATE_CONSTRAINTS，复用并 最小修改上一轮约束，不再委派 constraint-extractor。

SCENE_SCAN 子步骤（EXTRACT 前，仅首轮；--scene off 跳过）：委派 scene-scanner。委派消息必须显式传入当前 run 的绝对路径 <run-dir>、只读输入 <run-dir>/inputs/<doc>.md 和唯一写入目标 <run-dir>/inputs/scene_scan.json；禁止只传 inputs/scene_scan.json 让子 Agent 按仓库 cwd 解析。scene-scanner 读取 prompts/scan_scenes.md，按设备类型 → 量化模板 → 特性参数三级提取，并自跑 python scripts/validate_artifacts.py scene_scan <run-dir>/inputs/scene_scan.json）。 完成后主协调器读 scene_scan.json：

• has_scenarios=false → 跳过（无 directive，按全场景提取，行为不变）。scan_notes 含 quant_signal_no_template warning 时仅记录性提示用户"文档含量化参数信号但未提取到 模板，可能遗漏剪枝"，不置 has_scenarios、不阻断、不补造场景。
• has_scenarios=true 且 --scene all → 跑 python scripts/render_scene_directive.py --scan <run-dir>/inputs/scene_scan.json --run-dir <run-dir> --scope all （scope=all：全部设备全部模板全部特性参数取值分支全展开，不剪枝、不弹窗）。
• has_scenarios=true 且 --scene auto（默认）→ 主会话按 Q1 → Q2 → Q3 三轮顺序 征询，每轮一次 AskUserQuestion 调用、其内问题并行作答（每问选项≤4，超出部分在 question body 编号列全；支持 Other 自定义输入，Other 输入须落在已识别列表内，否则 提示重新输入符合的）。必须分三轮而非一次调用：AskUserQuestion 同次调用内所有 问题并行作答，后问拿不到前问答案；Q2 的问题集（逐设备）依赖 Q1 选中的设备、Q3 的 问题集（逐 (设备,模板) 对）依赖 Q2 选中的模板，且预枚举全部 (设备,模板) 组合会组合 爆炸并超每调用≤4 问上限，故只能逐级等上轮答案回来再发起下轮。
  • Q1 设备类型（1 个 multiSelect 问题）：选项 = scene_scan.device_types 全部（≤4 个直接列全；>4 个列前 3 + Other 自定义，question body 按编号列出全部 device_types，用户可按编号 Other 输入选中列表外的设备）。不设"全部设备"聚合项 ——要全选就逐个勾选（multiSelect）。device_types 为文档"产品支持情况"具体设备名， 无"通用"通配符。若 device_types 仅 1 个设备 → 直接默认选中该设备、跳过 Q1 征询，直接进 Q2（无选择意义时不打扰用户）。question 正文首行须含 Other 提示语： 『Other（自定义）= 按下方编号表输入列表外的设备类型名』（无"通用"通配符，须给真实设备名）。
  • Q2 逐设备量化模板（对 Q1 选中的每个设备各 1 个 multiSelect 问题，批量 ≤4 问/ 次，超出分多次调用）：选项 = 该设备 devices[].templates 全部（≤4 直接列全；>4 前 3 + Other，body 编号列全）。不设"全部模板"聚合项——要全选就逐个勾选。各设备 模板可不同（v3 无"通用"组，无标注内容已合并到各具体设备组下）。模板名编码量化方式 （如 非量化/全量化-A8W8/全量化-GQA）。某设备仅 1 个模板 → 自动选中该模板、 跳过该设备 Q2（与 Q1 单设备跳过同原则）。等 Q1 答案回来确定选中设备后再发起本轮。 question 正文首行须含 Other 提示语：『Other（自定义）= 按下方编号表输入列表外的 量化模板名』。
  • Q3 逐（设备,模板）特性参数（对 Q2 选中的每个 (device,template) 各 1 个 single-select 问题，批量 ≤4 问/次，超出分多次调用）。每问固定 2 个预设选项 + Other 自定义输入（AskUserQuestion 工具契约 ≥2 选项且自动提供 Other，无法零选项）：
    • 选项 1「保持自动 / 继承文档约束（未填写）」→ 该模板 null（全展开不剪枝）
    • 选项 2「全部固定默认值（最小覆盖）」→ 该模板 "fix_all_default"（每参数取 values[0]）
    • Other（可自定义输入参数特性配置） → 接受任意格式输入，不限于 JSON 对象。合法示例： 值级 JSON {"groupType":[-1,0],"splitItem":[0,1,2,3]}；param=value 串 groupType=-1,0; splitItem=0~3；自然语言「groupType 取 -1 和 0，splitItem 取 0/1/2/3」。 question 文本必须包含：(a) Other 提示语「Other（可自定义输入参数特性配置）= 贴入任意 格式的参数取值配置，主协调器会识别并组装成取值清单；选保持自动（未填写）→ 保持自动/ 继承文档约束」；(b) 该 (device,template) 完整 feature_params 编号表（从 scene_scan.json 读出，每参数列出 name / 取值 values / description / constraint， 由主协调器现场渲染，不新造脚本）；(c) 多格式示例 + 说明「未列参数=继承文档约束（全展开）； 单值如 [-1]=固定该值；多值如 [-1,0]=展开该子集」。 答案→selection：选项1→null；选项2→"fix_all_default"；Other→主协调器按 scene_scan feature_params 表把任意格式输入识别+组装为标准 {param:[values]} dict（参数名与取值 须落在 scan 的 values 内、类型感知；识别不了的参数或取值当场提示用户澄清，不静默丢弃）。 组装后的 dict 写入 selection.json，由 render_scene_directive.py 做最终严格校验（非法 exit 2 阻断、提示重输）。等 Q2 答案 回来确定选中 (device,template) 对后再发起本轮。
  • 汇总答案写入 selection.json（值级形态） {"device_types": [<...>], "selection": {<device>: {<template>: <tpl_value>}}} 其中 <tpl_value> ∈ null（选项1/未填写，按文档和已选场景自动适配）| "fix_all_default"（选项2）| {<param>: [<values>]}（Other 任意格式，主协调器组装为该 dict：单值→fix、多值→expand 子集、未列参数→按文档和已选场景自动适配）； 缺模板键 = 该模板未选（Q2 未选）。
  • 特性参数冲突识别（Q3 组装后、渲染 directive 前）：selection.json 落盘后先跑 python scripts/check_scene_conflicts.py --scan <run-dir>/inputs/scene_scan.json --selection <run-dir>/inputs/selection.json --run-dir <run-dir> （确定性、advisory、exit 0；判据 = scene_scan.params[].value_conflicts 结构化规则， 见 prompts/scan_scenes.md §4/§5；仅当冲突涉及的两个参数都被用户显式选择时才判， 任一方为自动/继承文档则跳过——下游 extractor 会自适应兼容值；产物 <run-dir>/inputs/scene_conflicts.json + stdout {ok,n_conflicts,conflicts,warnings}）。 读 stdout n_conflicts： n_conflicts > 0 → AskUserQuestion（单问，2 预设 + Other），question 正文逐条列出冲突 （device/template/参数→target/kind：forbidden 禁止取值|required 必须取值/当前取值/原因）：
    • 选项1「返回修改特性参数」→ 对受影响 (device,template) 重发 Q3、更新 selection.json、重跑 check，直至 n_conflicts==0；
    • 选项2「已知冲突强制继续」→ 进 render_scene_directive.py（directive 标注 known_conflicts 交下游 EXTRACT/GENERATE 处理，不阻断流程）；
    • Other→用户贴修改说明，主协调器据此改 selection.json 后重跑 check。 n_conflicts == 0 → 直接进 render_scene_directive.py。冲突不阻断（allow-continue）； 仅 selection 值合法性非法（check 返回 exit 2 INVALID_SELECTION/EMPTY_SCENE）才阻断、提示重输。
  • 跑 python scripts/render_scene_directive.py --scan <run-dir>/inputs/scene_scan.json --selection <run-dir>/inputs/selection.json --run-dir <run-dir> --scope subset （校验设备/模板/param 名/值 ∈ scan、解析用户明确选择参数的 param_modes、写 inputs/scene_directive.md（含机读块 <!-- scene: {device_types, selection, param_modes, selection_policy} -->，其中 selection 保留逐设备选中的模板，使“保持自动”且 param_modes 为空时仍能机器判定场景， param_modes[device][param] ∈ {"expand": [用户明确选择的取值子集]} | {"fix": X}；缺键按文档和已选场景自动适配，已选场景禁止的 Optional 参数显式 生成 param is None）、 回写 run_state.scene；非法选择 exit 2 阻断，提示用户重选，不静默回退）。 EXTRACT 时 constraint-extractor 读 directive 的 device_types 收窄 product_support （设备类型为具体设备名，直接与文档 √ 行取交集，无"通用"展开）；按 param_modes 产 allowed_range_value（expand 用机读块取值清单、fix 单值、缺键按文档和已选 场景适配）。已选场景禁止的 Optional 参数必须产出 param is None。该 product_support 随后驱动 generate_cases.py 逐平台 生成——设备选择经约束提取驱动生成，不直接改生成逻辑。 EXTRACT 调度消息须把 inputs/scene_directive.md（若存在）路径一并传入 constraint-extractor；执行反馈轮不重写 prompt 或 directive，constraint-updater 继续读取 同一场景指令，保持跨轮稳定。

6. 初始化首轮按顺序委派：
   • EXTRACT（fork-join，仅初始化首轮）：当 run_state.operator_src_snapshot 非空时， 并行委派 constraint-extractor（产 constraints.json + extraction_provenance.json——必载知识清单逐条 Skill 加载的 applied/ not_applicable 记录，首轮 CHECK 用它审计"命中未应用"）与 source-analyst （extract 域：产 <iter>/source_raw.json + inputs/supplementary-doc.md + inputs/uncertain-doc.md + inputs/conflict-doc.md + inputs/conflict_candidates.json）；两者只读文档快照、互不写对方产物，可并行。 barrier（两者都完成）后进补充。operator_src_snapshot 为空时只委派 constraint-extractor，退回纯文档驱动。
   • CLASSIFY（EXTRACT barrier 后）：主协调器跑 python scripts/classify_operator.py --doc <run>/inputs/<doc>.md，读 stdout JSON（operator_category + evidence），运行 python scripts/run_state.py set-fields --run-dir <run-dir> --set execution_strategy=<fusion|default> --set operator_category=<operator_category> --set operator_category_evidence=<evidence JSON> 回写 execution_strategy（fusion_comm_compute → fusion，否则 default）、 operator_category、operator_category_evidence。分类不进 constraints.json、 不依赖 constraint-extractor 自由文本。此步仅在初始化 EXTRACT 后执行一次，后续约束更新 沿用已确定的分类与执行策略。
   • SUPPLEMENT：当 supplementary-doc.md 或 supplement_constraints.md 任一非空时，先运行 python scripts/update_supplement_state.py <run>/run_state.json --supplementary <inputs>/supplementary-doc.md --human <inputs>/supplement_constraints.md --iteration <N> 刷新 revision/hash（旧 run 自动补字段），再委派 constraint-supplementer（读两者 + constraints.json，产 constraints_patch.json），先运行 python scripts/validate_artifacts.py constraints_patch <iter>/constraints_patch.json； 若该 patch 对应当前/上一轮 diagnosis 的结构化 findings，再运行 python scripts/validate_supplement_effect.py <analysis.json> <iter>/constraints.json <iter>/constraints_patch.json 确认 findings 全覆盖且 patch 非全量 noop。通过后运行 python scripts/apply_supplement_constraints.py <iter>/constraints.json <iter>/constraints_patch.json （内部做规范化等价去重，add/replace 无实际变化时返回 noop，再重跑 normalize + validate；失败则阻断，不得进 case-generator）。空 patch/noop 合法，但不得作为 本轮“补充已扩充”或问题已修复的证据。合并和检查成功后再次运行上述状态脚本并加 --consume，使 last_consumed_supplement_hash 与当前 hash 对齐。两者都 空则跳过本步。该 SUPPLEMENT 属于初始化提取装配；执行反馈轮由 constraint-updater 直接消费 analysis findings，不再重跑 source-analyst extract 域或 supplementer。
   • conflict 异步提示：若 inputs/conflict-doc.md 非空，主协调器输出结构化 requires_user_action 提示（code=CONFLICT_REQUIRES_REVIEW，列出冲突条目）， 不阻塞；记录提示后继续进入本轮 CONSTRAINT CHECK/REPAIR，检查通过后 full scope 才进 case-generator，constraints-only 才按后文终止。用户在任意时刻回 inputs/conflict_resolution.json（[{conflict_id, winner: "source"|"doc"}]）， 下一次约束更新前运行 python scripts/apply_conflict_resolution.py <iter>/constraints.json --candidates <inputs>/conflict_candidates.json --resolution <inputs>/conflict_resolution.json 把 source-wins 并入（replace patch + revalidate）。
   • CONSTRAINT CHECK/REPAIR（每个新约束版本的内部子循环，强制）：初始化首轮在 SUPPLEMENT 和已有 conflict resolution 合并完成、最终 constraints.json 已通过 normalize/validate 后执行；执行反馈轮在 constraint-updater 完成版本化最小更新后执行。 它不是顶层状态，且不会触发完整重提取。 每轮只维护 <iter>/constraint_check.json：
     1. 旧 run 若缺少 run_state.constraint_check，先按 max_rounds=3 补齐。若 run_state.constraint_check.iteration != current_iteration，运行 python scripts/run_state.py set-constraint-check --run-dir <run-dir> --reset 初始化该子状态为 {iteration: current_iteration, current_round: 0, status: pending, report: <iter>/constraint_check.json}，保留配置的 max_rounds。同 iteration 恢复时 不重置；若 report 已校验通过且状态为 passed，直接越过，防中断后重复检查。 每次子状态回写同时更新 run_state.updated_at。
     2. 将 check 轮次设为 current_round + 1，委派一个全新上下文的 constraint-checker。消息必须给绝对路径：run_state、算子文档快照、本轮最终 constraints、report，以及存在的 scene directive、supplementary-doc、 supplement_constraints、conflict_candidates、conflict_resolution。首轮 check 还必须给 <iter>/extraction_provenance.json 与 inputs/prompt_preanalysis.json 路径（checker 据此做必载知识审计：命中未应用 = open issue）。 checker 只写 report、不改约束； 每轮完整扫描并复核旧 open/unfixed，只有 checker 可标 fixed。
     3. 运行 python scripts/validate_artifacts.py constraint_check <iter>/constraint_check.json。 通过后运行 python scripts/run_state.py set-constraint-check --run-dir <run-dir> --current-round <N> --status <status> 把 report 的 current_round/status 回写子状态。报告 passed → 结束子循环，随后运行 python scripts/flow_control.py advance --run-dir <run-dir> 推进到 GENERATE （constraints-only 范围由推进器按 run_scope 自动改道 SUCCESS，见下）； failed（或 needs_repair 且轮次用尽）→ 运行 python scripts/flow_control.py advance --run-dir <run-dir> （推进器将裁决至 BLOCKED，history 附 code=CONSTRAINT_CHECK_FAILED）， 列出未修复问题并终止， 禁止进入 constraints-only SUCCESS 或 GENERATE。
     4. 报告 needs_repair → 委派一个与 checker 隔离的新上下文 constraint-repairer，输入同一证据集 + constraints + report。repairer 只能 Edit report 中 open/unfixed 对应约束，不得完整重提、不改 report 状态；修改后必须跑 validate_operator_rule → normalize → validate_artifacts constraints。成功后运行 python scripts/run_state.py set-constraint-check --run-dir <run-dir> --status recheck_pending， 回到第 2 步由新的 checker 上下文做下一轮完整复检。
     5. max_rounds=3 的语义是 check1 → repair → check2 → repair → check3；最后一次 repair 后必有 check，不接受未复检约束。任何下游阶段开始前都必须确认当前 iteration 的 report 有效且 status=passed。若 passed 后又因迟到的 conflict resolution 或人工操作修改了 constraints，旧 passed 立即失效；运行 python scripts/run_state.py set-constraint-check --run-dir <run-dir> --current-round 0 --status pending， 并针对新版本重新执行完整 check 预算。
   • DASHBOARD 拉起（首轮 CHECK 通过后、进 GENERATE/终止前）：首轮 CONSTRAINT CHECK/REPAIR passed 后，运行 python scripts/raise_dashboard.py --run-dir <run-dir> --iter iter_001（探测 8899 未监听则 后台拉起 dashboard_server.py；run_state.dashboard_raised=false 时打开浏览器一次并置 true， 已拉起则仅返回 URL）。把返回的 URL 提示给用户「可在该网页监控本轮约束/执行/诊断；人工修复时 亦在此编辑提交」。页面 5 秒轮询会自动跟随 EXECUTE/DIAGNOSE 到终态，无需手动刷新。仅首轮拉起一次； 后续轮次 dashboard_raised=true，人工修复检查点再调该脚本时仅返回 URL。
   • constraints-only 终止：若 run_state.test_framework="constraints"，在 EXTRACT 和可能的 SUPPLEMENT、CONSTRAINT CHECK/REPAIR 完成后运行 constraints normalize/validate；只有当前 iteration 的 constraint_check.json.status=passed 才运行 python scripts/flow_control.py advance --run-dir <run-dir>（推进器按 run_scope 自动裁决至 SUCCESS 并附 event=CONSTRAINTS_ONLY_SUCCESS），并明确 报告成功范围仅为约束提取。跳过 case-generator、executor、Golden 和执行质量门禁。
   • case-generator：读取 run_state.hs_scenario_mode，调用 generate_cases.py 时原样透传 --hs-scenario-mode；旧 run 缺少该字段时使用 original，不得自行改成 planned。
   • 生成的等待由主协调器负责，不由 case-generator 子 Agent 负责（关键）：case-generator 是子 Agent，寿命只有 ~1-2 分钟，只能用前台 Bash 跑 scripts/generation_progress.py launch （~1 秒、exit 0）后报告生成子进程 pid/<iter> 路径/cases 路径/count/platforms 后结束本轮 （不等待、不"等通知"、不 read-poll；详见 case-generator 与 generate-cases skill）。该 launcher 用 CREATE_BREAKAWAY_FROM_JOB|CREATE_NEW_PROCESS_GROUP（Windows）/ start_new_session=True（POSIX） 把 generate_cases.py 拉成脱离会话 job/session 的子进程后自身立即退出——从此无长寿命 bg 任务 可被会话生命周期（中断/重启/上下文压缩，无 60 分钟上限）杀死；唯一长寿命进程是脱离的 generate_cases.py，scripts/probe_breakaway.py 已证其在 launcher 退出后存活到完成。 当 case-generator 报告"生成在脱离会话的进程里跑（pid=…）"时，主协调器接管等待：
     1. 优先启动一个 Monitor，其 command 必须是无 shell 包装的单条绝对路径命令： <venv-python-absolute> <repo-absolute>/scripts/generation_progress.py watch --output-dir <iter-absolute> --interval 60。 watch 立即采样、每约 60 秒输出一行 JSON，并在 complete/failed 时自动退出；Monitor 中断不影响已经脱离会话的生成子进程。不能使用 Monitor 时，才每 ~60 秒前台运行一次同样 使用绝对路径的 generation_progress.py status --output-dir <iter-absolute>。 Monitor command 禁止包含变量赋值/展开、cd、管道、命令替换、shell while/case/sleep/grep/head/ps；这些结构会触发非业务安全审批询问。
     2. 每次 watch/status 采样返回后必须向用户报告 per_platform 各平台 done/total/elapsed/ pid_alive（done 递增、pid_alive=true 即活跃）——输出这四项是强制，不得用"平台名 看起来不对"之类的旁支判断替换进度数字。这样用户每 ~60 秒看到一次进度，而不是长时间空白。 2a. 轮询回合排他（强制，防进度丢失）：state=running 期间，主协调器每回合的唯一动作 是——跑一次 status → 报告进度 → 决定下一回合。禁止在轮询回合发起探查性 Read/Grep/源码或平台选择调查/记忆回溯/长思考；任何旁支疑虑推迟到 state=complete/failed 之后，或先发完本次进度、下一回合再处理，绝不可用调查取代一次轮询。进度展示一旦从某回合起 长时间空白，根因几乎都是"本该轮询的回合被旁支调查/长考占用"——这是"有时有进度、有时没进度" 的唯一可控根因，必须在本层杜绝。轮询节奏由本回合主动发起 status 保证，不依赖模型"想起来才轮询"。
     3. state=running 期间即使 per_platform 暂时空或残缺也是平台间过渡的正常现象 （某平台一完成其 JSONL 即被 convert 删掉转成 cases_<plat>.json、从进度里"消失"）， 绝不据此停掉生成进程。per_platform 语义（关键，防误判调查）：running 期间 per_platform 列出的是当前正在被生成的目标平台（generate_platform_outputs 按 product_support 顺序逐平台 生成全部平台，每个产 cases_<plat>.json），不是执行/canonical 平台；canonical/CSV 平台是在 生成全部完成后由 _select_ttk_platform 按 servers.json 服务器顺序及各 platforms 顺序选定的， 与 running 期间 per_platform 出现哪个平台无关。故 per_platform 里出现 servers.json 未覆盖的 平台（如 A3 训练/推理）属正常、不是选错平台，禁止据此调查 generate_cases.py 平台选择逻辑 或 kill 重启——平台是否选对只在 state=complete 后、generation_summary.json.selected_platform 不符 servers.json 时才处理（EXECUTE 前的事）。
     4. state=complete（generation_summary.json 已产出）后跑 python scripts/validate_artifacts.py cases <cases 路径>，通过后运行 python scripts/flow_control.py advance --run-dir <run-dir> 进入 EXECUTE； state=failed 读 status JSON 的 error 字段（已有界摘录）报告 generator_bug，不自行解析日志。
     5. 绝不在已有 cases_<plat>.json 时重跑 generate_cases.py（generate_platform_outputs:192 先 target.unlink 删 cases_<plat>.json 再生成，重跑=丢弃已完成平台数小时成果）； 脱离进程被异常中止（部分平台有 cases、部分没有、缺 generation_summary.json）时 报告现状让用户定夺，不自行重跑。 （无论长短，case-generator 都只脱离启动+交棒，不前台跑长任务、不等待；主协调器统一 status 轮询 + validate_artifacts.py cases 校验。）
   • case-executor：
     • default（run_state.execution_strategy != "fusion"）：real 模式内部完成 generate→自检→real-run 两子步骤；CPU golden 已在生成时直接 mock（形状感知 zeros，不经文档推导），无推导环节；validate_artifacts.py executor 须通过， 否则不得进 real-run。
     • fusion（run_state.execution_strategy == "fusion"）：先读 run_state.json 取 execution_strategy 确认策略；generate 与自检子步骤不变（fusion 走 _SPECIAL_TEMPLATES 专属 .tpl，已是真实实现而非 mock）；real-run 替换为 4 步流程（CPU 标杆→NPU 级联标杆→改名→精度对比），拼 execute_cases.py --mode real --strategy fusion --num <case_count> 透传策略与用例数。精度对比结果记录性、不入成败；路径门禁失败写 engine_error 终止流程。
   • 执行完成后运行 python scripts/flow_control.py advance --run-dir <run-dir> （裁决 EXECUTE → GATE），随后再委派 quality-reviewer；gate 产出后由第 7 步的 advance 决定去向。
   • quality-reviewer
7. 若基础产物可读、至少生成一条用例且执行器已完成运行，运行 python scripts/flow_control.py advance --run-dir <run-dir>（推进器按 quality_gate.json 的 blocking 与 execution_result.failed 裁决至 SUCCESS / DIAGNOSE / BLOCKED）， 按其决策结束或继续。Golden 覆盖率和准确度 warning 当前不作为门禁。HS+TTK 所选执行平台 semantically_clean_count=0，或 planned 模式缺失计划内必需场景时，生成器必须 以 HS_SEMANTIC_GATE_FAILED 停在 GENERATE，不得进入 EXECUTE；其他部分语义 warning 仍按非阻断处理。
8. 若有用例失败：当 operator_src_snapshot 非空时，先委派 source-analyst diagnose 域（读 execution_result + 其 plog manifest/ERROR 摘要/必要原始 PLOG + uncertain-doc + source_raw，error_string 匹配后逐条确认，只有确认成功的 uncertain 追加到 inputs/supplementary-doc.md，产 <iter>/source_evidence.json），再委派 failure-analyst（读 source_evidence 与同一 PLOG 证据下根因）。operator_src_snapshot 为空时直接委派 failure-analyst，但真实 TTK 执行仍必须传入 execution_result.plog 指向的全部诊断产物。 failure-analyst 完成后先运行 python scripts/validate_artifacts.py analysis <iter>/analysis.json；失败时阻断路由并让 Agent 修正。schema 2.1 的 constraint_findings 是执行反馈轮唯一问题清单，直接交给 constraint-updater；不再生成或合并 supplement_additions.md。 主协调器禁止只看顶层 root_cause，必须按已校验的 overall_action 路由：
   • UPDATE_CONSTRAINTS：所有失败簇均为 constraint_extraction 且 findings 覆盖完整。 （human-checkpoint 检查点） 若 human_checkpoint_round > 0 且 current_iteration >= human_checkpoint_round 且 current_iteration < max_iterations 且 current_iteration > human_checkpoint_resolved_iteration（本轮尚未弹过），在进入下方 自动更新前先弹 AskUserQuestion 检查点（四选一，固定顺序）， 并把human_checkpoint_resolved_iteration 置为 current_iteration（防上下文压缩后对同一轮 重复询问）：
     1. 人工修复（仅 human_constraints_upload == true 时可选；false 时该选项标注"需带 --human-constraints-upload 启用"）：先运行 python scripts/raise_dashboard.py --run-dir <run-dir> --iter iter_<N>（页面已拉起则仅返回 URL、 未拉起则拉起浏览器一次），把返回的 URL 提示给用户「请到该网页编辑约束并提交，网页提交会自动生成 <run>/iter_<N>/constraints_copy.json」；随后挂起 AWAITING_HUMAN_CONSTRAINTS + 挂监听器， 监听器仍检测 iter_<N>/constraints_copy.json 出现+稳定后唤醒（文件来源由手动上传改为网页提交， 监听机制不变），走「挂起、监听与唤醒」节。
     2. 人工补充（原检查点选项）：用户补充事实/证据，append 到 inputs/supplement_constraints.md，重新运行 failure-analyst 形成可校验 findings 后再进 下方自动更新。
     3. 自动修复（自主迭代）：走下方版本化自动更新。
     4. 立即停止：STOPPED_BY_USER。 检查点之后每个 >= human_checkpoint_round 的失败轮都重新弹该四选一（resolved 仅防同一轮重复，不阻断后续新轮再问）， 用户可逐轮在四种方式间切换。 human_constraints_upload == false时检查点退化为"人工修复不可选"，其余三项不变（向后兼容）。 以下自动更新分支在「未触发检查点」或「检查点选择人工补充/自动修复」时执行：
     5. 运行 python scripts/flow_control.py advance --run-dir <run-dir>：推进器按重算的 overall_action 与轮次裁决——< max_iterations 时迁移至 UPDATE_CONSTRAINTS 并 current_iteration += 1；轮次已满时自动改道 MAX_ITERATIONS 终止。不得进入 EXTRACT/SUPPLEMENT，不调用 prompt-optimizer。
     6. 用上一轮 execution_result.input_artifacts.constraints 的 path/sha256 核对实际生成 用例所用约束；缺少或哈希不一致时阻断，不能复制一个已被修改的文件。
     7. 运行 python scripts/constraint_update_state.py prepare --source <prev>/constraints.json --target <next>/constraints.json --analysis <prev>/analysis.json --execution-result <prev>/execution_result.json 创建新轮版本和 .pre_update，禁止原地修改上一轮。
     8. 委派 constraint-updater，读取上一轮全部失败簇/findings/用例/执行证据，对新轮 constraints 做最小 Edit，并完成 finalize 与 constraint_update 校验。 4a. 回归校验：constraint-updater 完成回归校验后，若返回 exit code 3，主协调器读取 <next>/regression_check.json。
        • 若 limit_reached=true（updater 自修正 3 次后仍有回归）：主协调器必须暂停流程， 用 AskUserQuestion 弹框让用户选择：
          • 选项 1：接受当前回归，先运行 finalize （python scripts/constraint_update_state.py finalize --report <next>/constraint_update.json
            • python scripts/validate_artifacts.py constraint_update <next>/constraint_update.json）， 然后继续进入 CHECK/REPAIR（用户确认回归可接受）
          • 选项 2：回滚到 <next>/constraints.json.pre_update 版本，终止本轮更新 （执行 cp <next>/constraints.json.pre_update <next>/constraints.json，再运行 python scripts/flow_control.py advance --run-dir <run-dir> --user-decision stop， 推进器将裁决至 BLOCKED 并附 code=CONSTRAINT_REGRESSION_USER_ABORT）
          • 选项 3：用户手动修改约束后继续（主协调器等待用户提供修改后的 constraints.json， 收到后重新运行 validate_constraint_regression.py --attempt 1，通过后运行 finalize，再进入 CHECK/REPAIR）
        • 若 limit_reached=false 且 ok=true：无回归，继续。
     9. 运行 python scripts/run_state.py set-constraint-check --run-dir <run-dir> --reset 重置 run_state.constraint_check 到新 iteration，复用上文 CHECK/REPAIR 子循环； checker 必须验证所有 finding 的 expected_effect。passed 后直接 GENERATE → EXECUTE， 不重新完整提取。
   • MIXED_FAILURE_REVIEW：运行 python scripts/flow_control.py advance --run-dir <run-dir>（推进器裁决至 MIXED_FAILURE_REVIEW），展示每个 cluster、case、根因、建议动作和可用 findings； 默认阻断自动更新/生成。用户可先处理 generator/executor 问题，或明确批准只应用约束 findings（用户批准 → advance --user-decision approve，推进器迁移至 UPDATE_CONSTRAINTS 并 bump；用户停止 → --user-decision stop；沉默 → 保持等待）。 批准后仍须走上述版本化 UPDATE_CONSTRAINTS 和 CHECK/REPAIR，不能跳过。
   • NEEDS_HUMAN_EVIDENCE：运行 flow_control.py advance（推进器无条件迁入 HUMAN_CHECKPOINT），请用户补充事实/停止；收到补充后 append 到 supplement_constraints.md 并经 update_supplement_state.py 刷新，随后 advance （推进器检测补充 hash 变化后迁回 DIAGNOSE）重新运行 failure-analyst 形成可校验 findings，再决定 UPDATE_CONSTRAINTS，仍不 re-EXTRACT；用户停止 → advance --user-decision stop。
   • STOP_GENERATOR_BUG / STOP_EXECUTOR_BUG：运行 python scripts/flow_control.py advance --run-dir <run-dir>，推进器按重算的 overall_action 直接裁决至同名终态，停止。 prompt_optimization 只允许在任务成功后形成知识沉淀提案，不参与当前任务在线路由。

挂起、监听与唤醒（human_constraints_upload == true 时，由 human-checkpoint 检查点「人工修复」触发）

当 run_state.human_constraints_upload == true 且到达 human_checkpoint_round 检查点 （current_iteration >= human_checkpoint_round 且本轮以 constraint_extraction 失败、本轮未弹过、 < max_iterations）时，检查点弹四选一；用户选「人工修复」即进入本节流程，把下一轮约束的修改权交给用户。 前 human_checkpoint_round 轮纯自动迭代（走上方 UPDATE_CONSTRAINTS 自动更新分支，不挂起）。 检查点之后每个 >= human_checkpoint_round 的失败轮都重新弹四选一，用户可逐轮在人工修复 / 人工补充 / 自动修复 / 停止间切换。

1. 挂起：把 run_state.state 置为 AWAITING_HUMAN_CONSTRAINTS，history append {"state":"AWAITING_HUMAN_CONSTRAINTS","code":"HUMAN_CONSTRAINTS_PENDING","iteration":<N>,"at":<ISO8601>}。
2. 诊断摘要：向用户输出本轮诊断摘要（failure_clusters、每簇 root_cause + recommended_action、overall_action、constraint_findings、root_cause_summary）， 明确告诉用户「这些是发现的问题，请在约束文件里据此修改」。
3. 提示用户到网页修改（agent 不创建文件）：不复制任何文件。运行 python scripts/raise_dashboard.py --run-dir <run-dir> --iter iter_<N>（页面已拉起则仅返回 URL、 未拉起则拉起浏览器一次），把返回的 URL 提示给用户：「请到该网页编辑约束并提交，网页提交会自动生成 <run>/iter_<N>/constraints_copy.json」；当前轮约束只读基线是 <run>/iter_<N>/constraints.json。 文件出现即代表用户已在网页提交、准备开启下一轮；文件尚未出现即代表用户仍在修改，继续等待。
4. 挂监听器：用 Monitor 工具（persistent: true，命令为单条绝对路径、无变量/管道/ shell 循环——遵守 WORKFLOW.md Monitor 用法纪律）挂起监听器： <venv-python-absolute> <repo-absolute>/scripts/watch_constraints_copy.py --run-dir <run-dir-absolute> 监听器轮询 iter_<N>/constraints_copy.json 的出现 + 稳定性：启动时文件应缺席（agent 不创建）——缺席时继续等待、不退出；文件出现后连续两次轮询 mtime/size 不变（≈ interval×2， 默认 10 秒，防部分写入竞态）即判定「上传完成」，输出一行 JSON 后退出（单次触发后退出：只报告一个事件即结束）， Monitor 把该事件送回空闲会话。向用户提示：「请把修改后的约束上传到 <abs>/iter_<N>/constraints_copy.json；上传完成后自动开启下一轮。若怀疑监听失效，重新 运行上述 Monitor 命令即可重新挂起。」
5. 空闲等待：会话进入空闲，等待监听器事件唤醒。窗口须保持开启（单窗口方案固有代价）。

唤醒与接入： 6. 监听器事件唤醒会话后，提示「已检测到用户上传的约束文件，开启第 N+1 轮迭代」。 7. 运行确定性接入脚本： python scripts/apply_human_constraints.py --run-dir <run-dir-absolute> （可选 --max-iterations N 提升上限，须 > 当前轮次）。该脚本三阶段（预检→校验→落盘，前两阶段不写盘） 把用户约束接入为 iter_<N+1>/constraints.json：operator_name 一致性 → OperatorRule → validate_constraints → 归一化 → 复验 → noop 检查 → 建 iter 目录 + .pre_update 备份 + .submitted 原样存档 + 归一化 constraints.json + 原子更新 run_state（state=UPDATE_CONSTRAINTS、 current_iteration=N+1、history HUMAN_CONSTRAINTS_APPLIED origin=human）→ 消费 mv iter_<N>/constraints_copy.json → iter_<N>/constraints_copy.consumed-<ts>.json。读 stdout JSON：

• ok=true, mode=applied → 接入成功，进第 8 步 CHECK/REPAIR；
• ok=true, mode=already_applied → 幂等恢复（接入已完成但轮次未跑），直接进第 8 步；
• ok=false → 校验失败（错误码如 OPERATOR_NAME_MISMATCH / NO_CHANGE / CONSTRAINTS_VALIDATION_FAILED / MAX_ITERATIONS_REACHED 等）。文件未被消费， 向用户转述错误，用户改完 iter_<N>/constraints_copy.json 重新上传/保存即可再次触发（监听器 下一轮重新挂起后会再检测）。MAX_ITERATIONS_REACHED 时可用 --max-iterations N 提升上限 后重跑该脚本（或让用户重新发起）。

8. CHECK/REPAIR 子循环：人工来源无 findings 清单，checker 做首轮式完整语义检查 （文档快照 + prompt + 场景指令 + 补充证据）；failed → BLOCKED 照旧。 passed → GENERATE → EXECUTE → GATE → DIAGNOSE。若再次以 constraint_extraction 失败且 current_iteration >= human_checkpoint_round → 回到 human-checkpoint 检查点重新弹四选一 （用户可再选人工修复 / 人工补充 / 自动修复 / 停止，逐轮切换）。终态（SUCCESS / BLOCKED / MAX_ITERATIONS / STOP_* / STOPPED_BY_USER）不变，问环自然结束。

断开恢复：

• 同对话恢复：claude --continue——模型记得挂起上下文，重新执行第 4 步（挂监听器） 后空闲等待（第 3 步不创建文件，agent 始终不复制）。
• 全新会话恢复：/iterate-operator --resume-run <run-dir>——主协调器读 run_state.json：
  • state=AWAITING_HUMAN_CONSTRAINTS → 执行第 4 步挂监听器挂起等待上传；
  • state=UPDATE_CONSTRAINTS 且 iter_<current> 无生成/执行产物 → 接入已完成但轮次未跑， 直接从 CHECK/REPAIR 续跑；
  • state=UPDATE_CONSTRAINTS 且已有生成/执行产物 → 本轮已跑，按正常状态机续跑；
  • 其他终态 → 报告状态结束。 会话挂掉期间用户已上传的 iter_<N>/constraints_copy.json 不丢失——新会话恢复时按 run_state 归位。
• 监听器随会话死亡即失效（其生命期与会话绑定）；恢复时重新挂起即可。

9. 轮次上限由推进器强制：DIAGNOSE 路由时 current_iteration >= max_iterations 会被 python scripts/flow_control.py advance --run-dir <run-dir> 直接裁决至 MAX_ITERATIONS（无需模型判断轮次）。
10. （终态前）分层沉淀询问：若存在 prompt_update_proposal.json，先按 docs/PROMPT_EVOLUTION.md 核验试验结果，再逐条展示目标 canonical 文件、摘要、 失败/文档证据、适用范围与候选 diff，向用户询问“应用 / 暂缓 / 拒绝”。

• 未验证或验证失败的提案默认只允许暂缓/拒绝；
• ACLNN 提案必须归入 base/common/feature/exact operator 之一，torch_npu 只能进入 自己的 prompt/knowledge 根；
• 只有用户明确选择应用后，主协调器才能修改 canonical 文件；用户沉默、运行成功 或批处理模式均不构成批准；
• 应用后重跑 validate_aclnn_knowledge、路由测试（init_run）和 validate_prompt_assembly.py --record（build_*_prompt_base.py 已退场归档于 archive/builders/，base 直接编辑后不再 --check），并把决定与验证结果落入当前 run。

11. 每次委派前后都按 CLAUDE.md 的格式在主会话报告。所有交接必须落盘， 不把一个 Agent 的未验证推理作为另一个 Agent 的事实。
12. 如果提供了 --batch-dir，本算子进入 SUCCESS、BLOCKED、MAX_ITERATIONS、 STOP_GENERATOR_BUG、STOP_EXECUTOR_BUG 或 STOPPED_BY_USER 后，调用 python scripts/batch_state.py --batch-dir <batch-dir> complete。如果 run 创建前即因 文档消失等算子级问题阻断，则调用 complete --terminal-state BLOCKED --message <原因>。 不得把真实执行配置缺失静默记为算子失败；目录批次初始化时应先统一校验该配置。

框架分流（强制）

• 每个 Agent 委派前读取 run_state.json 的 operator_family 与 test_framework。
• atk：产物为每平台 compact JSON，沿用原 ACLNN 生成和 ATK executor。
• ttk：先产出统一 cases.json，再适配为 cases_ttk.csv；generator 命令必须带 --test-framework ttk。operator_family=hs 默认加载可用的自主推导或源码 Golden， 但不以 Golden manifest 或精度结果阻塞流程；只有用户明确要求完全跳过 Golden 时 才使用 --no-golden。operator_family=aclnn 直接走原生 ttk aclnn。两者均不得进入 ATK 链。
• constraints：只产出并校验 constraints.json，不调用任何 case/executor 命令； SUCCESS 必须注明 run_scope=constraints_only，不能表述成用例或精度闭环成功。
• EXTRACT 阶段与测试框架无关，任何 framework 都必须先产生非空且校验通过的 constraints.json，并在每个 outer iteration 通过 constraint_check.json 语义门禁。 如果 state 仍为 PLAN 或文件不存在，说明未委派提取器，不能报告“约束为空”；如果 check 未 passed，不能进入 GENERATE/SUCCESS。

不要在主协调器中亲自完成专职 Agent 的工作，不要并行运行存在数据依赖的阶段。