hydro-ai-helper 1.8.5

package/.eslintrc.json

@@ -0,0 +1,31 @@
+{
+  "root": true,
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "ignorePatterns": ["dist/", "node_modules/", "frontend/", "*.js", "src/__tests__/"],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": ["warn", {
+      "argsIgnorePattern": "^_",
+      "varsIgnorePattern": "^_"
+    }],
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-non-null-assertion": "warn",
+    "no-console": "off",
+    "prefer-const": "warn",
+    "no-var": "error"
+  }
+}

package/.github/workflows/sync-releases-to-gitee.yml

@@ -0,0 +1,119 @@
+name: Sync Releases to Gitee
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: 'Tag name to sync (e.g., v1.5.5)'
+        required: true
+
+jobs:
+  sync-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get release info
+        id: release
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TAG_NAME="${{ github.event.inputs.tag_name }}"
+            # Fetch release info from GitHub API
+            RELEASE_INFO=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+              "https://api.github.com/repos/${{ github.repository }}/releases/tags/${TAG_NAME}")
+            RELEASE_NAME=$(echo "$RELEASE_INFO" | jq -r '.name // .tag_name')
+            RELEASE_BODY=$(echo "$RELEASE_INFO" | jq -r '.body // ""')
+            PRERELEASE=$(echo "$RELEASE_INFO" | jq -r '.prerelease')
+          else
+            TAG_NAME="${{ github.event.release.tag_name }}"
+            RELEASE_NAME="${{ github.event.release.name }}"
+            RELEASE_BODY=$(cat << 'RELEASE_BODY_EOF'
+          ${{ github.event.release.body }}
+          RELEASE_BODY_EOF
+          )
+            PRERELEASE="${{ github.event.release.prerelease }}"
+          fi
+
+          echo "tag_name=${TAG_NAME}" >> $GITHUB_OUTPUT
+          echo "release_name=${RELEASE_NAME}" >> $GITHUB_OUTPUT
+          echo "prerelease=${PRERELEASE}" >> $GITHUB_OUTPUT
+
+          # Save body to file to handle multiline
+          echo "$RELEASE_BODY" > /tmp/release_body.txt
+
+      - name: Check if release exists on Gitee
+        id: check
+        run: |
+          RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
+            "https://gitee.com/api/v5/repos/alture/hydro-ai-helper/releases/tags/${{ steps.release.outputs.tag_name }}?access_token=${{ secrets.GITEE_ACCESS_TOKEN }}")
+
+          if [ "$RESPONSE" = "200" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "Release already exists on Gitee, will update"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "Release does not exist on Gitee, will create"
+          fi
+
+      - name: Create or Update release on Gitee
+        run: |
+          RELEASE_BODY=$(cat /tmp/release_body.txt)
+          TAG_NAME="${{ steps.release.outputs.tag_name }}"
+          RELEASE_NAME="${{ steps.release.outputs.release_name }}"
+          PRERELEASE="${{ steps.release.outputs.prerelease }}"
+
+          # Convert prerelease to boolean
+          if [ "$PRERELEASE" = "true" ]; then
+            PRERELEASE_PARAM="true"
+          else
+            PRERELEASE_PARAM="false"
+          fi
+
+          if [ "${{ steps.check.outputs.exists }}" = "true" ]; then
+            # Get existing release ID
+            RELEASE_ID=$(curl -s \
+              "https://gitee.com/api/v5/repos/alture/hydro-ai-helper/releases/tags/${TAG_NAME}?access_token=${{ secrets.GITEE_ACCESS_TOKEN }}" \
+              | jq -r '.id')
+
+            # Update existing release
+            curl -X PATCH \
+              "https://gitee.com/api/v5/repos/alture/hydro-ai-helper/releases/${RELEASE_ID}" \
+              -H "Content-Type: application/json" \
+              -d "$(jq -n \
+                --arg token "${{ secrets.GITEE_ACCESS_TOKEN }}" \
+                --arg tag "$TAG_NAME" \
+                --arg name "$RELEASE_NAME" \
+                --arg body "$RELEASE_BODY" \
+                --argjson prerelease "$PRERELEASE_PARAM" \
+                '{
+                  access_token: $token,
+                  tag_name: $tag,
+                  name: $name,
+                  body: $body,
+                  prerelease: $prerelease
+                }')"
+
+            echo "Release updated on Gitee"
+          else
+            # Create new release
+            curl -X POST \
+              "https://gitee.com/api/v5/repos/alture/hydro-ai-helper/releases" \
+              -H "Content-Type: application/json" \
+              -d "$(jq -n \
+                --arg token "${{ secrets.GITEE_ACCESS_TOKEN }}" \
+                --arg tag "$TAG_NAME" \
+                --arg name "$RELEASE_NAME" \
+                --arg body "$RELEASE_BODY" \
+                --arg branch "main" \
+                --argjson prerelease "$PRERELEASE_PARAM" \
+                '{
+                  access_token: $token,
+                  tag_name: $tag,
+                  name: $name,
+                  body: $body,
+                  target_commitish: $branch,
+                  prerelease: $prerelease
+                }')"
+
+            echo "Release created on Gitee"
+          fi

package/.github/workflows/sync-to-gitee.yml

@@ -0,0 +1,53 @@
+name: Sync to Gitee
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.GITEE_SSH_KEY }}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          cat >> ~/.ssh/config << EOF
+          Host gitee.com
+            HostName gitee.com
+            User git
+            IdentityFile ~/.ssh/id_rsa
+            StrictHostKeyChecking no
+            ServerAliveInterval 60
+            ServerAliveCountMax 3
+            TCPKeepAlive yes
+          EOF
+          chmod 600 ~/.ssh/config
+
+      - name: Push to Gitee
+        run: |
+          git remote add gitee git@gitee.com:alture/hydro-ai-helper.git 2>/dev/null || true
+
+          # Retry logic for push
+          max_retries=3
+          retry_count=0
+
+          until git push gitee main --force; do
+            retry_count=$((retry_count + 1))
+            if [ $retry_count -ge $max_retries ]; then
+              echo "Failed after $max_retries attempts"
+              exit 1
+            fi
+            echo "Retry $retry_count/$max_retries in 10 seconds..."
+            sleep 10
+          done
+
+          git push gitee --tags --force || true

package/.vercelignore

@@ -0,0 +1,31 @@
+# 排除 HydroOJ 插件相关文件
+src/
+frontend/
+dist/
+specs/
+.specify/
+.claude/
+.chatgpt/
+
+# 排除开发文件
+*.md
+!README.md
+tsconfig.json
+tsconfig.vercel.json
+.eslintrc.json
+.gitignore
+
+# 排除测试文件
+__tests__/
+*.test.ts
+*.spec.ts
+
+# 排除文档
+docs/
+assets/
+DEPLOYMENT*.md
+PHASE*.md
+IMPLEMENTATION*.md
+TROUBLESHOOTING.md
+VERCEL*.md
+QUICKSTART.md

package/CONTRIBUTING.md

@@ -0,0 +1,165 @@
+# 贡献指南
+
+感谢您对 HydroOJ AI Helper 的关注！本文档将帮助您了解如何参与项目贡献。
+
+## 开发环境配置
+
+### 前置要求
+
+- Node.js >= 18.0.0
+- npm >= 8.0.0
+- HydroOJ 开发环境（用于集成测试）
+
+### 安装步骤
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-repo/hydro-ai-helper.git
+cd hydro-ai-helper
+
+# 安装依赖
+npm install
+
+# 编译 TypeScript
+npm run build
+
+# 运行代码检查
+npm run lint
+
+# 运行测试
+npm test
+```
+
+## 代码规范
+
+### TypeScript 规范
+
+- 使用 TypeScript 严格模式
+- 所有公开 API 必须有类型定义
+- 避免使用 `any` 类型，必要时使用类型断言并添加注释说明原因
+
+### ESLint 规范
+
+项目使用 ESLint 进行代码检查。提交前请确保：
+
+```bash
+npm run lint
+```
+
+无任何错误或警告。
+
+### 命名约定
+
+- 文件名：使用 camelCase（如 `promptService.ts`）
+- 类名：使用 PascalCase（如 `PromptService`）
+- 函数/变量：使用 camelCase（如 `buildSystemPrompt`）
+- 常量：使用 UPPER_SNAKE_CASE（如 `DEFAULT_RATE_LIMIT`）
+- 接口：使用 PascalCase，无 `I` 前缀（如 `ChatRequest`）
+
+### 目录结构
+
+```
+src/
+├── handlers/       # HTTP 请求处理器
+├── services/       # 业务逻辑服务
+├── models/         # 数据模型
+├── utils/          # 工具函数
+├── types/          # 类型定义
+├── constants/      # 常量定义
+├── lib/            # 通用库函数
+└── __tests__/      # 单元测试
+    ├── services/
+    ├── utils/
+    └── __mocks__/
+```
+
+## 测试要求
+
+### 单元测试
+
+- 使用 Jest 作为测试框架
+- 测试文件放在 `src/__tests__/` 目录下
+- 测试文件命名：`*.test.ts`
+
+运行测试：
+
+```bash
+# 运行所有测试
+npm test
+
+# 运行特定测试文件
+npm test -- --testPathPattern="promptService"
+
+# 生成覆盖率报告
+npm test -- --coverage
+```
+
+### 集成测试
+
+集成测试脚本位于 `tests/integration/` 目录，使用 curl 进行 API 测试。
+
+## PR 提交流程
+
+### 1. 创建分支
+
+```bash
+git checkout -b feature/your-feature-name
+# 或
+git checkout -b fix/your-bug-fix
+```
+
+### 2. 开发与测试
+
+```bash
+# 开发时使用 watch 模式
+npm run dev
+
+# 确保代码检查通过
+npm run lint
+
+# 确保测试通过
+npm test
+
+# 确保构建成功
+npm run build
+```
+
+### 3. 提交规范
+
+使用语义化提交信息：
+
+- `feat:` 新功能
+- `fix:` Bug 修复
+- `docs:` 文档更新
+- `style:` 代码格式调整（不影响逻辑）
+- `refactor:` 代码重构
+- `test:` 测试相关
+- `chore:` 构建/工具链相关
+
+示例：
+
+```bash
+git commit -m "feat: add rate limit service for API throttling"
+git commit -m "fix: handle edge case in prompt validation"
+```
+
+### 4. 创建 Pull Request
+
+- 标题简洁明了，说明改动内容
+- 描述中说明改动原因和实现方式
+- 关联相关 Issue（如有）
+- 确保 CI 检查全部通过
+
+## 问题反馈
+
+如发现 Bug 或有功能建议，请通过 GitHub Issues 提交，并提供：
+
+- 问题描述
+- 复现步骤
+- 预期行为
+- 实际行为
+- 环境信息（Node.js 版本、HydroOJ 版本等）
+
+## 许可证
+
+本项目采用 MIT 许可证。提交贡献即表示您同意将代码以 MIT 许可证发布。

package/README.md

@@ -0,0 +1,273 @@
+# HydroOJ AI 学习助手
+
+<div align="center">
+
+![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://hydro-ai-helper.vercel.app/api/badge-installs)
+![Active Users (7d)](https://img.shields.io/endpoint?url=https://hydro-ai-helper.vercel.app/api/badge-active)
+![GitHub stars](https://img.shields.io/github/stars/AltureT/hydro-ai-helper?style=social)
+![GitHub forks](https://img.shields.io/github/forks/AltureT/hydro-ai-helper?style=social)
+![License](https://img.shields.io/github/license/AltureT/hydro-ai-helper)
+
+</div>
+
+一个以教学为优先的 AI 辅助学习插件，帮助学生在解题过程中获得思路引导而非直接答案。
+
+## 特色功能
+
+### 多轮对话与上下文理解
+
+- **连续追问**：学生可以在同一对话中持续追问，AI 能够理解并引用之前的对话内容
+- **对话持久化**：页面刷新后对话记录自动恢复，按题目隔离
+- **智能截断**：对话历史超过 7 条时自动截取最近消息，防止 token 超限
+
+### 选中答疑（"我不理解"功能）
+
+- **精准追问**：在 AI 回复中选中不理解的文字，弹出"我不理解"按钮
+- **选中高亮保持**：点击按钮时选中状态保留，清晰标识追问内容
+- **简洁回复**：针对选中内容的解释限制在 2 段以内，直击要点
+- **支持历史消息**：可对任意一条 AI 历史回复使用选中答疑
+
+### 差异化问题类型
+
+| 类型     | 说明                     | 回复风格               |
+| -------- | ------------------------ | ---------------------- |
+| 理解题意 | 对题目要求不太清楚       | 详细解释，循序渐进     |
+| 理清思路 | 需要帮助梳理解题思路     | 结构化框架，有层次     |
+| 分析错误 | 代码有问题，需要找出原因 | 简洁直接，快速定位     |
+| 代码优化 | 已 AC 后寻求效率提升     | 复杂度分析，启发式引导 |
+
+### 代码优化功能（v1.8.0）
+
+- **AC 专属**：仅对已通过该题的用户显示"代码优化"选项
+- **实时检测**：提交 AC 后自动在 AI 面板显示优化选项，无需刷新页面
+- **代码加载确认**：选择优化时弹出确认框，可选择加载 AC 代码或使用当前代码
+- **启发式引导**：AI 分析时间/空间复杂度，提供优化方向但不直接给出代码
+- **服务端校验**：后端验证 AC 状态，防止绕过前端限制
+
+### 统一管理入口（v1.6.0）
+
+- **单一菜单**：控制面板中只有一个"AI 助手"入口，整合原有三个分散菜单
+- **Tab 切换**：通过选项卡在对话记录、使用统计、AI 配置之间切换
+- **URL 参数**：支持 `?tab=conversations|analytics|config` 直接跳转特定功能
+- **浏览器导航**：Tab 切换支持前进/后退按钮
+
+### 教师端数据分析
+
+- **多维度统计**：按班级/学生/题目查看 AI 使用情况
+- **可排序表格**：点击表头对任意列升序/降序排序
+- **快捷跳转**：点击题目名称跳转详情页，点击对话数跳转筛选后的记录列表
+- **数据导出**：支持 CSV 导出
+
+### 多 API 端点与模型管理
+
+- **多端点配置**：支持添加多个 API 端点，实现负载均衡和容灾
+- **模型自动获取**：调用 `/models` 端点自动获取可用模型列表，无需手动输入
+- **Fallback 机制**：选择多个模型按优先级排序，首选模型不可用时自动切换备选
+- **拖拽排序**：拖拽模型卡片调整优先级顺序
+- **API Key 加密**：使用 AES-256-GCM 加密存储 API Key
+
+### 安全增强
+
+- **越狱检测**：拦截试图绕过 AI 辅导限制的请求
+- **白名单机制**：可信题目内容从服务端获取，避免误报
+- **越狱记录**：支持分页查看越狱记录，便于管理员审计
+
+### 现代化 UI
+
+- **三列布局**：宽屏设备（≥1200px）自动切换 LeetCode 风格布局（题目 | 代码 | AI 对话）
+- **响应式设计**：窄屏设备显示浮动对话面板
+- **面板宽度可调**：拖拽 AI 面板左边缘调整宽度（300-900px）
+- **统一主题**：紫色渐变主色调，圆角卡片设计
+
+## 核心特性
+
+**学生端**：题目页面浮动对话面板、自动读取题目、问题类型选择、可选附带代码、多轮对话、选中答疑、代码优化（AC 后）
+
+**教师端**：查看学生对话记录、按时间/题目/班级/学生筛选、可排序统计表格、导出 CSV（支持脱敏）
+
+**管理员端**：统一 AI 助手管理入口、配置多个 API 端点、自动获取模型列表、模型优先级与 Fallback、频率限制、System Prompt 自定义、越狱记录分页查看
+
+## 安装
+
+```bash
+# 克隆并构建
+git clone https://github.com/AltureT/hydro-ai-helper.git
+cd hydro-ai-helper
+npm install
+npm run build
+
+# 安装到 HydroOJ
+hydrooj addon add /path/to/hydro-ai-helper
+pm2 restart hydrooj
+```
+
+验证：访问 `/ai-helper/hello` 返回 JSON 即表示成功。
+
+## 配置
+
+### 环境变量
+
+设置 `ENCRYPTION_KEY`（32 字符）用于加密 API Key：
+
+```bash
+export ENCRYPTION_KEY="your-32-character-secret-key!!!"
+```
+
+生成随机密钥：`openssl rand -base64 24 | head -c 32`
+
+### 管理员配置
+
+登录后访问 **控制面板 → AI 助手**（`/ai-helper`），切换到"AI 配置" Tab：
+
+#### API 端点配置
+
+支持添加多个 API 端点，每个端点包含：
+
+| 字段         | 说明                 | 示例                        |
+| ------------ | -------------------- | --------------------------- |
+| 端点名称     | 自定义名称           | `主服务`、`备用服务`        |
+| API Base URL | AI 服务地址          | `https://api.openai.com/v1` |
+| API Key      | API 密钥（加密存储） | `sk-...`                    |
+| 启用状态     | 是否参与 AI 调用     | 开启/关闭                   |
+
+点击「获取模型」按钮自动获取该端点可用的模型列表。
+
+#### 模型选择与优先级
+
+从所有启用端点的模型中选择需要使用的模型，通过拖拽调整优先级顺序。当首选模型不可用时（限流、服务器错误等），系统自动尝试备选模型。
+
+#### 其他配置
+
+| 字段          | 说明               | 默认值             |
+| ------------- | ------------------ | ------------------ |
+| 频率限制      | 每用户每分钟请求数 | `5`                |
+| System Prompt | AI 系统提示词      | 内置教学辅导提示词 |
+
+配置后点击「测试连接」验证，然后保存。
+
+## 使用
+
+### 学生
+
+1. 访问题目详情页，右下角展开 AI 面板（宽屏自动显示右侧栏）
+2. 选择问题类型（理解题意/理清思路/分析错误）
+3. 可选：描述你的理解和尝试
+4. 可选：附带当前代码
+5. 发送后查看 AI 引导式回答
+6. 如有不理解的地方，选中文字点击"我不理解"继续追问
+7. AC 后可使用"代码优化"功能，获取效率提升建议
+
+### 教师/管理员
+
+访问 **控制面板 → AI 助手**（`/ai-helper`），通过 Tab 切换访问：
+
+- **对话记录** Tab：查看学生对话记录，支持按时间/题目/班级/学生筛选
+- **使用统计** Tab：查看 AI 使用统计数据，支持多维度分析
+- **AI 配置** Tab（仅管理员）：配置 API 端点、模型优先级、系统提示词等
+
+支持 URL 参数直接跳转：`/ai-helper?tab=analytics`、`/ai-helper?tab=config`
+
+数据导出：在对话列表页点击"导出数据"
+
+### 示例截图
+
+**学生端问答面板与题目联动示例：**
+
+<img src="assets/screenshots/1.png" alt="学生端示例" width="800">
+
+<img src="assets/screenshots/2.png" alt="学生端示例" width="400">
+
+**后台管理：**
+
+<img src="assets/screenshots/3.png" alt="后台管理示例" width="800">
+
+<img src="assets/screenshots/4.png" alt="后台管理示例" width="800">
+
+<img src="assets/screenshots/5.png" alt="后台管理示例" width="800">
+
+<img src="assets/screenshots/6.png" alt="后台管理示例" width="400">
+
+<img src="assets/screenshots/7.png" alt="后台管理示例" width="500">
+
+## 项目结构
+
+```
+hydro-ai-helper/
+├── src/                # 后端（TypeScript）
+│   ├── models/         # 数据模型
+│   ├── services/       # 业务逻辑
+│   ├── handlers/       # 路由处理器
+│   └── lib/            # 工具函数
+├── frontend/           # 前端（React）
+│   ├── student/        # 学生端组件
+│   ├── teacher/        # 教师端组件
+│   ├── admin/          # 管理员组件
+│   └── components/     # 通用组件（如 Tab 容器）
+└── dist/               # 编译输出
+```
+
+## 开发
+
+```bash
+npm run dev      # 开发模式（watch）
+npm run build    # 构建
+npm run lint     # 代码检查
+```
+
+## 遥测与隐私
+
+### 数据收集说明
+
+为了更好地了解插件使用情况并改进功能，本插件会收集以下**匿名统计数据**：
+
+- 插件安装数（通过随机 UUID 去重）
+- 最近 7 天活跃用户数（聚合统计）
+- 总对话数
+- 插件版本信息
+
+### 隐私保护措施
+
+✅ **完全匿名**：使用随机 UUID，不收集任何可识别个人身份的信息
+✅ **域名哈希**：域 ID 经过 SHA-256 哈希处理
+✅ **仅聚合数据**：只统计用户数和对话数，不记录具体内容
+✅ **自动清理**：90 天未上报的数据自动删除
+✅ **用户可控**：可通过管理员配置关闭遥测功能
+
+### 如何关闭遥测
+
+如果你不希望上报统计数据，可以在数据库中设置：
+
+```javascript
+// 连接到 MongoDB
+use your_hydro_db
+
+// 关闭遥测
+db.ai_plugin_install.updateOne(
+  { _id: 'install' },
+  { $set: { telemetryEnabled: false } }
+)
+```
+
+关闭后，插件仍可正常使用，但不会上报任何数据。
+
+### 数据用途
+
+收集的数据仅用于：
+- 在 GitHub README 显示安装数和活跃用户数徽章
+- 了解插件使用趋势，优先开发最需要的功能
+- 评估插件稳定性和性能
+
+**我们承诺**：
+- ❌ 不会出售或共享数据给第三方
+- ❌ 不会收集学生的代码、题目内容或对话记录
+- ❌ 不会追踪个人用户行为
+
+## 关于本项目
+
+本项目是 [HydroOJ](https://github.com/hydro-dev/Hydro) 开源在线评测系统的第三方插件，由 AI 辅助开发完成。如有问题或建议，欢迎提交 Issue。
+
+## 许可证
+
+MIT License