feat(hackathon): AI-mediated peer cross-evaluation system with dual-track Issue publishing

[Jerryxiaohei]

背景与动机

当前 HackForger 评审体系为单向评审：评委打分，参赛团队被动接受。本 Issue 提案引入 AI 中介的交叉评测机制，实现两个核心价值：

1. 社区氛围：参赛团队通过结构化评测互相了解、互相帮助，将评测过程沉淀为可检索的开源社区内容
2. AI 评委增强：对于仅有 AI 评委的赛段，交叉评测和选手自辩提供了多视角上下文，帮助 AI 评审更客观准确

核心设计原则

• 知识产权保护：评审方永远无法直接访问被评项目的私有 Repo，AI Agent 是唯一的信息中间层
• 社区开放性：评测结论以 Issue 形式双轨发布（项目方私信 + 社区公开存档）
• 与现有系统融合：基于已有的 Phase 系统、HackathonSubmission 模型和 assistant.go 占位符扩展，不破坏现有架构

---

完整流程

阶段一：分配（系统自动）

peer_review Phase 激活
        ↓
系统按轮转算法分配：每个参赛者评审 N 个其他队的提交
（N 由黑客松管理员配置，推荐 2-3 个）
        ↓
创建 HackathonPeerReviewAssignment 记录
        ↓
评审方收到站内通知（Feed 事件）

分配约束（可选，管理员配置）：

• 同赛道优先（技术背景相近，评测更有质量）
• 禁止同组织成员互评（避免利益冲突）
• 每个项目至少被 2 个不同团队评审

---

阶段二：AI 中介问答（评审核心）

Team A（评审方）访问 /hackforger/hackathons/{id}/peer-review/{assignment_id}
        ↓
前端展示：被评项目的公开信息（名称、赛道、队伍）+ 聊天界面
        ↓
Team A 向 AI Agent 提问
（"这个项目用了什么架构？""主要创新点是什么？""有哪些明显不足？"）
        ↓
AI Agent（以系统 bot 账号运行）：
  - 以系统特权读取 Team B 的私有 Repo（README、代码结构、提交历史）
  - 按照披露策略合成回答（见下文「信息披露边界」）
  - 从不粘贴原始代码
        ↓
问答历史保存为 HackathonPeerReviewMessage 记录
（每次问答均记录，作为后续 AI 评委的参考上下文）

评审方在聊天过程中逐步形成评测结论，完成后点击「提交评测报告」。

---

阶段三：发布（双轨 Issue）

Team A 确认提交后，AI Agent 以 bot 账号自动发布两份 Issue：

Issue ① — 发布至 Team B 的 Repo（私信性质）

标题：[HackForger 交叉评测] {HackathonName} · {ReviewerTeamName} 评测报告

内容：
- 评测者：@{reviewer}（已匿名化展示，防止人情分）
- 评测维度：技术实现 / 创新性 / 完整度 / 文档质量
- 亮点：...
- 改进建议：...
- 综合评分：X / 10

> 本报告由 HackForger AI 评测 Agent 协助生成，评测方无法直接访问本仓库。

Team B 可以在此 Issue 中回复（自辩、补充说明、澄清误解），回复内容将一并提供给 AI 评委作为参考。

Issue ② — 发布至社区评测 Repo

系统在黑客松开始时自动创建 hackforger-reviews-{hackathon-slug}（公开 Repo），每份评测作为一个 Issue 存档：

标题：[评测存档] {HackathonName} · {ProjectName} 交叉评测

内容：
- 项目名称、赛道、黑客松
- 评测问答摘要（AI 脱敏处理后）
- 评测结论
- 社区可在此 Issue 参与讨论、补充视角

社区用户（包括未参赛者）可以在 Issue ② 中评论，形成开源社区的知识沉淀。

---

阶段四：AI 评委评分（上下文增强）

AI Judge 评分触发
        ↓
系统构建评分上下文（AIJudgeContext）：

  {
    "submission": HackathonSubmission（基本信息、赛道）,
    "pr_diff": PR #PRID 的代码变更（完整 diff）,
    "peer_reviews": [
      {
        "reviewer": "Team A（匿名）",
        "qa_summary": "问答历史摘要",
        "conclusion": "评测结论",
        "self_defense": "Team B 的回应（如有）"
      },
      ...
    ],
    "criteria": [评分维度和权重]
  }
        ↓
Claude API 综合评分
（AI 评委同时看到：代码变更 + 同伴评价 + 团队自辩）
        ↓
生成分维度评分 + 评分理由

---

数据模型

新增表

// 分配记录
type HackathonPeerReviewAssignment struct {
    ID           int64              `xorm:"pk autoincr"`
    HackathonID  int64              `xorm:"NOT NULL INDEX"`
    PhaseID      int64              `xorm:"NOT NULL"`
    ReviewerID   int64              `xorm:"NOT NULL"`   // 评审方用户 ID
    SubmissionID int64              `xorm:"NOT NULL"`   // 被评审的提交
    Status       string             `xorm:"VARCHAR(20) NOT NULL DEFAULT 'assigned'"`
    // assigned | chatting | submitted | published
    CreatedUnix  timeutil.TimeStamp `xorm:"created"`
    UpdatedUnix  timeutil.TimeStamp `xorm:"updated"`
}

// 评测会话（一次分配对应一个会话）
type HackathonPeerReviewSession struct {
    ID              int64              `xorm:"pk autoincr"`
    AssignmentID    int64              `xorm:"NOT NULL UNIQUE"`
    TargetIssueID   int64              `xorm:"DEFAULT 0"` // Issue① ID（项目 Repo）
    ReviewIssueID   int64              `xorm:"DEFAULT 0"` // Issue② ID（社区 Repo）
    PublishedAt     *time.Time
    CreatedUnix     timeutil.TimeStamp `xorm:"created"`
}

// 问答消息
type HackathonPeerReviewMessage struct {
    ID         int64              `xorm:"pk autoincr"`
    SessionID  int64              `xorm:"NOT NULL INDEX"`
    Role       string             `xorm:"VARCHAR(10) NOT NULL"` // "reviewer" | "agent"
    Content    string             `xorm:"TEXT NOT NULL"`
    CreatedUnix timeutil.TimeStamp `xorm:"created"`
}

PhaseType 新增记录

在 hackathon_phase_type 表中新增 peer_review 类型，与现有 submission、judging 等阶段并列，无需改动 Phase 模型。

---

信息披露边界（AI Agent System Prompt 策略）

AI Agent 读取私有 Repo 后，按以下策略回答问题：

内容类型	策略
项目整体定位、解决的问题	✅ 完整披露
技术栈（语言、框架、主要依赖）	✅ 完整披露
整体架构思路（前后端分离、微服务等）	✅ 完整披露
模块划分和目录结构（仅层级，不含文件名）	✅ 披露
具体算法思路（自然语言描述，不含代码）	✅ 可描述
代码质量整体评价（测试覆盖、文档完整度）	✅ 可评价
任何源代码片段	❌ 禁止
具体文件名和路径	❌ 禁止
配置文件、密钥、环境变量	❌ 禁止
数据库 Schema 细节	❌ 禁止
第三方服务集成细节（可推断商业逻辑）	⚠️ 仅说"使用了第三方支付"，不说具体服务商

披露边界可由黑客松管理员在创建赛事时配置（保守 / 标准 / 开放三档）。

---

实现分阶段计划

Phase 1 — 数据层（1-2天）

• 新增 HackathonPeerReviewAssignment、HackathonPeerReviewSession、HackathonPeerReviewMessage 三张表
• 注册 peer_review PhaseType
• 基础 CRUD（models/hackforger/peer_review_*.go）

Phase 2 — AI Agent 服务（2-3天）

• 扩展 services/hackforger/assistant.go，实现真实 Claude API 调用
• 实现系统 bot 账号的 Repo 内容读取（README、目录树、提交历史摘要）
• 实现 buildSystemPrompt() 按披露策略构建上下文
• 实现 PeerReviewChat(sessionID, question) 服务函数

Phase 3 — 发布服务（1-2天）

• 实现 PublishPeerReview(sessionID) — 以 bot 账号在目标 Repo 创建 Issue①
• 实现黑客松社区评测 Repo 的自动创建（hackforger-reviews-{slug}）
• 实现 Issue② 的创建和格式化
• 将 Issue 线程 ID 回写至 HackathonPeerReviewSession

Phase 4 — AI 评委集成（2-3天）

• 实现 BuildAIJudgeContext(submissionID) — 聚合提交 + PR diff + peer review Issues
• 实现真实 Claude API 评分（替换现有占位符 SubmitScores）
• 评分结果写入现有 HackathonJudgeScore 表（与人工评审复用同一表）

Phase 5 — 前端（2-3天）

• 评审任务列表页：/hackforger/hackathons/{id}/peer-review
• 聊天评测界面：支持多轮问答 + 最终报告确认
• 管理员配置页：分配数量、披露级别、社区 Repo 可见性

---

验收标准

• 私有 Repo 内容零字节流向评审方（只有 AI 合成的摘要可见）
• 评测 Issue 在目标项目 Repo 和社区 Repo 各存在一份
• Team B 在 Issue① 的回应内容能被 AI 评委读取到
• 黑客松管理员可配置「仅 AI 评委」赛段，此时 AI 读取 peer review 上下文后独立评分
• 社区用户可在 Issue② 中参与讨论（不需要黑客松参赛资格）
• 系统 bot 账号发布的 Issue 有明确的 bot 标识，避免被误认为真人评审

---

相关文件

• 现有占位符：services/hackforger/assistant.go、routers/api/v1/hackforger/assistant.go
• Phase 系统：models/hackforger/phase.go
• 提交模型：models/hackforger/hackathon_submission.go
• 评审服务：services/hackforger/hackathon_judge.go
• 架构说明：CLAUDE.md，docs/frontend-dev-guide.md

---

开放问题

• 分配算法：纯随机轮转 vs. 赛道内优先分配？
• 匿名化策略：评审方身份对项目方匿名（防人情），还是在报告发布后公开？
• 评测周期：评审方有多长时间完成评测？超时如何处理（跳过 or 强制发布草稿）？
• 社区 Repo 权限：完全公开 vs. 仅黑客松参与者可见？