CANN graph-autofusion 之 SuperKernel Auto Tune 会话契约证据门控的自动调优编排协议【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusionSuperKernel Auto Tune 是 CANN graph-autofusion 开源仓库中一套面向昇腾AscendSuperKernel 的自动调优编排框架它通过一份可校验的“会话契约”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导入父会话证据时的授权与摘要绑定契约的交互模型非常简单控制 Agentcontroller在 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四选一并生成entrypointfull的规范步骤列表。会话通过_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_atseal_handoff 第 1331 行。若封存的是最终阶段则会话状态置为completed并自动渲染FINAL_E2E_REPORT.md。verify全量校验——重新加载会话逐步骤核对phase-result.json的语义摘要、outcome_status一致性、PHASE_REPORT.md存在性以及派发回执摘要completed 会话还必须存在FINAL_E2E_REPORT.mdverify_session 第 1375 行。校验通过返回{valid: true, ...}且退出码为 0否则退出码为 1。中断恢复只认持久化会话会话被中断后不要依据聊天历史推断进度只能从持久化的会话文件恢复python3 scripts/auto_tune_session.py resume \ --session artifacts/auto-tune-session.jsonresume会先执行完整verify校验失败则拒绝恢复并给出错误列表成功时返回session_id、status与next_stepresume_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与 Schemaschema_version必须是常量superkernel-auto-tune-session-v1optional_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-256outcome_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/FINALsource-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且通过verifysession_id必须与派生会话不同产物根必须不相交父子artifact_root不得互为包含关系_roots_overlap检查且派生会话文件必须位于其自身artifact_root之内证据必须是 BASE/SMAP 交接物profiling_analysis必须是 schema 1.2 且带内容指纹校验analysis_content_fingerprint、source_scope_mapping协议为source_scope_map_v2且状态为exactledger必须是 schema 2 账本且包含该分析对应的 experiment/roundsource-range 与both还需要带exact_cover源区间的source_scope_map_v2schema 2.0/2.1其source_revision必须与分析一致所有导入文件必须位于父artifact_root内且路径/大小/SHA-256 与 BASE 交接的consumed_artifacts/produced_artifacts绑定一致evidence_import清单的identityexperiment_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其余一律视为非法fullIntake - S0 - Stage A - Stage O - BASE - optional - Finaloptional-from-basemultistream - optional source-range - Finalsource-range-from-smapoptional source-range - Final。在both模式下一旦 multistream 被接受accepted会自动在 source-range 工作之前插入一个新鲜的派生 BASE 步骤base-profile-derived含派生会话并在此前把旧 BASE 标记为superseded详见第六节规则 6。这一插入逻辑在seal_handoff中由_insert_derived_base第 1064 行实现。七个阶段与逻辑 worker 绑定逻辑 worker IDagent_id绑定 Skill用户可见职责sk-intake-preparationsuperkernel-intake-preparation环境确认与实验准备sk-s0-baselinesuperkernel-s0-baselineS0 基线性能测量sk-stage-a-scope-selectionsuperkernel-stage-a-scope-selectionStage A 框定方式选择sk-stage-o-option-tuningsuperkernel-stage-o-option-tuningStage O Option 调优sk-base-profile-source-mappingsuperkernel-base-profile-source-mappingBASE profile、独立分析与 SMAPsk-optional-experimentssuperkernel-optional-experiments双流与 P/FINAL 实验sk-final-e2e-reportsuperkernel-final-e2e-report最终 E2E 确认与报告派发与子 Agent 提示词要素dispatch会生成一个superkernel-auto-tune-phase-task-v1任务它绑定精确的待执行步骤、逻辑 worker ID 与 Skill、已封存前驱摘要、当前会话指纹session_fingerprint64 位十六进制以及必须遵守的结果 Schema。控制 Agent 随后用宿主机内置的原生通用子 Agentgeneric subagent执行该阶段——绝不使用根级自定义 Agent 注册宿主内置通用子 AgentCodexworker仅有通用默认角色时用defaultClaude Codegeneral-purposeOpenCodegeneral子 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_statusdispatch-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_requestedboth时先执行 multistream。合法的 multistream 接受会创建派生家族、把旧 BASE 标记为superseded并在 P/FINAL 之前回到 BASE profile/源码映射任何其他 multistream 终态则精确保留其在位者。P/FINAL 只吃当前 BASEP/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_runoptionalnone分支则为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环境与准备s0S0 基线stage_aStage A 框定方式stage_oStage O Optionbase_profile_source_mappingBASE Profile 与 SMAPoptional_experiments可选实验final_e2e最终 Clean E2E。并且要包含not_run等未执行结果——也就是说即便某个阶段被短路报告也要如实记录“未执行”而不是假装跑过。最终报告的内容来源于 schema 2 实验账本的final_e2e结构化对象它是唯一的终局性能判定记录classificationbeneficial/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-6beneficial分类要求收益严格为正。最终阶段结果的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。【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考