package com.easyagents.skill.codec;

import com.easyagents.skill.exception.SkillPackageException;
import com.easyagents.skill.model.Skill;
import com.easyagents.skill.model.SkillPackage;
import com.easyagents.skill.model.SkillPackageLayout;
import com.easyagents.skill.validation.SkillValidationReport;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;

/**
 * Skill 包双向流式编解码接口。
 */
public interface SkillPackageCodec {

    /**
     * 从 ZIP 输入流导入 Skill。
     *
     * @param inputStream ZIP 输入流
     * @return Skill 列表
     * @throws SkillPackageException ZIP 结构、内容或安全校验失败
     * @deprecated 请使用 {@link #decode(InputStream, SkillPackageReadOptions)} 获取包形态、hash 和诊断。
     */
    @Deprecated
    List<Skill> importZip(InputStream inputStream);

    /**
     * 解码 Skill ZIP。
     *
     * <p>兼容默认实现委托旧导入接口；正式 Codec 应覆盖。</p>
     *
     * @param inputStream ZIP 输入流
     * @param options 读取选项
     * @return 解码结果
     * @throws SkillPackageException ZIP 结构、内容、安全校验或资源存储失败
     */
    default SkillPackageReadResult decode(InputStream inputStream, SkillPackageReadOptions options) {
        List<Skill> skills = importZip(inputStream);
        SkillPackageLayout layout = skills.size() > 1
                ? SkillPackageLayout.MULTI_DIRECTORY : SkillPackageLayout.SINGLE_DIRECTORY;
        return new SkillPackageReadResult(new SkillPackage(layout, skills), new SkillValidationReport(), null);
    }

    /**
     * 将 Skill 包编码为标准 ZIP。
     *
     * @param skillPackage Skill 包
     * @param outputStream 输出流，不由本方法关闭
     * @param options 写出选项
     * @return 编码结果
     * @throws SkillPackageException Skill 包不合法、资源不可读或 ZIP 写出失败
     */
    default SkillPackageWriteResult encode(SkillPackage skillPackage, OutputStream outputStream,
                                           SkillPackageWriteOptions options) {
        throw new SkillPackageException("This SkillPackageCodec does not support encoding.");
    }
}
