npm - hydro-ai-helper - Versions diffs - 3.0.0 → 3.0.2 - Mend

hydro-ai-helper 3.0.0 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +108 -202
package/README_en.md +209 -0
package/dist/handlers/studentHandler.js +12 -6
package/dist/handlers/studentHandler.js.map +1 -1
package/dist/handlers/testdataGenHandler.js +41 -7
package/dist/handlers/testdataGenHandler.js.map +1 -1
package/dist/lib/textTruncate.js +41 -0
package/dist/lib/textTruncate.js.map +1 -0
package/dist/services/goJudgeSandboxService.js +3 -10
package/dist/services/goJudgeSandboxService.js.map +1 -1
package/dist/services/testdataGenService.js +32 -73
package/dist/services/testdataGenService.js.map +1 -1
package/package.json +2 -1

package/README.md CHANGED Viewed

@@ -1,11 +1,11 @@
-# HydroOJ AI Learning Assistant
+# HydroOJ AI 学习助手
 <div align="center">
-**[中文](README_zh.md) | English**
+**中文 | [English](README_en.md)**
-![GitHub release (latest by date)](https://img.shields.io/github/v/release/AltureT/hydro-ai-helper?label=Release)
-![GitHub all releases](https://img.shields.io/github/downloads/AltureT/hydro-ai-helper/total?label=Downloads&color=brightgreen)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/AltureT/hydro-ai-helper?label=版本)
+![GitHub all releases](https://img.shields.io/github/downloads/AltureT/hydro-ai-helper/total?label=下载量&color=brightgreen)
 ![Installations](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-installs)
 ![Active Users (7d)](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-active)
 ![Conversations](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-conversations)
@@ -15,156 +15,138 @@
 </div>
-A teaching-first AI tutoring plugin for [HydroOJ](https://github.com/hydro-dev/Hydro) — guided hints and thought-provoking questions, never complete solutions. Supports English and Chinese (i18n).
+一个以教学为优先的 [HydroOJ](https://github.com/hydro-dev/Hydro) AI 辅助学习插件 — 引导思考，不给答案。支持中英文界面。
-## Screenshots
+## 截图预览
-<img src="assets/screenshots/1.png" alt="Student panel - AI chat" width="800">
+<img src="assets/screenshots/1.png" alt="学生端 - AI 对话" width="800">
 <details>
-<summary><b>Batch AI Learning Summary</b></summary>
+<summary><b>AI 生成测试数据</b></summary>
-<img src="assets/screenshots/8.png" alt="Batch summary - scoreboard integration" width="800">
+<img src="assets/screenshots/10.png" alt="题目文件页 - AI 生成测试数据面板" width="800">
-<img src="assets/screenshots/9.png" alt="Batch summary - generated results" width="800">
+</details>
+<details>
+<summary><b>批量 AI 学习总结</b></summary>
+<img src="assets/screenshots/8.png" alt="学习总结 - 成绩表集成" width="800">
+<img src="assets/screenshots/9.png" alt="学习总结 - 生成结果" width="800">
 </details>
 <details>
-<summary><b>Admin screenshots</b></summary>
+<summary><b>管理后台截图</b></summary>
-<img src="assets/screenshots/4.png" alt="Admin - conversation records" width="800">
+<img src="assets/screenshots/4.png" alt="后台 - 对话记录" width="800">
-<img src="assets/screenshots/5.png" alt="Admin - usage analytics" width="800">
+<img src="assets/screenshots/5.png" alt="后台 - 使用统计" width="800">
-<img src="assets/screenshots/6.png" alt="Admin - AI configuration" width="800">
+<img src="assets/screenshots/6.png" alt="后台 - AI 配置" width="800">
-<img src="assets/screenshots/7.png" alt="Admin - cost dashboard" width="500">
+<img src="assets/screenshots/7.png" alt="后台 - 成本看板" width="500">
 </details>
-## Features
-### Students
-- AI chat panel on problem pages with real-time streaming (SSE) and LaTeX rendering
-- Choose question type: **Understand** / **Approach** / **Debug** / **Optimize** (AC-only)
-- Multi-turn conversations with history; select confusing text for instant clarification
-- View personalized AI learning summaries on scoreboard pages
-### Teachers
-- **Teaching Analysis** — class-level insights from collective submission data, helping teachers discover teaching problems and take action
-  - 8-dimension rule-engine analysis: common errors, comprehension gaps, learning strategies, at-risk students, difficulty anomalies, progress trends, cognitive paths, AI tutoring effectiveness
-  - Error signature clustering: groups similar compile/runtime errors across students to surface shared misconceptions
-  - Temporal behavior patterns: classifies students into 5 patterns (strategic solver, disengaged, burst-then-quit, stuck-silent, persistent learner)
-  - Cross-dimensional correlation: detects compound risk patterns (e.g., high AI usage + low AC rate)
-  - Code fill-in exercises: auto-generates blanked-code exercises from AC submissions for targeted practice
-  - LLM-powered actionable suggestions with priority framework (P0/P1/P2) — specific classroom actions, not generic advice
-  - 60/40 split layout with sticky AI suggestion sidebar, skeleton loading, confidence badges
-- **Batch AI Summary** — one-click personalized learning summaries for all students on scoreboard pages
-  - Longitudinal student history tracking: records error trends, struggle indicators, and actionable advice across assignments
-  - Smart submission sampling based on milestones (first submit, first AC, score improvements, status changes)
-  - Supplemental generation for late-arriving students without regenerating existing summaries
-  - Draft/publish workflow with real-time SSE progress, stop/continue/retry controls
-- **AI Test Data Generation (Beta)** — generate a full test data set from the Markdown statement on the problem files page (`/p/:pid/files`)
-  - Supports traditional problems and LeetCode-style function problems (incl. linked-list problems via class or plain-list implementations); generates `template.py` / `template.java` / `template.cc` and `compile.sh`
-  - Fill-in-the-blank (complete-the-code) problems: auto-detects scaffold code in the statement (manual override available); reference solution and test outputs strictly match the scaffold's print format
-  - Paste an existing reference solution to make it the single source of truth for all test outputs; it is written alongside as the std file
-  - Adjustable data scale (small/medium/large); cases must cover statement samples and a boundary group (min scale, scale limits, special values, special structures), each labeled with its intent
-  - `config.yaml` judge config (`user_extra_files` / `subtasks` / `langs`) is built deterministically by the plugin; judge settings sync automatically once written
-  - Ships a reference solution; every file is previewed, editable and opt-in before writing, with explicit overwrite warnings
-  - Same permission model as Hydro problem file management (problem owner or problem-edit permission) — inaccessible to students
-- Browse student conversations with filters (time / problem / class / student / userId)
-- Autocomplete search for class and problem filters
-- Multi-dimensional effectiveness metrics and question-type distribution
-- CSV export with optional anonymization and metrics columns
-### Admins
-- Unified portal: Conversations / Analytics / Configuration tabs
-- Multi-endpoint API management with model auto-discovery, drag-to-reorder priority, and automatic failover
-- Per-scenario model assignment: dedicate different models to student chat / learning summary / teaching analysis / test data generation, falling back to the global chain when unset
-- Cost control: token usage tracking, budget limits, cost dashboard
-- Rate limiting, custom system prompt, one-click plugin update
+## 功能特性
+### 学生端
+- 题目页 AI 对话面板，SSE 实时流式响应，LaTeX 公式自动渲染
+- 差异化问题类型：**理解题意** / **理清思路** / **分析错误** / **代码优化**（AC 后专属）
+- 多轮对话自动恢复；选中不理解的文字一键追问
+- 在成绩表页面查看教师发布的个性化 AI 学习总结
+### 教师端
+- **AI 生成测试数据** — 在题目文件页（`/p/:pid/files`）根据题面一键生成完整测试数据
+  - **沙箱实跑 + 双重验证**：数据生成器与标程在 Hydro 判题沙箱中实际运行产出 `.in`/`.out`，并经过独立暴力解对拍、输入校验、模板实跑与题面样例回归四道机器关卡；验证失败自动带上下文让 AI 修复一轮
+  - 支持传统题、LeetCode 风格函数题（自动生成 `template.py/java/cc` 与 `compile.sh`）与填空题（完善代码）
+  - 可粘贴已有标准答案作为输出的唯一权威；`config.yaml` 评测配置确定性生成，写入后评测设置自动同步
+  - 生成的每个代码文件（std.py、generator.py、validator.py 等）首行注明用途；全量预览、可编辑、勾选确认后才写入
+  - ⚠️ 对模型能力非常敏感：请在场景模型中为「测试数据生成」配置最强模型；另有骨架模式（不调用 AI）兜底
+- **教学分析** — 从全班提交数据发现教学问题，生成可操作的教学建议
+  - 8 维度规则引擎（常见错误 / 理解障碍 / 高危学生 / 进步趋势等）+ 错误签名聚类 + 时序行为模式分类
+  - LLM 生成 P0/P1/P2 优先级教学建议 — 具体课堂行动，非泛泛而谈；可从 AC 代码自动生成填空练习
+- **批量 AI 学习总结** — 成绩表页面一键为每位学生生成个性化学习总结
+  - 跨作业历史追踪 + 基于里程碑的智能提交采样；迟到学生可单独补充生成
+  - 草稿/发布工作流，SSE 实时进度，停止/继续/重试控制
+- 对话记录浏览（时间/题目/班级/学生筛选，自动补全）、有效性指标、CSV 导出（支持脱敏）
+### 管理员端
+- 统一入口：对话记录/使用统计/AI 配置 Tab 切换
+- 多端点 API 管理，自动获取模型列表，拖拽排序优先级，自动 Failover
+- 场景模型分配：学生对话/学习总结/教学分析/测试数据生成可分别指定专属模型
+- 成本控制：Token 用量追踪、预算限制、成本看板
+- 频率限制、自定义系统提示词、一键更新
 <details>
-<summary><b>Security</b></summary>
+<summary><b>安全特性</b></summary>
-- Multi-layer jailbreak detection (input / prompt / output) with cross-turn protection
-- CSRF token validation, SSRF prevention, AES-256-GCM encrypted API key storage
-- Paginated jailbreak audit logs
+- 多层级越狱检测（输入/提示词/输出），跨轮次防护
+- CSRF Token 校验、SSRF 防护、API Key AES-256-GCM 加密存储
+- AI 生成的代码只在 go-judge 沙箱中执行，不进入 Web 进程
+- 越狱记录分页审计
 </details>
-## Installation
+## 安装
 ```bash
-# Clone (choose one)
+# 克隆（二选一）
 git clone https://github.com/AltureT/hydro-ai-helper.git   # GitHub
-git clone https://gitee.com/alture/hydro-ai-helper.git      # Gitee (mirror)
+git clone https://gitee.com/alture/hydro-ai-helper.git      # Gitee（镜像）
 cd hydro-ai-helper
 npm install
 npm run build:plugin
-# Install into HydroOJ
+# 安装到 HydroOJ
 hydrooj addon add /path/to/hydro-ai-helper
 pm2 restart hydrooj
 ```
-Verify: visit `/ai-helper/hello` — a JSON response means success.
+验证：访问 `/ai-helper/hello` 返回 JSON 即表示成功。
-## Configuration
+## 配置
-### Environment Variables
+### 环境变量
-Set `ENCRYPTION_KEY` (32 characters) to encrypt API keys:
+`ENCRYPTION_KEY`（必需，32 字符）— 加密 API Key：
 ```bash
-export ENCRYPTION_KEY="your-32-character-secret-key!!!"
+export ENCRYPTION_KEY="your-32-character-secret-key!!!"   # 生成：openssl rand -base64 24 | head -c 32
 ```
-Generate a random key: `openssl rand -base64 24 | head -c 32`
+`AI_HELPER_UPDATE_CHANNEL`（可选）— 应用内一键更新通道：
-**Update channel** (optional): the in-app one-click/overwrite update follows `AI_HELPER_UPDATE_CHANNEL`:
+- `stable`（默认）— 只更新到正式发布版本（`vX.Y.Z` tag），经 GPG 签名校验。所有真实用户的服务器都应使用此通道。
+- `edge` — 跟踪 `main` 分支最新代码，**仅限维护者自己的测试服务器**。
-- `stable` (default) — updates only to official releases (`git tag vX.Y.Z`), GPG-verified. Recommended for all real-user servers.
-- `edge` — tracks the latest `main` branch code. Set this **only on your own test server**; do not set it on users' servers.
+`AI_HELPER_TESTDATA_GENERATION_MODE`（可选）— 测试数据生成是否要求沙箱（`hydrojudge.sandbox_host`）：
-```bash
-export AI_HELPER_UPDATE_CHANNEL=edge   # test server only
-```
-**AI test-data execution** (optional): `AI_HELPER_TESTDATA_GENERATION_MODE` controls whether AI-generated generators run in Hydro's go-judge sandbox (`hydrojudge.sandbox_host`):
-- `auto` (default) — use the sandbox when reachable; otherwise fall back to the legacy direct-output mode with a warning.
-- `sandbox` — require the sandbox and fail safely when it is unavailable.
-- `direct` — always use the legacy direct-output mode.
-```bash
-export AI_HELPER_TESTDATA_GENERATION_MODE=sandbox
-```
-### Admin Setup
+- `auto`（默认）— 沙箱可达时实跑验证，不可达时降级直出并明确标注"未验证"
+- `sandbox` — 强制要求沙箱，不可用时安全失败
+- `direct` — 始终使用直出模式（不推荐）
-Go to **Control Panel → AI Assistant** (`/ai-helper`) → "AI Configuration" tab:
+### 管理员配置
-1. **Add API endpoints** — endpoint name, API Base URL, API Key → click "Fetch Models"
-2. **Select models & priority** — pick models, drag to reorder; failover is automatic
-3. **Adjust settings** — rate limit (default 5/min/user), custom system prompt
-4. **Test & save** — "Test Connection" to verify, then save
+登录后访问 **控制面板 → AI 助手**（`/ai-helper`）→「AI 配置」Tab：
-## Telemetry & Privacy
+1. **添加 API 端点** — 填写端点名称、API Base URL、API Key → 点击「获取模型」
+2. **选择模型与优先级** — 选择模型，拖拽排序；首选不可用时自动切换
+3. **场景模型** — 为「测试数据生成」等场景指定专属模型（该场景建议配最强模型）
+4. **测试并保存** — 点击「测试连接」验证后保存
-Collects **anonymous statistics** (installation count, active users over 7/30/90-day windows, conversations, per-day feature usage counters, version) for GitHub badges and development.
+## 遥测与隐私
-- Fully anonymous (random UUID, no PII); domain IDs are SHA-256 hashed
-- Records the **country and region** of the reporting request (coarse-grained, inferred by Cloudflare from the server's egress IP; **the IP itself is never stored**), instance-level only
-- No code, conversations, or personal data; instance records auto-clean after 270 days without reports (covers school vacations), per-day feature usage kept for 400 days
+收集**匿名统计数据**（安装数、活跃用户窗口、对话数、按日功能用量、版本），用于 GitHub 徽章和开发参考。完全匿名（随机 UUID，无个人信息，不存储 IP），不收集代码、对话内容或个人数据；仅记录 Cloudflare 粗粒度推断的国家/省份用于地区分布。
 <details>
-<summary><b>Disable telemetry</b></summary>
+<summary><b>关闭遥测</b></summary>
 ```javascript
 use your_hydro_db
@@ -176,128 +158,52 @@ db.ai_plugin_install.updateOne(
 </details>
-## Changelog
+## 更新日志
 <details open>
-<summary><b>v2.5.0</b> — AI Test Data Generation (Beta)</summary>
-**AI Test Data Generation (problem files page, NEW)**
-- One-click generation from the Markdown statement: test cases, function-problem judge templates (template.py/java/cc + compile.sh), config.yaml (judge settings sync automatically) and a reference solution
-- Supports traditional problems, LeetCode-style function problems (incl. class Solution signatures and linked lists) and fill-in-the-blank problems
-- Paste an existing reference solution as the single source of truth; adjustable data scale with mandatory sample/boundary coverage
-- Skeleton mode as an AI-outage fallback (no AI call, deterministic scaffolding)
-- Full preview, editable, opt-in writes with overwrite warnings; same permission model as Hydro problem file management
-- New "Test Data Generation" AI scenario with its own model chain; unrestricted output length and a 10-minute per-attempt timeout
-- Sectioned-text output contract (zero escaping for code); the panel shows an actionable error instead of silently disappearing when loading fails
-</details>
+<summary><b>v3.0.0</b> — 测试数据生成：沙箱实跑 + 双重验证</summary>
-<details>
-<summary><b>v2.0.0</b> — Teaching Analysis & Design Overhaul</summary>
-**Teaching Analysis System (NEW)**
-- 8-dimension class-level analysis: common errors, comprehension gaps, learning strategies, at-risk students, difficulty anomalies, progress trends, cognitive paths, AI tutoring effectiveness
-- Rule-engine-first architecture: anomaly detection via data pipeline, LLM for actionable suggestions — 1/30 cost of pure-LLM approach
-- Error signature clustering with compiler error normalization
-- Temporal behavior pattern analyzer (5-way student classification)
-- Cross-dimensional correlation detection (3 priority pairs)
-- Auto-generated code fill-in exercises from AC submissions
-- Adaptive class-size strategy (<10 / 10-20 / 20-100+ students)
-- 60/40 split layout with sticky suggestion sidebar, skeleton loading, confidence badges
-**Batch Summary Enhancement**
-- Student history tracking across assignments (error trends, struggle indicators, prior advice)
-- Supplemental generation mode for late-arriving students
-- Rewritten prompts with educational psychology principles and historical context injection
-- Smart primary button state machine (generate new / retry failed / continue)
-**Frontend Redesign**
-- Unified design token system with green accent theme for teacher features
-- Tab restyling with ARIA accessibility attributes and keyboard navigation
-- Finding cards with severity-based color coding (high/medium/low)
-- Responsive 60/40 → vertical layout below 768px
+- 测试数据不再由 AI 直接给出：生成器与标程在 go-judge 沙箱中实际运行产出 `.in`/`.out`
+- 四道机器关卡：独立暴力解对拍、输入校验器逐点校验、函数题模板实跑比对、题面样例回归
+- 验证失败自动把失败阶段、出错测试点、输入与 traceback 关键行回喂 AI 修复一轮；教师取消不误报
+- 生成的代码文件首行自带用途注释；文件页与场景模型页醒目提示配置最强模型
+- 遥测增强：错误上报携带 AI 失败详情、启动失败金丝雀告警、功能用量累计与实例来源省份
 </details>
 <details>
-<summary><b>v1.21.0</b> — Batch AI Learning Summary</summary>
+<summary><b>v2.5.0</b> — AI 生成测试数据（Beta）</summary>
-- One-click AI summary generation for all students on homework/contest scoreboard pages
-- Smart submission sampling based on milestones (first submit, first AC, score improvements, status changes)
-- Real-time SSE progress with stop / continue / retry-failed controls
-- Draft → publish workflow; teachers can edit summaries before publishing
-- Student view: auto-displays published summary on scoreboard with periodic polling
-- Submission reference links in summaries clickable to view code details
-- CSV export for generated summaries
+- 根据题面一键生成测试点、函数题评测模板、config.yaml 与参考标程（AI 直出模式）
+- 支持传统题、函数题与填空题；可粘贴标准答案作为唯一权威；骨架模式兜底
+- 新增「测试数据生成」AI 场景（可单独指定模型链）
 </details>
 <details>
-<summary><b>v1.20.0</b> — Teacher Analytics Enhancement</summary>
+<summary><b>v2.0.0</b> — 教学分析系统 & 设计升级</summary>
-- Autocomplete search for class, problem, and student filters
-- UserId filtering and unified filter layout
-- SVG icon set replacing emoji indicators
-- Cost analytics period accuracy fixes
+- 8 维度班级分析 + 错误签名聚类 + 时序行为模式（规则引擎优先，成本约为纯 LLM 方案的 1/30）
+- LLM 生成 P0/P1/P2 教学建议；从 AC 代码自动生成填空练习
+- 学习总结跨作业历史追踪与补充生成；前端统一设计 Token 系统
 </details>
 <details>
-<summary><b>v1.19.0</b> — i18n & Effectiveness Metrics</summary>
-- Full English/Chinese internationalization (frontend + backend)
-- Multi-dimensional conversation effectiveness metrics replacing simple binary flag
-- Metrics columns in analytics tables and CSV export
+<summary><b>更早版本</b></summary>
-</details>
-<details>
-<summary><b>v1.18.0</b> — Telemetry Dashboard & Error Diagnostics</summary>
-- Telemetry dashboard SPA for monitoring plugin installations
-- Enhanced error diagnostics with endpoint-level context
-- Admin feedback collection UI
-</details>
-<details>
-<summary><b>v1.16.x</b> — Stability & Security</summary>
-- Stabilize telemetry instanceId for Docker environments
-- Upgrade DOMPurify to address XSS vulnerabilities
-- Collapse jailbreak logs by default
-</details>
-<details>
-<summary><b>v1.14.x</b> — SSE Streaming & Cost Control</summary>
-- SSE streaming output — real-time character-by-character display
-- Token usage tracking, budget limits, cost dashboard
-- CSRF protection, SSRF prevention, 3-layer prompt injection defense
-- Homework/contest mode support
-</details>
-<details>
-<summary><b>v1.12.0 and earlier</b></summary>
-- v1.12.0: Judge data integration, contest mode, ~45% token reduction
-- v1.11.0: Improved guided response style, cross-turn jailbreak defense
-- v1.10.x: Anonymous telemetry, one-click update
-- v1.9.0: Security audit and hardening
-- v1.8.x: "Code Optimization" question type (AC-only)
-- v1.6.0: Unified admin portal with tabs
-- v1.4.0: Multi-endpoint config with failover
-- v1.2.0: Differentiated question types
-- v1.0.0: Initial release
+- v1.21.0：批量 AI 学习总结（里程碑采样、SSE 进度、草稿/发布）
+- v1.19.0–v1.20.0：全面中英文国际化、多维有效性指标、筛选自动补全
+- v1.18.0：遥测看板 SPA、错误诊断增强
+- v1.14.x–v1.16.x：SSE 流式响应、成本控制、CSRF/SSRF/Prompt 注入防御、安全修复
+- v1.0.0–v1.12.0：初始发布、差异化问题类型、多端点 Failover、评测数据集成、竞赛模式
 </details>
-## About
+## 关于
-A third-party plugin for [HydroOJ](https://github.com/hydro-dev/Hydro). Feel free to open an Issue for questions or suggestions.
+[HydroOJ](https://github.com/hydro-dev/Hydro) 开源在线评测系统的第三方插件。如有问题或建议，欢迎提交 Issue。
-## License
+## 许可证
 MIT License

package/README_en.md ADDED Viewed

@@ -0,0 +1,209 @@
+# HydroOJ AI Learning Assistant
+<div align="center">
+**[中文](README.md) | English**
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/AltureT/hydro-ai-helper?label=Release)
+![GitHub all releases](https://img.shields.io/github/downloads/AltureT/hydro-ai-helper/total?label=Downloads&color=brightgreen)
+![Installations](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-installs)
+![Active Users (7d)](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-active)
+![Conversations](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-conversations)
+![Version (mode)](https://img.shields.io/endpoint?url=https://stats.how2learns.com/api/badge-version)
+![GitHub stars](https://img.shields.io/github/stars/AltureT/hydro-ai-helper?style=social)
+![License](https://img.shields.io/github/license/AltureT/hydro-ai-helper)
+</div>
+A teaching-first AI tutoring plugin for [HydroOJ](https://github.com/hydro-dev/Hydro) — guided hints and thought-provoking questions, never complete solutions. Supports English and Chinese (i18n).
+## Screenshots
+<img src="assets/screenshots/1.png" alt="Student panel - AI chat" width="800">
+<details>
+<summary><b>AI Test Data Generation</b></summary>
+<img src="assets/screenshots/10.png" alt="Problem files page - AI test data generation panel" width="800">
+</details>
+<details>
+<summary><b>Batch AI Learning Summary</b></summary>
+<img src="assets/screenshots/8.png" alt="Batch summary - scoreboard integration" width="800">
+<img src="assets/screenshots/9.png" alt="Batch summary - generated results" width="800">
+</details>
+<details>
+<summary><b>Admin screenshots</b></summary>
+<img src="assets/screenshots/4.png" alt="Admin - conversation records" width="800">
+<img src="assets/screenshots/5.png" alt="Admin - usage analytics" width="800">
+<img src="assets/screenshots/6.png" alt="Admin - AI configuration" width="800">
+<img src="assets/screenshots/7.png" alt="Admin - cost dashboard" width="500">
+</details>
+## Features
+### Students
+- AI chat panel on problem pages with real-time streaming (SSE) and LaTeX rendering
+- Choose question type: **Understand** / **Approach** / **Debug** / **Optimize** (AC-only)
+- Multi-turn conversations with history; select confusing text for instant clarification
+- View personalized AI learning summaries on scoreboard pages
+### Teachers
+- **AI Test Data Generation** — generate a full test data set from the statement on the problem files page (`/p/:pid/files`)
+  - **Sandbox execution + double verification**: the generator and reference solution actually run in Hydro's judge sandbox to produce `.in`/`.out`, then pass four machine gates — independent brute-force cross-check, input validation, template execution, and statement-sample regression; on failure the AI gets one automatic repair round with full context
+  - Supports traditional problems, LeetCode-style function problems (auto-generates `template.py/java/cc` and `compile.sh`) and fill-in-the-blank problems
+  - Paste an existing reference solution as the single source of truth; `config.yaml` is built deterministically and judge settings sync automatically
+  - Every generated code file (std.py, generator.py, validator.py, …) starts with a purpose comment; everything is previewed, editable and opt-in before writing
+  - ⚠️ Highly sensitive to model capability: assign your strongest model to the Test Data Generation scenario; a skeleton mode (no AI) is available as fallback
+- **Teaching Analysis** — class-level insights from collective submission data
+  - 8-dimension rule engine (common errors / comprehension gaps / at-risk students / progress trends, …) + error-signature clustering + temporal behavior patterns
+  - LLM-powered P0/P1/P2 prioritized suggestions — specific classroom actions, not generic advice; auto-generates fill-in exercises from AC code
+- **Batch AI Summary** — one-click personalized learning summaries for all students on scoreboard pages
+  - Longitudinal history tracking + milestone-based submission sampling; supplemental generation for late-arriving students
+  - Draft/publish workflow with real-time SSE progress and stop/continue/retry controls
+- Conversation browsing (time / problem / class / student filters with autocomplete), effectiveness metrics, CSV export with optional anonymization
+### Admins
+- Unified portal: Conversations / Analytics / Configuration tabs
+- Multi-endpoint API management with model auto-discovery, drag-to-reorder priority, and automatic failover
+- Per-scenario model assignment: student chat / learning summary / teaching analysis / test data generation
+- Cost control: token usage tracking, budget limits, cost dashboard
+- Rate limiting, custom system prompt, one-click plugin update
+<details>
+<summary><b>Security</b></summary>
+- Multi-layer jailbreak detection (input / prompt / output) with cross-turn protection
+- CSRF token validation, SSRF prevention, AES-256-GCM encrypted API key storage
+- AI-generated code runs only inside the go-judge sandbox, never in the web process
+- Paginated jailbreak audit logs
+</details>
+## Installation
+```bash
+# Clone (choose one)
+git clone https://github.com/AltureT/hydro-ai-helper.git   # GitHub
+git clone https://gitee.com/alture/hydro-ai-helper.git      # Gitee (mirror)
+cd hydro-ai-helper
+npm install
+npm run build:plugin
+# Install into HydroOJ
+hydrooj addon add /path/to/hydro-ai-helper
+pm2 restart hydrooj
+```
+Verify: visit `/ai-helper/hello` — a JSON response means success.
+## Configuration
+### Environment Variables
+`ENCRYPTION_KEY` (required, 32 characters) — encrypts API keys:
+```bash
+export ENCRYPTION_KEY="your-32-character-secret-key!!!"   # generate: openssl rand -base64 24 | head -c 32
+```
+`AI_HELPER_UPDATE_CHANNEL` (optional) — in-app update channel:
+- `stable` (default) — updates only to official releases (`vX.Y.Z` tags), GPG-verified. Use on all real-user servers.
+- `edge` — tracks the latest `main` branch code; for the maintainer's own test server only.
+`AI_HELPER_TESTDATA_GENERATION_MODE` (optional) — whether test data generation requires the sandbox (`hydrojudge.sandbox_host`):
+- `auto` (default) — verify in the sandbox when reachable; otherwise fall back to direct output clearly marked "unverified"
+- `sandbox` — require the sandbox and fail safely when unavailable
+- `direct` — always use direct output (not recommended)
+### Admin Setup
+Go to **Control Panel → AI Assistant** (`/ai-helper`) → "AI Configuration" tab:
+1. **Add API endpoints** — endpoint name, API Base URL, API Key → click "Fetch Models"
+2. **Select models & priority** — pick models, drag to reorder; failover is automatic
+3. **Scenario models** — assign dedicated models per scenario (use your strongest model for Test Data Generation)
+4. **Test & save** — "Test Connection" to verify, then save
+## Telemetry & Privacy
+Collects **anonymous statistics** (installations, active-user windows, conversations, per-day feature usage, version) for GitHub badges and development. Fully anonymous (random UUID, no PII, IPs never stored); no code, conversations or personal data — only a coarse country/region inferred by Cloudflare for distribution stats.
+<details>
+<summary><b>Disable telemetry</b></summary>
+```javascript
+use your_hydro_db
+db.ai_plugin_install.updateOne(
+  { _id: 'install' },
+  { $set: { telemetryEnabled: false } }
+)
+```
+</details>
+## Changelog
+<details open>
+<summary><b>v3.0.0</b> — Test data generation: sandbox execution + double verification</summary>
+- Test data is no longer emitted directly by the AI: the generator and reference solution actually run in the go-judge sandbox to produce `.in`/`.out`
+- Four machine gates: independent brute-force cross-check, per-case input validation, function-template execution, statement-sample regression
+- On failure, the failing stage, test case, input and traceback tail are fed back to the AI for one automatic repair round; teacher cancellation is no longer misreported
+- Generated code files start with purpose comments; prominent strongest-model reminders on both the files page and the scenario-model page
+- Telemetry: error reports carry AI failure details, startup-failure canary alerts, cumulative feature usage and instance region
+</details>
+<details>
+<summary><b>v2.5.0</b> — AI Test Data Generation (Beta)</summary>
+- One-click generation of test cases, judge templates, config.yaml and a reference solution from the statement (direct-output mode)
+- Traditional / function / fill-in-the-blank problems; paste a reference solution as the single source of truth; skeleton-mode fallback
+- New "Test Data Generation" AI scenario with its own model chain
+</details>
+<details>
+<summary><b>v2.0.0</b> — Teaching Analysis & Design Overhaul</summary>
+- 8-dimension class analysis + error-signature clustering + temporal behavior patterns (rule-engine first, ~1/30 the cost of pure LLM)
+- LLM-generated P0/P1/P2 teaching suggestions; auto-generated fill-in exercises from AC code
+- Longitudinal summary tracking with supplemental generation; unified frontend design tokens
+</details>
+<details>
+<summary><b>Earlier versions</b></summary>
+- v1.21.0: batch AI learning summaries (milestone sampling, SSE progress, draft/publish)
+- v1.19.0–v1.20.0: full i18n, multi-dimensional effectiveness metrics, filter autocomplete
+- v1.18.0: telemetry dashboard SPA, richer error diagnostics
+- v1.14.x–v1.16.x: SSE streaming, cost control, CSRF/SSRF/prompt-injection defenses, security fixes
+- v1.0.0–v1.12.0: initial release, question types, multi-endpoint failover, judge-data integration, contest mode
+</details>
+## About
+A third-party plugin for the [HydroOJ](https://github.com/hydro-dev/Hydro) open-source online judge. Issues and suggestions welcome.
+## License
+MIT License