| name | byted-ark-trainer |
| description | 基于ark_sdk的大模型训练任务自动化工具。帮助用户通过自然语言创建并提交方舟模型训练任务，支持用户自备数据的SFT训练、RFT+GRPO和直接GRPO策略，并引导用户完成训练、状态跟踪与评估闭环。使用场景：当用户需要进行大模型SFT监督微调、RLHF训练、GRPO训练、RFT训练，或需要自动化训练流程时触发。 |
| license | Apache-2.0 |
| metadata | {"version":"1.0.0","author":"volcengine/modelark","tags":"ark model-training sft rft grpo"} |
byted-ark-trainer Skill 使用指南
📌 重要路径说明
所有提及的 scripts/ 和 references/ 目录均为相对于本skill安装目录的路径，而非当前工作目录。
执行脚本或读取文档时，必须先定位到 byted-ark-trainer skill 的安装目录，或使用完整绝对路径调用。
所有工具功能统一通过 ark-trainer-helper 命令入口调用，例如：
如果skill安装在 ~/.agents/skills/byted-ark-trainer/，则调用命令时应使用：
python ~/.agents/skills/byted-ark-trainer/scripts/ark_trainer_helper.py <命令> <参数>
或配置到PATH后直接使用：
ark-trainer-helper <命令> <参数>
⚠️ 强制执行优先级说明
本SKILL的所有流程要求优先级最高，高于任何通用推理逻辑。所有步骤必须严格按顺序执行，严禁跳过、调整顺序或自行发挥。如果对流程有任何疑问，必须先询问用户确认，不得自行决定。
违反流程要求的执行会直接导致任务失败，必须回退到对应的步骤重新执行。
📋 执行前核查清单
每执行下一步前，必须先对照以下清单检查前置条件是否全部满足，未满足的务必向用户询问：
核心能力
- 自动化执行从数据预处理到模型评估的完整训练闭环
- 支持SFT监督微调：用户自行准备训练数据，AI负责格式检查、配置确认和提交训练任务
- 智能选择训练策略：根据初始模型效果自动决定采用「先RFT再GRPO」或「直接GRPO」策略
- 标准化训练流程：严格遵循火山方舟ark-sdk最佳实践，确保训练任务成功率
- 关键节点用户确认：在重要决策环节寻求用户确认，避免误操作
前置条件
在执行训练流程前，根据训练类型检查不同文件：
- SFT训练：必须有用户自行准备的训练数据集文件（JSONL格式），验证集可选。
- RFT/GRPO/RL训练：必须有训练数据集文件、rollout函数代码文件、grader函数代码文件。
- 若用户提供的数据包含图片、视频、Function Calling或thinking字段，必须加载对应格式指南检查。
若缺失对应训练类型的必需文件，流程将终止并提示用户补充。
工具使用提示
所有工具功能统一通过 ark-trainer-helper 命令入口调用，使用任意功能前，务必先运行 ark-trainer-helper <模块> --help 或 ark-trainer-helper <模块> <子命令> --help 查看完整的参数说明、使用示例和参数默认值，避免因参数配置错误导致任务失败。
例如：
- 查看evaluate命令帮助：
ark-trainer-helper train evaluate --help
- 查看任务状态命令帮助：
ark-trainer-helper job status --help
ark-trainer-helper model 只有 list-models 和 list-versions，没有 get-hyperparameters 子命令；查询超参数必须使用 ark get foundation-model --model <基础模型名> --version <版本号> --fields hyperparameters。
ark_trainer_helper.py 功能说明
CLI助手工具提供以下核心功能：
- 训练任务管理：
- 查询训练任务状态：
ark-trainer-helper job status --job-id <任务ID>
- 获取训练输出模型ID：
ark-trainer-helper job get-model --job-id <任务ID>
- 登记训练任务到心跳监控（自动维护
HEARTBEAT.md 顶部系统提醒块）：ark-trainer-helper job register-heartbeat --job-id <任务ID> --job-type <SFT/RFT/GRPO/...> --job-url <任务链接> --exp-dir <实验子目录绝对路径>
- 基础模型查询：
- 查询基础模型列表（支持名称模糊查询和训练类型筛选）：
ark-trainer-helper model list-models
ark-trainer-helper model list-models --name doubao
ark-trainer-helper model list-models --supported-customization-type FinetuneLoRA
- 查询基础模型所有可用版本：
ark-trainer-helper model list-versions --model-name <模型名> (例如 doubao-seed-1-6)
- 查询模型支持的训练超参数：
ark get foundation-model --model <基础模型名> --version <版本号> --fields hyperparameters
（该命令可用于获取训练任务支持的所有超参数列表、取值范围和默认值）
- 端点管理：
- 训练工具集：
- 模型评估（计算BON/AON/AvgN指标）：
ark-trainer-helper train evaluate --dataset <数据集路径> --rollout <rollout文件路径> --grader <grader文件路径> --output-dir <实验子目录>/eval_output
⚠️ 实际评估的模型由 rollout.py 内部 chat.completions.create(model=...) 传入的字符串决定。运行 evaluate 前必须先把 rollout 中的 model= 改成目标模型名/版本/端点ID/自定义模型ID；详见「评估前强制步骤：把 rollout 的 model 字段改成当前评估对象」。本命令不接受 --model 参数。
⚠️ --output-dir 必须指向本次实验子目录下的子目录（例如 experiments/exp_xxx/eval_output / rft_eval_output / final_eval_output），不得放在工作区根目录或其他实验的目录中。日志会自动写入 <output-dir>/logs/eval_YYYYMMDD_HHMMSS.log，支持自动轮转，最大10MB。
- RFT训练数据收集：
ark-trainer-helper train rft-data-collect --eval-results <评估结果JSON路径> --output-file <输出JSONL路径> --rollout <rollout文件路径>
所有命令均可通过 --help 查看详细参数。
数据集格式指南按需加载
用户提供训练数据后，不要凭经验判断格式；必须按训练类型和数据内容加载对应指南，只加载需要的文件：
| 场景 | 必读指南 |
|---|
| SFT监督微调 | references/模型精调数据集格式指南/SFT.md |
| GRPO/PPO/RL数据 | references/模型精调数据集格式指南/RL.md |
| DPO/偏好学习 | references/模型精调数据集格式指南/DPO.md |
| CPT/继续预训练 | references/模型精调数据集格式指南/CPT.md |
| Function Calling样本 | references/模型精调数据集格式指南/Function Calling 样本要求.md |
| 图片或多模态图片样本 | references/模型精调数据集格式指南/图片文件要求.md |
| 视频样本或视频抽帧 | references/模型精调数据集格式指南/视频文件要求.md，必要时再读 references/模型精调数据集格式指南/对视频内容进行抽帧处理.md |
| thinking/reasoning_content字段 | references/模型精调数据集格式指南/数据集Thinking字段处理工具.md，多轮场景再读 references/模型精调数据集格式指南/多轮reasoning_content的样本文件拆分.md |
SFT数据集校验至少要确认：JSONL每行都是合法JSON；文件绝对路径不含 *、?、[、]；样本结构符合用户要训练的模型类型；必填字段存在且类型正确；多模态资源路径/TOS/base64格式符合附录要求；reasoning_content、thinking、Function Calling字段只在模型和格式指南允许时使用。
🧯 常见问题处理规则
遇到同类情况必须优先按本节处理，避免重复试错。
1. Python环境与依赖预检
2. .env必须导出给子进程
3. Rollout/Grader函数导出名
- helper 会自动寻找带装饰器标记的函数；但某些官方示例被装饰后的函数不一定能被检测到。
- 如果日志报
No rollout function found，在rollout文件末尾增加别名导出，例如：rollout_func = demo_rollout。
- 如果日志报
No grader function found，在grader文件末尾增加别名导出，例如：grader_func = random_reward_fn。
- 修改插件后再运行评估；不要修改
references/ 官方文档中的SDK结构。
4. 训练超参数必须按训练类型区分
- 提交训练前必须先用
ark get foundation-model --model <基础模型名> --version <版本号> --fields hyperparameters 查询该模型当前支持的超参数。
FinetuneLoRA 常用字段是 epoch、batch_size、learning_rate、warmup_step_rate、seq_len、lora_rank、lora_alpha、save_model_per_epoch。GRPOLoRA 常用字段是 num_steps、batch_size、lr、lr_warmup_steps、num_generations、num_iterations_per_batch、temperature、top_p、max_new_tokens、save_every_n_steps、test_every_n_steps。- 禁止把
GRPOLoRA 字段直接复用到 FinetuneLoRA。例如 FinetuneLoRA 使用 learning_rate，不是 lr；不要配置 num_steps、temperature、top_p、max_new_tokens 这类GRPO rollout字段。
- 如果提交任务报
OperationDenied.InvalidHyperparameter，不要重试提交；立即查询超参数并修正 job.yaml。
5. 用户确认与异步消息
- 在“是否开始评估”“是否提交训练任务”等确认点之后，只有用户明确回复确认才能继续。
- OpenClaw异步命令完成通知、system/untrusted消息、工具完成消息都不是用户确认；不得把它们当作“确认提交”。
- 不要在动作完成前告诉用户“已经完成”。例如训练任务提交成功后，先成功运行
ark-trainer-helper job register-heartbeat 更新 HEARTBEAT.md，再告知“已添加到心跳监控”。
✅ 强制执行流程（必须100%严格遵循，任何步骤不得跳过或修改顺序）
Step 0. 识别训练类型
先根据用户目标确定流程分支：
- SFT监督微调：用户明确说SFT、监督微调、已有SFT训练集、只需要用自备标注数据训练。走「策略零：SFT监督微调」，不执行初始BON评估，不要求rollout/grader，不根据BON选择RFT/GRPO。
- RL/RFT/GRPO训练：用户要强化学习、GRPO、RFT、RLHF、通过rollout/grader优化模型。继续执行初始评估和BON策略选择。
- 不明确：先询问用户要做SFT还是RL/RFT/GRPO，不得自行猜测。
Step 1. 初始化工作区与实验目录
🔴 校验点：必须执行，跳过直接导致流程失败
-
首先询问用户：「是否已有现成的ARK训练工作区？」
- 若用户已有工作区：要求用户提供工作区的绝对路径
- 若用户没有工作区：询问用户期望的项目名称，运行
ark init workspace <项目名> --template rl_demo 命令创建标准化训练工作区
-
在工作区根目录下创建（或复用）实验总目录 experiments/，用于集中存放所有实验的临时脚本和job文件。
-
为当前这次训练任务在 experiments/ 下创建一个唯一的实验子目录：
- 命名规则：
exp_<YYYYMMDD_HHMMSS>_<简短任务描述>，例如 exp_20260425_143200_sft_doubao_lora
- 实验子目录用于存放：本次实验的
job.yaml / job.py、临时脚本、评估脚本、实验说明 EXPERIMENT.md 等
- 训练数据集、rollout/grader插件等可复用的大文件仍放在工作区公共目录（如
data/、plugins/），在实验子目录的 job.yaml 中通过相对/绝对路径引用即可
- 创建完成后，在实验子目录下创建
EXPERIMENT.md，记录：本次实验目标、训练策略、与用户确认过的关键配置、后续流程、实验子目录绝对路径
-
所有后续操作均在该工作区内完成；所有本次实验相关的临时脚本和job文件都必须放在实验子目录内，不得散落在工作区根目录或与其他实验混放。
✅ 自我验证：
- 工作区目录结构完整，包含
data/、plugins/、experiments/ 等标准结构
- 本次实验的子目录已创建且记录下了绝对路径
EXPERIMENT.md 已初始化并写入实验计划和已确认信息
工作区结构参考：byted-ark-trainer/references/ark-sdk guide.md 中「项目的初始化」章节。
📁 实验目录结构示例
<工作区根目录>/
├── data/ # 公共数据集目录
├── plugins/ # 公共 rollout/grader 插件目录
├── experiments/ # 所有实验集中存放
│ ├── exp_20260425_143200_sft_doubao_lora/
│ │ ├── EXPERIMENT.md # 本次实验计划、已确认信息、后续流程
│ │ ├── job.yaml # 本次实验的训练任务配置
│ │ ├── submit.sh # 可选：本次实验使用的提交脚本
│ │ ├── eval_output/ # 初始评估结果目录（evaluate --output-dir 指向这里；日志自动落在其下 logs/ 子目录）
│ │ ├── rft_eval_output/ # 可选：RFT 阶段 teacher 模型轨迹收集结果目录
│ │ └── final_eval_output/ # 可选：训练完成后的测试集评估结果目录
│ └── exp_20260426_101500_grpo_v1/
│ ├── EXPERIMENT.md
│ └── job.yaml
└── .env
📝 EXPERIMENT.md 最小模板
每个实验子目录必须在创建时初始化 EXPERIMENT.md，后续随着用户确认信息增量更新：
# 实验：<实验名>
- 实验子目录绝对路径：/absolute/path/to/experiments/exp_xxx
- 工作区绝对路径：/absolute/path/to/workspace
- 创建时间：2026-04-25 14:32:00
- 训练策略：SFT / RFT+GRPO / 直接GRPO
- 基础模型：doubao-seed-1-6 (version 250828)
## 实验计划
1. ...
2. ...
## 基础模型与训练方式确认
- 精确模型名：doubao-seed-1-6
- 选定版本：251015
- 该模型支持的训练方式：FinetuneSft, FinetuneLoRA, GRPO, GRPOLoRA, DPO, DPOLoRA, PPO, OPD, OPDLoRA
- 本次选用的训练方式：FinetuneLoRA
- 允许配置的超参数清单：epoch / batch_size / learning_rate / lora_rank / ...
- 查询命令：`ark get foundation-model --model doubao-seed-1-6 --version 251015 --fields hyperparameters`
## 已与用户确认的信息
- Python环境：...
- 数据集路径（训练/测试）：...
- rollout / grader 文件路径：...
- 超参数：...
- 任务链接：<任务提交后补充>
- 任务ID：<任务提交后补充>
## 后续流程
- 任务完成后需要执行的下一步（例如：获取模型ID → 在测试集上评估 → 对比BON/AON/AvgN）
Step 2. 前期检查
验证以下内容：
- 工作区是否成功创建且结构完整
- 根据训练类型检查文件：
- SFT：训练数据集必须存在；验证集可选；不要求rollout/grader。
- RL/RFT/GRPO：数据集、rollout函数、grader函数必须存在且符合规范。
- Python环境检查：
- 使用用户指定Python执行
<用户指定python> <skill目录>/scripts/ark_trainer_helper.py --help
- 若缺少依赖，安装到同一个用户指定Python环境后再继续，不得临时切换Python
- 环境变量检查：
- 检查是否存在
.env 文件，或环境变量中是否已配置：
ARK_API_KEY：ARK平台API密钥VOLCENGINE_ACCESS_KEY：火山引擎访问密钥AKVOLCENGINE_SECRET_KEY：火山引擎访问密钥SK
- 若上述环境变量未配置，主动询问用户提供，并写入工作区
.env 文件
- 使用
set -a; source .env; set +a 或显式 export，确认Python子进程能读取这些变量
- 询问并确认用户已完成授权配置
若校验不通过，提示用户补充修正，不继续流程。
Step 2.5. 基础模型与训练方式确认
🔴 强制校验点：所有训练类型（SFT / RFT / GRPO / DPO / ...）在进入数据集处理之前必须完成本步，且每一项都需要得到用户明确确认。严禁凭经验/训练数据猜测模型是否存在、版本号是否正确、或该模型+版本是否支持用户期望的训练方式。
执行顺序和校验要点如下：
1) 确认模型存在且名称精确
用户给出模型名后（例如"doubao-seed-1-6"），不要直接当作最终名称使用——list-models --name 是前缀模糊匹配，doubao-seed-1-6 会同时命中 doubao-seed-1-6、doubao-seed-1-6-flash、doubao-seed-1-6-lite、doubao-seed-1-6-vision、doubao-seed-1-6-thinking、doubao-seed-1-6-nano 等多个模型。
ark-trainer-helper model list-models --name <用户输入的模型名>
- 若查询结果为空：告知用户该名称不存在，要求用户确认拼写或提供别名/完整名称；禁止自行修正。
- 若查询结果为唯一一条且模型名与用户输入完全一致：可直接采用。
- 若查询结果为多条或存在相似命中：展示所有命中列表（模型名 + 描述），让用户明确选择"精确模型名"，再继续下一步。不得在用户未选择前往下走。
2) 查询模型支持的版本并由用户选择
ark-trainer-helper model list-versions --model-name <精确模型名>
展示所有版本号给用户，询问用户希望使用的版本。若用户没有偏好，优先向用户推荐稳定版本（例如纯数字日期的版本号如 250615、251015），而不是 dev / preview / med 等后缀版本；但最终版本号必须由用户明确确认，不得自行决定。
3) 校验该模型+版本是否支持用户期望的训练方式，并获取超参数表
说明：同一模型的不同版本可视为支持相同的训练方式与超参数。因此本步只需任选一个版本（优先用户选定版本）查询一次；若用户选定版本查询失败（如版本已下线、接口返回为空），可退回到该模型的其他版本查询，结论仍可复用。
ark get foundation-model --model <精确模型名> --version <版本号> --fields hyperparameters
- 该命令的输出会按训练方式分节，例如可能出现的分节：
FinetuneSft、FinetuneLoRA、GRPO、GRPOLoRA、DPO、DPOLoRA、PPO、OPD、OPDLoRA 等。
- 输出中存在哪个训练方式小节，就代表该模型支持该训练方式；没有出现的训练方式一律视为不支持。
- 将支持的训练方式列表与用户期望的训练方式比对：
- 用户要 SFT：需存在
FinetuneLoRA（LoRA 训练，默认）或 FinetuneSft（全量）中的至少一个。LoRA 优先。
- 用户要 RFT：RFT 阶段本质是 SFT，同样检查
FinetuneLoRA / FinetuneSft。
- 用户要 GRPO：需存在
GRPOLoRA（LoRA，默认）或 GRPO（全量）中的至少一个。LoRA 优先。
- 其他训练方式（DPO / PPO 等）按同样原则对照分节名。
- 若用户期望的训练方式未在输出中出现：立即停止流程，告知用户"模型 <名称> 版本 <版本号> 不支持 <训练方式>"，列出实际支持的方式，让用户重新选择模型/版本或调整训练方式；严禁硬提交后再让火山侧报错。
- 若用户期望的训练方式存在：记录该分节下的全部超参数字段名、取值范围、默认值，这些是后续编写
job.yaml 时允许配置的唯一超参数集合；严禁跨训练方式复用字段（例如把 GRPOLoRA 的 lr / num_steps 用到 FinetuneLoRA）。
4) 信息汇总并写入 EXPERIMENT.md
在进入数据集处理前，必须把本步结论以如下结构写入当前实验子目录的 EXPERIMENT.md：
## 基础模型与训练方式确认
- 精确模型名：doubao-seed-1-6
- 选定版本：250615
- 该模型支持的训练方式：FinetuneSft, FinetuneLoRA, GRPO, GRPOLoRA, DPO, DPOLoRA, PPO, OPD, OPDLoRA
- 本次选用的训练方式：FinetuneLoRA
- 允许配置的超参数（FinetuneLoRA）：
- epoch: [1, N], default=...
- batch_size: {...}, default=...
- learning_rate: [..., ...], default=...
- lora_rank: ...
- ...
- 查询命令与时间：`ark get foundation-model --model doubao-seed-1-6 --version 250615 --fields hyperparameters`（2026-04-25 14:30）
只有当以上四步全部完成、并得到用户明确确认后，才能进入 Step 3 数据集处理。
Step 3. 数据集处理
🔴 RL/RFT/GRPO校验点：必须确保有明确的训练集和测试集才能继续后续流程，禁止使用整个数据集同时做训练和评估
- 若是SFT场景：
- 获取用户自备训练集路径；验证集可选。
- 加载
references/模型精调数据集格式指南/SFT.md，根据模型类型和数据内容校验格式。
- 若用户未提供验证集，可询问是否需要配置
validation_percentage 或不配置验证集；不得强制划分测试集。
- SFT训练数据存放或引用至工作区
data/ 目录，保留原始文件不变。
- 若是RL/RFT/GRPO场景，首先询问用户数据集提供方式：
- 若用户分别提供了训练集和测试集：直接获取两个文件的路径，无需划分
- 若用户只提供了一个数据集：询问用户期望的训练集/测试集划分比例（例如8:2、7:3等），按用户指定比例划分
- RL/RFT/GRPO训练集存放至工作区
data/ 目录
- RL/RFT/GRPO测试集单独存放用于后续评估
✅ 自我验证：SFT确认训练数据格式通过；RL/RFT/GRPO确认训练集和测试集是两个独立的文件
📝 初始评估前信息确认（仅RL/RFT/GRPO）
🔴 强制要求：RL/RFT/GRPO初始评估前必须执行，用户确认后才能继续；SFT场景跳过本节
-
整理初始评估相关的关键信息，示例格式：
📊 初始评估前信息汇总
====================================
Python环境：conda环境 py310 (ark-sdk v2.1.0)
工作目录：/home/user/ark_training/my_project
测试集：test.jsonl (200条)
Rollout文件：/home/user/ark_training/rollout.py
Grader文件：/home/user/ark_training/grader.py
评估模型：doubao-seed-1-6
评估配置：每个样本8次rollout，最大并发15
====================================
-
向用户说明初始评估流程：
📋 即将执行初始评估：
1. 在测试集上运行模型评估，计算BON/AON/AvgN指标
2. 根据BON指标自动选择训练策略（BON<0.3：RFT+GRPO；BON≥0.3：直接GRPO）
3. 评估结果将作为训练策略选择的唯一依据
-
询问用户：「以上评估信息是否确认无误？是否开始初始评估？」
-
只有用户明确确认后，才能进入初始评估步骤
⚠️ 未获得用户确认不得执行评估任务
Step 4. 初始模型评估（仅RL/RFT/GRPO）
RL/RFT/GRPO必须执行，不得跳过；SFT场景跳过本步骤
- 先把
rollout.py 中的 model= 字段改成当前基础模型（按「评估前强制步骤：把 rollout 的 model 字段改成当前评估对象」中的流程操作）。本次评估对象是 Step 2.5 确认的基础模型名+版本（如 doubao-seed-1-6-flash-250615）。
- 调用
ark-trainer-helper train evaluate（使用完整路径）在测试集上评估当前基础模型效果。--output-dir 必须指向本次实验子目录下的 eval_output/（不是工作区根目录、不是其他实验目录）：
ark-trainer-helper train evaluate \
--dataset <测试集路径> \
--rollout <rollout.py路径> \
--grader <grader.py路径> \
--output-dir experiments/exp_xxx/eval_output
- 计算并输出 BON/AON/AvgN 指标
- 自动保存完整轨迹数据到输出目录，可用于后续bad case分析
- 运行日志自动落在
experiments/exp_xxx/eval_output/logs/eval_YYYYMMDD_HHMMSS.log（与结果天然绑定在同一目录，查 bad case 时无需跨目录翻找）
⚠️ RL/RFT/GRPO不允许跳过该步骤，训练策略选择必须基于评估结果。
⚠️ 本命令不接受 --model 参数；实际评估的模型完全由 rollout.py 内部 model= 字段决定。每次执行evaluate命令前，务必检查 rollout.py 中的 model= 字段是否与当前预期评估对象一致。
Step 5. 训练策略决策（仅RL/RFT/GRPO）
RL/RFT/GRPO必须基于BON指标判断，不得提前选择策略；SFT场景按用户明确意图直接走SFT策略
- 当BON < 0.3：使用「先RFT再GRPO」策略
- 当BON ≥ 0.3：使用「直接GRPO」策略
📝 正式训练前信息确认
🔴 强制要求：正式训练前必须执行，用户确认后才能继续
-
整理评估结果和训练相关的所有关键信息，示例格式：
📊 正式训练前信息汇总
====================================
初始评估结果：
BON Score: 0.21 / AON Score: 0.05 / AvgN Score: 0.18
训练策略：BON=0.21 < 0.3，采用「先RFT再GRPO」策略
训练配置：
训练类型：默认使用LoRA训练（FinetuneLoRA + GRPOLoRA）
RFT Teacher模型：doubao-seed-1-6 或 cm-xxxxxxxxxxxx-xxxxx（用户提供）
训练集：train.jsonl (1000条)
Rollout/Grader文件与评估阶段一致
====================================
SFT场景示例：
📊 SFT训练前信息汇总
====================================
训练策略：SFT监督微调（用户自备训练数据）
数据集格式校验：已按 references/模型精调数据集格式指南/SFT.md 检查通过
训练类型：默认使用LoRA训练（FinetuneLoRA），如用户明确要求全量则使用FinetuneSft
基础模型：doubao-seed-1-6-flash (version 250828)
训练集：data/sft_train.jsonl (1000条)
验证集：未配置 / validation_percentage=10 / data/sft_val.jsonl
====================================
-
向用户说明完整训练流程：
📋 即将执行完整训练流程：
【先RFT再GRPO策略】
1. 使用teacher模型在训练集上生成RFT轨迹数据
2. 筛选reward=1.0的优质轨迹生成RFT训练数据
3. 提交RFT训练任务
4. RFT完成后提交GRPO训练任务
5. 训练完成后在测试集上重新评估模型效果
6. 输出最终效果提升报告和模型ID
（如果是直接GRPO策略则对应调整流程说明）
SFT场景需说明：
📋 即将执行SFT训练流程：
1. 使用用户自备训练集提交SFT训练任务
2. 跟踪训练任务状态
3. 训练完成后返回模型ID
4. 如用户提供评估集和评估方式，再执行后续效果评估
-
明确询问用户：「以上训练信息是否确认无误？是否同意开始正式训练？」
-
只有当用户明确回复确认后，才能进入后续训练执行步骤
-
如果用户对配置有异议，先调整相关参数，重新确认后再执行
⚠️ 严禁在未获得用户明确确认的情况下提交任何训练任务
策略零：SFT监督微调
适用条件：用户明确要做SFT/监督微调，且训练数据由用户自行准备。SFT不是RFT，不需要teacher模型，不需要rollout/grader，不需要初始BON评估。
-
确认训练目标与数据类型：
- 获取基础模型名和版本、训练集路径、可选验证集路径或验证集切分比例。
- 判断数据属于文本生成、多模态、视频生成、文本向量化、Function Calling、thinking/reasoning_content等哪类格式。
- 读取
references/模型精调数据集格式指南/SFT.md；若包含图片、视频、Function Calling或thinking字段，再按「数据集格式指南按需加载」读取对应附录。
-
检查SFT数据集格式：
- 检查JSONL每行都是合法JSON，单条样本独占一行。
- 检查文件绝对路径不包含
*、?、[、]。
- 按SFT指南校验训练集和可选验证集的必填字段、字段类型、角色顺序、
loss_weight、thinking、reasoning_content、多模态资源地址。
- 如果格式不符合要求，明确列出问题行号和字段原因，要求用户修正；不得自动提交训练任务。
-
配置SFT训练任务：
- 默认使用LoRA训练：
customization_type: FinetuneLoRA。
- 如果用户明确要求全量SFT，使用
customization_type: FinetuneSft，并提前告知全量训练产物可能不支持自动创建共享端点。
- 必须从模板起步：把
references/templates/job_sft_lora.yaml（YAML）或 references/templates/job_sft_lora.py（Python）复制到本次实验子目录（experiments/exp_xxx/job.yaml 或 job.py），再按实际情况改值。严禁从零手写 job 文件，也严禁参考其他实验子目录里已有的 job 文件当模板。
- 按实际改的内容包括：
name、model_reference.foundation_model.{name, model_version}（model_version 必须是字符串！）、data.training_set.local_files、hyperparameters、可选 data.validation_set 或 data.validation_percentage。
hyperparameters 只保留 Step 2.5 查询到的白名单字段，模板里默认带的字段如果不在白名单内必须删除。- 更深入的字段含义可参考
references/ark-sdk guide.md 中「精调参数的配置」章节；模板文件头的注释也给出了常见踩坑速查。
- 严禁在工作区根目录或其他实验子目录中创建或修改
job.yaml。
- 提交前必须执行
ark get foundation-model --model <基础模型名> --version <版本号> --fields hyperparameters 查询该模型版本支持的 FinetuneLoRA 或 FinetuneSft 超参数，并只配置查询结果允许的字段。
- SFT任务不要配置
custom_rl_pipeline，不要配置 enable_trajectory。
-
提交前确认：
- 向用户展示基础模型、训练类型、训练集/验证集、数据格式校验结果、超参数、本次实验子目录的绝对路径、预计提交命令。
- 用户明确确认后，先在实验子目录执行 FaaS 权限修复命令（见下方「提交前强制步骤：修复 FaaS 权限」），再执行
ark create mcj -f job.yaml 提交任务（或使用绝对路径提交）。
策略一：先RFT再GRPO
-
RFT数据准备：
- 要求用户提供RFT数据收集使用的teacher模型（可以是基础模型名+版本、端点ID或自定义模型ID；不要强制要求必须是
cm-）
- teacher模型可与初始评估的基础模型不同；但后续RFT训练任务的基础模型仍必须使用初始评估阶段的基础模型
- ⚠️ 注意：不得复用初始评估阶段的轨迹数据，必须使用teacher模型重新生成轨迹
- 先把
rollout.py 中的 model= 字段改成 teacher 模型（按「评估前强制步骤：把 rollout 的 model 字段改成当前评估对象」流程操作；初始评估时改过的值需要在此重新改为 teacher 模型）。
- 调用
ark-trainer-helper train evaluate（使用完整路径）使用teacher模型在训练集上运行，生成完整轨迹数据。--output-dir 必须指向当前实验子目录下的 rft_eval_output/：
ark-trainer-helper train evaluate \
--dataset <训练集路径> \
--rollout <rollout.py路径> \
--grader <grader.py路径> \
--output-dir experiments/exp_xxx/rft_eval_output
日志自动落在 experiments/exp_xxx/rft_eval_output/logs/eval_YYYYMMDD_HHMMSS.log。
⚠️ 本命令不接受 --model 参数；teacher 模型必须已经写入 rollout.py。若漏改，收集到的将是上一次 rollout 中的模型的轨迹，RFT 训练数据质量失去可信性。
- 调用
ark-trainer-helper train rft-data-collect（使用完整路径）从评估结果中筛选reward=1.0的优质轨迹，自动生成符合RFT格式的训练数据。--output-file 建议写在同一实验子目录下：
ark-trainer-helper train rft-data-collect \
--eval-results experiments/exp_xxx/rft_eval_output/eval_results.json \
--output-file experiments/exp_xxx/rft_train_data.jsonl \
--rollout <rollout.py路径>
如果rollout插件无法通过 rollout_tools 或 tools 变量暴露工具定义，改用 --tools-file <tools.json> 要求用户提供tools.json文件显式传入顶层 tools 定义。
-
提交RFT训练任务：
⚠️ 重要提醒：RFT训练使用的基础模型必须与初始评估阶段使用的模型一致！teacher模型仅用于收集RFT轨迹数据，不作为训练的基础模型。
- 必须从模板起步：RFT 阶段本质是 SFT，从
references/templates/job_sft_lora.yaml 或 job_sft_lora.py 复制到本次实验子目录起步，严禁从零手写。
- 训练类型选择：默认
FinetuneLoRA；用户明确要求全量时才用 FinetuneSft。
- 基础模型配置：使用初始评估阶段的基础模型（不要使用 teacher 模型）
- 使用上一步生成的 RFT 训练数据作为训练集（填入
data.training_set.local_files）
hyperparameters 只保留 Step 2.5 查询到的白名单字段- 深入字段含义参考
byted-ark-trainer/references/ark-sdk guide.md（使用完整路径）中「精调参数的配置」章节
- 配置完成后在实验子目录内先执行 FaaS 权限修复命令（见「提交前强制步骤：修复 FaaS 权限」），再执行
ark create mcj -f job.yaml 提交任务
策略二：直接GRPO
跳过RFT阶段，直接提交GRPO训练任务：
- 必须从模板起步：把
references/templates/job_grpo_lora.yaml 或 job_grpo_lora.py 复制到本次实验子目录起步，严禁从零手写。
- 更深入的字段含义参考
byted-ark-trainer/references/ark-sdk guide.md（使用完整路径）和 byted-ark-trainer/references/RL guide.md（使用完整路径）文档
- 在本次实验子目录（
experiments/exp_xxx/）下创建 job.yaml，不得放在工作区根目录
- 使用基础模型作为训练起点（配置
foundation_model 字段）
- 训练类型选择：
GRPO 或 GRPOLoRA
- 正确配置rollout和grader plugin参数
- 建议开启轨迹分析功能
- 配置完成后在实验子目录内先执行 FaaS 权限修复命令（见「提交前强制步骤：修复 FaaS 权限」），再提交任务
- 任务提交成功后：更新
EXPERIMENT.md（含后续流程=「GRPO完成后在测试集上评估并输出BON/AON/AvgN对比」）；必须用 ark-trainer-helper job register-heartbeat 命令登记到 HEARTBEAT.md，严禁手写
提交前强制步骤：修复 FaaS 权限
⚠️ 在任何 ark create mcj / python job.py 提交命令之前，必须先在工作区根目录下执行以下两条命令，给 FaaS 足够的目录遍历权限和文件读取权限：
find . -type d -exec chmod 755 {} \;
find . -type f -name "*.py" -exec chmod 644 {} \;
评估前强制步骤：把 rollout 的 model 字段改成当前评估对象
⚠️ ark-trainer-helper train evaluate 不提供 --model 参数；实际请求打到哪个模型完全由 rollout.py 内部 chat.completions.create(model="...") 传入的字符串决定。每次 evaluate（及 RFT 数据收集阶段的 evaluate）之前，必须先按本步骤把 rollout 中的 model= 改成本次要评估的对象，不得省略。
什么时候必须改 model？
在 byted-ark-trainer 流程中，以下三个时机都会调用 train evaluate，每个时机对应的评估对象不一样：
- Step 4 初始评估：评估对象 = Step 2.5 确认的基础模型（形如
doubao-seed-1-6-flash-250615，即「基础模型名-版本」拼接）。
- 策略一 RFT 数据收集：评估对象 = 用户指定的 teacher 模型（可以是基础模型名+版本、端点ID
ep-xxx、或自定义模型ID cm-xxx）。
- 训练完成后评估：评估对象 = 本次训练产出的自定义模型ID（
ark-trainer-helper job get-model 返回的 cm-xxxxxxxxxxxx-xxxxx）。
--output-dir 必须指向实验子目录
- 每次 evaluate 的
--output-dir 必须指向当前实验子目录下的一个子目录，推荐命名：
- 初始评估：
experiments/exp_xxx/eval_output
- RFT 数据收集：
experiments/exp_xxx/rft_eval_output
- 训练后评估：
experiments/exp_xxx/final_eval_output
- 不允许使用
./eval_output、./final_eval_output 等相对工作区根目录的路径——否则不同实验的评估结果会互相覆盖，而且无法通过实验子目录定位评估产物。
- 运行日志由本命令自动写入
<output-dir>/logs/eval_YYYYMMDD_HHMMSS.log（10MB 自动轮转）。结果与日志天然绑定在同一目录，便于 bad case 分析和心跳接手 AI 排查。
- 评估完成后要把本次
--output-dir 的绝对路径增量记录到 EXPERIMENT.md，便于后续对比。
训练完成后流程
- 训练任务完成后，用
ark-trainer-helper job get-model --job-id <任务ID> 获取训练产出的自定义模型 ID（格式 cm-xxx）。禁止让用户手动去控制台查询，也不得自己编造或假设模型 ID。
- RL/RFT/GRPO场景：先把
rollout.py 中的 model= 字段改成本次训练产出的自定义模型ID（cm-xxxxxxxxxxxx-xxxxx），再调用 ark-trainer-helper train evaluate（使用完整路径）在测试集上重新评估模型效果。--output-dir 必须指向当前训练任务所属实验子目录下的 final_eval_output/（与该次训练的 job.yaml、初始评估的 eval_output/ 同级）：
ark-trainer-helper train evaluate \
--dataset <测试集路径> \
--rollout <rollout.py路径> \
--grader <grader.py路径> \
--output-dir experiments/exp_xxx/final_eval_output
日志自动落在 experiments/exp_xxx/final_eval_output/logs/eval_YYYYMMDD_HHMMSS.log。
⚠️ 本命令不接受 --model 参数；要评估的模型完全由 rollout.py 中 model= 决定。忘改 rollout 将导致「训练前后对比」其实对比的是同一个模型两遍，BON/AON/AvgN 数字差异毫无意义。详见「评估前强制步骤：把 rollout 的 model 字段改成当前评估对象」。
- SFT场景默认只返回任务详情和模型ID；如果用户提供评估集、评估脚本或明确要求效果评估，再按用户给定方式执行评估。
- RL/RFT/GRPO场景对比训练前后的BON/AON/AvgN指标，输出效果提升报告。
- 提供任务详情链接和模型ID给用户。
训练类型说明
- SFT默认配置：默认使用
FinetuneLoRA；若用户明确要求全量SFT，使用 FinetuneSft。
- RL默认配置：默认使用LoRA训练模式（FinetuneLoRA/GRPOLoRA），训练速度快、资源占用低，且支持自动创建共享端点。
- 全量训练：若用户明确要求使用全量训练（FinetuneSft/GRPO），需提前告知用户：全量训练产出的自定义模型可能不支持自动创建共享端点，需要用户自行部署模型并提供端点ID才能进行后续流程。
任务提交后流程
1. 任务状态跟踪
训练任务提交后，通过心跳任务跟踪任务状态：
📝 心跳任务添加方式
心跳任务可能在另一个新的AI会话中被触发，当前上下文届时不可用。HEARTBEAT.md 本身只承担索引的作用——它告诉接手的AI「有哪些任务需要监控」「去哪里读完整上下文」；所有详细信息（实验计划、已确认信息、后续流程）统一保存在每个实验子目录下的 EXPERIMENT.md，不在 HEARTBEAT.md 中冗余登记。
✅ 登记任务：必须使用 helper 命令，禁止手写
登记训练任务到 HEARTBEAT.md 的唯一允许方式是调用以下命令：
ark-trainer-helper job register-heartbeat \
--job-id <任务ID> \
--job-type <SFT/RFT/GRPO/RFT+GRPO 等> \
--job-url <控制台任务详情链接> \
--exp-dir <实验子目录绝对路径> \
[--submit-time 'YYYY-MM-DD HH:MM']
[--status Running]
[--heartbeat-file ~/.openclaw/workspace/HEARTBEAT.md]
该命令会自动：
- 若
HEARTBEAT.md 不存在 → 用完整模板创建（含 6 条 AI 接手必读系统提醒 + 表头 + 新任务一行）
- 若
HEARTBEAT.md 已存在但顶部系统提醒块缺失/不完整 → 在文件最顶部自动补齐提醒块，再 append 新任务行
- 若同
--job-id 已登记 → 幂等跳过，不重复写
⛔ 严禁使用文本编辑器（edit / write）直接修改 HEARTBEAT.md——人肉写法几乎必然漏掉顶部系统提醒块，导致心跳触发时接手的 AI 丢失必要上下文。只有当 helper 命令不可用（例如脚本报错、Python 环境挂了），并且已经向用户报告并获得用户明确同意时，才可以退回到手写方式；手写时必须按本章末尾的文件模板完整复制顶部系统提醒块。
HEARTBEAT.md 的规范文件模板（仅用于排查/理解；不要据此手动编辑文件）
# byted-ark-trainer心跳监控任务列表
> ⚠️【系统提醒 · AI接手训练任务时必读】
> 1. **必须先加载 ark-trainer skill**：保持 ark-trainer skill 始终在上下文中，若不在则主动加载 ark-trainer skill（读取该skill的SKILL.md）。
> 2. **接手任务前必须先读取对应的实验目录**：在处理下表任何任务前，必须先打开该任务「实验目录绝对路径」下的 `EXPERIMENT.md`，理解实验计划、已与用户确认的关键配置、后续流程。**不读完 `EXPERIMENT.md` 不允许执行任何动作**。
> 3. **逐项检查任务状态**：对下表每个ARK训练任务执行 `ark-trainer-helper job status --job-id <任务ID>` 查询最新状态，并把结果同步回下表的「最新状态」列。
> 4. **任务完成且有后续流程时，不需要用户二次确认**：若任务状态变为 Completed，按该任务 `EXPERIMENT.md` 中「后续流程」的记录**立即执行下一步**（例如 RFT 完成后提交 GRPO、训练完成后在测试集上评估），执行完毕后再通知用户结果，并把结果增量更新到 `EXPERIMENT.md`。
> 5. **任务失败必须报告用户，不得自行移除**：状态为 Failed/Terminated 时，立即向用户展示完整错误信息和失败原因，询问是否重试或调整配置；**只有在用户明确确认后才能将该任务从下表中移除**，在用户确认之前必须保留该条目以便追溯。
> 6. **严禁编造上下文**：如果实验目录或 `EXPERIMENT.md` 缺失导致无法理解任务意图，不得自行猜测，必须先询问用户。
| 任务ID | 任务类型 | 提交时间 | 最新状态 | 任务链接 | 实验目录绝对路径 |
|--------|----------|----------|----------|----------|------------------|
| mcj-20260425143200-sft01 | SFT | 2026-04-25 14:32 | Running | https://console.volcengine.com/ark/... | /abs/path/workspace/experiments/exp_xxx |
其他允许的人工改动（用编辑器直接改是 OK 的）
- 心跳触发时更新「最新状态」列（
Running → Completed / Failed 等）
- 用户明确确认删除 Failed/Terminated 任务条目后，删除对应那一行
除以上两种情况，其它所有新增/重写动作必须走 ark-trainer-helper job register-heartbeat。
🔄 心跳触发时的处理逻辑
每次心跳任务触发时（可能在新的AI会话中），执行以下操作：
- 上下文恢复：
- 先确认 ark-trainer skill 已加载；未加载则主动加载
- 读取
HEARTBEAT.md 顶部的系统提醒并严格遵守
- 遍历任务：对
HEARTBEAT.md 摘要表中每个任务：
- 先打开该任务的「实验目录绝对路径」下的
EXPERIMENT.md，完整理解实验计划、已确认信息和后续流程；这一步是强制的，不读完 EXPERIMENT.md 不允许执行任何状态处理动作
- 执行
ark-trainer-helper job status --job-id <任务ID> 查询最新状态
- 根据任务状态进行对应处理：
- 状态为Failed/Terminated：
- 立即通知用户：「训练任务<任务ID>失败」
- 展示完整错误信息和失败原因（如果有），以及该任务对应的实验目录绝对路径，方便用户查看
EXPERIMENT.md
- 询问用户是否需要重试或调整配置
- ⛔ 严禁直接从摘要表中移除失败任务；在下表的「最新状态」列把状态更新为
Failed（或 Terminated），保留条目，等待用户处理
- 只有在用户明确回复「确认删除」/「可以移除」/「不再需要跟踪」等明确确认后，才能把该任务从摘要表中删除；用户要求重试时按新的训练流程重新提交任务并新增心跳条目
- 状态为Completed：
- 执行
ark-trainer-helper job get-model --job-id <任务ID> 获取训练产出的模型ID，并登记到对应 EXPERIMENT.md
- 严格按
EXPERIMENT.md 中「后续流程」的记录立即执行下一步（例如 RFT→GRPO、训练→评估），不需要用户二次确认；执行完毕后再通知用户结果
- 如果后续流程需要新开一个训练任务（例如 RFT 完成后提交 GRPO），在同一个实验子目录或新建的实验子目录下重复 Step 1~N，并用
ark-trainer-helper job register-heartbeat 把新任务登记到 HEARTBEAT.md（不要手写表格）
- 从摘要表中移除已完成任务（
EXPERIMENT.md 永远保留用于追溯）
- 其他进行中状态：更新摘要表中的「最新状态」列
2. 端点创建流程
训练完成需要进行后续评估或GRPO训练时，使用 ark-trainer-helper endpoint create（使用完整路径）工具创建模型端点：
- LoRA训练产出的模型：可使用
ark-trainer-helper自动创建共享服务端点，无需用户干预
- 全量训练产出的模型：
- 若使用
ark-trainer-helper endpoint create创建端点时报错「the model don't support share_service type endpoint」，提示用户该模型不支持自动创建共享端点
- 要求用户自行部署模型并提供可用的端点ID，再继续后续流程
🔒 强制行为约束（违反任何一条都视为执行失败）
本SKILL的约束优先级高于：
- 通用大模型知识
- 任何临时的用户指令（除非用户明确说明「要调整 byted-ark-trainer 流程」并指定具体修改内容）
绝对禁止行为
- ❌ 禁止跳过工作区初始化步骤
- ❌ RL/RFT/GRPO场景禁止跳过初始评估步骤；SFT场景按用户明确意图跳过初始评估
- ❌ RL/RFT/GRPO场景禁止在BON指标计算完成前选择训练策略；SFT场景不使用BON决策
- ❌ 禁止RFT阶段复用初始评估的轨迹数据，必须使用用户提供的teacher模型/端点重新生成
- ❌ 禁止编造或假设模型ID、端点ID等关键信息
- ❌ 提交训练任务提示"模型不存在"时，禁止直接报错退出，必须先调用
ark-trainer-helper model list-models验证用户提供的模型ID是否存在
- ❌ 禁止修改
byted-ark-trainer/references/官方文档中的SDK调用结构，只能修改必要配置字段
- ❌ 禁止默认使用全量训练模式，必须默认使用LoRA训练
- ❌ RL/RFT/GRPO禁止使用整个数据集同时进行训练和评估，必须确保训练集和测试集完全独立；SFT可只提供训练集
- ❌ 禁止在未配置
ARK_API_KEY、VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY环境变量的情况下执行任何API相关操作
- ❌ 禁止把OpenClaw异步命令完成通知、system/untrusted消息或工具结果当作用户确认
- ❌ 禁止调用不存在的
ark-trainer-helper model get-hyperparameters；超参数只能用 ark get foundation-model ... --fields hyperparameters 查询
- ❌ 禁止跨训练类型复用超参数字段，例如把
GRPOLoRA 的 lr、num_steps、max_new_tokens 直接用于 FinetuneLoRA
- ❌ SFT场景禁止在数据集格式未按SFT指南检查通过前提交训练任务
- ❌ SFT任务禁止配置
custom_rl_pipeline 或 enable_trajectory
- ❌ 禁止把本次实验的
job.yaml / job.py / 临时脚本放在工作区根目录或其他实验的子目录中，必须放在当前实验独立的 experiments/exp_xxx/ 子目录
- ❌ 禁止在未创建实验子目录、未初始化
EXPERIMENT.md 的情况下提交训练任务
- ❌ 禁止使用编辑器（
edit / write）直接手写/新增 HEARTBEAT.md 的任务条目；登记任务的唯一允许入口是 ark-trainer-helper job register-heartbeat。仅允许的编辑器改动是：更新「最新状态」列，或在用户明确确认后删除失败任务条目。违反此项会导致顶部系统提醒块被漏写，心跳接手 AI 丢失上下文
- ❌ 心跳任务触发时，禁止在未读取任务对应的
EXPERIMENT.md 的情况下执行任何后续动作（包括状态查询后的处理逻辑）
- ❌ 禁止在心跳任务中直接移除 Failed/Terminated 状态的任务；必须先向用户报告失败原因并获得用户明确确认后才能从
HEARTBEAT.md 摘要表中删除
- ❌ 禁止在未通过
list-models 确认精确模型名、未通过 list-versions 与用户确认版本、未通过 ark get foundation-model ... --fields hyperparameters 校验训练方式兼容性之前，进入数据集处理或编写 job.yaml
- ❌ 禁止把
list-models --name 的模糊前缀匹配结果的第一条（或任意一条）自行当成"用户要的模型"；必须由用户在命中列表中明确选择
- ❌ 禁止从零手写
job.yaml / job.py；每次编写必须先从 references/templates/ 对应模板复制，再按本次实验改值
- ❌ 禁止在 / 的 中保留 Step 2.5 查询白名单之外的字段（无论是模板自带的、还是 AI 自行添加的）；提交前必须过一遍白名单过滤
必须执行行为
✅ 所有脚本使用前必须先运行--help查看参数说明
✅ 使用用户指定Python执行helper；首次使用前必须确认依赖可用
✅ 从.env加载密钥时必须确保变量被导出给Python子进程
✅ 提交训练任务前必须查询并校验当前模型版本支持的训练超参数
✅ SFT场景必须按需加载 references/模型精调数据集格式指南/SFT.md 和相关附录，检查用户提供的数据集格式
✅ 关键配置（训练类型、超参数、模型选择）必须向用户确认后再提交任务
✅ 任何 ark create mcj / python job.py 提交命令之前，必须先在实验子目录内执行 FaaS 权限修复命令（find . -type d -exec chmod 755 {} \; 和 find . -type f -name "*.py" -exec chmod 644 {} \;），详见「提交前强制步骤：修复 FaaS 权限」
✅ 任何 ark-trainer-helper train evaluate 之前（包括初始评估、RFT 数据收集、训练后评估三个时机），必须先手工把 rollout.py 中 chat.completions.create(model=...) 的 model 字段改成当前评估对象（基础模型名+版本 / teacher 端点ID / 训练产出 cm-xxx）；详见「评估前强制步骤：把 rollout 的 model 字段改成当前评估对象」
✅ train evaluate 的 --output-dir 必须指向当前实验子目录下的子目录（experiments/exp_xxx/eval_output / rft_eval_output / final_eval_output），运行日志会自动落在 <output-dir>/logs/ 下，与评估结果同目录便于排查
✅ 全量训练前必须明确告知用户端点创建风险并获得用户确认
✅ 每个步骤执行完成后必须验证成功才能进入下一步
✅ 遇到任何错误或不明确的情况必须立即停止并询问用户，不得自行处理
✅ 调用scripts目录下的脚本或读取references目录下的文档时，必须使用完整路径或确保当前工作目录为 byted-ark-trainer skill 的安装目录
✅ 每次训练任务都必须有一个独立的 experiments/exp_<时间戳>_<任务描述>/ 子目录；该子目录内必须同时存在 EXPERIMENT.md 与 job.yaml（或 job.py）
✅ 随着与用户的确认推进，必须增量地把每一项已确认的信息写入 EXPERIMENT.md，确保该文件任何时刻都是「接手AI能够独立理解当前任务」的充分上下文
✅ 向 HEARTBEAT.md 登记任务时必须用 ark-trainer-helper job register-heartbeat 命令；该命令会自动维护顶部系统提醒块并把新任务行 append 到摘要表。详细上下文统一写入 EXPERIMENT.md，HEARTBEAT.md 中不再冗余登记
✅ 心跳任务检测到 Failed/Terminated 状态时，必须先向用户报告并等待用户确认后，才能从摘要表中删除对应条目
✅ 进入数据集处理之前，必须按 Step 2.5 完成「模型存在确认 → 版本选择 → 训练方式兼容性与超参数校验」三步，并把结论写入 EXPERIMENT.md 的「基础模型与训练方式确认」一节
参考文档
- 训练任务配置模板（编写 job 文件的第一去处）：
byted-ark-trainer/references/templates/ - 提供 SFT-LoRA 和 GRPO-LoRA 的 job.yaml + job.py 现成模板。每次编写 job.yaml / job.py 时必须先复制这里对应的模板再改，严禁从零手写。见目录索引 byted-ark-trainer/references/templates/README.md。
- ark-sdk 使用指南：
byted-ark-trainer/references/ark-sdk guide.md - 包含环境配置、工作区初始化、任务提交、命令行工具用法等基础内容
- 强化学习配置指南：
byted-ark-trainer/references/RL guide.md - 包含rollout/grader plugin开发规范、配置示例、测试方法等RL训练专属内容
- 模型精调数据集格式指南：
byted-ark-trainer/references/模型精调数据集格式指南/ - 包含SFT、RL、DPO、CPT、Function Calling、多模态、thinking字段等数据格式要求，按训练类型和数据内容加载。
遇到配置或API使用问题时优先查阅上述文档。
