/**
 * Copyright (c) 2025 TWork Team. All rights reserved.
 * This source code is licensed under the TWork License.
 */

/**
 * NL 解析相关类型定义
 *
 * 用于自然语言创建定时任务的类型：NL 解析请求/响应、能力目录、动态模板。
 */

// ============================================================================
// 能力目录
// ============================================================================

/** 单个能力条目 */
export interface CapabilityEntry {
  /** 唯一标识符，如 "skill:docx-full" | "tool:browser_tool" | "mcp:linear:createIssue" */
  id: string;
  /** 能力类型 */
  type: 'tool' | 'skill' | 'mcp' | 'browser' | 'task_workbench' | 'session_tool';
  /** 人类可读名称（中文优先） */
  displayName: string;
  /** 功能描述（一句话） */
  description: string;
  /** 原始标识符（tool 名 / skill 名 / mcp__slug__toolName） */
  sourceId: string;
  /** 所属分类 */
  category: string;
  /** 使用场景关键词（供 NL 匹配） */
  keywords: string[];
  /** 能力级别 */
  capabilityLevel?: 'safe' | 'normal' | 'dangerous';
  /** 是否默认启用 */
  enabledByDefault: boolean;
}

/** 能力目录汇总 */
export interface CapabilityCatalog {
  /** 生成时间戳 */
  generatedAt: number;
  /** 能力版本号（用于缓存失效） */
  version: string;
  /** 所有能力条目 */
  entries: CapabilityEntry[];
  /** 按分类分组 */
  groups: Record<string, CapabilityEntry[]>;
  /** 能力概览摘要（用于 system prompt 注入） */
  summary: string;
}

// ============================================================================
// NL 解析
// ============================================================================

/** NL 解析请求 */
export interface NlParseRequest {
  /** 工作区 ID */
  workspaceId: string;
  /** 自然语言输入文本 */
  nlText: string;
  /** 解析使用的模型（可选，默认 Qwen3-235B） */
  model?: string;
}

/** NL 解析后的任务配置 */
export interface NlParsedTask {
  /** 任务名称 */
  name: string;
  /** 调度类型 */
  scheduleType: 'recurring' | 'once';
  /** Cron 表达式（scheduleType=recurring 时使用） */
  cron?: string;
  /** 一次性执行时间 ISO 8601（scheduleType=once 时使用） */
  executeAt?: string;
  /** IANA 时区 */
  timezone?: string;
  /** 动作类型 */
  actionType: 'prompt' | 'webhook';
  /** 执行提示词 */
  prompt?: string;
  /** Webhook URL */
  webhookUrl?: string;
  /** Webhook HTTP 方法 */
  webhookMethod?: string;
  /** 执行使用的模型 */
  model?: string;
  /** 引用的能力 ID 列表 */
  capabilities?: string[];
  /** 会话标签 */
  labels?: string[];
  /** 权限模式 */
  permissionMode?: string;
  /** 有效期开始 (ISO 8601) */
  validFrom?: string;
  /** 有效期结束 (ISO 8601) */
  validUntil?: string;
  /** 结果投递目标 */
  deliverTo?: string;
}

/** NL 解析结果 */
export interface NlParseResult {
  /** 置信度 0.0 ~ 1.0 */
  confidence: number;
  /** 解析出的任务配置 */
  task: NlParsedTask;
  /** 需要用户确认的事项 */
  warnings: string[];
}

/** NL 解析响应 */
export interface NlParseResponse {
  /** 是否成功 */
  success: boolean;
  /** 解析结果 */
  result?: NlParseResult;
  /** 错误信息 */
  error?: string;
  /** 是否使用了回退策略 */
  fallbackUsed: boolean;
}

// ============================================================================
// 动态模板
// ============================================================================

/** 动态快速模板 */
export interface DynamicTemplate {
  /** 模板 ID */
  id: string;
  /** 模板名称 */
  name: string;
  /** 模板描述 */
  description: string;
  /** Cron 表达式 */
  cron: string;
  /** 执行提示词 */
  prompt: string;
  /** 所属分类 */
  category: string;
  /** 引用的能力 ID 列表 */
  capabilities: string[];
  /** 图标标识 */
  icon: string;
}

// ============================================================================
// 能力目录构建选项
// ============================================================================

/** 能力目录构建选项 */
export interface CapabilityCatalogBuildOptions {
  /** 工具注册表（提供 getAll() 方法） */
  toolRegistry?: {
    getAll(): Array<{ name: string; displayName?: string; description: string; capabilityLevel?: string }>;
  };
  /** 技能注册表（提供 getAll() 方法） */
  skillRegistry?: {
    getAll(): Array<{
      name: string;
      displayName?: string;
      chineseName?: string;
      description: string;
      keywords?: string[];
      triggers?: string[];
      category?: string;
      enabled?: boolean;
    }>;
  };
  /** MCP 客户端池（提供已连接源和工具列表） */
  mcpPool?: {
    getConnectedSlugs(): string[];
    getTools(slug: string): Array<{ name: string; description?: string }>;
  };
}