refactor(logging): 补齐核心模块日志与中文注释约束

common-agent-agent/src/main/java/com/bruce/agent/controller/AgentSessionController.java

@@ -10,6 +10,7 @@ import com.bruce.agent.vo.AgentSessionDetailVO;
 import com.bruce.agent.vo.AgentWorkspaceVO;
 import com.bruce.common.domain.model.RequestResult;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -20,6 +21,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+/**
+ * Agent 会话控制器。
+ * <p>
+ * 负责会话创建、详情、消息查询与工作台聚合查询，保持前端只消费 DTO / VO 契约。
+ */
+@Slf4j
 @RestController
 @RequestMapping("/api/agent-sessions")
 @RequiredArgsConstructor
@@ -31,16 +38,19 @@ public class AgentSessionController {
 
     @PostMapping("/create")
     public RequestResult<Boolean> create(@RequestBody AgentSessionCreateDTO request) {
+        log.info("Agent会话创建请求开始，agentId={}, sessionCode={}", request.getAgentId(), request.getSessionCode());
         return RequestResult.success(agentSessionService.createSession(request));
     }
 
     @GetMapping("/detail")
     public RequestResult<AgentSessionDetailVO> detail(@RequestParam("id") Long id) {
+        log.info("Agent会话详情查询开始，sessionId={}", id);
         return RequestResult.success(agentSessionService.getDetailById(id));
     }
 
     @GetMapping("/{sessionId}/messages")
     public RequestResult<List<AgentMessageVO>> messages(@PathVariable("sessionId") Long sessionId) {
+        log.info("Agent消息列表查询开始，sessionId={}", sessionId);
         return RequestResult.success(agentMessageService.listBySessionId(sessionId));
     }
 
@@ -48,12 +58,15 @@ public class AgentSessionController {
     public RequestResult<Boolean> appendMessage(@PathVariable("sessionId") Long sessionId,
                                                 @RequestBody AgentSessionMessageCreateDTO request) {
         request.setSessionId(sessionId);
+        log.info("Agent消息写入请求开始，sessionId={}, role={}, requestId={}",
+                sessionId, request.getRole(), request.getRequestId());
         return RequestResult.success(agentMessageService.appendMessage(request));
     }
 
     @GetMapping("/workspace")
     public RequestResult<AgentWorkspaceVO> workspace(@RequestParam("agentId") Long agentId,
                                                      @RequestParam(value = "sessionId", required = false) Long sessionId) {
+        log.info("Agent工作台查询开始，agentId={}, sessionId={}", agentId, sessionId);
         return RequestResult.success(agentWorkspaceService.getWorkspace(agentId, sessionId));
     }
 }

common-agent-mcp/src/main/java/com/bruce/mcp/controller/McpImportController.java

@@ -11,6 +11,7 @@ import com.bruce.mcp.vo.McpCapabilityVO;
 import com.bruce.mcp.vo.McpServerVO;
 import com.bruce.mcp.vo.McpWorkspaceVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -21,6 +22,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+/**
+ * MCP 接入控制器。
+ * <p>
+ * 负责导入服务、查询服务与能力、以及工作台聚合视图查询。
+ */
+@Slf4j
 @RestController
 @RequestMapping("/api/mcp")
 @RequiredArgsConstructor
@@ -33,16 +40,19 @@ public class McpImportController {
 
     @PostMapping("/import")
     public RequestResult<Boolean> importServer(@RequestBody McpImportDTO request) {
+        log.info("MCP服务导入开始，serverCode={}, importType={}", request.getServerCode(), request.getImportType());
         return RequestResult.success(mcpImportService.importServer(request));
     }
 
     @GetMapping("/servers")
     public RequestResult<List<McpServerVO>> listServers() {
+        log.info("MCP服务列表查询开始");
         return RequestResult.success(mcpServerService.listServers());
     }
 
     @GetMapping("/servers/{serverId}/capabilities")
     public RequestResult<List<McpCapabilityVO>> listCapabilities(@PathVariable("serverId") Long serverId) {
+        log.info("MCP能力列表查询开始，serverId={}", serverId);
         return RequestResult.success(mcpCapabilityService.listByServerId(serverId));
     }
 
@@ -51,16 +61,19 @@ public class McpImportController {
      */
     @GetMapping("/servers/code/{serverCode}/capabilities")
     public RequestResult<List<McpCapabilityVO>> listCapabilitiesByServerCode(@PathVariable("serverCode") String serverCode) {
+        log.info("MCP能力列表按编码查询开始，serverCode={}", serverCode);
         return RequestResult.success(mcpCapabilityService.listByServerCode(serverCode));
     }
 
     @PostMapping("/capabilities/save")
     public RequestResult<Boolean> saveCapability(@RequestBody McpCapabilitySaveDTO request) {
+        log.info("MCP能力保存开始，serverId={}, capabilityCode={}", request.getServerId(), request.getCapabilityCode());
         return RequestResult.success(mcpCapabilityService.saveCapability(request));
     }
 
     @GetMapping("/workspace")
     public RequestResult<McpWorkspaceVO> workspace(@RequestParam("serverId") Long serverId) {
+        log.info("MCP工作台查询开始，serverId={}", serverId);
         return RequestResult.success(mcpWorkspaceService.getWorkspace(serverId));
     }
 }

common-agent-modelprovider/src/main/java/com/bruce/modelprovider/service/impl/ModelRouteServiceImpl.java

@@ -8,6 +8,7 @@ import com.bruce.modelprovider.service.IModelConfigService;
 import com.bruce.modelprovider.service.IModelRouteRuleService;
 import com.bruce.modelprovider.service.IModelRouteService;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 
 import java.util.ArrayList;
@@ -25,9 +26,7 @@ import java.util.stream.Collectors;
  */
 @Service
 @RequiredArgsConstructor
-/**
+@Slf4j
- * ModelRouteServiceImpl，负责模型平台对应层的职责。
- */
 public class ModelRouteServiceImpl implements IModelRouteService {
 
     private final IModelRouteRuleService modelRouteRuleService;
@@ -40,13 +39,12 @@ public class ModelRouteServiceImpl implements IModelRouteService {
      * @return 路由决策结果，包含主模型、备用模型和命中原因
      */
     @Override
-    /**
-     * 方法 route，用于执行业务逻辑处理。
-     */
     public ModelRouteDecision route(ModelRouteContext context) {
         if (context == null) {
             throw new IllegalArgumentException("路由上下文不能为空");
         }
+        log.info("模型路由决策开始，taskType={}, matchScope={}, scopeId={}, modelType={}",
+                context.getTaskType(), context.getMatchScope(), context.getScopeId(), context.getRequiredModelType());
         ModelRouteRule rule = selectRule(context);
         if (rule == null) {
             ModelConfig defaultModel = modelConfigService.lambdaQuery()
@@ -62,6 +60,8 @@ public class ModelRouteServiceImpl implements IModelRouteService {
             decision.setPrimaryModel(defaultModel);
             decision.setRouteStrategy("MANUAL");
             decision.setReason("命中模型类型默认模型");
+            log.info("模型路由决策完成，taskType={}, strategy={}, primaryModelId={}, reason={}",
+                    context.getTaskType(), decision.getRouteStrategy(), defaultModel.getId(), decision.getReason());
             return decision;
         }
 
@@ -98,6 +98,8 @@ public class ModelRouteServiceImpl implements IModelRouteService {
         decision.setFallbackModels(fallbackModels);
         decision.setRouteStrategy(rule.getRouteStrategy());
         decision.setReason("命中规则: " + rule.getRouteCode());
+        log.info("模型路由决策完成，taskType={}, routeCode={}, primaryModelId={}, fallbackCount={}",
+                context.getTaskType(), rule.getRouteCode(), primary.getId(), fallbackModels.size());
         return decision;
     }
 

common-agent-observability/src/main/java/com/bruce/observability/controller/ObservabilityTraceController.java

@@ -9,6 +9,7 @@ import com.bruce.observability.vo.ObservabilityModelCallSummaryVO;
 import com.bruce.observability.vo.ObservabilityRunSummaryVO;
 import com.bruce.observability.vo.ObservabilityTraceVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -20,6 +21,7 @@ import java.util.List;
 /**
  * 运行观测控制器，聚合 Workflow、Agent 和模型调用信息，返回脱敏摘要。
  */
+@Slf4j
 @RestController
 @RequestMapping("/api/observability")
 @RequiredArgsConstructor
@@ -31,21 +33,25 @@ public class ObservabilityTraceController {
 
     @GetMapping("/runs")
     public RequestResult<List<ObservabilityRunSummaryVO>> runs() {
+        log.info("运行观测列表查询开始");
         return RequestResult.success(observabilityRunService.listRecentRuns());
     }
 
     @GetMapping("/runs/{requestId}")
     public RequestResult<ObservabilityTraceVO> trace(@PathVariable("requestId") String requestId) {
+        log.info("运行追踪查询开始，requestId={}", requestId);
         return RequestResult.success(observabilityTraceService.getTrace(requestId));
     }
 
     @GetMapping("/model-calls")
     public RequestResult<List<ObservabilityModelCallSummaryVO>> modelCalls(@RequestParam("requestId") String requestId) {
+        log.info("模型调用摘要查询开始，requestId={}", requestId);
         return RequestResult.success(observabilityTraceService.listModelCalls(requestId));
     }
 
     @GetMapping("/runs/{requestId}/export")
     public RequestResult<ObservabilityExportVO> export(@PathVariable("requestId") String requestId) {
+        log.info("运行追踪导出开始，requestId={}", requestId);
         return RequestResult.success(observabilityExportService.exportTrace(requestId));
     }
 }

common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagChunkEmbeddingServiceImpl.java

@@ -4,9 +4,21 @@ import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 import com.bruce.rag.entity.RagChunkEmbedding;
 import com.bruce.rag.mapper.RagChunkEmbeddingMapper;
 import com.bruce.rag.service.IRagChunkEmbeddingService;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 
+/**
+ * 切片向量服务基础实现。
+ * <p>
+ * 当前模块首轮以主数据补全为主，这里保留统一的服务落点，便于后续继续承接向量写入、
+ * 重建索引和状态审计日志。
+ */
+@Slf4j
 @Service
 public class RagChunkEmbeddingServiceImpl extends ServiceImpl<RagChunkEmbeddingMapper, RagChunkEmbedding>
         implements IRagChunkEmbeddingService {
+
+    public RagChunkEmbeddingServiceImpl() {
+        log.debug("RAG切片向量服务初始化完成");
+    }
 }

common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagChunkServiceImpl.java

@@ -4,8 +4,20 @@ import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 import com.bruce.rag.entity.RagChunk;
 import com.bruce.rag.mapper.RagChunkMapper;
 import com.bruce.rag.service.IRagChunkService;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 
+/**
+ * 切片服务基础实现。
+ * <p>
+ * 当前阶段主要复用 MyBatis-Plus 通用能力承载切片主数据访问，
+ * 统一保留服务层入口以便后续扩展切片重建和日志审计。
+ */
+@Slf4j
 @Service
 public class RagChunkServiceImpl extends ServiceImpl<RagChunkMapper, RagChunk> implements IRagChunkService {
+
+    public RagChunkServiceImpl() {
+        log.debug("RAG切片服务初始化完成");
+    }
 }

common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagDocumentParseResultServiceImpl.java

@@ -7,6 +7,7 @@ import com.bruce.rag.entity.RagDocumentParseResult;
 import com.bruce.rag.mapper.RagDocumentParseResultMapper;
 import com.bruce.rag.service.IRagDocumentParseResultService;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 import org.springframework.util.DigestUtils;
 import org.springframework.util.StringUtils;
@@ -17,6 +18,12 @@ import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * 文档解析快照服务实现。
+ * <p>
+ * 负责把解析结果固化为文档快照，供切片与后续索引链路复用。
+ */
+@Slf4j
 @Service
 @RequiredArgsConstructor
 public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentParseResultMapper, RagDocumentParseResult>
@@ -29,6 +36,7 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
         if (documentId == null) {
             return null;
         }
+        log.info("查询文档解析快照开始，documentId={}", documentId);
         return getOne(Wrappers.<RagDocumentParseResult>lambdaQuery()
                 .eq(RagDocumentParseResult::getDocumentId, documentId)
                 .last("limit 1"));
@@ -39,6 +47,8 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
         if (storeId == null || documentId == null || parseResult == null) {
             throw new IllegalArgumentException("保存解析快照参数不完整");
         }
+        log.info("保存文档解析快照开始，storeId={}, documentId={}, textLength={}",
+                storeId, documentId, parseResult.getTextLength());
         RagDocumentParseResult existing = getByDocumentId(documentId);
         RagDocumentParseResult snapshot = existing == null ? new RagDocumentParseResult() : existing;
         snapshot.setStoreId(storeId);
@@ -56,6 +66,8 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
         } else {
             updateById(snapshot);
         }
+        log.info("保存文档解析快照完成，storeId={}, documentId={}, parseVersion={}, snapshotId={}",
+                storeId, documentId, snapshot.getParseVersion(), snapshot.getId());
     }
 
     @Override
@@ -91,6 +103,7 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
             Map<String, Object> payload = metadata == null ? new LinkedHashMap<>() : metadata;
             return objectMapper.writeValueAsString(payload);
         } catch (Exception e) {
+            log.error("解析元数据序列化失败，metadataKeys={}", metadata == null ? 0 : metadata.keySet(), e);
             throw new IllegalStateException("解析元数据序列化失败", e);
         }
     }
@@ -103,6 +116,7 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
             return objectMapper.readValue(metadataJson, new TypeReference<>() {
             });
         } catch (Exception e) {
+            log.error("解析元数据反序列化失败，metadataJson={}", metadataJson, e);
             throw new IllegalStateException("解析元数据反序列化失败", e);
         }
     }

common-agent-skill/src/main/java/com/bruce/skill/controller/SkillWorkspaceController.java

@@ -7,6 +7,7 @@ import com.bruce.skill.service.ISkillWorkspaceService;
 import com.bruce.skill.vo.SkillVersionVO;
 import com.bruce.skill.vo.SkillWorkspaceVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -18,6 +19,7 @@ import org.springframework.web.bind.annotation.RestController;
 /**
  * Skill 工作台接口，首轮对齐前端原型中的详情、草稿、测试、发布和归档能力。
  */
+@Slf4j
 @RestController
 @RequestMapping("/api/skills")
 @RequiredArgsConstructor
@@ -28,30 +30,35 @@ public class SkillWorkspaceController {
 
     @GetMapping("/{skillCode}")
     public RequestResult<SkillWorkspaceVO> detail(@PathVariable("skillCode") String skillCode) {
+        log.info("Skill工作台详情查询开始，skillCode={}", skillCode);
         return RequestResult.success(skillWorkspaceService.getWorkspace(skillCode));
     }
 
     @PostMapping("/{skillCode}/draft")
     public RequestResult<Boolean> saveDraft(@PathVariable("skillCode") String skillCode,
                                             @RequestBody SkillVersionSaveDTO request) {
+        log.info("Skill草稿保存开始，skillCode={}, versionNo={}", skillCode, request.getVersionNo());
         return RequestResult.success(skillVersionService.saveDraft(skillCode, request));
     }
 
     @PostMapping("/{skillCode}/test")
     public RequestResult<SkillVersionVO> test(@PathVariable("skillCode") String skillCode,
                                               @RequestBody SkillVersionSaveDTO request) {
+        log.info("Skill测试执行开始，skillCode={}, versionNo={}", skillCode, request.getVersionNo());
         return RequestResult.success(skillVersionService.test(skillCode, request));
     }
 
     @PostMapping("/{skillCode}/publish")
     public RequestResult<Boolean> publish(@PathVariable("skillCode") String skillCode,
                                           @RequestBody SkillVersionSaveDTO request) {
+        log.info("Skill发布开始，skillCode={}, versionNo={}", skillCode, request.getVersionNo());
         return RequestResult.success(skillVersionService.publish(skillCode, request));
     }
 
     @PostMapping("/{skillCode}/archive")
     public RequestResult<Boolean> archive(@PathVariable("skillCode") String skillCode,
                                           @RequestParam("versionNo") Integer versionNo) {
+        log.info("Skill归档开始，skillCode={}, versionNo={}", skillCode, versionNo);
         return RequestResult.success(skillVersionService.archive(skillCode, versionNo));
     }
 }

common-agent-workflow/src/main/java/com/bruce/workflow/controller/ProjectController.java

@@ -5,6 +5,7 @@ import com.bruce.workflow.dto.ProjectSaveDTO;
 import com.bruce.workflow.service.IProjectService;
 import com.bruce.workflow.vo.ProjectVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -14,6 +15,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+/**
+ * Studio 项目空间控制器。
+ * <p>
+ * 负责项目列表、详情和保存接口，对外统一返回 Project 相关 VO。
+ */
+@Slf4j
 @RestController
 @RequestMapping("/api/studio-projects")
 @RequiredArgsConstructor
@@ -23,16 +30,19 @@ public class ProjectController {
 
     @GetMapping("/list")
     public RequestResult<List<ProjectVO>> list() {
+        log.info("Studio项目列表查询开始");
         return RequestResult.success(projectService.listProjects());
     }
 
     @GetMapping("/detail")
     public RequestResult<ProjectVO> detail(@RequestParam("id") Long id) {
+        log.info("Studio项目详情查询开始，projectId={}", id);
         return RequestResult.success(projectService.getProject(id));
     }
 
     @PostMapping("/save")
     public RequestResult<Boolean> save(@RequestBody ProjectSaveDTO request) {
+        log.info("Studio项目保存开始，projectId={}, projectCode={}", request.getId(), request.getProjectCode());
         return RequestResult.success(projectService.saveProject(request));
     }
 }