chengzi/ClassFeedback
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
73cce4c4f5c7be3eaaacc9186b430831e077236d
ClassFeedback/.pi/skills/class-feedback-report/SKILL.md

18 KiB
Raw Blame History

name, description
name description
class-feedback-report 按班组整理 OJ 课堂反馈：自动定位课程与章节、拉取全班逐生逐次提交（代码+编译报错+状态），产出「第N次提交错在哪 → 整体分析 → 建议」的学生诊断报告草稿（MD+HTML+PDF），供带班教师审核后使用。老师说「引导我进行操作」「帮我处理本项目」「整理课堂反馈」「学生分析报告」时使用本技能；引导模式会带着老师一步步完成环境检查、账号配置与报告生成。

Skill: 班级课堂反馈与提交诊断

按班级生成每位学生的提交诊断报告（第一次提交错在哪、第二次错在哪……整体分析、建议）， 数据全部来自 HydroOJ 课程插件的只读 API，评价与建议由 AI 起草、教师审核后才能发给学生/家长。

关键词：课堂反馈、提交诊断、错误分析、班级报告、学生分析、整理反馈、引导我进行操作、帮我处理本项目

操作引导模式（老师第一次使用，或说「引导我进行操作」「帮我处理本项目」时从这里开始）

面向不熟悉命令行的老师：AI 按下面清单逐步执行并代替老师敲命令，每完成一步简短汇报再进行下一步。 老师只需要回答问题（用哪个站、账号密码、哪个班级）。

  1. 仓库准备（第一次必做，老师只回答问题）：问老师姓名/工号 → 仓库地址默认 https://git.qonnwolf.com/<工号>/ClassFeedback（机构仓库名统一 ClassFeedback， git 服务 git.qonnwolf.com）。
    • 已有本地克隆 → 进入仓库目录 git pull；
    • 没有 → 引导老师在 git.qonnwolf.com 网页生成访问令牌（设置 → 应用 → 访问令牌， 勾选 repository 读写），令牌让老师填进仓库根 .env 的 GIT_TOKEN（见第 3 步）， 然后 git clone https://git.qonnwolf.com/<工号>/ClassFeedback（公共克隆不需要令牌， 推送时才用），新老师还没有仓库 → 引导网页建仓（名字必须是 ClassFeedback）或 本地 git init + remote add origin + 首推；
    • 结构自检：.claude/memory/class/、skills/class-feedback-report/、 AGENTS.md、CLAUDE.md、.gitignore、.env 缺失则按包内 repo-template/ 补建 （.env 从 .env.example 复制，填好后永不入库）。
  2. 环境自检（自动执行，无需老师操作）：node -v 需 ≥18；确认本 skill 的 scripts/fetch-class-data.mjs、scripts/check-login.mjs、scripts/mkpdf.mjs 存在； Windows 确认 Edge 已安装（PDF 用）。有缺项先解决缺项再继续。
  3. 配置凭据（.env，一次性；站点固定为 qonnwolf）：脚本自动读取仓库根 .env， 请老师自行编辑填写以下字段（推荐老师自己填，密码不经过对话；老师愿意口述时 AI 可代填，填完提醒「.env 不入库」）： 
    OJ_BASE_URL=https://oj.qonnwolf.com
OJ_USERNAME=你的OJ用户名
OJ_PASSWORD=你的OJ密码
GIT_USER=你的工号
GIT_TOKEN=你的访问令牌
GIT_REPO_URL=https://git.qonnwolf.com/你的工号/ClassFeedback
    填好后运行 node scripts/check-login.mjs（脚本自动读 .env，无需命令行传凭据）验证； 输出 OK|登录成功… 才继续；失败按「异常处理」回应老师。 令牌的 git 配置一次性执行： git remote set-url origin https://<GIT_USER>:<GIT_TOKEN>@git.qonnwolf.com/<工号>/ClassFeedback （存在本地 .git/config，不入库），之后 git push 不再需要令牌。
  4. 收集班级组名：请老师提供完整班组名（如「克力周日0830CSP02」）。 老师不确定时：先跑 fetch（不带 --group 会报错，带 --group 才扫课程），或用 GET /course/api/list 列出课程标题让老师指认，再从课程页确认组名。
  5. 确认章节与花名册（先取小组成员，再分析）：跑 fetch 后，向老师展示并请其确认： 「班组-课次号」标识（如 克力周日0830CSP02-04）、章节名、班组花名册（N 人 + 姓名列表）， 以及班组花名册（N 人 + 姓名列表）。老师确认无误后才进入逐生分析写报告；成员有出入时先解决报名/分组问题。 ⚠️ 报告编号用「课次号」（第几次课），不用 OJ 章节号——章节号（章节标题前缀数字，如「03 二维数组」） 是教材进度，课次号是实际上课序数，两者常差 1～2，混用会与内部正本 YYYYMMDD_课程编号-课次.md 对不上。
  6. 执行生成（每个学生五件事，缺一不可）： ① 家长版报告 md/html → .claude/memory/class/<班组>/<学生名>/<姓名>-<班组>-<课次号>-反馈报告.{md,html}； ② PDF 同目录本地生成（git 忽略，不入库）； ③ 内部课评正本 → 同目录 feedback/YYYYMMDD_课程编号-课次.md （校宝核查口径：每位学生每次课有且仅有一个文件；请假加 (请假)、补课加 (补课-去XX)； 内容为简明事实：日期、班组、状态、本讲要点、订正情况）； ④ 更新画像 → .claude/memory/class/<班组>/<学生名>/profile.md（追加本讲表现要点、刷新能力评估）； ⑤ 班级汇总 → .claude/memory/class/<班组>/summaries/YYYYMMDD_班组-课次号_班级反馈.md。
  7. git 同步：git add .claude/memory/class .claude/skills docs（*.pdf 被 .gitignore 自动排除）→ git commit -m "课评: <班组>-<课次号> <日期>" → git push； 推送失败（令牌过期/无权限）→ 引导老师重新生成令牌并更新凭据。
  8. 交付：汇报每个学生三件套的文件路径 + 内部正本 + 画像更新情况 + 班级汇总， 并明确提醒：家长版报告是草稿，审核措辞后才能发学生/家长。

异常处理（引导模式中随时可能触发）：

  • 登录失败 → 请老师核对账号密码；确认是教师账号或拥有该班成绩查看权限（普通学生账号不行）。
  • 「没有找到包含班组的课程」→ 班组名不全或该班不在所选站；列出可见课程标题协助老师确认。
  • analysis 响应慢 → 正常现象（全班粒度重接口），等待即可，不要并发重试。

前置条件（跳过引导、直接使用时自行满足）

  • Node 18+（自带 fetch）；出 PDF 需要 Edge 或 Chrome 浏览器；git（同步课评仓库）。
  • 凭据统一放仓库根 .env（从 .env.example 复制；已被 .gitignore 排除，绝不提交）： 
    OJ_BASE_URL=https://oj.qonnwolf.com
OJ_USERNAME=你的OJ用户名
OJ_PASSWORD=你的OJ密码
GIT_USER=你的工号
GIT_TOKEN=你的访问令牌
GIT_REPO_URL=https://git.qonnwolf.com/你的工号/ClassFeedback
    OJ 账号需要「教师或授权校区查看者」权限（普通学生账号只能看到自己的数据）。 脚本自动向上查找并加载 .env；环境变量 COURSE_API_USERNAME/PASSWORD 可临时覆盖。
  • 凭据只在 .env 和 git 凭据里，不得写进命令行参数、报告或日志。

安装（项目级，随仓库走）

方式 A（推荐）：老师直接克隆自己的 ClassFeedback 仓库——新仓库模板已自带本技能 （skills/class-feedback-report/），克隆即用。

方式 B（存量仓库补装）：把 class-feedback-report/ 文件夹复制到项目仓库的 skills/ 目录下（与 .claude/memory/class/ 同在 .claude/ 内），并在仓库根的 AGENTS.md / CLAUDE.md 写明「本项目技能在 skills/ 目录」。不要装到用户级目录（/.zcode、/.claude）—— 技能必须随项目仓库走，老师换 agent、换电脑都只要拉仓库。

API 使用速查

本 skill 全部基于课程插件的只读 JSON 接口（完整文档见 docs/API.md）。 鉴权方式：先 POST /login（JSON：uname + password）拿 sid Cookie，后续请求带 Cookie: sid=... 和 Accept: application/json；脚本自动从仓库根 .env 读取凭据。

接口 用途 权限
GET /course/api/list?page=N 列出可见课程（定位班组所在课程） 已登录
GET /course/api/detail/:cid 课程与章节结构 可访问该课程
GET /course/api/v1/courses/:cid/students?group=班组名 按班组拉花名册 教师或授权查看者
GET /course/api/v1/courses/:cid/sections/:csid/feedback/overview?group= 章节班级统计（完成率、首刷率） 教师或授权查看者
GET /course/api/v1/courses/:cid/sections/:csid/feedback/students?group=&limit=100 逐生统计信号 教师或授权查看者
GET /course/api/v1/courses/:cid/sections/:csid/feedback/students/:uid 单生逐题证据（无代码） 教师或授权查看者
GET /course/api/analysis/:cid/:csid?withCode=true&withHistory=true 全班提交历史+代码+编译报错（重接口，每次运行只调一次） 教师或授权查看者
GET /p/<pid> 客观题题干与选项（HTML，脚本已自动解析） 可见该题

注意：withHistory=true 必须带上，否则 history 全空；响应为全章节全班粒度（数百 KB），按需使用。

使用流程

1. 抓取班级数据（脚本自动完成）

node "<skill目录>/scripts/fetch-class-data.mjs" \
  --group="克力周日0830CSP02" \
  --base-url="https://oj.qonnwolf.com" \
  --out="F:\HydroOJ\artifacts\class-feedback\digest-<班级名>.json"
  • 脚本自动：定位含该班组的课程（多门时优先「秋季」并在 stderr 提示）、选最后一个有提交活动的章节、 拉花名册、调 analysis?withCode=true&withHistory=true 一次性取全班提交历史； 自动识别客观题（提交内容是答案卷的题）并抓取题干与选项存入 objective[pid].questions （每个问题含 no/text/options[]，katex 拆行已合并处理）。
  • 可选参数：--course=<cid> 指定课程、--section=<csid> 指定章节、--uid=<uid> 只整理某个学生。
  • 产出 digest JSON：每生 {stats 信号, problems:[{pid,title,submissions:[{seq,status,score,errorHead,code}]}]}。

2. 阅读原料，逐生写诊断

读 digest（大班可分生读取）。一名学生一个 MD 文件 + 一个自包含 HTML 文件（内嵌 CSS，可直接转发/打印）。

每个非 AC 提交都要给出人话结论，判定规则：

状态 判定方法 人话示例
CE 直接读 errorHead（gcc 报错带行号） 变量没有定义 / 少分号 / 函数名写错（print→printf）/ 重复定义 / 输入输出符号写反
WA 读 code 对照题意；有 AC 版时做 diff，差异处即病因 数组开小了 / 边界条件差一个等于号 / 输出少换行 / 变量没初始化 / 输出没按题意保留小数位
TLE 读 code 看循环 循环条件写错死循环（1<=T 恒真）/ 方向写反 / 漏读入起点 / 算法太慢
RE 读 code 数组越界 / 除零

多鼓励：报告必须有「🌟 值得表扬的地方」卡片放在最前；一遍通过的题写「一遍通过，非常不错！」； 订正到底的写韧劲；AC 版代码写得好的点名夸（如「min 用得干脆利落」）。表扬必须基于事实，不许编造。 整体分析先扬后抑：亮点在前，习惯问题在后；建议用编号列表给可执行动作。

客观题（选择/判断）特殊处理——不写提交历史，直接给错题+题目分析+选项： 这类题学生只能提交对/错，会反复试答案，所以报告直接列出「答错的题」：

  1. 取标准答案：用该题全部学生 AC 卷交叉比对（≥2 人一致即认定），无需教师提供答案。
  2. 学生 WA 卷与标准答案逐题 diff → 得出每题「答错次数」和「答案轨迹」。
  3. 题干与选项直接用 digest 的 objective[pid].questions（脚本已抓取）；若缺失再手工 GET <base-url>/p/<pid> 提取。
  4. 每道错题输出：题干原文 + 完整选项（逐项列出） + 你的答案轨迹 + 正确答案 + 考点分析 （一段人话讲透为什么；选项里的陷阱项要点名，如「−1.2 是诱导你按小数除法算的」）。
  5. 开头加一句提示：「客观题不建议反复提交试答案，错的就是没弄懂的知识点」。

整体分析要跨题目归纳习惯问题，可用的典型模式：

  • 多题首刷全 CE → 没编译就直接提交，粗心；
  • 变量未声明/未初始化反复出现 → 声明与初始化意识弱；
  • WA 集中在边界/格式 → 审题不细，输出格式（换行、小数位）没对题面；
  • 反复「交一发试试」→ 概念不清靠猜，订正态度好但方法不对；
  • 大量提交后全部 AC → 订正能力强（要点名表扬的亮点）；
  • 一次通过率高 → 基础扎实（可建议进拓展）。

3. 按固定模板输出报告（一人一 MD + 一 HTML）

MD 结构（顺序固定）：

# 学生提交诊断报告 · <姓名>
> 班级/章节/日期/审核稿声明 + 📊 总览（进度、首刷%、提交次数）

## 🌟 值得表扬的地方        ← 放最前，2~4 条事实型表扬
## 💻 编程题逐题诊断        ← 每题一个小节：第一次提交…第N次提交：通过 + 📌复盘框
## 📝 选择题 · 错题分析      ← 只列答错的题：题干/答案轨迹/正确答案/考点分析
## 📝 判断题 · 错题分析      ← 同上
## 📖 整体分析              ← 先扬后抑
## ✅ 给<姓名>的建议         ← 3~4 条可执行动作

HTML：与 MD 同名 .html，自包含单文件（内嵌 CSS、无外部依赖、可打印）。受众是家长，设计以 「读起来舒服、看得懂」为先（v2 定稿规范，经用户确认）：

  • 样式参考（必须先读）：samples/report-sample.html 与 samples/report-sample.md—— 生成任何报告前先读样例，完整复用其 CSS、卡片结构、徽章配色与文案语气，只替换内容， 确保所有 AI 产出的报告观感一致。
  • 暖色纸感背景（#faf8f4）+ 白卡片，基础字号 ≥16.5px、行距 ≥1.9；max-width 820px；移动端断点适配；
  • 🌟表扬绿卡前置；📊完成情况用进度条可视化（课堂/作业/拓展），不带图例行；
  • 编程题时间线的状态徽章用家长能懂的话：✍️ 写错语法（CE）/ 🔄 结果不对（WA）/ ⏱️ 运行超时（TLE）/ 🎉 通过（AC）；
  • 客观题错题卡：题干引用块 + 选项逐项格子（正确选项绿框 ✓、孩子错选橙框）+ 答案轨迹 + 💡考点黄框；
  • 结尾「📖 老师的整体评价」先扬后抑；「接下来要养的小习惯」每个分点独立成行（①②③各一段）；
  • 不要「写给家长的话」导读卡、不要「在家可以这样帮孩子」模块、不要小图标图例（用户已确认去掉）；
  • 「教师审核稿」提示缩为一行小字置顶（不放大横幅），术语尽量翻译成生活语言；
  • PDF 导出（v2 定稿：单页长图式，标准宽 660px，桌面布局、单页无分页）：scripts/mkpdf.mjs <html> <pdf> 两遍法——先用无头 Edge 在 660px 视口量内容真实高度，再以 @page{size:660px <高度+120>px; margin:0} 输出一整页 PDF（零页边距、颜色保真、自动剔除悬浮按钮与审核稿行）。 用法：node scripts/mkpdf.mjs 报告.html 报告.pdf（中文路径已内置 ASCII 临时名处理）。
  • 交付三件套与命名（用户定稿）：每名学生 3 个文件、统一命名 <姓名>-<班组>-<课次号>-反馈报告.{md,html,pdf}， 例：王凯平-克力周日0830CSP02-04-反馈报告.md / .html / .pdf。 「班组-课次号」（如 克力周日0830CSP02-04）必须同时出现在文件名和报告标题里——它说明 是哪个班、第几次课；章节名（如「二维数组图形」）写在报告标题的副行。 ⚠️ 课次号 = 本学期第几次课（与内部正本 YYYYMMDD_课程编号-课次.md 一致），不是 OJ 章节号。 OJ 章节号（章节标题前缀数字）只可在报告内文提及（如「OJ 章节：03 二维数组」），不得用于文件名。 班级汇总命名 <班组>-<课次号>-反馈汇总-<日期>.md。

同时生成班级汇总 MD（整体表 + 共性问题 + 教师跟进优先级），命名 <班级>-<章节>-反馈汇总-<日期>.md；全部产物建议放同一个输出目录（如 class-feedback\）， 三件套命名以「姓名-课程阶段-章节-反馈报告」为准。

4. 审核红线（必须写进每次交付说明）

  • 报告是草稿，发送给学生/家长前必须由带班教师审核措辞；
  • 诊断只写事实与学习习惯（变量没定义、没编译就交），不写人身评价（笨/懒/不认真听讲）；
  • 代码、编译报错、答错的具体选项属于教学敏感数据，报告不要发到学生群，只给教师本人；
  • 一个学生的报告不要引用其他学生的成绩做对比排名。

依赖与已知边界

  • 课程插件须 ≥ C2.3（feedback v1 + analysis withCode/withHistory），qonnwolf 已验证（2026-09-09）。
  • analysis 是整章节全班粒度的重接口（可达数百 KB），一次运行只调一次，不要按学生循环调用。
  • WA/TLE 的「题意对照」依赖 AI 读代码推断；拿不准的结论在报告中用「疑似」标注，由教师定夺。
  • 测试点级别的输入输出细节 API 不提供，如需可让教师去 OJ 记录页（用首刷 rid）人工查看。
Reference in New Issue View Git Blame Copy Permalink