OoderAgent-Skills 技术规范设计深度揭秘：构建AI原生时代的技能生态系统

/**
 * 技能 - 核心实体
 * 
 * <p>技能是系统的唯一核心实体，场景是技能的形态之一</p>
 * 
 * <h3>类比文件系统：</h3>
 * <ul>
 *   <li>Skill = File/Folder（文件/文件夹）</li>
 *   <li>SkillForm = 是文件还是文件夹</li>
 *   <li>SceneType = 文件夹类型（源码包/资源文件夹/普通文件夹）</li>
 *   <li>SkillCategory = 文件扩展名（.doc/.exe/.flow）</li>
 * </ul>
 */
public interface Skill {
    // ========== 基础信息 ==========
    String getSkillId();           // 全局唯一标识，类比文件路径
    String getName();              // 技能名称，类比文件名
    String getVersion();           // 版本

    // ========== 形态维度 ==========
    SkillForm getForm();           // SCENE(场景/容器) vs STANDALONE(独立/原子)
    Optional<SceneType> getSceneType(); // AUTO(自驱) / TRIGGER(触发) / HYBRID(混合)

    // ========== 分类维度 ==========
    SkillCategory getCategory();   // knowledge/llm/tool/workflow/data/service/ui/other

    // ========== 目的维度 ==========
    Set<ServicePurpose> getPurposes(); // 服务范围 + 时效 + 主动性

    // ========== 能力维度 ==========
    List<Capability> getCapabilities(); // 技能对外暴露的能力单元
}

/**
 * 用户知识贡献服务接口
 *
 * <p>提供用户向知识库贡献知识的完整能力，包括：</p>
 * <ul>
 *   <li>文件上传 - 支持 PDF、Word、Markdown 等格式</li>
 *   <li>文本输入 - 直接输入结构化知识</li>
 *   <li>URL 导入 - 自动抓取网页内容</li>
 *   <li>批量导入 - 支持压缩包、目录批量导入</li>
 * </ul>
 *
 * <p>技术实现要点：</p>
 * <ul>
 *   <li>异步处理：大文件上传后异步进行分块和索引</li>
 *   <li>权限校验：只有具备写权限的用户才能贡献知识</li>
 *   <li>内容审核：支持人工审核和自动敏感信息检测</li>
 *   <li>版本管理：支持知识版本回滚和对比</li>
 * </ul>
 */
public interface UserContributionService {
    /**
     * 上传文件到知识库
     * 
     * <p>处理流程：</p>
     * <ol>
     *   <li>权限校验：检查 userId 对 kbId 的写权限</li>
     *   <li>文件解析：根据 MIME 类型选择对应解析器</li>
     *   <li>内容提取：提取文本内容</li>
     *   <li>异步索引：提交到索引队列</li>
     * </ol>
     */
    Document uploadFile(String userId, String kbId, FileUploadRequest request);

    Document inputText(String userId, String kbId, TextKnowledgeRequest request);
    Document importFromUrl(String userId, String kbId, UrlImportRequest request);
    BatchImportResult batchUpload(String userId, String kbId, List<FileUploadRequest> requests);

    /**
     * 获取用户贡献统计
     * 
     * <p>用于激励机制和社区运营</p>
     */
    ContributionStats getStats(String userId);
}

public class ContributionStats {
    private String userId;
    private int totalContributions;      // 总贡献数
    private long totalPoints;            // 总积分（每次贡献10分）
    private int level;                   // 等级（1-5级）
    private Map<String, Long> typeCounts; // 按类型统计（file/text/url）

    // 等级计算规则：
    // Level 1: 0-49 分
    // Level 2: 50-199 分  
    // Level 3: 200-499 分
    // Level 4: 500-999 分
    // Level 5: 1000+ 分
}

/**
 * Agent LLM 会话上下文
 * 核心隔离单元，每个Agent独立维护自己的LLM配置和对话
 *
 * <h3>设计要点：</h3>
 * <ul>
 *   <li>每个 Agent 拥有独立的 userId，与人类用户平等</li>
 *   <li>对话历史隔离：不同 Agent 的对话互不影响</li>
 *   <li>资源配额隔离：防止单个 Agent 耗尽系统资源</li>
 *   <li>连接池共享：多个 Agent 可以共享同一 LLM 连接池</li>
 * </ul>
 */
public class AgentLlmSessionContext {
    // ========== 身份标识 ==========
    private final String agentId;       // Agent唯一标识（系统内部）
    private final String userId;        // 用户ID（对外身份，与人类用户平等）
    private final String agentType;     // Agent类型：hr-assistant / code-reviewer

    // ========== LLM配置 ==========
    private final String llmConfigId;   // LLM配置引用
    private final LlmConfig llmConfig;  // 具体的LLM参数（temperature, maxTokens等）

    // ========== 连接管理 ==========
    private final String connectionPoolId;    // 连接池ID（多个Agent可共享）
    private final LlmConnectionPool connectionPool; // 连接池引用

    // ========== 状态管理 ==========
    private final String conversationMemoryId;      // 对话存储ID
    private final List<ChatMessage> conversationHistory; // 对话历史（内存缓存）
    private final AgentLlmQuota quota;              // Agent级配额
    private volatile AgentState state;              // 当前状态

    // ========== 生命周期 ==========
    private final long createdAt;       // 创建时间
    private volatile long lastActiveAt; // 最后活跃时间
    private final long idleTimeout;     // 空闲超时时间
}

/**
 * 角色配置
 * 
 * <p>定义场景技能中的角色信息，用于多角色协作场景</p>
 * 
 * <h3>典型应用场景 - 招聘流程：</h3>
 * <ul>
 *   <li>HR Agent (roleId: HR, priority: 1, required: true)</li>
 *   <li>面试官 Agent (roleId: INTERVIEWER, priority: 2, minCount: 1, maxCount: 3)</li>
 *   <li>候选人 Agent (roleId: CANDIDATE, priority: 3, required: true)</li>
 * </ul>
 */
public class RoleConfig {
    private String roleId;           // 角色ID：MANAGER, EMPLOYEE, HR
    private String roleName;         // 角色显示名称
    private String description;      // 角色描述
    private int priority;            // 优先级（用于排序和决策权）
    private boolean required;        // 是否必需角色
    private int minCount;            // 最小人数（0表示可选）
    private int maxCount;            // 最大人数（0表示无限制）
    private Map<String, Object> metadata;  // 扩展属性（如技能要求、经验等级）
}

@Component
public class PermissionEngine {
    /**
     * 计算用户数据访问范围
     *
     * <p>核心逻辑：用户角色权限 ∩ Skill 权限要求 = 实际可访问范围</p>
     * 
     * <h3>计算步骤：</h3>
     * <ol>
     *   <li>获取用户角色和权限（包括 Agent 用户）</li>
     *   <li>获取 Skill 的权限要求</li>
     *   <li>计算交集：部门范围、资源范围、操作权限、数据敏感度</li>
     * </ol>
     */
    public DataScope calculateDataScope(String userId, String skillId) {
        // 1. 获取用户角色和权限
        UserRole userRole = userService.getUserRole(userId);

        // 2. 获取Skill权限要求
        SkillPermission skillPermission = skillService.getPermission(skillId);

        // 3. 计算数据范围交集（取最严格的限制）
        DataScope dataScope = new DataScope();
        dataScope.setDepartments(intersect(userRole.getDepartments(), skillPermission.getDepartments()));
        dataScope.setResources(intersect(userRole.getResources(), skillPermission.getResources()));
        dataScope.setAllowedOperations(intersect(userRole.getOperations(), skillPermission.getOperations()));
        dataScope.setMaxSensitivity(Math.min(userRole.getMaxSensitivity(), skillPermission.getRequiredSensitivity()));

        return dataScope;
    }

    /**
     * 将权限应用到RAG检索请求
     * 
     * <p>在检索阶段实时过滤，确保数据安全</p>
     */
    public void applyToRagSearch(DataScope scope, KnowledgeSearchRequest request) {
        // 添加部门过滤器
        if (!scope.getDepartments().isEmpty()) {
            request.addFilter("department", scope.getDepartments());
        }

        // 添加资源过滤器
        if (!scope.getResources().isEmpty()) {
            request.addFilter("resource", scope.getResources());
        }

        // 添加敏感度过滤器
        if (scope.getMaxSensitivity() < Integer.MAX_VALUE) {
            request.addFilter("sensitivity_lte", scope.getMaxSensitivity());
        }
    }
}

/**
 * 知识库绑定信息
 * 
 * <p>实现 Skill 与知识库的灵活关联</p>
 * 
 * <h3>绑定模式：</h3>
 * <ul>
 *   <li>一对一：一个 Skill 绑定一个专属知识库</li>
 *   <li>一对多：一个 Skill 绑定多个知识库（如分层知识库）</li>
 *   <li>多对一：多个 Skill 共享一个公共知识库</li>
 * </ul>
 */
public class KnowledgeBinding {
    private String sceneGroupId;    // 场景组ID（用于场景技能）
    private String kbId;            // 知识库ID
    private String kbName;          // 知识库名称（冗余，便于展示）
    private String layer;           // 层级：company/department/team/personal
    private long bindTime;          // 绑定时间（用于审计和排序）
}

/**
 * 知识库
 * 
 * <p>为每个 Skill 提供完整的 LLM-RAG 支持</p>
 */
public class KnowledgeBase {
    // ========== 基础信息 ==========
    private String kbId;            // 知识库ID（全局唯一）
    private String name;            // 名称
    private String description;     // 描述
    private String ownerId;         // 所有者ID（人类用户或 Agent 用户）
    private String visibility;      // 可见性：private(私有) / public(公开) / team(团队)

    // ========== RAG 核心配置 ==========
    private String embeddingModel;  // 嵌入模型：text-embedding-ada-002 / bge-large-zh 等
    private int chunkSize;          // 分块大小（默认500字符）
    private int chunkOverlap;       // 分块重叠（默认50字符，保证语义连续性）

    // ========== 统计信息 ==========
    private int documentCount;      // 文档数量
    private long totalSize;         // 总大小（字节）
    private String indexStatus;     // 索引状态：pending/indexing/indexed/failed

    // ========== 扩展属性 ==========
    private Map<String, Object> metadata;  // 自定义元数据（如标签、分类）
    private List<String> tags;      // 标签（用于快速检索）
}

@Component
public class AdaptiveRag {

    /**
     * 自适应检索
     *
     * <p>根据查询类型自动选择最优检索策略，提升 RAG 效果</p>
     */
    public RagResult adaptiveRetrieve(String query, RagContext baseContext) {
        // 1. 查询分类（基于关键词匹配）
        QueryType queryType = classifyQuery(query);

        // 2. 根据查询类型选择策略
        RetrievalStrategy strategy = selectStrategy(queryType);

        // 3. 应用策略参数到上下文
        RagContext optimizedContext = applyStrategy(baseContext, strategy);

        // 4. 执行检索
        RagResult result = ragPipeline.retrieve(optimizedContext);

        // 5. 后处理（根据策略进行结果优化）
        result = postProcess(result, strategy);

        return result;
    }

    /**
     * 检索策略枚举
     * 
     * <p>不同查询类型对应不同策略参数</p>
     */
    public enum RetrievalStrategy {
        HIGH_PRECISION(3, 0.85f, true),   // 高精确度：topK小，阈值高，启用重排序
        BALANCED(5, 0.75f, true),          // 平衡：适中参数
        MULTI_SOURCE(10, 0.7f, true),      // 多源：topK大，收集更多来源
        DIVERSE(8, 0.65f, true),           // 多样化：较低阈值，确保多样性
        DEEP(10, 0.7f, true),              // 深度：大量检索，深度推理
        DEFAULT(5, 0.75f, false);          // 默认：标准参数

        private final int topK;            // 返回结果数量
        private final float threshold;     // 相似度阈值
        private final boolean rerankEnabled; // 是否启用重排序
    }
}

/**
 * 审计日志条目
 * 
 * <p>记录用户（包括 Agent 用户）的所有操作</p>
 */
public class AuditEntry {
    // ========== 身份标识 ==========
    private String logId;           // 日志ID（全局唯一）
    private String userId;          // 用户ID（人类用户或 Agent 用户）
    private String role;            // 用户角色（用于权限分析）

    // ========== 操作信息 ==========
    private String operation;       // 操作类型：query/invoke/upload/feedback
    private String resourceType;    // 资源类型：skill/kb/document/agent
    private String resourceId;      // 资源ID
    private String details;         // 操作详情（JSON格式）

    // ========== 执行信息 ==========
    private boolean success;        // 是否成功
    private long duration;          // 执行时长（毫秒，用于性能分析）
    private String clientIp;        // 客户端IP
    private String sceneId;         // 场景ID（用于场景分析）

    // ========== 时间信息 ==========
    private long timestamp;         // 时间戳

    // ========== 扩展属性 ==========
    private Map<String, Object> attributes;  // 扩展属性（如查询内容、响应摘要）
}