增加AI写作功能

一、概述

AI写作是知识库系统的重要智能化功能,通过集成大语言模型(如通义千问、DeepSeek),帮助用户快速生成、扩写、优化和续写文档内容。本章将详细介绍如何在 kb-ai 服务和前端项目中实现完整的 AI 写作功能。

1.1 功能定位

AI写作作为知识库的智能创作工具,提供以下核心能力:

功能模块说明使用场景
内容生成根据主题和要求自动生成文档快速撰写技术方案、周报、PRD等
流式生成SSE实时输出生成内容提升用户体验,减少等待焦虑
内容扩写对已有内容进行扩展丰富文档细节,增加深度和广度
内容优化润色和优化已有文档提升文档质量,改善表达
内容续写从已有内容的结尾处继续写作完成未完成的文档
写作模板预设8种写作提示模板快速开始,减少重复输入

1.2 涉及项目模块

模块说明
kb-aiAI写作后端服务(DTO、VO、Service、Controller)
kb-gateway网关路由配置
knowledge-base-frontend前端页面、Store、Service、路由

二、后端实现

2.1 添加 Caffeine 缓存依赖

AI写作模板是硬编码的静态数据,为避免每次请求重复构建,引入 Caffeine 本地缓存。

编辑 kb-ai/pom.xml,在 <dependencies> 中添加:

<!-- Caffeine本地缓存 -->
<dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
</dependency>
Caffeine 版本由 Spring Boot BOM 统一管理,无需显式指定版本号。

2.2 创建请求 DTO

创建 kb-ai/src/main/java/com/knowledge/base/ai/dto/WritingRequestDTO.java:

package com.knowledge.base.ai.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * AI写作请求参数
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "AI写作请求参数")
public class WritingRequestDTO {

    /**
     * 写作主题/标题
     */
    @Schema(description = "写作主题/标题", example = "如何写好一份技术方案")
    @NotBlank(message = "写作主题不能为空")
    private String topic;

    /**
     * 写作要求/补充说明
     */
    @Schema(description = "写作要求/补充说明", example = "面向技术管理者的技术方案,包含背景、目标、方案设计、实施计划")
    private String requirements;

    /**
     * 内容类型:article-文章, report-报告, documentation-技术文档, email-邮件, announcement-公告
     */
    @Schema(description = "内容类型", example = "article",
            allowableValues = {"article", "report", "documentation", "email", "announcement"})
    private String contentType;

    /**
     * 写作风格:formal-正式, casual-轻松, technical-技术, creative-创意, academic-学术
     */
    @Schema(description = "写作风格", example = "formal",
            allowableValues = {"formal", "casual", "technical", "creative", "academic"})
    private String style;

    /**
     * 语气:neutral-中性, enthusiastic-热情, serious-严肃, friendly-友好, authoritative-权威
     */
    @Schema(description = "语气", example = "neutral",
            allowableValues = {"neutral", "enthusiastic", "serious", "friendly", "authoritative"})
    private String tone;

    /**
     * 期望字数
     */
    @Schema(description = "期望字数", example = "1000")
    private Integer length;

    /**
     * 参考/现有内容(用于扩写、优化、续写场景)
     */
    @Schema(description = "参考/现有内容(用于扩写、优化、续写场景)")
    private String existingContent;

    /**
     * 操作类型:generate-生成, expand-扩写, optimize-优化, continue-续写
     */
    @Schema(description = "操作类型", example = "generate",
            allowableValues = {"generate", "expand", "optimize", "continue"})
    @NotBlank(message = "操作类型不能为空")
    private String actionType;

    /**
     * 模板ID(使用预设模板时传入)
     */
    @Schema(description = "模板ID(使用预设模板时传入)", example = "tech-solution")
    private String templateId;

    /**
     * 使用的模型名称,默认使用配置的默认模型
     */
    @Schema(description = "使用的模型名称,默认使用配置的默认模型", example = "qwen")
    private String model;
}

设计要点:

  • topic 使用 @NotBlank 校验,确保写作主题不为空
  • contentType、style、tone 使用 allowableValues 约束取值范围
  • model 允许用户指定使用的 AI 模型,不指定则使用系统默认模型
  • actionType 用于前端复用同一个请求体调用不同接口

2.3 创建响应 VO

创建 kb-ai/src/main/java/com/knowledge/base/ai/vo/WritingResultVO.java:

package com.knowledge.base.ai.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * AI写作结果响应
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "AI写作结果响应")
public class WritingResultVO implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 生成的内容
     */
    @Schema(description = "生成的内容", example = "# 技术方案\n\n## 一、项目背景...")
    private String content;

    /**
     * Token消耗量
     */
    @Schema(description = "Token消耗量", example = "1500")
    private Integer tokens;

    /**
     * 字数
     */
    @Schema(description = "字数", example = "800")
    private Integer wordCount;

    /**
     * 使用的模型
     */
    @Schema(description = "使用的模型", example = "qwen")
    private String model;
}

创建 kb-ai/src/main/java/com/knowledge/base/ai/vo/WritingTemplateVO.java:

package com.knowledge.base.ai.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * 写作模板响应
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "写作模板响应")
public class WritingTemplateVO implements Serializable {

    private static final long serialVersionUID = 1L;

    @Schema(description = "模板ID", example = "tech-solution")
    private String id;

    @Schema(description = "模板名称", example = "技术方案")
    private String name;

    @Schema(description = "模板描述", example = "适用于撰写技术方案文档")
    private String description;

    @Schema(description = "分类", example = "技术文档")
    private String category;

    @Schema(description = "提示Prompt", example = "请撰写一份技术方案...")
    private String prompt;

    @Schema(description = "建议的内容类型", example = "article")
    private String suggestedContentType;

    @Schema(description = "建议的写作风格", example = "technical")
    private String suggestedStyle;
}

2.4 创建 Service 接口

创建 kb-ai/src/main/java/com/knowledge/base/ai/service/AiWritingService.java:

package com.knowledge.base.ai.service;

import com.knowledge.base.ai.dto.WritingRequestDTO;
import com.knowledge.base.ai.vo.WritingResultVO;
import com.knowledge.base.ai.vo.WritingTemplateVO;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;

import java.util.List;

/**
 * AI写作服务接口
 *
 * @author 苏三
 * @since 1.0.0
 */
public interface AiWritingService {

    /**
     * 根据主题和需求生成写作内容
     */
    WritingResultVO generate(WritingRequestDTO dto, Long userId);

    /**
     * 流式生成写作内容(SSE)
     */
    SseEmitter generateStream(WritingRequestDTO dto, Long userId);

    /**
     * 扩写已有内容
     */
    WritingResultVO expand(WritingRequestDTO dto, Long userId);

    /**
     * 优化/润色已有内容
     */
    WritingResultVO optimize(WritingRequestDTO dto, Long userId);

    /**
     * 从已有内容续写
     */
    WritingResultVO continueWriting(WritingRequestDTO dto, Long userId);

    /**
     * 获取写作提示模板列表
     */
    List<WritingTemplateVO> getTemplates();
}

2.5 创建 Service 实现

创建 kb-ai/src/main/java/com/knowledge/base/ai/service/impl/AiWritingServiceImpl.java:

package com.knowledge.base.ai.service.impl;

import com.knowledge.base.ai.config.ModelProvider;
import com.knowledge.base.ai.dto.WritingRequestDTO;
import com.knowledge.base.ai.service.AiWritingService;
import com.knowledge.base.ai.vo.WritingResultVO;
import com.knowledge.base.ai.vo.WritingTemplateVO;
import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.output.Response;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

/**
 * AI写作服务实现类
 *
 * <p>按照阿里巴巴Java开发规范设计,提供AI写作(生成、扩写、优化、续写)的业务逻辑。
 * 支持同步生成和SSE流式生成两种模式。</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class AiWritingServiceImpl implements AiWritingService {

    private final ModelProvider modelProvider;

    @Override
    public WritingResultVO generate(WritingRequestDTO dto, Long userId) {
        String modelName = dto.getModel() != null ? dto.getModel() : modelProvider.getDefaultModelName();
        log.info("AI写作生成请求:userId={}, model={}, actionType={}", userId, modelName, dto.getActionType());

        String prompt = buildWritingPrompt(dto);
        logModelCallParams("生成", modelName, dto, prompt);
        ChatLanguageModel model = resolveModel(dto.getModel());

        try {
            UserMessage userMessage = UserMessage.from(prompt);
            log.info(">>> 开始调用大模型 [{}]:promptLength={}", modelName, prompt.length());
            Response<AiMessage> response = model.generate(userMessage);
            String content = response.content().text().trim();

            logModelCallResult("生成", modelName, response, content);
            return WritingResultVO.builder()
                    .content(content)
                    .tokens(response.tokenUsage() != null ? response.tokenUsage().totalTokenCount() : null)
                    .wordCount(content.length())
                    .model(modelName)
                    .build();
        } catch (Exception e) {
            log.error("AI写作生成失败:model={}, error={}", modelName, e.getMessage(), e);
            throw new RuntimeException("AI写作生成失败: " + e.getMessage());
        }
    }

    @Override
    public SseEmitter generateStream(WritingRequestDTO dto, Long userId) {
        String modelName = dto.getModel() != null ? dto.getModel() : modelProvider.getDefaultModelName();
        log.info("AI写作流式生成请求:userId={}, model={}", userId, modelName);

        SseEmitter emitter = new SseEmitter(30 * 60 * 1000L);
        String prompt = buildWritingPrompt(dto);
        logModelCallParams("流式生成", modelName, dto, prompt);
        ChatLanguageModel model = resolveModel(dto.getModel());

        try {
            UserMessage userMessage = UserMessage.from(prompt);
            log.info(">>> 开始调用大模型 [{}] (流式):promptLength={}", modelName, prompt.length());
            Response<AiMessage> response = model.generate(userMessage);
            String fullContent = response.content().text().trim();

            logModelCallResult("流式生成", modelName, response, fullContent);

            // 按字符分块发送,模拟流式输出
            int chunkSize = 10;
            for (int i = 0; i < fullContent.length(); i += chunkSize) {
                int end = Math.min(i + chunkSize, fullContent.length());
                String chunk = fullContent.substring(i, end);
                emitter.send(SseEmitter.event()
                        .name("message")
                        .data(chunk));
            }

            // 发送完成事件
            WritingResultVO result = WritingResultVO.builder()
                    .content(fullContent)
                    .tokens(response.tokenUsage() != null ? response.tokenUsage().totalTokenCount() : null)
                    .wordCount(fullContent.length())
                    .model(modelName)
                    .build();
            emitter.send(SseEmitter.event()
                    .name("done")
                    .data(result));
            emitter.complete();

            log.info("AI写作流式生成完成:userId={}, wordCount={}", userId, fullContent.length());
        } catch (IOException e) {
            log.error("AI写作流式生成SSE发送失败:model={}, error={}", modelName, e.getMessage(), e);
            emitter.completeWithError(e);
        } catch (Exception e) {
            log.error("AI写作流式生成失败:model={}, error={}", modelName, e.getMessage(), e);
            try {
                emitter.send(SseEmitter.event()
                        .name("error")
                        .data("AI写作生成失败: " + e.getMessage()));
                emitter.complete();
            } catch (IOException ex) {
                emitter.completeWithError(ex);
            }
        }

        return emitter;
    }

    @Override
    public WritingResultVO expand(WritingRequestDTO dto, Long userId) {
        String modelName = dto.getModel() != null ? dto.getModel() : modelProvider.getDefaultModelName();
        log.info("AI写作扩写请求:userId={}, model={}, topic={}", userId, modelName, dto.getTopic());

        if (dto.getExistingContent() == null || dto.getExistingContent().isEmpty()) {
            throw new RuntimeException("扩写功能需要提供已有内容(existingContent)");
        }

        String prompt = String.format("""
                你是一位专业的文档写作助手。请对以下内容进行扩写,要求:
                1. 保持原文的主题和风格
                2. 丰富内容细节,增加深度和广度
                3. 补充相关的背景信息、论证和实例
                4. 保持逻辑连贯,结构清晰
                5. 不要添加任何额外的解释,直接输出扩写后的完整内容

                原文主题:%s

                原文内容:
                %s
                """, dto.getTopic(), dto.getExistingContent());

        logModelCallParams("扩写", modelName, dto, prompt);
        ChatLanguageModel model = resolveModel(dto.getModel());

        try {
            UserMessage userMessage = UserMessage.from(prompt);
            log.info(">>> 开始调用大模型 [{}] (扩写):promptLength={}", modelName, prompt.length());
            Response<AiMessage> response = model.generate(userMessage);
            String content = response.content().text().trim();

            logModelCallResult("扩写", modelName, response, content);
            return WritingResultVO.builder()
                    .content(content)
                    .tokens(response.tokenUsage() != null ? response.tokenUsage().totalTokenCount() : null)
                    .wordCount(content.length())
                    .model(modelName)
                    .build();
        } catch (Exception e) {
            log.error("AI写作扩写失败:model={}, error={}", modelName, e.getMessage(), e);
            throw new RuntimeException("AI写作扩写失败: " + e.getMessage());
        }
    }

    @Override
    public WritingResultVO optimize(WritingRequestDTO dto, Long userId) {
        String modelName = dto.getModel() != null ? dto.getModel() : modelProvider.getDefaultModelName();
        log.info("AI写作优化请求:userId={}, model={}, topic={}", userId, modelName, dto.getTopic());

        if (dto.getExistingContent() == null || dto.getExistingContent().isEmpty()) {
            throw new RuntimeException("优化功能需要提供已有内容(existingContent)");
        }

        String styleDesc = getStyleDescription(dto.getStyle());
        String prompt = String.format("""
                你是一位专业的文档编辑助手。请对以下内容进行优化和润色,要求:
                1. %s
                2. 修正语法错误和表达不清的地方
                3. 优化句子结构,使语言更加流畅
                4. 改善段落组织,增强可读性
                5. 保持原文档的核心意思和信息不变

                原文标题:%s

                原文内容:
                %s
                """, styleDesc, dto.getTopic(), dto.getExistingContent());

        logModelCallParams("优化", modelName, dto, prompt);
        ChatLanguageModel model = resolveModel(dto.getModel());

        try {
            UserMessage userMessage = UserMessage.from(prompt);
            log.info(">>> 开始调用大模型 [{}] (优化):promptLength={}", modelName, prompt.length());
            Response<AiMessage> response = model.generate(userMessage);
            String content = response.content().text().trim();

            logModelCallResult("优化", modelName, response, content);
            return WritingResultVO.builder()
                    .content(content)
                    .tokens(response.tokenUsage() != null ? response.tokenUsage().totalTokenCount() : null)
                    .wordCount(content.length())
                    .model(modelName)
                    .build();
        } catch (Exception e) {
            log.error("AI写作优化失败:model={}, error={}", modelName, e.getMessage(), e);
            throw new RuntimeException("AI写作优化失败: " + e.getMessage());
        }
    }

    @Override
    public WritingResultVO continueWriting(WritingRequestDTO dto, Long userId) {
        String modelName = dto.getModel() != null ? dto.getModel() : modelProvider.getDefaultModelName();
        log.info("AI写作续写请求:userId={}, model={}, topic={}", userId, modelName, dto.getTopic());

        if (dto.getExistingContent() == null || dto.getExistingContent().isEmpty()) {
            throw new RuntimeException("续写功能需要提供已有内容(existingContent)");
        }

        String prompt = String.format("""
                你是一位专业的文档写作助手。请从以下内容的结尾继续进行写作,要求:
                1. 延续原文的主题、风格和逻辑
                2. 内容自然衔接,不要重复已有的内容
                3. 进一步深入展开论述或补充后续内容
                4. 保持结构完整,逻辑清晰
                5. 不要添加任何额外的解释,直接输出续写内容

                原文主题:%s

                已有内容:
                %s

                请从以上内容的结尾处继续写下去。
                """, dto.getTopic(), dto.getExistingContent());

        logModelCallParams("续写", modelName, dto, prompt);
        ChatLanguageModel model = resolveModel(dto.getModel());

        try {
            UserMessage userMessage = UserMessage.from(prompt);
            log.info(">>> 开始调用大模型 [{}] (续写):promptLength={}", modelName, prompt.length());
            Response<AiMessage> response = model.generate(userMessage);
            String content = response.content().text().trim();

            logModelCallResult("续写", modelName, response, content);
            return WritingResultVO.builder()
                    .content(content)
                    .tokens(response.tokenUsage() != null ? response.tokenUsage().totalTokenCount() : null)
                    .wordCount(content.length())
                    .model(modelName)
                    .build();
        } catch (Exception e) {
            log.error("AI写作续写失败:model={}, error={}", modelName, e.getMessage(), e);
            throw new RuntimeException("AI写作续写失败: " + e.getMessage());
        }
    }

    @Override
    @Cacheable(value = "writingTemplates")
    public List<WritingTemplateVO> getTemplates() {
        log.info("获取写作模板列表(未命中缓存,重新构建)");
        List<WritingTemplateVO> templates = new ArrayList<>();

        templates.add(WritingTemplateVO.builder()
                .id("tech-solution")
                .name("技术方案")
                .description("适用于撰写技术方案文档,包含背景分析、方案设计、技术选型、实施计划等完整结构")
                .category("技术文档")
                .prompt("请撰写一份技术方案,包含以下部分:\n一、项目背景与目标\n二、技术现状分析\n三、方案设计\n四、技术选型说明\n五、实施计划\n六、风险评估与应对")
                .suggestedContentType("article")
                .suggestedStyle("technical")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("project-report")
                .name("项目报告")
                .description("适用于项目总结报告,包含项目概述、执行过程、成果分析、经验总结等")
                .category("工作汇报")
                .prompt("请撰写一份项目总结报告,包含以下部分:\n一、项目概述\n二、执行过程\n三、主要成果\n四、问题与挑战\n五、经验与反思\n六、下一步计划")
                .suggestedContentType("report")
                .suggestedStyle("formal")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("prd")
                .name("产品需求文档(PRD)")
                .description("适用于产品需求文档,包含需求背景、功能描述、用户场景、验收标准等")
                .category("产品文档")
                .prompt("请撰写一份产品需求文档(PRD),包含以下部分:\n一、需求背景与目标\n二、目标用户分析\n三、核心功能说明\n四、用户使用流程\n五、交互设计要求\n六、验收标准")
                .suggestedContentType("documentation")
                .suggestedStyle("technical")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("api-doc")
                .name("API接口文档")
                .description("适用于编写API接口文档,包含接口说明、请求参数、响应格式、示例代码等")
                .category("技术文档")
                .prompt("请撰写一份API接口文档,包含以下部分:\n一、接口概述\n二、认证方式\n三、请求格式说明\n四、响应格式说明\n五、各接口详细说明(含请求示例和响应示例)\n六、错误码说明")
                .suggestedContentType("documentation")
                .suggestedStyle("technical")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("weekly-report")
                .name("周报/工作汇报")
                .description("适用于周报或工作汇报,包含本周工作、下周计划、问题反馈等")
                .category("工作汇报")
                .prompt("请撰写一份工作周报,包含以下部分:\n一、本周完成工作\n二、重点工作进展\n三、遇到的问题及解决方案\n四、下周工作计划\n五、需要协调的事项")
                .suggestedContentType("report")
                .suggestedStyle("formal")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("meeting-minutes")
                .name("会议纪要")
                .description("适用于会议纪要,包含会议信息、讨论内容、决议事项、待办任务等")
                .category("工作汇报")
                .prompt("请撰写一份会议纪要,包含以下部分:\n一、会议基本信息(时间、地点、参会人员)\n二、会议议题\n三、讨论内容要点\n四、决议事项\n五、待办任务及负责人\n六、下次会议时间")
                .suggestedContentType("email")
                .suggestedStyle("formal")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("announcement")
                .name("公告通知")
                .description("适用于公司内部公告或通知,包含公告事项、具体内容、执行要求等")
                .category("行政文档")
                .prompt("请撰写一份公告通知,包含以下部分:\n一、公告标题\n二、公告缘由\n三、具体事项说明\n四、执行要求或时间安排\n五、联系方式")
                .suggestedContentType("announcement")
                .suggestedStyle("formal")
                .build());

        templates.add(WritingTemplateVO.builder()
                .id("email-template")
                .name("邮件模板")
                .description("适用于编写工作邮件,包含邮件主题、称呼、正文、结尾等")
                .category("日常沟通")
                .prompt("请撰写一封工作邮件,包含以下要素:\n1. 清晰明确的邮件主题\n2. 恰当的称呼\n3. 简洁明了的事项说明\n4. 必要的背景信息\n5. 明确的行动要求或期望\n6. 专业的结尾和签名")
                .suggestedContentType("email")
                .suggestedStyle("formal")
                .build());

        return templates;
    }

    // ==================== 私有辅助方法 ====================

    /**
     * 构建写作Prompt
     *
     * <p>根据用户输入的参数(内容类型、风格、语气、字数等),
     * 构建一个结构化的Prompt发送给大语言模型。</p>
     *
     * @param dto 写作请求参数
     * @return 完整的Prompt字符串
     */
    private String buildWritingPrompt(WritingRequestDTO dto) {
        StringBuilder prompt = new StringBuilder();
        prompt.append("你是一位专业的文档写作助手。请根据以下要求进行写作。\n\n");

        // 内容类型说明
        String contentType = dto.getContentType() != null ? dto.getContentType() : "article";
        String contentTypeDesc = switch (contentType) {
            case "report" -> "这是一份报告,要求结构清晰,数据翔实,论证充分";
            case "documentation" -> "这是一份技术文档,要求准确、规范、可操作,包含代码示例";
            case "email" -> "这是一封邮件,要求礼貌、简洁、重点突出";
            case "announcement" -> "这是一份公告,要求正式、严谨、表述清楚";
            default -> "这是一篇文章,要求主题明确,逻辑清晰,表达流畅";
        };
        prompt.append(contentTypeDesc).append("。\n\n");

        // 风格说明
        String style = dto.getStyle() != null ? dto.getStyle() : "formal";
        String styleDesc = switch (style) {
            case "casual" -> "请使用轻松随意的风格,避免过于正式的表达";
            case "technical" -> "请使用专业技术风格,适当使用专业术语,注重准确性和严谨性";
            case "creative" -> "请使用具有创造性的表达方式,不拘泥于传统格式";
            case "academic" -> "请使用学术论文风格,注重论证的严谨性和引用的规范性";
            default -> "请使用正式规范的风格,表达专业、得体";
        };
        prompt.append(styleDesc).append("。\n");

        // 语气说明
        if (dto.getTone() != null && !dto.getTone().isEmpty()) {
            String toneDesc = switch (dto.getTone().toLowerCase()) {
                case "enthusiastic" -> "语气热情积极,富有感染力";
                case "serious" -> "语气严肃认真,注重权威性";
                case "friendly" -> "语气友好亲切,拉近与读者的距离";
                case "authoritative" -> "语气权威专业,展现专业深度";
                default -> "语气平和中性,客观陈述";
            };
            prompt.append(toneDesc).append("。\n");
        }

        // 字数说明
        int length = (dto.getLength() != null && dto.getLength() > 0) ? dto.getLength() : 800;
        prompt.append("字数要求:约").append(length).append("字。\n\n");

        // 主题和要求
        prompt.append("写作主题:").append(dto.getTopic()).append("\n");
        if (dto.getRequirements() != null && !dto.getRequirements().isEmpty()) {
            prompt.append("写作要求:").append(dto.getRequirements()).append("\n");
        }

        // 已有内容(用于扩写、优化、续写场景)
        if (dto.getExistingContent() != null && !dto.getExistingContent().isEmpty()) {
            prompt.append("\n参考内容:\n```\n")
                    .append(dto.getExistingContent())
                    .append("\n```\n");
        }

        prompt.append("\n请直接输出写作结果,不要添加额外的解释说明。使用Markdown格式组织内容。");
        return prompt.toString();
    }

    /**
     * 打印大模型调用参数日志
     */
    private void logModelCallParams(String action, String modelName, WritingRequestDTO dto, String prompt) {
        log.info("══════ AI写作[{}] - 模型调用参数 ══════", action);
        log.info("  模型名称: {}", modelName);
        log.info("  写作主题: {}", dto.getTopic());
        log.info("  内容类型: {}", dto.getContentType() != null ? dto.getContentType() : "article(默认)");
        log.info("  写作风格: {}", dto.getStyle() != null ? dto.getStyle() : "formal(默认)");
        log.info("  语气:     {}", dto.getTone() != null ? dto.getTone() : "neutral(默认)");
        log.info("  期望字数: {}", (dto.getLength() != null && dto.getLength() > 0) ? dto.getLength() : 800);
        log.info("  Prompt总长度: {} 字符", prompt.length());
        log.info("══════════════════════════════════════════");
    }

    /**
     * 打印大模型调用结果日志
     */
    private void logModelCallResult(String action, String modelName, Response<AiMessage> response, String content) {
        Integer inputTokens = response.tokenUsage() != null ? response.tokenUsage().inputTokenCount() : null;
        Integer outputTokens = response.tokenUsage() != null ? response.tokenUsage().outputTokenCount() : null;
        Integer totalTokens = response.tokenUsage() != null ? response.tokenUsage().totalTokenCount() : null;
        log.info("<<< 大模型调用完成 [{}]:model={}, 输出长度={}字, " +
                        "inputTokens={}, outputTokens={}, totalTokens={}",
                action, modelName, content.length(),
                inputTokens, outputTokens, totalTokens);
    }

    /**
     * 根据模型名称解析ChatLanguageModel
     */
    private ChatLanguageModel resolveModel(String modelName) {
        if (modelName != null && !modelName.isEmpty()) {
            return modelProvider.getModel(modelName);
        }
        return modelProvider.getDefaultModel();
    }

    /**
     * 获取风格描述(用于优化场景)
     */
    private String getStyleDescription(String style) {
        if (style == null || style.isEmpty()) {
            return "提升文章的整体可读性和专业性";
        }
        return switch (style.toLowerCase()) {
            case "casual" -> "使用轻松易读的表达方式,使文章更加亲切";
            case "technical" -> "使用更专业精准的技术术语,提升技术准确性";
            case "creative" -> "使用更有创意和感染力的表达方式";
            case "academic" -> "使用更严谨的学术表达,增强论证逻辑";
            default -> "提升文章的整体可读性和专业性";
        };
    }
}

设计要点:

  1. Prompt构建:buildWritingPrompt() 方法将用户的参数选择(内容类型、风格、语气、字数等)转化为结构化的 Prompt 指令,确保大模型按预期输出
  2. 大模型调用:通过 ModelProvider 获取 ChatLanguageModel 实例,调用 model.generate() 进行文本生成
  3. SSE流式输出:generateStream() 方法使用 SseEmitter 实现服务器推送,将生成内容按10字符分块发送
  4. 详细日志:每个大模型调用前后打印结构化日志,包括模型参数和 token 消耗
  5. 参数校验:扩写/优化/续写功能检查 existingContent 是否为空

2.6 创建缓存配置

创建 kb-ai/src/main/java/com/knowledge/base/ai/config/CacheConfig.java:

package com.knowledge.base.ai.config;

import com.github.benmanes.caffeine.cache.Caffeine;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.caffeine.CaffeineCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.concurrent.TimeUnit;

/**
 * 本地缓存配置
 *
 * <p>使用Caffeine作为本地缓存实现,为频繁访问的只读数据提供高性能缓存。</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Configuration
@EnableCaching
public class CacheConfig {

    /**
     * 配置Caffeine CacheManager
     *
     * <p>写作模板等只读数据缓存24小时,避免每次请求都重建列表。</p>
     *
     * @return CacheManager实例
     */
    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(Caffeine.newBuilder()
                .expireAfterWrite(24, TimeUnit.HOURS)
                .maximumSize(100)
                .recordStats());
        return cacheManager;
    }
}

设计要点:

  • @EnableCaching 启用 Spring Cache 抽象
  • .expireAfterWrite(24, HOURS) — 模板数据24小时过期
  • .maximumSize(100) — 最多缓存100个不同的缓存键
  • .recordStats() — 启用缓存命中率统计

2.7 创建 Controller

创建 kb-ai/src/main/java/com/knowledge/base/ai/controller/AiWritingController.java:

package com.knowledge.base.ai.controller;

import com.knowledge.base.ai.dto.WritingRequestDTO;
import com.knowledge.base.ai.service.AiWritingService;
import com.knowledge.base.ai.vo.WritingResultVO;
import com.knowledge.base.ai.vo.WritingTemplateVO;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.common.utils.UserContextUtil;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;

import java.util.List;

/**
 * AI写作控制器
 *
 * <p>提供AI写作相关接口,包括内容生成、扩写、优化、续写和模板管理。</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@RestController
@RequestMapping("/writing")
@RequiredArgsConstructor
@Tag(name = "AI写作", description = "AI写作相关接口")
public class AiWritingController {

    private final AiWritingService aiWritingService;

    /**
     * 根据主题和需求生成写作内容
     */
    @PostMapping("/generate")
    @Operation(summary = "生成写作内容", description = "根据写作主题和需求参数,使用AI生成写作内容")
    public Result<WritingResultVO> generate(
            @Valid @RequestBody WritingRequestDTO dto,
            HttpServletRequest request) {
        log.info("AI写作生成请求:topic={}, contentType={}, style={}", dto.getTopic(), dto.getContentType(), dto.getStyle());
        Long userId = UserContextUtil.getUserIdFromHeader(request);
        WritingResultVO result = aiWritingService.generate(dto, userId);
        return Result.success(result);
    }

    /**
     * 流式生成写作内容(SSE)
     */
    @PostMapping("/generate/stream")
    @Operation(summary = "流式生成写作内容", description = "流式(SSE)生成写作内容,实时返回生成结果")
    public SseEmitter generateStream(
            @Valid @RequestBody WritingRequestDTO dto,
            HttpServletRequest request) {
        log.info("AI写作流式生成请求:topic={}", dto.getTopic());
        Long userId = UserContextUtil.getUserIdFromHeader(request);
        return aiWritingService.generateStream(dto, userId);
    }

    /**
     * 扩写已有内容
     */
    @PostMapping("/expand")
    @Operation(summary = "扩写内容", description = "对已有内容进行扩展,丰富细节和深度")
    public Result<WritingResultVO> expand(
            @Valid @RequestBody WritingRequestDTO dto,
            HttpServletRequest request) {
        Long userId = UserContextUtil.getUserIdFromHeader(request);
        WritingResultVO result = aiWritingService.expand(dto, userId);
        return Result.success(result);
    }

    /**
     * 优化/润色内容
     */
    @PostMapping("/optimize")
    @Operation(summary = "优化润色", description = "对已有内容进行优化和润色,提升表达质量")
    public Result<WritingResultVO> optimize(
            @Valid @RequestBody WritingRequestDTO dto,
            HttpServletRequest request) {
        Long userId = UserContextUtil.getUserIdFromHeader(request);
        WritingResultVO result = aiWritingService.optimize(dto, userId);
        return Result.success(result);
    }

    /**
     * 续写内容
     */
    @PostMapping("/continue")
    @Operation(summary = "续写内容", description = "从已有内容的结尾处继续写作")
    public Result<WritingResultVO> continueWriting(
            @Valid @RequestBody WritingRequestDTO dto,
            HttpServletRequest request) {
        Long userId = UserContextUtil.getUserIdFromHeader(request);
        WritingResultVO result = aiWritingService.continueWriting(dto, userId);
        return Result.success(result);
    }

    /**
     * 获取写作提示模板
     */
    @GetMapping("/templates")
    @Operation(summary = "获取写作模板", description = "获取预设的写作提示模板列表,用于快速开始写作")
    public Result<List<WritingTemplateVO>> getTemplates() {
        log.info("获取写作模板列表");
        List<WritingTemplateVO> templates = aiWritingService.getTemplates();
        return Result.success(templates);
    }
}

关键设计:

  • @RequestMapping("/writing"):*注意这里是 */writing**,不是 **/api/ai/writing**!** 因为 Spring Cloud Gateway 通过 StripPrefix=2 已经剥离了 /api/ai 前缀
  • 流式端点返回 SseEmitter,不包装在 Result 中
  • 使用 UserContextUtil.getUserIdFromHeader(request) 从请求头获取当前用户

2.8 API 接口汇总

方法路径说明
POST/api/ai/writing/generate同步生成写作内容
POST/api/ai/writing/generate/stream流式(SSE)生成写作内容
POST/api/ai/writing/expand扩写已有内容
POST/api/ai/writing/optimize优化润色已有内容
POST/api/ai/writing/continue续写已有内容
GET/api/ai/writing/templates获取写作模板列表
注意:客户端访问路径以 /api/ai/writing 开头,经 Gateway 剥离前缀后,转发到 kb-ai 服务时变为 /writing。

2.9 Gateway 路由确认

确认 kb-gateway/src/main/resources/application.yml 中包含 kb-ai 路由(通常已存在):

- id: kb-ai
  uri: lb://kb-ai
  predicates:
    - Path=/api/ai/**
  filters:
    - StripPrefix=2

同时确认白名单中包含 /api/ai/**:

gateway:
  white-list:
    - /api/ai/**

三、前端实现

3.1 添加 TypeScript 类型定义

编辑 src/types/index.ts,在 Document 接口后添加 AI 写作相关类型:

/** AI写作请求参数 */
export interface WritingRequest {
  topic: string;
  requirements?: string;
  contentType?: 'article' | 'report' | 'documentation' | 'email' | 'announcement';
  style?: 'formal' | 'casual' | 'technical' | 'creative' | 'academic';
  tone?: 'neutral' | 'enthusiastic' | 'serious' | 'friendly' | 'authoritative';
  length?: number;
  existingContent?: string;
  actionType?: string;
  templateId?: string;
  model?: string;
}

/** AI写作结果 */
export interface WritingResult {
  content: string;
  tokens?: number;
  wordCount?: number;
  model?: string;
}

/** 写作模板 */
export interface WritingTemplate {
  id: string;
  name: string;
  description: string;
  category: string;
  prompt: string;
  suggestedContentType?: string;
  suggestedStyle?: string;
}

/** 内容类型选项 */
export interface ContentTypeOption {
  value: string;
  label: string;
}

/** 写作风格选项 */
export interface StyleOption {
  value: string;
  label: string;
}

/** 语气选项 */
export interface ToneOption {
  value: string;
  label: string;
}

3.2 添加 API 服务方法

编辑 src/services/ai.service.ts,在现有方法后添加 6 个 AI 写作 API:

// ==================== AI Writing APIs ====================

// 获取写作模板
getWritingTemplates: () => {
  return http.get<WritingTemplate[]>('/ai/writing/templates');
},

// 生成写作内容
generateWriting: (data: WritingRequest) => {
  return http.post<WritingResult>('/ai/writing/generate', { ...data, actionType: 'generate' });
},

// 流式生成写作内容
generateWritingStream: (
  data: WritingRequest,
  onMessage: (chunk: string) => void,
  onDone?: (result: WritingResult) => void,
  onError?: (error: string) => void,
) => {
  const apiBase = import.meta.env.VITE_API_BASE_URL;
  return fetch(`${apiBase}/ai/writing/generate/stream`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': tokenStorage.getAuthorizationHeader(),
    },
    body: JSON.stringify(data),
  }).then(async (response) => {
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();
    if (!reader) throw new Error('无法读取响应流');

    let buffer = '';
    let currentEvent = '';
    let messageLines: string[] = [];

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split('\n');
      buffer = lines.pop() || '';

      for (const line of lines) {
        if (line.startsWith('event:')) {
          if (messageLines.length > 0) {
            onMessage(messageLines.join('\n'));
            messageLines = [];
          }
          currentEvent = line.slice(6).trim();
          continue;
        }
        if (line.startsWith('data:')) {
          const data = line.startsWith('data: ') ? line.slice(6) : line.slice(5);
          if (currentEvent === 'error') {
            onError?.(data);
            continue;
          }
          if (currentEvent === 'done') {
            try { onDone?.(JSON.parse(data)); } catch { /* ignore */ }
            continue;
          }
          messageLines.push(data);
          continue;
        }
        if (line === '') {
          if (messageLines.length > 0) {
            onMessage(messageLines.join('\n'));
            messageLines = [];
          }
          currentEvent = '';
        }
      }
    }
    if (messageLines.length > 0) {
      onMessage(messageLines.join('\n'));
    }
  });
},

// 扩写内容
expandWriting: (data: WritingRequest) => {
  return http.post<WritingResult>('/ai/writing/expand', { ...data, actionType: 'expand' });
},

// 优化内容
optimizeWriting: (data: WritingRequest) => {
  return http.post<WritingResult>('/ai/writing/optimize', { ...data, actionType: 'optimize' });
},

// 续写内容
continueWriting: (data: WritingRequest) => {
  return http.post<WritingResult>('/ai/writing/continue', { ...data, actionType: 'continue' });
},

SSE 流式解析逻辑:

  • 使用 fetch() 直接读取 HTTP 响应流
  • TextDecoder 逐块解码字节
  • 按行解析 SSE 协议:event: / data: / 空行分隔
  • message 事件累积多行数据后回调 onMessage
  • done 事件解析 JSON 后回调 onDone
  • error 事件回调 onError

3.3 创建 Zustand Store

创建 src/stores/ai-writing.store.ts:

import { create } from 'zustand';
import { WritingRequest, WritingResult, WritingTemplate } from '@/types';
import { aiService } from '@/services';

interface AIWritingState {
  // 数据
  templates: WritingTemplate[];
  generatedContent: string;
  isGenerating: boolean;
  isStreaming: boolean;
  tokens: number;
  wordCount: number;
  lastResult: WritingResult | null;
  error: string | null;

  // 操作
  fetchTemplates: () => Promise<void>;
  generateContent: (data: WritingRequest) => Promise<WritingResult>;
  generateContentStream: (data: WritingRequest) => Promise<WritingResult>;
  expandContent: (data: WritingRequest) => Promise<WritingResult>;
  optimizeContent: (data: WritingRequest) => Promise<WritingResult>;
  continueWriting: (data: WritingRequest) => Promise<WritingResult>;
  setGeneratedContent: (content: string) => void;
  clearResult: () => void;
  reset: () => void;
}

export const useAIWritingStore = create<AIWritingState>((set) => ({
  templates: [],
  generatedContent: '',
  isGenerating: false,
  isStreaming: false,
  tokens: 0,
  wordCount: 0,
  lastResult: null,
  error: null,

  fetchTemplates: async () => {
    try {
      const response = await aiService.getWritingTemplates();
      const data = (response as any)?.data || response;
      set({ templates: Array.isArray(data) ? data : [] });
    } catch (err) {
      console.error('获取写作模板失败:', err);
    }
  },

  generateContent: async (data: WritingRequest) => {
    set({ isGenerating: true, error: null, generatedContent: '' });
    try {
      const response = await aiService.generateWriting(data);
      const result = (response as any)?.data || response;
      set({
        generatedContent: result?.content || '',
        tokens: result?.tokens || 0,
        wordCount: result?.wordCount || 0,
        lastResult: result,
        isGenerating: false,
      });
      return result;
    } catch (err: any) {
      const msg = err?.message || '生成失败';
      set({ isGenerating: false, error: msg });
      throw err;
    }
  },

  generateContentStream: async (data: WritingRequest) => {
    set({ isGenerating: true, isStreaming: true, error: null, generatedContent: '' });
    let fullContent = '';
    try {
      await aiService.generateWritingStream(
        { ...data, actionType: 'generate' },
        (chunk: string) => {
          fullContent += chunk;
          set({ generatedContent: fullContent });
        },
        (result: WritingResult) => {
          set({
            generatedContent: result.content || fullContent,
            tokens: result.tokens || 0,
            wordCount: result.wordCount || 0,
            lastResult: result,
            isGenerating: false,
            isStreaming: false,
          });
        },
        (err: string) => {
          set({ isGenerating: false, isStreaming: false, error: err });
        },
      );
      return { content: fullContent, tokens: 0, wordCount: fullContent.length, model: '' };
    } catch (err: any) {
      const msg = err?.message || '流式生成失败';
      set({ isGenerating: false, isStreaming: false, error: msg });
      throw err;
    }
  },

  expandContent: async (data: WritingRequest) => {
    set({ isGenerating: true, error: null });
    try {
      const response = await aiService.expandWriting(data);
      const result = (response as any)?.data || response;
      set({
        generatedContent: result?.content || '',
        tokens: result?.tokens || 0,
        wordCount: result?.wordCount || 0,
        lastResult: result,
        isGenerating: false,
      });
      return result;
    } catch (err: any) {
      const msg = err?.message || '扩写失败';
      set({ isGenerating: false, error: msg });
      throw err;
    }
  },

  optimizeContent: async (data: WritingRequest) => {
    set({ isGenerating: true, error: null });
    try {
      const response = await aiService.optimizeWriting(data);
      const result = (response as any)?.data || response;
      set({
        generatedContent: result?.content || '',
        tokens: result?.tokens || 0,
        wordCount: result?.wordCount || 0,
        lastResult: result,
        isGenerating: false,
      });
      return result;
    } catch (err: any) {
      const msg = err?.message || '优化失败';
      set({ isGenerating: false, error: msg });
      throw err;
    }
  },

  continueWriting: async (data: WritingRequest) => {
    set({ isGenerating: true, error: null });
    try {
      const response = await aiService.continueWriting(data);
      const result = (response as any)?.data || response;
      set({
        generatedContent: result?.content || '',
        tokens: result?.tokens || 0,
        wordCount: result?.wordCount || 0,
        lastResult: result,
        isGenerating: false,
      });
      return result;
    } catch (err: any) {
      const msg = err?.message || '续写失败';
      set({ isGenerating: false, error: msg });
      throw err;
    }
  },

  setGeneratedContent: (content: string) => {
    set({ generatedContent: content });
  },

  clearResult: () => {
    set({
      generatedContent: '',
      tokens: 0,
      wordCount: 0,
      lastResult: null,
      error: null,
    });
  },

  reset: () => {
    set({
      templates: [],
      generatedContent: '',
      isGenerating: false,
      isStreaming: false,
      tokens: 0,
      wordCount: 0,
      lastResult: null,
      error: null,
    });
  },
}));

Store 设计说明:

  • fetchTemplates() 在页面加载时调用,首次从后端获取模板列表
  • generateContentStream() 通过回调函数实时更新 generatedContent,实现流式输出效果
  • 生成过程中 isGenerating 为 true,前端据此禁用按钮防止重复提交
  • clearResult() 和 reset() 用于清空当前结果或完全重置状态

3.4 导出 Store

编辑 src/stores/index.ts,添加导出:

export { useAIWritingStore } from './ai-writing.store';

3.5 添加路由

编辑 src/router/index.tsx:

步骤1:在文件顶部添加懒加载导入:

const AIWritingPage = lazy(() => import('@/pages/AIWritingPage'));

步骤2:在 MainLayout 的 children 路由中添加(建议放在 AI助手路由之后):

{
  path: 'ai-writing',
  element: (
    <ProtectedRoute>
      <Suspense fallback={<LoadingFallback />}>
        <AIWritingPage />
      </Suspense>
    </ProtectedRoute>
  ),
},

3.6 添加导航入口(顶部导航栏)

编辑 src/components/layout/MainLayout.tsx,在 AI助手 导航链接后添加 AI写作 入口:

{/* AI写作 - 最明显的入口 */}
<NavLink
  to="/ai-writing"
  className={({ isActive }) =>
    `nav-item ${isActive ? 'active' : ''}`
  }
>
  <EditOutlined />
  <span>AI写作</span>
</NavLink>

3.7 添加文档详情页入口按钮

编辑 src/pages/DocumentDetailPage.tsx,在文档操作按钮区域添加"AI写作"按钮:

步骤1:确保已导入 EditOutlined 图标:

import { EditOutlined, ... } from '@ant-design/icons';

步骤2:在操作按钮区域(分享文档按钮旁)添加:

<Button
  icon={<EditOutlined />}
  onClick={() => {
    const content = currentDoc?.content || '';
    const preview = content.length > 500 ? content.substring(0, 500) : content;
    const title = currentDoc?.title || '';
    navigate(`/ai-writing?content=${encodeURIComponent(preview)}&title=${encodeURIComponent(title)}`);
  }}
>
  AI写作
</Button>

说明:点击后跳转到 AI写作页面,并自动将当前文档的标题和前500字内容填入表单。用户可以直接基于当前文档进行续写、扩写或优化。

3.8 创建 AI写作页面

创建 src/pages/AIWritingPage.tsx(核心页面,约1100行):

import React, { useEffect, useState, useCallback, useRef } from 'react';
import { useSearchParams, useNavigate } from 'react-router-dom';
import {
  Input, Select, Button, Space, Tag, Typography, Spin, InputNumber, Tooltip,
} from 'antd';
import { App } from 'antd';
import {
  RobotOutlined, ThunderboltOutlined, EditOutlined,
  CopyOutlined, CheckOutlined, ExpandOutlined,
  FormatPainterOutlined, ForwardOutlined, FileAddOutlined,
  ClearOutlined, ArrowLeftOutlined,
} from '@ant-design/icons';
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';
import { useAIWritingStore } from '@/stores';
import type { WritingRequest } from '@/types';
import type { Components } from 'react-markdown';

const { Text } = Typography;
const { TextArea } = Input;

// ==================== 设计系统 ====================

const COLORS = {
  pageBg: '#f7f8fa',
  cardBg: '#ffffff',
  cardBorder: '#e9ebf0',
  sidebarBg: '#fafbfc',
  sidebarBorder: '#edf0f4',
  textPrimary: '#111827',
  textSecondary: '#4b5563',
  textMuted: '#9ca3af',
  accent: '#2563eb',
  accentLight: '#3b82f6',
  accentBg: 'rgba(37, 99, 235, 0.06)',
  accentBorder: 'rgba(37, 99, 235, 0.15)',
  success: '#10b981',
  warning: '#f59e0b',
  danger: '#ef4444',
  inputBg: '#f9fafb',
  inputBorder: '#e5e7eb',
  inputFocusBorder: '#2563eb',
  sendBtnStart: '#2563eb',
  sendBtnEnd: '#1d4ed8',
};

const SHADOWS = {
  card: '0 1px 3px rgba(0, 0, 0, 0.04), 0 1px 2px rgba(0, 0, 0, 0.02)',
  button: '0 2px 8px rgba(37, 99, 235, 0.25)',
  icon: '0 4px 12px rgba(37, 99, 235, 0.18)',
};

// ==================== 选项数据 ====================

const contentTypes = [
  { value: 'article', label: '文章' },
  { value: 'report', label: '报告' },
  { value: 'documentation', label: '技术文档' },
  { value: 'email', label: '邮件' },
  { value: 'announcement', label: '公告' },
];

const styleOptions = [
  { value: 'formal', label: '正式' },
  { value: 'casual', label: '轻松' },
  { value: 'technical', label: '技术' },
  { value: 'creative', label: '创意' },
  { value: 'academic', label: '学术' },
];

const toneOptions = [
  { value: 'neutral', label: '中性' },
  { value: 'enthusiastic', label: '热情' },
  { value: 'serious', label: '严肃' },
  { value: 'friendly', label: '友好' },
  { value: 'authoritative', label: '权威' },
];

// ==================== 页面组件 ====================

const AIWritingPage: React.FC = () => {
  const navigate = useNavigate();
  const [searchParams] = useSearchParams();
  const { message } = App.useApp();
  const store = useAIWritingStore();

  // 表单状态
  const [topic, setTopic] = useState('');
  const [requirements, setRequirements] = useState('');
  const [contentType, setContentType] = useState('article');
  const [style, setStyle] = useState('formal');
  const [tone, setTone] = useState('neutral');
  const [length, setLength] = useState<number | null>(800);
  const [useStream, setUseStream] = useState(true);

  // 读取 URL 参数预填表单(从文档详情页跳转时携带)
  useEffect(() => {
    const titleParam = searchParams.get('title');
    const contentParam = searchParams.get('content');
    if (titleParam) setTopic(decodeURIComponent(titleParam));
    if (contentParam) setRequirements(decodeURIComponent(contentParam));
  }, [searchParams]);

  // 加载模板
  useEffect(() => { store.fetchTemplates(); }, []);

  // 应用模板
  const applyTemplate = useCallback((tpl: typeof store.templates[0]) => {
    setTopic(tpl.prompt || '');
    if (tpl.suggestedContentType) setContentType(tpl.suggestedContentType);
    if (tpl.suggestedStyle) setStyle(tpl.suggestedStyle);
  }, []);

  // 构建请求
  const buildRequest = (actionType: WritingRequest['actionType']): WritingRequest => ({
    topic: topic.trim(),
    requirements: requirements.trim() || undefined,
    existingContent: requirements.trim() || undefined,
    contentType: contentType as WritingRequest['contentType'],
    style: style as WritingRequest['style'],
    tone: tone as WritingRequest['tone'],
    length: length || undefined,
    actionType,
  });

  // 生成内容
  const handleGenerate = async () => {
    if (!topic.trim()) { message.warning('请输入写作主题'); return; }
    try {
      await (useStream
        ? store.generateContentStream(buildRequest('generate'))
        : store.generateContent(buildRequest('generate')));
    } catch { message.error('生成失败,请稍后重试'); }
  };

  // 插入到新文档(新窗口打开)
  const handleInsertToDocument = () => {
    if (!store.generatedContent) return;
    const encodedContent = encodeURIComponent(store.generatedContent);
    const encodedTitle = encodeURIComponent(topic || 'AI 生成文档');
    window.open(`/documents/new?content=${encodedContent}&title=${encodedTitle}`, '_blank');
  };

  // 复制
  const handleCopyContent = () => {
    if (!store.generatedContent) return;
    navigator.clipboard.writeText(store.generatedContent).then(() => {
      message.success('已复制到剪贴板');
    });
  };

  // 清空
  const handleClear = () => {
    setTopic(''); setRequirements('');
    setContentType('article'); setStyle('formal');
    setTone('neutral'); setLength(800);
    store.clearResult();
  };

  // ...(扩写、优化、续写 handler 实现省略,完整代码参见源码文件)

  return (
    <>
      <style>{MARKDOWN_STYLES}</style>
      <div style={{
        height: 'calc(100vh - 80px)', display: 'flex', gap: 0,
        background: COLORS.pageBg, overflow: 'hidden',
      }}>
        {/* ======== 左侧输入面板 (380px) ======== */}
        <div style={{
          width: 380, minWidth: 380, height: '100%',
          overflow: 'hidden auto', borderRight: `1px solid ${COLORS.sidebarBorder}`,
          background: COLORS.sidebarBg, padding: '20px 20px 24px',
          display: 'flex', flexDirection: 'column', gap: 18,
        }}>
          {/* 头部:渐变图标 + 标题 + 返回按钮 */}
          {/* 写作主题输入框 */}
          {/* 写作要求文本域 */}
          {/* 内容类型 + 写作风格(并排 Select) */}
          {/* 语气 + 期望字数(并排 Select/InputNumber) */}
          {/* 生成方式切换:流式生成 | 普通生成 */}
          {/* 操作按钮组:生成、扩写、优化、续写 */}
          {/* 写作模板卡片列表 */}
          {/* 清空按钮 */}
        </div>
        {/* ======== 右侧内容面板 ======== */}
        <div style={{ flex: 1, height: '100%', display: 'flex', flexDirection: 'column', background: COLORS.pageBg }}>
          {/* 工具栏:统计信息 + 复制/插入到文档按钮 */}
          {/* Markdown 渲染内容区(空状态/加载中/错误/结果) */}
          {/* 底部声明:"内容由 AI 生成..." */}
        </div>
      </div>
    </>
  );
};

export default AIWritingPage;
完整的页面代码约1100行,包含 Markdown CSS 样式注入、代码高亮、空状态/加载/错误三种状态处理、模板卡片 hover 交互等。完整代码参见项目源码 src/pages/AIWritingPage.tsx。

页面设计说明:

  • 左右两栏布局:左侧380px输入面板,右侧flex:1内容展示区
  • 配色方案与全局保持一致(#2563eb 蓝色系)
  • 支持 URL 参数预填充(从文档详情页跳转)
  • 流式生成时实时渲染 Markdown,打字机效果
  • 8个写作模板卡片,点击自动填入 Prompt
  • "插入到文档"按钮在新标签页打开创建文档页面

3.9 支持新建文档页接收预填参数

编辑 src/pages/CreateDocumentPage.tsx,使其能读取 URL 中的 content 和 title 参数:

步骤1:导入 useSearchParams:

import { useNavigate, useSearchParams } from 'react-router-dom';

步骤2:在组件内读取参数并初始化状态:

const [searchParams] = useSearchParams();
const prefilledTitle = searchParams.get('title') || '';
const prefilledContent = searchParams.get('content') || '';

const [title, setTitle] = useState(decodeURIComponent(prefilledTitle));
const [content, setContent] = useState(decodeURIComponent(prefilledContent));

四、配置调整

4.1 修复开发环境跨域问题

编辑 frontend/.env.development,将 VITE_API_BASE_URL 改为相对路径,使 fetch() 流式请求也走 Vite 代理:

# API配置 - 通过Vite代理转发,避免跨域问题
VITE_API_BASE_URL=/api

原因:流式端点使用原生 fetch() 直接调用,如果 VITE_API_BASE_URL 是完整 URL(如 http://localhost:8080/api),浏览器会发起跨域请求。改为相对路径 /api 后,请求走 Vite 代理,无跨域问题。


五、测试

按顺序启动下面这些微服务:

kb-gateway

kb-statistic

启动前端

cd knowledge-base-frontend

npm run dev

浏览器访问AI写作页面:

http://localhost:3003/ai-writing

图片.png

在页面中输入主题和相关内容,点击生成内容按钮:

图片.png

会在右边的窗口中生成相关文档。

点击右上角的插入到文档按钮:

图片.png

会新窗口打开创建新文档页面,并且将AI创作的文章标题和内容自动填充到这个页面中。

点击发布文档按钮:

图片.png

即可将文档发布成功。

使用AI写作功能写文档,效率非常高。

总结

本章实现了完整的 AI 写作功能,涵盖了以下要点:

维度实现内容
后端接口6个REST API端点(生成、流式生成、扩写、优化、续写、模板)
大模型集成通过 LangChain4j 统一调用 Qwen/DeepSeek,Prompt 结构化构建
流式输出SSE 协议实现实时推流,前端逐字渲染 Markdown
缓存优化Caffeine 本地缓存写作模板,24小时过期
前端页面专业两栏写作工作台,8种写作模板,Markdown 渲染
导航入口顶部导航栏 + 文档详情页,两个入口
文档集成生成内容一键插入新建文档页面
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏