← 返回学习路线

SYSTEM

D37 后端:`POST /api/ai/check` 编排(JSON 接口,非 SSE)

QuillAgent文档2. D37 后端:`POST /api/ai/check` 编排(JSON 接口,非 SSE)growth
src/content/notes/growth/D37-后端:`POST-api-ai-check`-编排-JSON-接口,非-SSE.md

2. D37 后端:POST /api/ai/check 编排(JSON 接口,非 SSE)

2.1 任务

  • 规则引擎结果 + LLM 语义检查(MEDIA→FLAT_BEGIN / OFFICIAL→LOGIC_GAP;NOVEL 不调模型)合并返回。
  • LLM 输出解析容错:非法 JSON / 超时 / 调用失败 → 仅返回规则结果,不报错(降级信息写入 summary)。
  • 语义检查范围 = 开头切片(默认 800 字,check.llm.maxChars 可配);全文逐段逻辑检查为 v1.1(04 计划语义级 P2 裁剪口径)。
  • 接口普通 JSON,不走 AiStreamService。

2.2 代码

backend/src/main/java/com/quill/agent/service/check/CheckService.java

package com.quill.agent.service.check;

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.quill.agent.config.AgentYmlConfig;
import com.quill.agent.dto.CheckDtos.CheckIssue;
import com.quill.agent.dto.CheckDtos.CheckResponse;
import com.quill.agent.dto.ModelConfig;
import com.quill.agent.service.modelrouter.ModelRouter;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * 全文自检编排(02-接口文档 §2.7):
 * 词级 = CheckRuleEngine(纯函数,必做);语义级 = ModelRouter 单轮(开头切片),
 * 非法 JSON / 超时 / 调用异常一律优雅降级为仅规则结果。
 * 安全:LLM 返回只取结构化字段,绝不执行其中的任何"指令"。
 */
@Service
public class CheckService {

    private static final Logger log = LoggerFactory.getLogger(CheckService.class);
    private static final Pattern SENTENCE = Pattern.compile("[^。!?!?;;]*[。!?!?;;]+|[^。!?!?;;]+$");

    private final CheckRuleEngine ruleEngine;
    private final AgentYmlConfig config;
    private final ModelRouter router;
    private final ObjectMapper objectMapper;

    public CheckService(CheckRuleEngine ruleEngine, AgentYmlConfig config,
                        ModelRouter router, ObjectMapper objectMapper) {
        this.ruleEngine = ruleEngine;
        this.config = config;
        this.router = router;
        this.objectMapper = objectMapper;
    }

    public CheckResponse check(String genre, String text, ModelConfig modelConfig) {
        List<CheckIssue> issues = new ArrayList<>(ruleEngine.check(genre, text));
        int ruleCount = issues.size();
        String degrade = "";

        if (!"NOVEL".equals(genre)) {           // NOVEL 无语义级检规,不调模型
            try {
                issues.addAll(semanticIssues(genre, text, modelConfig));
            } catch (Exception ex) {
                log.warn("语义检查降级(非法 JSON/超时/调用失败):{}", ex.getMessage());
                degrade = "(语义检查未通过,仅词级结果)";
            }
        }
        int semanticCount = issues.size() - ruleCount;
        String summary = "共发现 " + issues.size() + " 个问题(词级 " + ruleCount
                + " 个,语义级 " + semanticCount + " 个)。" + degrade;
        return new CheckResponse(issues, summary);
    }

    /** 语义检查:开头切片单轮调用;LLM 只回 sentenceIndex + suggestion,offset 由本服务按句定位 */
    private List<CheckIssue> semanticIssues(String genre, String text, ModelConfig cfg) {
        int maxChars = config.intVal(800, "check", "llm", "maxChars");
        String slice = text.length() <= maxChars ? text : text.substring(0, maxChars);
        String sysKey = "MEDIA".equals(genre) ? "flatBegin" : "logicGap";
        String system = config.str("", "check", "semantic", sysKey);
        String user = "<document>\n" + slice + "\n</document>";
        int timeout = config.intVal(60, "check", "llm", "timeoutSeconds");

        String raw = router.stream(cfg, system, user)
                .collectList()
                .map(list -> String.join("", list))
                .block(Duration.ofSeconds(timeout));          // 聚合后按超时降级

        List<SemanticHit> hits = parseHits(raw);              // 非法 JSON → 抛异常由上层降级
        String[] sentences = sentences(slice);
        List<CheckIssue> issues = new ArrayList<>();
        for (SemanticHit h : hits) {
            int[] range = sentenceRange(sentences, h.sentenceIndex());
            issues.add(new CheckIssue(h.type(), "MAJOR", range[0], range[1],
                    text.substring(range[0], Math.min(range[1], text.length())),
                    h.suggestion(), null, h.sentenceIndex()));
        }
        return issues;
    }

    private List<SemanticHit> parseHits(String raw) {
        if (raw == null || raw.isBlank()) throw new IllegalStateException("empty semantic result");
        try {
            return objectMapper.readValue(raw, new TypeReference<List<SemanticHit>>() {
            });
        } catch (Exception ex) {
            throw new IllegalStateException("invalid semantic json", ex);
        }
    }

    /** 按句切分(含句尾标点),返回 [起,止) 绝对偏移 */
    private String[] sentences(String text) {
        List<String> list = new ArrayList<>();
        Matcher m = SENTENCE.matcher(text);
        while (m.find()) {
            list.add(m.group());
        }
        return list.toArray(String[]::new);
    }

    /** sentenceIndex → [offsetStart, offsetEnd);越界回退整片 */
    private int[] sentenceRange(String[] sentences, int index) {
        if (sentences.length == 0) return new int[]{0, 0};
        int i = Math.max(0, Math.min(index, sentences.length - 1));
        int start = 0;
        for (int k = 0; k < i; k++) {
            start += sentences[k].length();
        }
        return new int[]{start, start + sentences[i].length()};
    }

    /** LLM 语义命中(仅信任这两个字段与哨兵类型,其余字段丢弃) */
    public record SemanticHit(String type, int sentenceIndex, String suggestion) {
    }
}

AiController.java 追加(普通 JSON,注入 CheckService):

    /** 全文自检(D37):普通 JSON 接口,非 SSE;content 为纯文本投影 */
    @PostMapping("/check")
    public ApiResponse<CheckDtos.CheckResponse> check(@Valid @RequestBody CheckRequest req) {
        return ApiResponse.ok(checkService.check(normalizeGenre(req.genre()), req.content(), req.modelConfig()));
    }

    public record CheckRequest(
            @NotBlank(message = "genre 不能为空") String genre,
            @NotBlank(message = "content 不能为空")
            @Size(max = 200_000, message = "文档过长,请分段自检") String content,
            @NotNull(message = "modelConfig 不能为空") @Valid ModelConfig modelConfig) {
    }