shinka-convert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shinka Convert Skill

Use this skill to turn an existing project into a Shinka-ready task.

This is the alternative starting point to

shinka-setup

```
shinka-setup
```
: new task from natural-language task description
```
shinka-convert
```
: existing codebase to Shinka task conversion

After conversion, the user should still be able to use

shinka-run

使用此Skill将现有项目转换为可适配Shinka的任务。

这是

shinka-setup

的替代起始方案：

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

转换完成后，用户仍可使用

shinka-run

。

When to Use

使用场景

Invoke this skill when the user:

Wants to optimize an existing script or repo with Shinka/ShinkaEvolve
Mentions adapting current code to Shinka output signatures,
```
metrics.json
```
,
```
correct.json
```
, or
```
EVOLVE-BLOCK
```
markers
Wants a sidecar Shinka task generated from the current working directory

Do not use this skill when:

The user wants a brand-new task scaffold from only a natural-language description
```
evaluate.py
```
and
```
initial.<ext>
```
already exist and the user only wants to launch evolution; use
```
shinka-run
```

当用户有以下需求时，调用此Skill：

希望使用Shinka/ShinkaEvolve优化现有脚本或仓库
提及要调整当前代码以适配Shinka的输出签名、
```
metrics.json
```
、
```
correct.json
```
或
```
EVOLVE-BLOCK
```
标记
希望从当前工作目录生成一个附属Shinka任务

请勿在以下场景使用此Skill：

用户仅希望通过自然语言描述创建全新任务脚手架
```
evaluate.py
```
和
```
initial.<ext>
```
已存在，且用户仅需启动进化流程；此时应使用
```
shinka-run
```

User Inputs

用户输入

Start from freeform instructions, then ask follow-ups only if high-impact details are missing.

Collect:

What behavior or file/function to optimize
Score direction and main metric
Constraints: correctness, runtime, memory, determinism, style, allowed edits
Whether original source must remain untouched
Any required data/assets/dependencies

从自由格式指令开始，仅在缺失高影响细节时进行跟进提问。

需收集的信息：

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

Default Output

默认输出

Generate a sidecar task directory at

./shinka_task/

unless the user requests another path.

The task directory should contain:

```
evaluate.py
```
```
run_evo.py
```
```
shinka.yaml
```
```
initial.<ext>
```
A copied snapshot of the minimal runnable source subtree needed for evaluation

Do not edit the original source tree unless the user explicitly requests in-place conversion.

除非用户指定其他路径，否则在

./shinka_task/

生成附属任务目录。

任务目录应包含：

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

除非用户明确要求原地转换，否则请勿编辑原始源代码树。

Workflow

工作流程

Inspect the current working directory.
- Identify language, entrypoints, package/module layout, dependencies, and current outputs.
- Prefer concrete evidence from the code over guesses.
Infer the evolvable region from the user's instructions.
- If ambiguous, ask targeted follow-ups.
- Keep the mutable region as small as practical.
Choose the minimal runnable snapshot scope.
- Copy only the source subtree needed to execute the task in isolation.
- Avoid repo-wide snapshots unless imports/runtime make that necessary.
Create the sidecar task directory.
- Default:
```
./shinka_task/
```
- Avoid overwriting an existing task dir without consent.
Rewrite the snapshot into a stable Shinka contract.
- Preserve original behavior outside the evolvable region.
- Keep CLI behavior intact where practical.
- Ensure the evolvable candidate entry file is named
```
initial.<ext>
```
  so
```
shinka-run
```
  can detect it.
- Add tight
```
EVOLVE-BLOCK-START
```
  /
```
EVOLVE-BLOCK-END
```
  markers.
Generate the evaluator path.
- Python: prefer exposing
```
run_experiment(...)
```
  and use
```
run_shinka_eval
```
  .
- Non-Python: use
```
subprocess
```
  and write
```
metrics.json
```
  plus
```
correct.json
```
  .
Generate
```
run_evo.py
```
and
```
shinka.yaml
```
.
- Ensure
```
init_program_path
```
  and
```
language
```
  match the candidate file.
- Keep the output directly compatible with
```
shinka-run
```
  .
Smoke test before handoff.
- Run
```
python evaluate.py --program_path <initial file> --results_dir /tmp/shinka_convert_smoke
```
- Confirm evaluator runs without exceptions.
- Confirm required metrics/correctness outputs are written.
Ask the user for the next step.
- Either run evolution manually
- Or use the
```
shinka-run
```
  skill

检查当前工作目录。
- 识别语言、入口点、包/模块结构、依赖项和当前输出。
- 优先依据代码中的具体证据，而非猜测。
根据用户指令推断可进化区域。
- 若存在歧义，进行针对性跟进提问。
- 尽可能缩小可变区域的范围。
选择最小可运行快照范围。
- 仅复制隔离执行任务所需的源代码子树。
- 除非导入/运行时要求，否则避免全仓库快照。
创建附属任务目录。
- 默认路径：
```
./shinka_task/
```
- 未经用户同意，请勿覆盖已存在的任务目录。
将快照重写为稳定的Shinka契约。
- 保留可进化区域外的原始行为。
- 尽可能保持CLI行为不变。
- 确保可进化候选入口文件命名为
```
initial.<ext>
```
  ，以便
```
shinka-run
```
  能够检测到。
- 添加严格的
```
EVOLVE-BLOCK-START
```
  /
```
EVOLVE-BLOCK-END
```
  标记。
生成评估器路径。
- Python：优先暴露
```
run_experiment(...)
```
  并使用
```
run_shinka_eval
```
  。
- 非Python：使用
```
subprocess
```
  并生成
```
metrics.json
```
  和
```
correct.json
```
  。
生成
```
run_evo.py
```
和
```
shinka.yaml
```
。
- 确保
```
init_program_path
```
  和
```
language
```
  与候选文件匹配。
- 确保输出可直接与
```
shinka-run
```
  兼容。
移交前进行冒烟测试。
- 运行
```
python evaluate.py --program_path <initial file> --results_dir /tmp/shinka_convert_smoke
```
- 确认评估器可无异常运行。
- 确认已生成所需的指标/正确性输出。
询问用户下一步操作。
- 手动运行进化流程
- 或使用
```
shinka-run
```
  Skill

Conversion Strategy by Language

按语言划分的转换策略

Python

Preferred path: expose
```
run_experiment(...)
```
in the snapshot and evaluate via
```
run_shinka_eval
```
If the existing code is CLI-only, add a thin wrapper in the snapshot rather than forcing a subprocess evaluator unless imports are too brittle
Keep imports relative to the copied task snapshot stable

首选方案：在快照中暴露
```
run_experiment(...)
```
并通过
```
run_shinka_eval
```
进行评估
若现有代码仅支持CLI，除非导入过于脆弱，否则在快照中添加轻量包装器，而非强制使用子进程评估器
保持复制的任务快照中的相对导入稳定

Non-Python

非Python

Keep the candidate program executable in its own runtime
Use Python
```
evaluate.py
```
as the Shinka entrypoint
Write
```
metrics.json
```
and
```
correct.json
```
in
```
results_dir
```

确保候选程序可在自身运行时中执行
使用Python编写的
```
evaluate.py
```
作为Shinka入口点
在
```
results_dir
```
中生成
```
metrics.json
```
和
```
correct.json
```

Required Evaluator Contract

必需的评估器契约

Metrics must include:

```
combined_score
```
```
public
```
```
private
```
```
extra_data
```
```
text_feedback
```

Correctness must include:

```
correct
```
```
error
```

Higher

combined_score

values indicate better performance unless the user explicitly defines an inverted metric that you transform during aggregation.

指标必须包含：

```
combined_score
```
```
public
```
```
private
```
```
extra_data
```
```
text_feedback
```

正确性必须包含：

```
correct
```
```
error
```

除非用户明确定义了需在聚合时转换的反向指标，否则

combined_score

值越高表示性能越好。

Python Conversion Template

Python转换模板

Prefer shaping the copied program like this:

from __future__ import annotations

优先将复制的程序调整为如下格式：

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


And the evaluator:

```py
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")

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


评估器示例：

```py
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,
    )
    if not correct:
        raise RuntimeError(err or "Evaluation failed")

Non-Python Conversion Template

非Python转换模板

Use

evaluate.py

to run the candidate and write outputs:

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))

使用

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))

Bundled Assets

捆绑资源

Use
```
scripts/run_evo.py
```
as the starting runner template
Use
```
scripts/shinka.yaml
```
as the starting config template

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

Notes

注意事项

Keep evolve regions tight; do not make the whole project mutable by default
Preserve correctness checks outside the evolve region where possible
Prefer deterministic evaluation and stable seeds
If the converted task is ready, offer to continue with
```
shinka-run
```

缩小evolve区域范围；默认不要将整个项目设为可变
尽可能保留evolve区域外的正确性检查
优先选择确定性评估和稳定种子
若转换后的任务已就绪，可提议继续使用
```
shinka-run
```