Kaoyan Essay Agent — Development skill for Claude Code

考研英语作文批改 Agent

一个自研 AI Agent 驱动的考研英语作文批改系统：**大模型负责"评"，本地工具负责"算"**，把 LLM 输出的不确定性收敛成确定、可解释、可复现的评分。

一次批改的真实结果（左：提交作文　右：结构化结果）

这个项目解决什么问题

考研英语作文需要**高频、快速、标准一致**的反馈：报班批改周期长、成本高；同一个人两次批改都可能给出不同分数；而"让大模型直接打分"有三个硬伤——同一篇作文两次分数不同、分数不可解释、还会被多轮对话里的历史分数带偏。

本项目的做法是把批改拆成两件事：**模型只负责"评"（给出分项等级与错误清单），分数由服务端的确定性工具"算"**，并且服务端最后会强制用工具算出的总分覆盖模型自报的总分。

核心亮点

• Function Calling 工具链：模型必须调用 5 个本地工具（word_count / grammar_check / vocabulary_analyze / structure_analyze / calculate_score）才能产出结果，工具循环最多 10 轮，超出即失败
• 确定性算分：calculate_score 按教育部五档标准换算（英语一 20 分 / 英语二 15 分 / 应用文 10 分），档内分数夹逼在本档区间内；跑题（topic_relevant=false）一票否决判第五档，语言分再高也不救
• 上下文管理与摘要压缩：Redis List 存多轮上下文，超过 4 轮自动把旧消息压成 ≤200 字摘要（独立线程池 + 15s 超时），失败则降级为规则裁剪并打 summary_degraded 标记
• Prompt 模板灰度 + 会话级版本锁定：按 sessionId 哈希灰度选版本，锁定在 Redis 7 天，保证同一会话评分标准前后一致，记录里留存 template_version 可回溯
• 模型协议自适应：按 /v1/models 返回的 supports_anthropic 自动选择 OpenAI / Anthropic 协议，并实现 OpenAI 协议下的流式 tool_calls 增量拼装，更换模型或服务商不需要改业务代码
• 多模态图片批改：手写作文 / 题目截图以 dataURL 直传视觉模型（SSE 流式解析），不做 OCR
• 横切能力：会话校验、固定窗口限流（5 次/分钟）、会话级分布式锁（SET NX PX + Lua 校验释放 + 抢锁轮询等待）、统一响应体与全局异常处理

功能

模块	说明
作文批改	文本 / 手写照片 / 题目截图三种输入；输出总分、档次、分项得分、错误清单、润色稿、高级表达
随机出题	按作文类型生成题目与写作要求
范文生成	生成符合评分标准的参考范文
多轮追问	针对批改结果继续对话，上下文自动压缩
弱项画像	错误类型分布、分项均分、分数趋势
历史记录	列表 / 详情 / 删除 / 重新批改 / 清空
报告导出	批改结果导出为 Markdown 文档（服务端 XSS 净化）
分数异议	对结果标注异议，只做标记不做改分
会话管理	UUID 会话、过期提示、清空重建

界面预览与功能说明

以下截图都是**真实运行截图**（Playwright 驱动无头浏览器抓取，模型为 `gpt-6.1-sol`）。

1. 作文批改（核心功能）

左侧是输入区：作文类型（英语一图画 / 英语二图表 /