package tech.easyflow.skill.service;

import com.easyagents.agent.runtime.mcp.McpToolManifestEntry;
import tech.easyflow.ai.entity.Mcp;
import tech.easyflow.ai.entity.PluginItem;
import tech.easyflow.ai.entity.Workflow;
import tech.easyflow.skill.entity.Skill;
import tech.easyflow.skill.entity.SkillToolBinding;

import java.util.List;
import java.util.Map;

/**
 * Skill Tool 目标资源的权限校验、清单读取与安全快照服务。
 */
public interface SkillToolResourceService {

    /**
     * 校验并加载已发布工作流。
     *
     * @param skill Skill
     * @param binding 工作流绑定
     * @return 已发布工作流
     */
    Workflow requireWorkflow(Skill skill, SkillToolBinding binding);

    /**
     * 校验并加载已启用插件工具。
     *
     * @param skill Skill
     * @param binding 插件绑定
     * @return 插件工具
     */
    PluginItem requirePlugin(Skill skill, SkillToolBinding binding);

    /**
     * 校验并加载可用的单服务 MCP。
     *
     * @param skill Skill
     * @param binding MCP 绑定
     * @return MCP 与当前 Tool 清单
     */
    McpResource requireMcp(Skill skill, SkillToolBinding binding);

    /**
     * 构建运行时所需的资源快照。
     *
     * @param resource 资源实体
     * @return 包含插件项与父插件调用配置的服务端内部资源快照
     */
    Map<String, Object> snapshotWorkflow(Workflow workflow);

    /**
     * 构建插件工具运行快照。
     *
     * @param pluginItem 插件工具
     * @return 服务端内部资源快照
     */
    Map<String, Object> snapshotPlugin(PluginItem pluginItem);

    /**
     * 构建 MCP 受控连接快照。
     *
     * <p>该快照仅供服务端 Runtime 使用，字段使用显式白名单，禁止直接序列化 MCP 实体。</p>
     *
     * @param mcp MCP 资源
     * @return 服务端内部连接快照
     */
    Map<String, Object> snapshotMcpConnection(Mcp mcp);

    /**
     * 不连接外部服务地读取绑定资源脱敏摘要。
     *
     * @param binding Tool 绑定
     * @return 可用于详情展示的摘要
     */
    Map<String, Object> currentSummary(SkillToolBinding binding);

    /**
     * MCP 与已规范化 Tool 清单。
     *
     * @param mcp MCP 资源
     * @param manifest 冻结清单
     * @param manifestHash 完整清单 hash
     */
    record McpResource(Mcp mcp,
                       List<McpToolManifestEntry> manifest,
                       String manifestHash) {
    }
}
