| name | task-skill |
| description | 太极平台训练任务子 skill —— 通过 MCP 协议管理混元训练平台的训练任务（taskId 以 basic_train_ 或 finetuning_ 开头，含模版化训练、自定义训练与模型开发），覆盖任务列表/详情/配置文件查询、分享权限、启动/停止、产出（checkpoint）、克隆任务、异常事件、项目标签等。当用户提及"训练任务 / 我的任务 / 任务状态 / 任务进度 / 启动任务 / 停止任务 / kill 任务 / 任务产出 / checkpoint / 克隆任务 / 自定义训练 / 模版化训练 / 模型开发 / 基模训练"等关键词时，应使用本 skill。 |
| version | 3.0.0 |
| author | taiji-team |
Task Skill（训练任务）
📂 脚本路径：scripts/connect_mcp.py | scripts/tool_manual.py
0. 边界说明
本模块范围：混元训练平台的训练任务，涵盖三类任务——
| taskId 前缀 | 任务类型 | task_category 值 |
|---|
finetuning_ | 模版化训练 | finetuning |
basic_train_ | 自定义训练 | custom_training |
basic_train_ | 模型开发 | model_dev |
覆盖任务列表/详情/配置文件查询、分享权限、启动/停止、产出（checkpoint）、克隆任务、异常事件、项目标签。
⚠️ 排除：
- 任务实例列表 / Pod 列表（
query_hunyuan_train_instance_list / query_hunyuan_train_pod_list）→ 走 instance-skill
- 训练指标查询（
list_hunyuan_train_available_metrics / query_hunyuan_train_metric_text / query_hunyuan_train_metric_chart）→ 不在本 skill，走 metric-skill，仅限自定义训练任务
- 模型转换 / SFT 转 bin →
model-convert-skill
- 应用组 / 资源使用 / 卡时配额 / 任务加白 →
resource-mgmt-skill
- 模型服务 / 服务组 / 实例日志 / 扩缩容 →
service-deploy-skill
缺 wsid / 工作空间上下文时可直调 list_user_workspaces（通过 scripts/tool_manual.py list_user_workspaces 查看参数），无需提示"去加载 workspace-skill"。
🔧 本模块特有行为规则（以下规则仅对本模块生效，不覆盖 §1 通用规则）：
- 误入场景：用户转向"任务实例/Pod/日志、训练指标、模型转换、资源配额"等非训练任务意图时，立即退出。
- 写操作：启动、停止、分享权限、克隆等。
1. 子 skill conventions（模块执行与全局行为）
会话初始化与热更新
首次加载本 skill 时，先在当前 skill 根目录执行：
python3 ./hot_reload.py
用户明确要求“更新 skill / 拉最新版”时执行：
python3 ./hot_reload.py --force
- 本 skill 被包含在
taiji-basic-platform-skills/ 整包中时，脚本会自动委托 basic 整包更新；不要单独覆盖当前子目录。
- 本 skill 被单独安装时，脚本只检查、下载并覆盖当前 skill；其版本与其他 skill、basic 整包互不影响。
- 若在本地开发未发布改动，先设置
TAIJI_NO_HOT_RELOAD=1，避免自动更新覆盖工作区文件。
1.1 凭证与敏感信息
scripts/connect_mcp.py 自动按以下优先级读取太极 PAT Token：环境变量 TAIJI_PAT_TOKEN → ~/.config/taiji/credentials.json。- Token 不属于业务参数；不得在工具 JSON 中传递、猜测、回显，或写入文档/日志/代码/命令示例/最终回复。
- 不得为验证 Token 调用无关工具或执行探活；直接执行用户真正需要的首个业务调用。
- 首次业务调用返回
NO_TOKEN_CONFIGURED/401/403 或明确凭证失效错误时，才引导用户提供或更新 Token（指引用户打开 https://taiji.woa.com/#/project-list → 工作台 → 右上角企业微信名 → 查看 ApiToken）。
- 收到 Token 后保存：
python3 scripts/connect_mcp.py save-token '<token>'，保存后只重试原请求一次；仍失败则如实报告并停止。网络错误/5xx/超时/响应解析错误不得归因于 Token。
1.2 本模块调用路径
用户 prompt
↓
⓪ 先看§0 边界说明——确认请求属于本模块；不属于则立即退出切换
↓ 属于本模块
① 查§3快速路由表——命中【流程文档】→ 先完整读该文档再规划；或者命中【工具链路】 → tool_manual.py 批量获取参数细节
↓ 未命中
② 语义分析：工具名/参数已确定 → 直接调用；不确定 → scripts/tool_manual.py <tool1> <tool2> ...
（仅对确定要调用的工具名批量获取，严禁逐个查询）
↓
③ ✅ 唯一调用通道：scripts/connect_mcp.py call <tool_name> '<json>'
- references 分两类，取用方式不同：
- 流程文档（
*_flow.md/*_analysis.md）——§3 命中或语义判定需要时必须先完整阅读该文档再执行，不得仅凭 §3 一行字直接调工具；
- 工具手册（
*_api.md，由 tool_manual.py 按需提取）——只提供单工具参数规则。
- 工具名或参数有任何不确定时，先基于 §2 用途列和 query 语义确定目标工具名，然后运行
tool_manual.py <tool1> <tool2>——仅对确定要调用的工具名批量获取参数，如果不能精确确认，可以适当多传，但严禁多轮逐个查询。
- 结果为空、工具返回错误、权限不足、网络失败或超时时，及时停止、如实说明返回信息；不得编造结果、自行暴力搜索、URL、资源状态或成功结论。当工具不支持用户要求的筛选维度或操作时，及时告知用户能力边界，不得通过写脚本、分页遍历客户端过滤等方式绕过。用准确的名称/ID查不到时，直接告知用户找不到，不得换模糊关键词、换工具反复尝试。
- 页面 URL 只能原样使用工具返回字段；严禁根据 ID、历史格式或推测拼接 URL。
- MCP 输出截断规则：当输出过长被截断（
Output too large）时，严禁再次调用 MCP 工具（如缩小 page_size 重查）。正确的处理方式是：用 Read 工具直接读取提示中指定的缓存文件路径，或使用 grep/head/tail 等轻量命令快速定位内容。MCP 调用昂贵（耗时 + Token），Read 和 grep 几乎零成本。
connect_mcp.py 是唯一调用通道：严禁改用 mcporter、裸 curl、use_mcp_tool 或自拼 HTTP；报错时仍用 connect_mcp.py 修正重试，不切换调用方式。
1.3 JSON 输出与结果处理
- 所有非交互命令默认向 stdout 输出且仅输出一个合法 JSON 值；Agent 直接使用
json.loads(stdout) 解析结果。
- 列表结果保持接口返回的原始顺序；Markdown 表格结束后必须保留一个空行再输出后续内容。
- 同参数不重调：同一工具同一组参数不得重复调用；返回体过大被落盘时用 Read/grep 处理已落盘文件，不要重新发起同一调用；分页查询按用户指定页/页数调用一次即止。
1.4 Agent 行为与跨模块边界
- 业务参数齐备时，Agent 直接执行工具调用并汇报真实结果；不得把命令交给用户自行运行。
- 仅在缺少工具必填业务字段、当前模块无法确认用户意图、调用失败，或写操作需确认时追问。
- 不得猜测、补全或批量枚举用户未提供的资源标识（工作空间、任务、应用组、模型、服务、路径、URL）。
- 严守用户输入的 id/name：当用户提供的 id/name 无法满足预期行为时（如搜索无结果），禁止自行搜索替代项重试；直接告诉用户实际情况。
- 误入立即退出：进入本模块后，若发现请求核心对象不属于本模块范围，立即切换到正确的子 skill，严禁在本模块内试探性调用。
- 需要跨模块直调工具时，先用
scripts/tool_manual.py <工具名> 确认该工具在本模块 references 中已声明为 helper，再通过 connect_mcp.py 调用。
1.5 写操作与安全
- 创建、更新、删除等写操作，必须遵循对应工具手册的前置查询、影响说明和确认要求。
- 用户未明确目标、范围或影响对象时，不得擅自执行写操作。
- 写操作成功前不得声称已创建、已更新、已停止或已完成。
- 工具专属的覆盖语义、read-modify-write、状态限制、二次确认和成功后停止规则保留在对应工具手册，不得被本节覆盖或弱化。
2. MCP 工具清单表
写操作标记：✍️。完整参数/返回/SOP 用 scripts/tool_manual.py <工具名> 按需获取（一次可传多个工具名）。
| 工具 | 用途 | 写操作 |
|---|
query_hunyuan_train_task_list | 查询训练任务列表（模版化训练/自定义训练/模型开发，支持状态/创建人/应用组/GPU/标签等筛选） | |
get_hunyuan_train_task_detail | 查询任务详情（可指定 instance_id 查某次实例的快照配置） | |
get_hunyuan_train_task_config_file | 查看任务配置文件列表 / 指定文件内容 | |
query_hunyuan_train_checkpoint_list | 查询任务产出列表（Checkpoint，支持模版化训练、自定义训练） | |
update_hunyuan_train_task_permission | 分享 / 移除训练任务的管理员权限（add / remove） | ✍️ |
start_hunyuan_train_task | 运行（启动）训练任务，创建一个新的训练实例并执行 | ✍️ |
stop_hunyuan_train_task | 停止训练任务，自动停止最新运行中的实例 | ✍️ |
clone_hunyuan_train_task | 克隆自定义训练任务并可选修改 GPU 资源、启动命令、配置文件参数、应用组/地域/GPU卡型、基座模型、镜像；支持复制原任务的伴生评估配置 | ✍️ |
clone_hunyuan_train_finetuning_task | 克隆模版化训练任务并可选修改训练数据、超参数、依赖文件 | ✍️ |
query_hunyuan_train_failure_event_list | 查询任务的异常事件（节点故障/GPU 错误，仅自定义训练） | |
list_hunyuan_train_task_tag_enums | 查询任务的项目标签枚举列表（仅自定义训练） | |
⚠️ 以下工具已移出本 skill，请加载 instance-skill：任务实例列表 → query_hunyuan_train_instance_list；Pod 列表 → query_hunyuan_train_pod_list；训练日志 → query_hunyuan_train_instance_logs。训练指标工具不在本 skill，请加载 metric-skill，仅限自定义训练任务。
能力差异矩阵
| 工具 | 模版化训练 | 自定义训练 | 模型开发 |
|---|
query_hunyuan_train_task_list | ✅ | ✅ | ✅ |
get_hunyuan_train_task_detail | ✅ | ✅ | ✅ |
get_hunyuan_train_task_config_file | ✅ | ✅ | ✅ |
update_hunyuan_train_task_permission | ✅ | ✅ | ✅ |
start_hunyuan_train_task | ✅ | ✅ | ✅ |
stop_hunyuan_train_task | ✅ | ✅ | ✅ |
query_hunyuan_train_checkpoint_list | ✅ | ✅ | ❌ |
clone_hunyuan_train_task | ❌ | ✅ | ✅ |
clone_hunyuan_train_finetuning_task | ✅ | ❌ | ❌ |
query_hunyuan_train_failure_event_list | ❌ | ✅ | ❌ |
list_hunyuan_train_task_tag_enums | ❌ | ✅ | ❌ |
跨模块速查工具
直达其他模块，通过 scripts/tool_manual.py <工具名> 确认参数后调用。
| 跨模块工具 | 用途 |
|---|
list_user_workspaces | 直调工作空间查询，缺 wsid 时列出可访问空间供用户选定 |
query_hunyuan_train_instance_logs | 查看训练日志 |
3. 快速路由表（多工具流程编排）
💡 涉及多工具的操作，一次用 scripts/tool_manual.py <工具1> <工具2> ... 批量获取多个工具说明，避免多次调用。
仅列多工具串联流程。单工具场景已在 §2 用途列覆盖。命中时按最小链路执行，避免冗余调用。
| 场景 | 流程 | 流转条件 |
|---|
| 任务失败诊断 | ① get_hunyuan_train_task_detail → ② query_hunyuan_train_failure_event_list → ③ 可选 query_hunyuan_train_instance_logs 查日志补充报错上下文 | 用户想知道任务为什么失败 |
| 任务克隆 | clone_hunyuan_train_task → 如需启动则 start_hunyuan_train_task | 用户说"复制/克隆"；clone 返回新 task_id 后按需启动 |
| 克隆时保留伴生评估 | clone_hunyuan_train_task(copy_evaluation_config=true)，若用户指定了源实例 ID 则加传 copy_evaluation_source_instance_id | 用户说"保留评估/伴生评估/自动评估"；不要切到 evaluation-skill |
| 克隆+伴生+启动 | ① clone_hunyuan_train_task(copy_evaluation_config=true) → ② start_hunyuan_train_task | 用户说"克隆并启动+保留评估"；不先查 detail，写操作无豁免时先确认 |
| 任务配置对比 | ① get_hunyuan_train_task_detail ×2 → ② get_hunyuan_train_task_config_file(file_name="custom.toml") ×2。最多 4 次调用，不追调 failure_event/instance/logs/SwanLab/checkpoint | 用户给两个 task_id 或 URL 做实验/配置对比 |
| 按任务名称对比配置 | ① query_hunyuan_train_task_list(keyword=<名称>) → ② get_hunyuan_train_task_detail → ③ get_hunyuan_train_task_config_file(file_name="custom.toml")，每个名称各走一次，不先查无 keyword 全量列表 | 用户说"比较 A 和 B 的配置" |
| 修改学习率 | ① get_hunyuan_train_task_config_file（不传 file_name，只看配置文件列表）→ ② clone_hunyuan_train_task，config_modifications 用 [{"action":"update","path":"TRAINING_ARGS","key":"lr","value":"<值>"}] | 用户说"改学习率为 X"；不调 detail，不读文件内容，克隆后不验证 |
| 训练数据换成路径 | clone_hunyuan_train_task，config_modifications 使用 [{"action":"update","path":"training","key":"dataset_path","value":"<path>"}] | 用户说"训练数据换成 X"；不传 task_name/description 避免重名冲突 |
| 启动再停止 | ① start_hunyuan_train_task(task_id) → ② stop_hunyuan_train_task(task_id) → ③ get_hunyuan_train_task_detail(wsid, task_id) 确认终态。start/stop 不传 wsid |
4. 模块注意事项
4.1 进入判定
- 何时进入：用户问"训练任务 / 我的任务 / 某人的任务 / 任务状态 / 启动 / 停止 / 任务产出 / ckpt / 克隆任务 / 模版化训练 / 自定义训练 / 模型开发"等任一意图，或 taskId 以
basic_train_ 或 finetuning_ 开头。
- 泛称"训练任务"未分类 → 先追问：用户只说"训练任务/在跑的训练任务"但未明确模版化/自定义/模型开发/全部时，必须先追问 task_category，不调任何工具。不要把泛称默认等同"全部"；只有用户明确说"全部"才分别查三类。
- 范围声明：本 skill 处理
basic_train_*（自定义训练 + 模型开发）和 finetuning_*（模版化训练）前缀任务。任务实例/Pod/日志相关操作已移至 instance-skill。
- raw IP / redirect / base64 / K8s service URL → 不是标准任务链接，不 base64 解码、不猜测 task_id，请用户提供标准链接或 task_id。
4.2 通用参数规则
- wsid 必填工具：
query_hunyuan_train_task_list、get_hunyuan_train_task_detail、get_hunyuan_train_task_config_file、clone_hunyuan_train_task、clone_hunyuan_train_finetuning_task、list_hunyuan_train_task_tag_enums。
- 分页
page 从 1 开始。
- 训练指标已移至
metric-skill（仅限自定义训练）；实例/Pod/日志已移至 instance-skill。
4.3 查列表的强制三要素
调 query_hunyuan_train_task_list 必须传 task_category + wsid + query_type，用户没说时必须追问"工作空间 ID + 想查哪类训练任务"。不要把泛称"训练任务"默认等同"全部"。
- wsid：用户已提供直接使用；未提供必须追问（严禁用
wsid=0 或空值调用）。
- task_category：未明确必须追问；回答"全部"时并行调多次。
- query_type：默认
query_type="all"；"我的"→my_created；"我有权限的"→my_permission。
4.4 任务名定位规则
- 用户说"任务状态"但没给 task_id → 先列任务再让用户挑，严禁猜测 task_id。
- 写入类工具调用前向用户复述操作对象 + 影响，得到确认后才执行；若用户明确说"不需要确认 / 直接执行"，可视为已授权。
- 列表/产出返回的数据必须按原始顺序展示，严禁重排/筛选/截断；默认只取第一页。
- 任务名定位只查一次：用户给的是任务名/非
basic_train_* 字符串时，先按名称和 wsid 定位一次；命中后复用返回的 task_id，不要把名称硬当 task_id 调详情。
4.5 克隆与伴生评估配置
- 用户说"克隆并保留伴生评估"时，调用
clone_hunyuan_train_task 并传 copy_evaluation_config=true，不要切到 evaluation-skill。
- 详细参数规则（
config_modifications 格式、镜像更换、应用组修改流程等）见 clone_hunyuan_train_task 的 api 文档。
4.7 严禁
- ① 把"模型转换 / SFT 转 bin"任务当成训练任务（→
model-convert-skill）；② 把"任务实例 / Pod 列表 / 训练日志"在本 skill 处理（→ instance-skill）；③ 跨用户调 stop_hunyuan_train_task；④ 在没有 wsid 的情况下调用需要 wsid 的工具；⑤ 对 raw IP / redirect / base64 / K8s service URL 做解码或猜测式搜索。
4.8 失败处理
写入失败 → 透传错误原因，不自动重试；权限错误（403）告知用户需要任务 owner 授权或调 update_hunyuan_train_task_permission；网络/超时如实告知，不重试、不切换工具。
4.9 taskId 格式与展示规范
finetuning_ 开头为模版化训练；basic_train_ 开头为自定义训练或模型开发，两者 taskId 格式相同，靠 task_list 返回的 task_category 字段区分（custom_training / model_dev）。- 分页
page 从 1 开始。
- 任务列表必须使用 Markdown 表格展示，禁止嵌套列表/缩进子列表。推荐列：
序号 | 任务名称 | 任务 ID | 描述 | 资源 | 状态 | 创建时间。资源列合并 "N机M卡 卡类型"（finetuning 无资源字段则显示 -）；状态列用 status_text（运行中加 ✅、已终止加 ⏹、已完成显示"结束(成功)"）；创建时间只显示日期部分；表格前显示汇总行，表格后先空一行加 --- 再追加提示；任务 ID 必须展示完整，严禁截断。
- 运行中（TRAINING_RUNNING）任务的
items 中没有 status / status_text / instance_id 字段；仅已完成/已终止/失败的实例才携带。finetuning 类型任务不返回 machine_count / gpu_per_machine / gpu_type / train_framework 等资源字段。
query_hunyuan_train_checkpoint_list 返回：released 为 boolean（true/false），不是字符串；file_size 为整数（字节），不是人类可读字符串。- 每次返回结果后按场景追加引导性问题；Markdown 表格后必须空一行 + 加
--- 分隔线再写引导文字。引导内容根据任务类型智能裁剪（模型开发任务不要引导"查看训练指标"和"查看产出列表"）。
4.6 结果引导规则
每次返回结果后，根据当前场景追加引导性问题，引导用户继续操作。
| 工具 | 推荐引导 |
|---|
query_hunyuan_train_task_list | "查看某任务详情？/ 训练指标？/ 克隆并修改？" |
query_hunyuan_train_checkpoint_list | "查看任务详情？/ 启动新训练？" |
get_hunyuan_train_task_config_file（列表） | "查看某个配置文件内容？请提供文件名。" |
get_hunyuan_train_task_config_file（内容） | "查看其他配置？/ 克隆并修改？" |
start_hunyuan_train_task | "任务已启动。查看实例/训练指标？" |
stop_hunyuan_train_task | "任务已停止。重新启动 / 查看产出？" |
clone_hunyuan_train_task | "新任务已创建。启动 / 查看详情？" |
query_hunyuan_train_failure_event_list | "查看训练日志排查原因？（可直调 query_hunyuan_train_instance_logs，见 helper_api.md）" |
引导内容根据任务类型裁剪（如模型开发不引导"训练指标"）。
4.10 能力边界
- 训完自动导出 mcore：本模块无法持续监测训练完成并自动触发模型转换。用户问"训完自动导出 mcore"时，说明当前能力边界，不要立即调 model-convert-skill 的转换工具。
- 任务配置读取：
get_hunyuan_train_task_config_file 没有 action 参数，不要传 action=list/read。每个 task_id 只调一次配置列表获取全部配置文件清单；读单个文件时才传 file_name。
