feat(apps/isgrace): isGrace — Hy3 驱动的 AI 学习搭子（Issue #4 参赛作品）

[KarlLeen]

isGrace — 把教材变成一门课，由 Hy3 全程驱动

Powered by Tencent-Hunyuan/Hy3（仅通过 OpenRouter API 调用，符合 issue 要求，绝无微调 / 本地推理）。

在线体验：https://isgrace.limlamleen.com
代码仓库：https://github.com/KarlLeen/hy3Isgrace
联系方式：limlamleen@gmail.com

它解决什么

用 AI 复习最容易踩的坑：Context 满了会悄悄压缩、忘掉教材内容；通用聊天工具不适合做题（要另开备忘录记答案，写代码体验也差）；免费额度用完要等几个小时，还担心账号被锁。isGrace 把教材（或课程大纲 + 考纲）导进去，让 Hy3 先用大白话讲一遍、确认听懂了再讲一遍学术深度版本，生成一份可以脱离教材复习的 cheatsheet，最后只基于教材内容出题考你、批改并给出理由。

Hy3 在系统中的角色

全部收敛在 server/services/llmService.ts 一处：

能力	说明
课程结构拆解	读教材目录 / 课程大纲，返回结构化模块列表 JSON
教材原文定位	全文扫描，返回每章逐字起止锚点，供代码精确切片（超大教材按窗口分块扫描，避免单次调用装不下）
两遍分层讲解	高中版 + 大学版，严格限定在上传材料范围内
Cheatsheet / 试题生成	结构化复习资料 + 带评分标准的选择题/简答题/编程题
主观题批改	按自己出题时写的评分标准打分并说明理由

选择 Hy3 的具体原因、以及围绕它的 reasoning effort 调优、262K 上下文窗口的实际运用，详见 apps/isgrace/README_CN.md。

已验证的技术亮点

针对真实的大部头教材（实测一本 47MB / 约 255 万字符的数据库教材）做过端到端验证并修复：

• 目录条目会被模型误认成章节起点 → 送去定位锚点前先过滤掉类似目录的文本区块
• 单次调用装不下整本书 → 改为按窗口顺序扫描，章节边界靠出现顺序自动推导
• 章节标题作为页眉重复出现几十次，找"最后一次"可能落在章节末尾 → 改为按预期位置就近匹配
• 长流式请求中途网络中断 → 仅在还没有内容展示给用户时自动重试，避免内容重复
• 上传材料 / 网页抓取内容中出现类似指令的文字（prompt injection）→ 明确要求模型仅当作要讲解的内容，不执行

目录结构

apps/isgrace/
├─ README.md / README_CN.md      项目说明（英文 / 中文）
├─ src/                          前端 (React 19 + TypeScript + Vite + Zustand)
├─ server/                       后端 (Express) — 材料解析、Hy3 调用、SSE 流式转发
└─ deploy/                       nginx + systemd 部署脚本（对应线上 isgrace.limlamleen.com）

验证

• tsc --noEmit（前端 + 后端）与 eslint 全通过
• 针对真实大部头 PDF 做过多轮端到端手工验证：教材上传解析、章节拆分、两遍讲解、cheatsheet 生成、出题批改、网络异常重试、prompt injection 防护，均用真实 Hy3 API 调用验证过

🤖 Generated with Claude Code