增加AI写作功能
一、概述
AI写作是知识库系统的重要智能化功能,通过集成大语言模型(如通义千问、DeepSeek),帮助用户快速生成、扩写、优化和续写文档内容。本章将详细介绍如何在 kb-ai 服务和前端项目中实现完整的 AI 写作功能。
1.1 功能定位
AI写作作为知识库的智能创作工具,提供以下核心能力:
| 功能模块 | 说明 | 使用场景 |
|---|---|---|
| 内容生成 | 根据主题和要求自动生成文档 | 快速撰写技术方案、周报、PRD等 |
| 流式生成 | SSE实时输出生成内容 | 提升用户体验,减少等待焦虑 |
| 内容扩写 | 对已有内容进行扩展 | 丰富文档细节,增加深度和广度 |
| 内容优化 | 润色和优化已有文档 | 提升文档质量,改善表达 |
| 内容续写 | 从已有内容的结尾处继续写作 | 完成未完成的文档 |
| 写作模板 | 预设8种写作提示模板 | 快速开始,减少重复输入 |
1.2 涉及项目模块
| 模块 | 说明 |
|---|---|
| kb-ai | AI写作后端服务(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 -> "提升文章的整体可读性和专业性";
};
}
}设计要点:
- Prompt构建:
buildWritingPrompt()方法将用户的参数选择(内容类型、风格、语气、字数等)转化为结构化的 Prompt 指令,确保大模型按预期输出 - 大模型调用:通过
ModelProvider获取ChatLanguageModel实例,调用model.generate()进行文本生成 - SSE流式输出:
generateStream()方法使用SseEmitter实现服务器推送,将生成内容按10字符分块发送 - 详细日志:每个大模型调用前后打印结构化日志,包括模型参数和 token 消耗
- 参数校验:扩写/优化/续写功能检查
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事件累积多行数据后回调onMessagedone事件解析 JSON 后回调onDoneerror事件回调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

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

会在右边的窗口中生成相关文档。
点击右上角的插入到文档按钮:

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

即可将文档发布成功。
使用AI写作功能写文档,效率非常高。
总结
本章实现了完整的 AI 写作功能,涵盖了以下要点:
| 维度 | 实现内容 |
|---|---|
| 后端接口 | 6个REST API端点(生成、流式生成、扩写、优化、续写、模板) |
| 大模型集成 | 通过 LangChain4j 统一调用 Qwen/DeepSeek,Prompt 结构化构建 |
| 流式输出 | SSE 协议实现实时推流,前端逐字渲染 Markdown |
| 缓存优化 | Caffeine 本地缓存写作模板,24小时过期 |
| 前端页面 | 专业两栏写作工作台,8种写作模板,Markdown 渲染 |
| 导航入口 | 顶部导航栏 + 文档详情页,两个入口 |
| 文档集成 | 生成内容一键插入新建文档页面 |