| name | swanlab-skill |
| description | 太极平台 SwanLab 实验管理子 skill —— 通过 MCP 协议与 SwanLab 实验跟踪平台交互，提供身份验证、空间管理、项目管理、实验管理、指标查询、日志查看、媒体数据获取等全功能。当用户提及"SwanLab / swanlab / 实验列表 / 实验详情 / SwanLab 项目 / SwanLab 空间 / 实验日志 / 实验配置 / 实验过滤 / 媒体数据"等关键词时，应使用本 skill。 |
| version | 2.0.0 |
| author | taiji-team |
SwanLab Skill（SwanLab 实验管理）
📂 脚本路径：scripts/connect_mcp.py | scripts/tool_manual.py
0. 边界说明
本模块范围：SwanLab 实验跟踪平台的全功能管理——身份验证、空间管理、项目管理、实验管理、指标查询、日志查看、媒体数据获取。本 skill 直接操作 SwanLab 平台，需要用户提供 swanlab_api_key。
跨模块边界：
- 平台预定义内置指标（loss / grad_norm 等）、tf_events 指标、通过 task_id 查 SwanLab 指标（
query_hunyuan_train_swanlab_metrics）→ metric-skill
- 训练任务搜索 / 详情 / 克隆 / 启停 →
task-skill
- 实例列表 / Pod 列表 / 日志 / 在实例 Pod 上执行命令 →
instance-skill
⚠️ 与 metric-skill 的区别：
- metric-skill 中的
query_hunyuan_train_swanlab_metrics：通过 task_id 查 SwanLab 指标，后端自动解析 workspace/project/run_id，用户无需提供 SwanLab API Key
- 本 skill（swanlab-skill）：直接操作 SwanLab 平台，需要用户提供 swanlab_api_key，支持完整的空间/项目/实验管理
🔗 validloss / 伴生 loss：用户给主任务的纯数字 task_id 查 validloss 时，走三步链路（详见 references/validloss_companion_flow.md）：
list_taiji_eval_companion_tasks（evaluation 模块）→ 查伴生任务，返回含 swanlab_run_id、swanlab_project、swanlab_api_token、swanlab_workspacequery_hunyuan_swanlab_run_columns（本 skill）→ 列出可用指标名（伴生指标名是 data/lm loss/{序号}.{数据集} validation 格式）query_hunyuan_swanlab_run_metrics（本 skill）→ 用完整指标名查数据
⚠️ 字段名转换：Step 1 返回字段名是 swanlab_api_token，传给 Step 2/3 时对应参数名是 swanlab_api_key（两者是同一个值，只是字段名不同）。
🔧 本模块特有行为规则（以下规则仅对本模块生效，不覆盖 §1 通用规则）：
- SwanLab API Key：本 skill 的所有工具都需要
swanlab_api_key 参数（SwanLab 平台 API Key，与太极 PAT Token 不同）。当用户未提供 swanlab_api_key 或 $ENV 形式的 key 时，先引导用户："需要您的 SwanLab API Key 才能操作。请在 SwanLab 个人设置页获取 API Key 后提供给我。"
- 流程文档：
validloss_companion_flow.md，§3 命中时先完整阅读再执行。
- 本模块无写操作工具。
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 <工具名> 按需获取（一次可传多个工具名）。
| 工具 | 用途 | 写操作 |
|---|
verify_hunyuan_swanlab_identity | 验证 SwanLab API Key 是否有效，返回用户基本信息 | |
query_hunyuan_swanlab_workspace_list | 查询当前用户可访问的所有空间列表 | |
get_hunyuan_swanlab_workspace_detail | 获取指定空间的详细信息 | |
query_hunyuan_swanlab_project_list | 查询指定空间下的项目列表（分页），支持排序和搜索 | |
get_hunyuan_swanlab_project_detail | 获取指定项目的详细信息 | |
query_hunyuan_swanlab_run_list | 查询指定项目下的实验列表（分页） | |
get_hunyuan_swanlab_run_detail | 获取指定实验的详细信息 | |
get_hunyuan_swanlab_run_profile | 获取实验的 profile 配置（超参数、元数据、依赖包、conda 环境） | |
filter_hunyuan_swanlab_runs | 通过条件过滤实验列表（支持简化模式和高级模式） | |
query_hunyuan_swanlab_run_metrics | 查询实验标量指标数据，支持 step/时间戳范围、采样、全量等模式 | |
get_hunyuan_swanlab_run_summary | 获取实验指标统计摘要（min/max/avg/median/latest） | |
query_hunyuan_swanlab_run_columns | 查询实验的指标列列表，支持按类型和关键词过滤 | |
query_hunyuan_swanlab_run_logs | 获取实验运行时的文本日志，支持偏移分页和级别过滤 | |
query_hunyuan_swanlab_run_medias | 获取实验的媒体数据（图片/音频/视频），返回预签名 URL | |
3. 快速路由表（多工具流程编排）
💡 涉及多工具的操作，一次用 scripts/tool_manual.py <工具1> <工具2> ... 批量获取多个工具说明，避免多次调用。
仅列多工具串联流程。单工具场景已在 §2 用途列覆盖。
| 场景 | 流程 | 流转条件 |
|---|
| validloss / 伴生 loss / 验证 loss / 主任务 loss | 三步链路：① list_taiji_eval_companion_tasks（主任务纯数字 task_id）→② query_hunyuan_swanlab_run_columns（列指标名）→③ query_hunyuan_swanlab_run_metrics（用完整指标名查数据） | 详见 references/validloss_companion_flow.md，三步缺一不可 |
4. 模块注意事项
4.1 通用行为
- 必须有
swanlab_api_key 或 $ENV 形式 key。没有时先引导用户提供，不要空参调用工具。
- 按层级操作：空间 → 项目 → 实验 → 指标/日志/媒体。如果用户直接给了 workspace + project_name + run_id，可以跳过中间步骤。
- 分页数据展示时标注总数和当前页码，引导用户翻页；默认只调用一次列表工具，不要主动翻页/重试同一页，也不要主动补
page/page_size，除非用户明确要求全部、下一页、指定页或每页数量。
- 指标数据展示遵循表格格式 + 统计摘要的规范。
- 成功即停：任一 SwanLab 工具返回
code=0 后，禁止用相同工具+相同参数重复调用；不要为了"验证/格式化/解析"再次请求。
wsid 只是太极上下文备注，不是 SwanLab 工具参数；SwanLab 空间用 workspace 或 username，禁止把 wsid 传给 SwanLab 工具，也不要因出现 wsid 跨调 workspace-skill / 用户组工具。- 对比两个实验 profile 时，对每个
run_id 只调用一次 get_hunyuan_swanlab_run_profile；两次都成功后在本地解析 JSON 对比，禁止因解析失败重复请求同一 run。
4.2 意图到工具强映射
- "空间列表 / 我的 SwanLab 空间" →
query_hunyuan_swanlab_workspace_list，不要用项目列表代替。
- "项目详情 / 项目信息" →
get_hunyuan_swanlab_project_detail。
- "实验详情 / run 详情" →
get_hunyuan_swanlab_run_detail；只有用户要求配置、超参数、环境、profile 时才用 get_hunyuan_swanlab_run_profile。
- "图片 / 音频 / 视频 / 媒体数据 / 预签名 URL" →
query_hunyuan_swanlab_run_medias；图片媒体且用户未指定 key 时默认 keys=["generated_images"]；该工具只调用一次，成功返回空列表时直接说明无媒体数据，禁止再调用 columns/detail 兜底。
- "指标列筛选 / FLOAT 列 / IMAGE 列" →
query_hunyuan_swanlab_run_columns，筛选参数名必须是 column_type，不要写成 type。
- 纯知识问答（如如何获取 API Key）→ 不调用工具，直接说明。
4.3 page_size 取值限制
后端 SDK 只接受白名单值 (10, 12, 15, 20, 24, 27, 50, 100)，传入其他值返回 HTTP 400。
4.4 严禁与失败处理
- 严禁把"通过 task_id 查 SwanLab 指标"的需求在本 skill 处理——那属于 metric-skill 的
query_hunyuan_train_swanlab_metrics。
- 严禁猜测 workspace / project_name / run_id。
- 严禁跨模块路由——用户问"平台内置指标 / 任务 / 实例 / 评测 / 模型"时立即跳出本 skill。
- 严禁工具返回错误后编造搜索结果、页面链接或统计数值。
- 失败处理：API Key 无效 → 提示用户检查 Key；workspace/project/run 不存在 → 提示用户检查名称；401/403 提示 token 失效；网络/超时如实告知，不重试、不切换工具。
