CANN graph-autofusion 之 SuperKernel Auto Tune 会话契约：证据门控的自动调优编排协议-平芜编程栈

CANN graph-autofusion 之 SuperKernel Auto Tune 会话契约：证据门控的自动调优编排协议

【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾（Ascend）芯片的轻量级、解耦式组件集合，旨在通过自动融合技术加速模型执行。目前已开源 SuperKernel 组件和 Autofuse 组件，未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion

SuperKernel Auto Tune 是 CANN graph-autofusion 开源仓库中一套面向昇腾（Ascend）SuperKernel 的自动调优编排框架，它通过一份可校验的“会话契约”（session contract）把 Intake、S0 基线、Stage A 框定、Stage O Option 调优、BASE 分析与最终 E2E 报告串成一条不可手改、可恢复、可审计的流水线。本文以.claude/skills/superkernel-auto-tune/references/auto-tune-session.md为核心骨架，结合仓库中的auto_tune_session.py实现、JSON Schema 定义与单元测试，完整讲解会话文件结构、全部 CLI 子命令、三种入口调度、八条状态转换规则，以及动态原生子 Agent 委托机制，让读者能够直接上手编排并验证一次 SuperKernel 自动调优会话。

一、契约总览：谁是可执行权威，什么是会话

整个调优编排的“可执行权威”是脚本 auto_tune_session.py，它定义了会话的初始化、推进（next）、派发（dispatch）、封存（seal）与校验（verify）等全部行为。与之配套的五份 JSON Schema 存放在 schemas 目录下：

Schema 文件	对应产物	核心职责
auto-tune-session-v1.schema.json	会话文档`superkernel-auto-tune-session-v1`	整个调优的编排索引，冻结 optional mode、记录步骤状态
phase-task-v1.schema.json	派发任务`superkernel-auto-tune-phase-task-v1`	绑定当前待执行步骤、逻辑 worker ID、Skill 与已封存交接摘要
phase-result-v1.schema.json	阶段结果`superkernel-auto-tune-phase-result-v1`	子 Agent 回传的结构化交接物，封存后不可变
dispatch-receipt-v1.schema.json	派发回执`superkernel-auto-tune-dispatch-receipt-v1`	记录每次真实调度的 stdout/stderr、返回码与运行状态
final-e2e-v1.schema.json	最终 E2E 结论对象	schema 2 账本中唯一的终局性能判定
evidence-import-v1.schema.json	证据导入清单`superkernel-auto-tune-evidence-import-v1`	派生会话（derived session）导入父会话证据时的授权与摘要绑定

契约的交互模型非常简单：控制 Agent（controller）在 Intake 之前先创建一个会话，随后每次通过next获取唯一合法的下一步，再用seal封存该阶段的阶段结果。会话文件与已封存的phase-result.json严禁手工编辑——所有状态推进都必须经由脚本校验后写入，以保证摘要（digest）链的完整性。

从源码结构看，auto_tune_session.py 中通过PHASES常量固化了七个阶段与逻辑 worker 的绑定关系（详见下文第五节），而_canonical_steps()（第 289 行）负责按 optional mode 与入口生成规范步骤序列，任何非规范的阶段顺序或阶段非法状态都会被会话校验器拒绝。

二、端到端 CLI 全流程：从 init 到 verify

以下命令序列摘自契约文档，完整覆盖一次全量会话的生命周期。所有命令均以仓库根目录下的 auto_tune_session.py 为入口：

python3 scripts/auto_tune_session.py init \ --session artifacts/auto-tune-session.json \ --artifact-root artifacts \ --session-id run-20260905-01 \ --optional-mode both python3 scripts/auto_tune_session.py next --session artifacts/auto-tune-session.json python3 scripts/auto_tune_session.py dispatch \ --session artifacts/auto-tune-session.json --output artifacts/dispatch-task.json python3 scripts/auto_tune_session.py run-next \ --session artifacts/auto-tune-session.json \ --runner-command-json agent-host-command.json python3 scripts/auto_tune_session.py seal \ --session artifacts/auto-tune-session.json --result handoff.json python3 scripts/auto_tune_session.py verify --session artifacts/auto-tune-session.json

各子命令的语义与源码入口对应如下（main 分发逻辑见第 1972 行起）：

init：创建一个新的会话。要求--session路径不存在（存在即报错），--optional-mode只能是none、multistream、source-range、both四选一，并生成entrypoint="full"的规范步骤列表。会话通过_atomic_json以“临时文件 +os.replace”方式原子写入，避免半截文件污染。
next：读取会话并返回第一个state == "pending"的步骤；若全部封存则返回None。
dispatch：为当前待执行步骤生成一份superkernel-auto-tune-phase-task-v1任务文件（create_dispatch_task，第 1127 行）。任务内绑定会话指纹session_fingerprint、step、已封存前驱的consumed_handoffs以及handoff.seal_command；派生会话还会携带evidence_import引用。
run-next：当宿主环境提供命令适配器（runner）时使用。脚本把--runner-command-json中读取的命令数组与--task <path> --result <path>拼接后执行，捕获 stdout/stderr，校验并封存结果，同时在dispatches/<step-id>-attempt-<NNN>/下写入一条不可变的派发回执。默认超时--timeout-seconds 3600。失败、超时或非法结果都会把步骤保留为 pending，允许恢复后重试；回执的runner_status取值为passed、failed、timed_out三者之一（run_agent_step 第 1213 行）。
seal：校验阶段结果与当前步骤匹配后，原子写入不可变的phases/<step-id>/phase-result.json与PHASE_REPORT.md，并把步骤标记为sealed、记录result_path、result_sha256、outcome_status与sealed_at（seal_handoff 第 1331 行）。若封存的是最终阶段，则会话状态置为completed并自动渲染FINAL_E2E_REPORT.md。
verify：全量校验——重新加载会话，逐步骤核对phase-result.json的语义摘要、outcome_status一致性、PHASE_REPORT.md存在性以及派发回执摘要；completed 会话还必须存在FINAL_E2E_REPORT.md（verify_session 第 1375 行）。校验通过返回{"valid": true, ...}且退出码为 0，否则退出码为 1。

中断恢复：只认持久化会话

会话被中断后，不要依据聊天历史推断进度，只能从持久化的会话文件恢复：

python3 scripts/auto_tune_session.py resume \ --session artifacts/auto-tune-session.json

resume会先执行完整verify，校验失败则拒绝恢复并给出错误列表，成功时返回session_id、status与next_step（resume_session 第 750 行）。这正是“会话即真相来源”（session as source of truth）的设计体现。

三、会话必填字段与数据模型

契约规定了会话文档的最低结构（[Required Session Fields]），以下 JSON 是契约原文，字段的取值约束可对照 auto-tune-session-v1.schema.json：

{ "schema_version": "superkernel-auto-tune-session-v1", "session_id": "SK-20260905-001", "optional_mode": "none|multistream|source-range|both", "entrypoint": "full|optional-from-base|source-range-from-smap", "status": "active|completed", "artifact_root": "/absolute/frozen/artifact/root", "steps": [ { "step_id": "intake-preparation", "phase": "intake_preparation", "agent_id": "sk-intake-preparation", "skill": "superkernel-intake-preparation", "state": "pending|sealed" } ] }

关键约束与字段语义（结合源码_validate_session与 Schema）：

schema_version必须是常量superkernel-auto-tune-session-v1；optional_mode四选一；entrypoint三选一；status只能是active或completed。
artifact_root必须是冻结产物根的绝对路径，会话文件本身位于其内。
steps非空；每个step_id需匹配^[a-z][a-z0-9-]{1,63}$且不得重复；phase必须属于七个预定义阶段之一，且agent_id、skill必须与该阶段在PHASES中的绑定完全一致（防止子 Agent 冒名顶替）。
步骤状态推进是线性有序的：sealed步骤之后不允许再出现pending步骤（_validate_session中的pending_seen检查）。
completed会话不允许存在任何 pending 步骤。
每次load、resume、verify、dispatch都会重校验_validate_canonical_schedule，确保步骤序列与 optional mode / entrypoint / multistream 是否被接受严格吻合。

agent_id：稳定的逻辑职责与审计键

agent_id（如sk-intake-preparation）是一个稳定的逻辑职责标识和审计键，它会在 phase manifest、task、result、session 四者之间交叉校验，但它不选择任何宿主机特定的自定义 Agent 配置（契约原文：“does not select a host-specific custom Agent profile”）。也就是说，agent_id只负责标识“谁该干这个阶段的活”，至于由哪个宿主 Agent 执行，由下一节的动态委托机制决定。

已封存步骤的绑定信息

每个已封存步骤在会话内还会绑定其不可变结果：

result_path/result_sha256：阶段结果文件的相对路径与语义摘要（对规范化 JSON 做 SHA-256）；
outcome_status：终态（succeeded、accepted、no_gain、blocked、failed、invalid、not_requested、not_run之一）；
可选的成功派发回执dispatch_receipt_path/dispatch_receipt_sha256：仅在run-next成功后写入。

详细的输入、决策、阻塞项、产物、失败场景与中文指导（summary_zh、next_step_guidance_zh、details_zh、decisions、blockers）都沉淀在阶段结果文档中，会话本身只保留摘要引用，避免把编排索引变成大而全的仓库。

四、派生会话与证据导入（evidence-gated derived session）

当用户之后要求执行 multistream 或 P/FINAL（source-range）实验时，不允许在原会话上续跑，而是从已完成（completed）的父会话派生一个全新会话。派生会话额外携带evidence_import.path与evidence_import.sha256两个字段，指向一份superkernel-auto-tune-evidence-import-v1清单。

python3 scripts/auto_tune_session.py derive-session \ --parent-session <parent-root>/auto-tune-session.json \ --session <new-root>/auto-tune-session.json --artifact-root <new-root> \ --session-id <new-run-id> --optional-mode <multistream|source-range|both> \ --profiling-analysis <parent-root>/<analysis.json> \ --ledger <parent-root>/<ledger.json> \ --source-scope-map <parent-root>/<source-scope-map.json> \ --approve-imported-evidence

该命令的硬性前提（源码derive_session与_validate_evidence_import双重把关）：

显式批准：必须传--approve-imported-evidence，清单中authorization.approved必须为true且source固定为explicit-user-request；
父会话必须 completed且通过verify，session_id必须与派生会话不同；
产物根必须不相交：父子artifact_root不得互为包含关系（_roots_overlap检查），且派生会话文件必须位于其自身artifact_root之内；
证据必须是 BASE/SMAP 交接物：profiling_analysis必须是 schema 1.2 且带内容指纹校验（analysis_content_fingerprint）、source_scope_mapping协议为source_scope_map_v2且状态为exact；ledger必须是 schema 2 账本且包含该分析对应的 experiment/round；source-range 与both还需要带exact_cover源区间的source_scope_map_v2（schema 2.0/2.1），其source_revision必须与分析一致；
所有导入文件必须位于父artifact_root内，且路径/大小/SHA-256 与 BASE 交接的consumed_artifacts/produced_artifacts绑定一致；
evidence_import清单的identity（experiment_id / round_id / candidate_name / source_revision）必须与分析对象完全一致。

P/FINAL 专属入口也可以使用等价的source-range-from-smap命令，或直接调用独立的superkernel-source-range-from-smapSkill。派生任务会携带不可变的evidence_import引用，每次派发前都必须重校验。

契约同时强调：会话文档只是一个“编排索引”（orchestration index），不是schema 2 账本、profile manifest、multistream 结果或阶段本地报告的替代品——证据本体仍留在各自权威文件中，会话只负责编排与引用。

五、动态原生委托：如何驱动阶段子 Agent

三种规范调度入口

契约规定校验器只接受以下三种规范调度（canonical schedule），其余一律视为非法：

full：Intake -> S0 -> Stage A -> Stage O -> BASE -> optional -> Final；
optional-from-base：multistream -> optional source-range -> Final；
source-range-from-smap：optional source-range -> Final。

在both模式下，一旦 multistream 被接受（accepted），会自动在 source-range 工作之前插入一个新鲜的派生 BASE 步骤base-profile-derived（含派生会话），并在此前把旧 BASE 标记为superseded（详见第六节规则 6）。这一插入逻辑在seal_handoff中由_insert_derived_base（第 1064 行）实现。

七个阶段与逻辑 worker 绑定

逻辑 worker ID（agent_id）	绑定 Skill	用户可见职责
`sk-intake-preparation`	`superkernel-intake-preparation`	环境确认与实验准备
`sk-s0-baseline`	`superkernel-s0-baseline`	S0 基线性能测量
`sk-stage-a-scope-selection`	`superkernel-stage-a-scope-selection`	Stage A 框定方式选择
`sk-stage-o-option-tuning`	`superkernel-stage-o-option-tuning`	Stage O Option 调优
`sk-base-profile-source-mapping`	`superkernel-base-profile-source-mapping`	BASE profile、独立分析与 SMAP
`sk-optional-experiments`	`superkernel-optional-experiments`	双流与 P/FINAL 实验
`sk-final-e2e-report`	`superkernel-final-e2e-report`	最终 E2E 确认与报告

派发与子 Agent 提示词要素

dispatch会生成一个superkernel-auto-tune-phase-task-v1任务，它绑定：精确的待执行步骤、逻辑 worker ID 与 Skill、已封存前驱摘要、当前会话指纹（session_fingerprint，64 位十六进制）以及必须遵守的结果 Schema。控制 Agent 随后用宿主机内置的原生通用子 Agent（generic subagent）执行该阶段——绝不使用根级自定义 Agent 注册：

宿主	内置通用子 Agent
Codex	`worker`；仅有通用默认角色时用`default`
Claude Code	`general-purpose`
OpenCode	`general`

子 Agent 提示词必须包含以下全部要素：

精确的phase-task.json路径及其step.agent_id、step.phase、step.skill；
明确指示加载并遵循step.skill——因为通用子 Agent不会自动继承控制 Skill 的指令；
在运行任何实验命令之前，先执行对应的阶段校验命令：scripts/execute_phase.py --task <phase-task.json>；
精确的可写结果路径与要求的superkernel-auto-tune-phase-result-v1Schema；
边界声明：子 Agent 只拥有本阶段，不得派发或执行后续阶段。

每个阶段执行前，本地阶段脚本 execute_phase.py 会先拒绝过期或投递错误的（stale/misrouted）任务，然后子 Agent 才能运行自己的工具计划。若想单步执行某个白名单工具，可使用：

scripts/execute_phase.py --task <dispatch-task.json> --tool <listed-tool> \ --lease-root <lease-root> --device-id <id> -- <tool args>

该包装器会拒绝白名单之外的工具，并让每个子命令都通过共享的 NPU 租约运行器（shared NPU lease runner）执行。

硬性约束：不要在“口头声称”的基础上委托后续阶段；每个阶段之间必须新建一个全新的通用子 Agent（不得跨阶段复用）；子 Agent 跑完后先seal校验其结构化结果，再查询next。如果宿主无法创建原生通用子 Agent，则保持步骤 pending、保留派发失败场景并上报阻塞项——控制 Agent 绝不能“冒充”阶段 worker 亲自干活。

派发回执与任务防重放

run-next会在dispatches/<step-id>-attempt-<NNN>/下留下一个不可变尝试目录，内含phase-task.json、phase-result.json、runner.stdout.log、runner.stderr.log与dispatch-receipt.json。回执记录attempt序号、起止时间、任务/结果/日志路径及各自 SHA-256、runner_argv_sha256与runner_status（dispatch-receipt-v1.schema.json）。该回执的摘要随后被绑定进已封存会话步骤，形成“任务 -> 执行 -> 结果 -> 回执”的完整审计闭环。validate_dispatch_task（第 1174 行）还会逐字段比对当前会话重建的任务，过期任务直接被拒绝。

六、八条状态转换规则：何时前进、何时短路

契约用八条规则定义了状态机的全部合法迁移，这是整个编排正确性的核心，逐条解读如下：

Intake 冻结 optional mode：一旦 Intake 完成，optional mode 不可再改。若出现关键环境阻塞，直接进入最终报告，并把 E2E 记为not_run。
S0 有门槛：只有当保留的五次运行稳定性门禁（preserved five-run stability gate）通过时，S0 才能继续前进。
Stage A 双出口：要么返回一个Sbest-SEED，要么返回终局“无优胜者”（no-winner）。no-winner 结果跳过 Stage O，直接进入最终报告。
Stage O 整矩阵结算：必须结算完整个实验矩阵后才返回Sbest-BASE。单个失败或被拒的试验只作为阶段证据保留，不单独终止矩阵。
BASE 映射的兜底：BASE profile/源码映射要么返回合法的当前在位者（incumbent），要么返回“默认优胜者失败”（default-winner failure）。只有既有的“候选排序策略”（ranked-candidate policy）才有资格把另一个 Stage A 候选重新送回 Stage O。
可选实验的派生语义：optional mode 为none时记录not_requested；both时先执行 multistream。合法的 multistream 接受会创建派生家族、把旧 BASE 标记为superseded，并在 P/FINAL 之前回到 BASE profile/源码映射；任何其他 multistream 终态则精确保留其在位者。
P/FINAL 只吃当前 BASE：P/FINAL 只接收当前映射的 BASE 在位者，永不修改已冻结的 Option maps；其未接受（non-accepted）终态同样保留在位者。
最终报告永远执行：最终报告阶段永远运行。只有当保留的晋级门禁（promotion gate）允许时才执行一次干净的 E2E 对比；否则把决定性证据记为not_run。

这些规则在源码中的落点是_must_short_circuit（第 1075 行）与_seal_not_run_steps（第 1087 行）：Intake/S0 非succeeded、Stage A 非accepted、Stage O 非accepted/no_gain、BASE 非succeeded/no_gain都会触发短路——所有尚未执行且非最终阶段的 pending 步骤被自动封存为not_run（optionalnone分支则为not_requested），并只留下 Final 一个合法去向。这类由控制器生成的交接物会标记system_generated_by: "superkernel-auto-tune"，且仅允许控制器创建，普通子 Agent 伪造该字段会被_validate_result拒绝。

中文要求：每个终态阶段报告都必须用中文描述其结果（summary_zh、details_zh等字段）；当状态为failed或“开始后的blocked”时，还必须包含失败场景的源路径。

七、最终 E2E 报告：唯一终局判定

封存最终交接（final handoff）会写出一份FINAL_E2E_REPORT.md。其details_zh必须覆盖以下七个主题（源码FINAL_DETAIL_KEYS，缺失即校验失败）：

environment：环境与准备；
s0：S0 基线；
stage_a：Stage A 框定方式；
stage_o：Stage O Option；
base_profile_source_mapping：BASE Profile 与 SMAP；
optional_experiments：可选实验；
final_e2e：最终 Clean E2E。

并且要包含not_run等未执行结果——也就是说，即便某个阶段被短路，报告也要如实记录“未执行”，而不是假装跑过。

最终报告的内容来源于 schema 2 实验账本的final_e2e结构化对象，它是唯一的终局性能判定，记录：classification（beneficial/no_gain/not_run/failed/blocked）、精确候选candidate_id、SK scope 策略、Option map、证据、判定理由，以及执行时的干净 baseline/candidate 指标。源码_validate_final_e2e（第 204 行）还会交叉验证：improvement_pct必须与 baseline/candidate 的median_ms严格一致（相对误差 1e-6），beneficial分类要求收益严格为正。最终阶段结果的status也必须与账本分类一一对应（beneficial -> accepted、no_gain -> no_gain、not_run -> not_run、failed -> failed、blocked -> blocked），否则封存被拒。

report_summary：结果前置的新账本增强

新的最终 worker 还会按 report-summary.md 与 report-summary-v1.schema.json 填充 schema 2 账本的可选report_summary字段。共享渲染器会在封存前校验它，并把结果速览、关键对比表、优胜者/回退配置放到元数据之前，让报告“结论先行”。_validate_report_summary（第 1459 行）强制要求：eligible 候选必须被测量且状态为accepted；非 profiling 行的baseline_ms必须与冻结 S0 一致；improvement_pct必须与测量值吻合；winner只有在beneficial分类下才允许出现且其candidate_id/scope_strategy/option_config必须与final_e2e完全一致。

历史账本（legacy ledger）没有report_summary也依然可读——缺失字段一律以显式N/A呈现。对于历史报告，render-final-report --summary <json>提供一个只读的展示覆盖（display override），但它永不改变终局分类：

python3 scripts/auto_tune_session.py render-final-report \ --session artifacts/auto-tune-session.json --output FINAL_E2E_REPORT.md

八、源码级佐证：测试如何锁定契约

仓库为这套契约提供了完整的单元测试 test_auto_tune_session.py（约 1384 行）。测试通过importlib直接加载auto_tune_session.py模块，并提供一个phase_result()辅助工厂：它会读取next_step(session)，按阶段自动生成合法状态的superkernel-auto-tune-phase-result-v1交接物，并为final_e2e_report阶段配套构造 schema 2 账本（含final_e2e的 classification、baseline/candidate 中位数与improvement_pct自洽计算）。从测试结构可以推断，覆盖点包括：规范调度序列校验、非法状态拒绝、短路not_run场景、派生会话的证据门控、派发任务防重放、verify的摘要一致性等。

同时，各阶段 Skill 的 execute_phase.py 通过sys.path引入superkernel-auto-tune/scripts/phase_entrypoint.py的run()，并绑定各自的phase.json——这印证了“先校验任务、后执行工具计划”的阶段入口约定，也说明每个阶段 Skill 只是同一套会话框架下的一个 manifest 化插件。

九、实践要点与边界提醒

基于契约与源码，落地一套 SuperKernel Auto Tune 会话时请牢记以下要点：

会话即唯一真相：一切进度以持久化会话文件为准，中断后用resume恢复，不要凭聊天记录推断；会话与已封存结果严禁手改。
证据门控不可绕过：派生会话必须显式批准（--approve-imported-evidence），导入的分析必须是 schema 1.2、账本必须是 schema 2、SMAP 必须是带exact_cover的source_scope_map_v2，且所有摘要必须与 BASE 交接绑定一致。
委托边界清晰：控制 Agent 只做编排（next/dispatch/seal/verify），永远不亲自执行调优阶段；每个阶段使用全新的宿主机原生通用子 Agent，并把agent_id作为可见任务名与审计键。
短路是特性不是错误：环境阻塞、无优胜者、矩阵失败都会按规则 1–8 自动把后续阶段封存为not_run并直达 Final，最终报告如实呈现not_run。
唯一终局判定：只有 schema 2 账本final_e2e的干净 E2E 对比才是终局结论，阶段实验（screening/option/optional_clean）与 profiling 诊断都不能替代它。

这套会话契约把“谁在何时、依据什么证据、把什么结果封存给谁”固化成了可机器校验的协议，让昇腾 SuperKernel 的自动调优从一次性的口头协作升级为可恢复、可审计、可复现的工程流水线。如需进一步理解证据门禁、安全约束与 Option 规则的细节，可继续阅读 controller-legacy-contract.md；各阶段 Skill 的完整编排视图见 SKILL.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考