onescience-modelscope-publish

输入获取方式

本技能支持两种输入方式：

1. 上下文 handoff（默认）：从调用方传入的 step_handoff 获取任务信息。
2. 文件 handoff（autonomous_mode）：从 .onescience/handoff/step_{step_id}.yaml 读取任务信息。执行后，将结果写入 .onescience/handoff/step_{step_id}_result.yaml。

启动时优先检查 .onescience/handoff/ 目录是否存在对应的交接文件；若存在则使用文件模式，否则使用上下文模式。

文件交接格式参见 skills/onescience-orchestrator/references/file_handoff_contract.md。

OneScience ModelScope 模型发布

职责边界

本技能负责将论文复现后的模型产物按 ModelScope（魔搭）仓库规范重组为标准目录结构，引导用户推送模型。不执行 modelscope upload 命令本身。

• 作为执行技能：由 onescience-orchestrator 调用，接收标准化输入，返回标准化输出。
• 核心职责：产物扫描归类、目标目录创建、文件复制组织、空目录检查、平台模板生成、上传命令输出。
• 不负责：模型训练、推理验证、ModelScope 账号认证、token 管理、手动分类纠错后的重新打包。

输入输出接口

输入（从 onescience-orchestrator 接收）

pack_handoff:
  source_dir: <论文复现产物根目录（绝对路径）>
  model_name: <ModelScope 上的模型名称，如 "MARIO">
  target_dir: <目标输出目录，可选，默认为当前工作目录>
  modelscope_org: <ModelScope 组织名，可选，默认为 "OneScience">

输出（返回给 onescience-orchestrator）

execution_result:
  skill: onescience-modelscope-publish
  status: <success | partial | failed>
  artifacts:
    target_dir: <目标目录绝对路径>
    directories_created: [model, weight, scripts, conf]
    files_copied_count: <归类复制的文件总数>
    files_excluded_count: <排除的文件总数>
    files_by_category:
      model: <归入 model/ 的文件列表>
      weight: <归入 weight/ 的文件列表>
      scripts: <归入 scripts/ 的文件列表>
      conf: <归入 conf/ 的文件列表>
      excluded: <排除（未复制）的文件列表>
    templates_generated: [configurations.json, README.md]
  observation:
    empty_directories: [<内容为空的子目录名称列表>]
    warnings: [<告警信息列表>]
    script_availability:
      train: <found | missing>
      inference: <found | missing>
      evaluation: <found | missing>
    upload_command: "modelscope upload {org}/{model_name} {target_dir}/{model_name} --token ***"
  notes: <补充说明>

核心流程

阶段一：输入校验

1. 校验 source_dir 是否存在且为有效目录路径。
   • 若不存在，返回 status=failed，提示用户确认产物目录路径。
2. 校验 source_dir 是否有可访问的文件。
   • 若目录为空，返回 status=failed，提示用户确认产物目录是否包含文件。
3. 若 model_name 为空，尝试从 source_dir 的父目录名推断，若仍无法推断，询问用户指定。

阶段二：产物扫描与分类

1. 递归遍历 source_dir 下的所有文件（排除隐藏文件和 .ipynb_checkpoints/）。
2. 对每个文件，按以下文件分类规则确定目标子目录：

扩展名	目标子目录	匹配条件
.py	model/	文件名含：model、net、module、nn、backbone、unet、encoder、decoder、layer、block、attention、transformer、resnet、vgg、densenet、lstm、gru、gan、diffusion、embedding、activation、normalization、conv、pooling、head、neck
.py	scripts/	文件名含：train、infer、eval、test、preprocess、run、main、demo、predict、deploy、serve、download、setup、install、convert、export、benchmark、profile
.py	model/	其他 .py 文件默认归入 model/
.pth, .pt, .ckpt, .safetensors, .bin, .h5, .keras, .onnx, .pb, .pkl, .joblib, .weights	weight/	模型权重文件
.yaml, .yml, .json, .toml, .ini, .cfg, .conf, .config	conf/	配置文件（排除根目录的 configurations.json）
.sh, .bash, .bat, .ps1	scripts/	Shell 脚本
.ipynb	scripts/	Jupyter Notebook
.log, .csv, .tsv, .npy, .npz, .png, .jpg, .jpeg, .pdf, .tar, .gz, .zip, .pickle, .data, .db, .sqlite, .txt, .md, .pkl（非权重类）、.gitattributes、.gitignore	排除	与模型配置/权重/训练测试脚本无关的文件，不放入目标目录

阶段三：目标目录创建与文件复制

1. 确定目标根目录：{target_dir}/{model_name}/。
   • 若 target_dir 未指定，使用当前工作目录。
2. 创建子目录：model/、weight/、scripts/、conf/。
3. 按分类结果将文件复制（非移动）到对应子目录。
   • 源目录中的文件不做任何修改。
   • 若目标文件已存在，覆盖写入（幂等操作）。
4. 输出分类统计信息（每个子目录的文件数量和文件名）。

阶段四：空目录检查

1. 检查以下四个核心目录是否包含文件：

   • target_dir/model/
   • target_dir/weight/
   • target_dir/scripts/
   • target_dir/conf/

2. 若某个目录为空（无任何文件），输出以下格式的告警信息：

   ⚠️ 警告：{子目录名称} 文件夹下内容为空。
   原因：源产物目录中未找到可归类到 {子目录名称}/ 的文件。
   建议：请确认是否需要补充 {对应的文件类型} 后再推送。
   

3. 空目录告警不阻断流程，仅记录在 observation.warnings 和 observation.empty_directories 中。

4. 若所有核心目录均为空，设置 status=partial；否则为 success。

阶段五：模板文件生成

在目标根目录（{target_dir}/{model_name}/）生成以下文件：

5.1 configurations.json（魔搭模型身份证骨架）

{
  "framework": "请根据模型填写，如 PyTorch / TensorFlow / PaddlePaddle",
  "task": "请根据模型填写任务类型",
  "allow_remote": true,
  "model": {
    "type": "请填写魔搭平台识别的模型类型",
    "repo_id": "OneScience/{model_name}"
  },
  "pipeline": {
    "type": "请填写魔搭 pipeline 类型"
  },
  "preprocessor": {},
  "train": {}
}

5.2 README.md（模型卡片页）

README.md 基于 references/template_README.md 的结构生成，并根据 source_dir 扫描结果填充实际内容。生成策略如下：

第一步：扫描 source_dir 收集填充素材

在阶段二文件分类完成后，汇总以下信息：

• 分类到 model/ 的文件名列表（推断模型架构类型）
• 分类到 scripts/ 的文件名列表（识别训练/推理/评估入口脚本）
• 分类到 weight/ 的文件名列表及文件大小
• 分类到 conf/ 的配置文件名列表
• 检测框架类型：若权重文件含 .pth/.pt/.safetensors，框架为 PyTorch；若含 .h5/.keras，框架为 TensorFlow/Keras；默认 PyTorch
• 检测 source_dir 中是否存在论文引用文件（.pdf 文件名、README.md 中的论文标题/链接等）

第二步半：命令可用性检查（在生成 README 命令前执行，静态文件存在性检查）

对于 README 中即将生成的 python scripts/{script_name} 类运行命令，必须先验证目标脚本是否实际存在于 target_dir/scripts/ 目录中，确保生成的命令可执行。

1. 列出 target_dir/scripts/ 目录下所有实际存在的文件名（不含路径前缀），记为 available_scripts。

2. 对以下三类命令，分别检查对应的脚本文件：

   • 训练命令：检查 available_scripts 中是否存在文件名匹配 train 或 run 关键字的 .py 或 .sh 文件
   • 推理命令：检查 available_scripts 中是否存在文件名匹配 infer 或 predict 关键字的 .py 或 .sh 文件
   • 评估命令：检查 available_scripts 中是否存在文件名匹配 eval 或 test 关键字的 .py 或 .sh 文件

3. 检查规则：

   • 若脚本文件存在 → 正常生成实际命令，如 python scripts/train.py
   • 若脚本文件不存在 → 不生成该命令，改用 HTML 注释标注缺失原因，如 <!-- 训练脚本未在 scripts/ 目录中找到，请补充 -->
   • 此规则同样适用于训练节、推理节、评估和可视化节三个章节

4. 此检查仅验证文件是否存在于目标目录，不验证语法正确性、依赖完整性和运行时行为（这些属于用户职责）。

5. 检查结果写入 observation.script_availability：

   observation:
     script_availability:
       train: <found | missing>
       inference: <found | missing>
       evaluation: <found | missing>
   

第三步：按章节构造 README.md

直接输出 Markdown 格式内容，不使用模板变量（除 {model_name}、{modelscope_org} 外）。各章节填充规则：

章节	填充策略
Frontmatter	使用 license: Apache License 2.0；tasks 字段根据 scripts/ 中检测到的脚本类型填入（如 [train, inference, evaluation]），无法确定时使用 - 请根据模型填写任务类型；frameworks 根据检测到的框架类型填入；language 固定 [en, zh]；tags 固定含 OneScience，并进行关键词补充；datasets 若 source_dir 中有明确数据集引用则填入，否则使用 - 请填写训练数据集
模型名称居中标题	<p align="center"><strong><span style="font-size: 30px;">{model_name}</span></strong></p>
# 模型介绍	若 source_dir 中存在 README.md 且含论文描述，提取并改写为模型介绍简介；否则填写 （请在此处描述模型的背景、论文来源和应用场景）
# 模型描述	列出 model/ 中的主要模型文件（如 model.py、net.py 等），根据文件名关键词推测架构类型（如含 transformer → "Transformer 架构"），以列表形式呈现；若 model/ 为空则填写通用占位
# 适用场景	根据 scripts/ 中检测到的脚本生成场景表格，格式：`
# 使用说明 → OneCode 使用	保留模板中的固定内容
# 使用说明 → 手动安装使用 → 硬件要求	保留模板中的 GPU/DCU/CPU 说明
# 使用说明 → 手动安装使用 → 下载模型包	将模板中的 modelscope download --model OneScience/Template 替换为 modelscope download --model {modelscope_org}/{model_name}
# 使用说明 → 手动安装使用 → 安装运行环境	保留 DCU/GPU 的 conda + pip 安装命令
# 使用说明 → 手动安装使用 → 训练数据介绍	若 source_dir 中有数据集相关信息（文件名、路径引用等），生成具体的下载说明；否则保留占位 （请在此处说明训练数据来源和获取方式）
# 使用说明 → 手动安装使用 → 训练	基于第二步半的检查结果：若 script_availability.train == found，生成实际命令（如 python scripts/train.py）；若为 missing，用 HTML 注释标注 <!-- 训练脚本未在 scripts/ 目录中找到，请补充 -->，不生成不可执行的命令
# 使用说明 → 手动安装使用 → 训练权重	若 weight/ 非空，列出权重文件清单；否则填写"即将上传"
# 使用说明 → 手动安装使用 → 推理	基于第二步半的检查结果：若 script_availability.inference == found，生成实际命令；若为 missing，用 HTML 注释标注 <!-- 推理脚本未在 scripts/ 目录中找到，请补充 -->
# 使用说明 → 手动安装使用 → 评估和可视化	基于第二步半的检查结果：若 script_availability.evaluation == found，生成实际命令；若为 missing，用 HTML 注释标注 <!-- 评估脚本未在 scripts/ 目录中找到，请补充 -->
# OneScience 官方信息	保留模板中的 Gitee/GitHub 链接表格
# 引用与许可证	若 source_dir 中有明确论文引用（标题、链接），提取并填写；否则填写 （请在此处填写论文引用信息）

第四步：关键原则

• 能从 source_dir 推断的信息，必须自动填充（如脚本路径、权重文件列表、框架类型），不得留空位
• 无法推断的信息，使用中文占位提示如 （请填写...），确保用户知道需要补充
• 模板中的固定内容（OneCode 链接、OneScience 官方信息、安装命令、硬件要求）直接原样保留
• 输出格式为完整可用的 Markdown 文件，不包含任何"此处应填写模板"等元说明
• 命令可用性优先：不生成引用不存在脚本的命令；缺失命令以注释标注，不输出不可执行的代码块

阶段六：输出上传引导命令

1. 在所有检查完成后，输出以下信息：

   模型产物已重组完成，目标目录：{target_dir_absolute}
   
   目录结构概览：
   model/     - {file_count} 个文件
   weight/    - {file_count} 个文件
   scripts/   - {file_count} 个文件
   conf/      - {file_count} 个文件
   (已排除)    - {file_count} 个文件（日志/数据/临时文件等，未复制到目标目录）
   
   {如果有空目录告警，在此显示}
   
   模板文件已生成：
   - configurations.json（魔搭模型身份证骨架，需手动补充模型信息）
   - README.md（模型卡片页）
   
   使用以下命令将模型推送到 ModelScope：
   modelscope upload {org}/{model_name} {target_dir}/{model_name} --token ***
   

2. modelscope upload 命令格式：

   • {org}：由 modelscope_org 参数指定，默认 OneScience
   • {model_name}：由 model_name 参数指定
   • --token ***：token 占位符，提示用户替换为自己的 ModelScope access token

文件分类规则（完整映射表）

.py 文件根据文件名关键词进行二次分类：

归类到 model/ 的关键词（模型结构/网络定义类）： model、net、module、nn、backbone、unet、encoder、decoder、layer、block、attention、transformer、resnet、vgg、densenet、lstm、gru、gan、diffusion、embedding、activation、normalization、conv、pooling、head、neck

归类到 scripts/ 的关键词（脚本/入口类）： train、infer、eval、test、preprocess、run、main、demo、predict、deploy、serve、download、setup、install、convert、export、benchmark、profile

默认规则：未匹配以上关键词的 .py 文件默认归入 model/。

文件排除规则

以下类型文件与模型配置、权重、训练/测试脚本无关，直接排除，不放入目标目录：

排除项	说明
.log	训练/运行日志文件
.csv, .tsv	数据表格文件（如训练日志导出的 loss/accuracy 记录）
.npy, .npz	NumPy 数据文件（训练/测试用的中间数据）
.png, .jpg, .jpeg, .pdf	图片/文档文件（如可视化图表、论文 PDF）
.tar, .gz, .zip	压缩归档文件
.pickle, .data, .db, .sqlite	序列化数据/数据库文件
.pkl（非权重类）	非模型权重的 pickle 文件（需结合文件名判断）
.txt	文本文件（如日志、notes、requirements 等）
.md	Markdown 文档文件
gitattributes（无前置点）	无前置点的 gitattributes 不被 git 识别为配置文件，属误生成文件，应删除。仅 .gitattributes（带点）有效。

例外：.pkl 若为模型权重文件（文件名含 weight/model 等关键词）仍归入 weight/。

空目录检查规则

• 核心检查目录：model/、weight/、scripts/、conf/

• 检查时机：文件复制完成后、模板文件生成前

• 判定标准：目录下不含任何文件（空目录递归扫描，忽略子目录）

• 告警格式：

  ⚠️ 警告：{dir_name}/ 文件夹下内容为空。 原因：源产物目录中未找到可归类到 {dir_name}/ 的文件。 建议：请确认是否需要补充{对应文件类型}后再推送。
  

  • model/ 空 → 提示"模型结构代码文件"
  • weight/ 空 → 提示"模型权重文件（.pth/.ckpt/.safetensors 等）"
  • scripts/ 空 → 提示"训练/推理脚本文件"
  • conf/ 空 → 提示"配置文件（.yaml/.json 等）"

输出契约

执行完成后必须返回标准化的 execution_result（符合"输入输出接口"章节定义），包含：

• status：success（所有核心目录非空）、partial（存在空核心目录）、failed（source_dir 不可用或无文件）
• artifacts：包含目标目录路径、创建的子目录列表、文件分类统计和生成的模板文件列表
• observation：包含空目录列表、告警信息和上传命令字符串
• notes：补充说明（如分类过程中的特殊情况）