shinka-convert

Shinka 转换技能

使用此技能将现有项目转换为适用于 Shinka 的任务。

这是 shinka-setup 的替代起点：

• shinka-setup：根据自然语言任务描述创建新任务
• shinka-convert：将现有代码库转换为 Shinka 任务

转换完成后，用户仍应能够使用 shinka-run。

适用场景

在用户出现以下情况时调用此技能：

• 想使用 Shinka/ShinkaEvolve 优化现有脚本或仓库
• 提到要让当前代码适配 Shinka 输出签名、metrics.json、correct.json 或 EVOLVE-BLOCK 标记
• 想根据当前工作目录生成一个独立的 Shinka 任务

以下情况不要使用此技能：

• 用户只根据自然语言描述创建全新的任务框架
• evaluate.py 和 initial.<ext> 已存在，且用户只想启动演进；请使用 shinka-run

用户输入

先收集自由格式的说明，仅在缺少影响重大的细节时再追问。

收集以下信息：

• 要优化的行为或文件／函数
• 分数方向和主要指标
• 约束：正确性、运行时间、内存、确定性、风格、允许的修改
• 是否必须保持原始源代码不变
• 所需的数据／资源／依赖项

默认输出

除非用户要求其他路径，否则在 ./shinka_task/ 下生成一个独立任务目录。

任务目录应包含：

• evaluate.py
• run_evo.py
• shinka.yaml
• initial.<ext>
• 评估所需的最小可运行源代码子树的副本

除非用户明确要求原地转换，否则不要修改原始源代码树。

工作流

1. 检查当前工作目录。
   • 确认语言、入口点、包／模块布局、依赖项和当前输出。
   • 优先依据代码中的具体证据，而非猜测。
2. 根据用户说明推断可演进区域。
   • 如有歧义，请针对性追问。
   • 尽可能缩小可修改区域。
3. 选择最小可运行快照范围。
   • 只复制能够独立执行任务所需的源代码子树。
   • 除非导入／运行时要求，否则避免复制整个仓库。
4. 创建独立任务目录。
   • 默认：./shinka_task/
   • 未经同意，不要覆盖现有任务目录。
5. 将快照改写为稳定的 Shinka 契约。
   • 保留可演进区域之外的原有行为。
   • 在可行的情况下保持 CLI 行为不变。
   • 确保可演进候选入口文件命名为 initial.<ext>，以便 shinka-run 检测到它。
   • 添加范围严格的 EVOLVE-BLOCK-START／EVOLVE-BLOCK-END 标记。
6. 生成评估器路径。
   • Python：优先公开 run_experiment(...)，并使用 run_shinka_eval。
   • 非 Python：使用 subprocess，并写入 metrics.json 和 correct.json。
7. 生成 run_evo.py 和 shinka.yaml。
   • 确保 init_program_path 和 language 与候选文件匹配。
   • 确保输出可直接兼容 shinka-run。
8. 交付前进行冒烟测试。
   • 运行 python evaluate.py --program_path <initial file> --results_dir /tmp/shinka_convert_smoke
   • 确认评估器运行时没有异常。
   • 确认已写入必需的指标／正确性输出。
9. 询问用户下一步操作。
   • 手动运行演进
   • 或使用 shinka-run 技能

按语言分类的转换策略

Python

• 首选在快照中公开 run_experiment(...)，并通过 run_shinka_eval 进行评估
• 如果现有代码仅支持 CLI，请在快照中添加轻量包装器，而不要强行使用子进程评估器；除非导入过于脆弱
• 保持相对于复制任务快照的导入稳定

非 Python

• 保持候选程序可在其自身运行时中执行
• 使用 Python evaluate.py 作为 Shinka 入口点
• 在 results_dir 中写入 metrics.json 和 correct.json

所需的评估器契约

指标必须包括：

• combined_score
• public
• private
• extra_data
• text_feedback

正确性必须包括：

• correct
• error

除非用户明确指定了反向指标，并在聚合时进行转换，否则 combined_score 值越高，表示性能越好。

Python 转换模板

优先将复制的程序按以下方式组织：

from __future__ import annotations

# EVOLVE-BLOCK-START
def optimize_me(...):
    ...
# EVOLVE-BLOCK-END

def run_experiment(random_seed: int | None = None, **kwargs):
    ...
    return score, text_feedback

评估器示例如下：

from shinka.core import run_shinka_eval

def main(program_path: str, results_dir: str):
    metrics, correct, err = run_shinka_eval(
        program_path=program_path,
        results_dir=results_dir,
        experiment_fn_name="run_experiment",
        num_runs=3,
        get_experiment_kwargs=get_kwargs,
        aggregate_metrics_fn=aggregate_fn,
        validate_fn=validate_fn,
    )
    if not correct:
        raise RuntimeError(err or "Evaluation failed")

非 Python 转换模板

使用 evaluate.py 运行候选程序并写入输出：

import json
import os
from pathlib import Path

def main(program_path: str, results_dir: str):
    os.makedirs(results_dir, exist_ok=True)
    metrics = {
        "combined_score": 0.0,
        "public": {},
        "private": {},
        "extra_data": {},
        "text_feedback": "",
    }
    correct = {"correct": False, "error": ""}

    (Path(results_dir) / "metrics.json").write_text(json.dumps(metrics, indent=2))
    (Path(results_dir) / "correct.json").write_text(json.dumps(correct, indent=2))

附带资源

• 使用 scripts/run_evo.py 作为起始运行器模板
• 使用 scripts/shinka.yaml 作为起始配置模板

备注

• 保持 evolve 区域精简；默认不要让整个项目都可变
• 尽可能将正确性检查保留在 evolve 区域之外
• 优先采用确定性评估和稳定的随机种子
• 如果转换后的任务已准备就绪，可提出继续使用 shinka-run