Metadata-Version: 2.1
Name: sxlog-teacher
Version: 1.0.5
Summary: 超星 AI 交互记录 · 教师端验证工具（验签、验链、行为取证、班级汇总、文件夹右键菜单）
Home-page: https://pypi.org/project/sxlog-teacher/
Author: 吴振谦（宁波大学科学技术学院）
Maintainer: 吴振谦（宁波大学科学技术学院）
License: LicenseRef-Proprietary
Keywords: chaoxing,超星,verify,hash chain,hmac,education
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Requires-Python: >=3.8
Project-URL: Homepage, https://pypi.org/project/sxlog-teacher/
Description-Content-Type: text/markdown

# sxlog-teacher · 超星 AI 交互记录验证工具（教师端）

批量验证学生提交的记录文件（`.txt`；旧版 `.sxlog` 同样支持）：**验签 → 验链 → 摘要复算 → 行为取证 → 出报告 → 跨文件查重**，
并可在资源管理器里**右键文件夹**一键完成。

```bash
pip install sxlog-teacher
sxlog-teacher install-hook     # 注册文件夹右键菜单（免管理员权限）
```

之后对装着学生作业的文件夹点右键 →「SXLOG 验证学生提交（批量）」即可。

**作者**：吴振谦 · 宁波大学科学技术学院

---

## 作者与项目信息

| 项目 | 信息 |
|---|---|
| **作者** | **吴振谦**（Wu Zhenqian） |
| **单位** | **宁波大学科学技术学院** |
| **教学场景** | 《电子系统项目开发与实践》等课程的过程性评价与作业追溯 |
| **配套包** | [`sxlog-student`](https://pypi.org/project/sxlog-student/) —— 学生端（记录插件安装器） |
| **许可** | 教学用途专有许可（LicenseRef-Proprietary） |

本包是学生端的**验证侧**：学生端负责如实采集与本地留存，本包负责独立复核 ——
两者共用同一套哈希链与签名实现（逐字节一致），因此教师端能验出任何事后改动。
判断权始终在教师手里：报告只呈现证据与风险提示，不代替教学判断。

---

## 三条使用路径

### 1. 右键菜单（最省事）

```
资源管理器 → 右键装着学生记录文件的文件夹（或文件夹空白处）
         → SXLOG 验证学生提交（批量）
```
会在该文件夹内生成 `SXLOG班级汇总_时间.html` 与 `.csv`，并自动用浏览器打开汇总报告。

### 2. 图形界面

```bash
sxlog-teacher gui "D:\作业收齐\第3次作业"
```
表格按风险排序（未通过置顶 → 高风险 → 中风险 → 低风险），**双击任意一行**打开该生的交互时间线报告。
点「生成班级汇总」出 HTML，点「导出 CSV」出 Excel 可直接打开的表格。

### 3. 命令行

```bash
sxlog-teacher verify "D:\作业收齐\第3次作业" --class-report 汇总.html --csv 汇总.csv --open
sxlog-teacher verify 张三_2024030118.txt --json # 单文件 + JSON 报告
sxlog-teacher verify . --quiet                  # 只输出一行一人的结论
```

## 验证逻辑（与插件端逐字节一致）

| 层 | 做法 | 能拦住什么 |
|---|---|---|
| ① 哈希链 | 每条记录哈希包含前一条哈希 | 删除 / 修改 / 插入任意一条记录 → 链断裂 |
| ② HMAC 签名 | 密钥 = `PBKDF2(教师私盐 \| 学号 \| 姓名, 15 万轮)` | 学生缺私盐，**即使自己重算整条哈希链也签不出来** |
| ③ 摘要复算 | 从记录重新统计并逐字段比对文件声明 | 手工改过 summary 的文件 |
| ④ 行为取证 | 粘贴占比、零击键长文本、击键间隔、输入法组合、AI→提交间隔、与 AI 回复相似度、复制行为 | 外部 AI 生成后粘贴、照抄 AI 答案 |
| ⑤ 跨文件比对 | 链尾哈希 / 会话 ID / **设备指纹** 查重 | 整份文件复制顶替、同一设备提交多个学号 |

**结论分级**：风险评分 ≥6 判「高」、≥3 判「中」；**完整性失败（签名/链不匹配）直接判高**，
不会出现"签名失败却显示风险低"这种误导性结论。

## 报告长什么样

**单份时间线报告**（自包含 HTML，学生 名_时间线.html）：
- 校验结论横幅 + 风险等级
- 统计指标：提问次数、打字/粘贴字符数、粘贴占比、击键总数、AI 平均响应时长、
  **AI 工具名与使用分布**、**设备指纹 / 设备哈希 / 本机标识**
- 交互密度图（每 5 分钟事件数）
- 完整交互记录：可按事件类型过滤、可全文搜索；学生提问/AI 回复/粘贴/复制/开始记录/设备信息分色显示

**班级汇总报告**：通过率、风险分布、每人一行（含 AI 工具与设备指纹），
以及查重与关联告警区。

**CSV**：UTF-8 BOM 编码，Excel 直接双击打开不乱码。

## 私盐管理（务必遵守）

- `verify_sxlog.py`（本包 `verifier.py`）含**明文教师私盐**，**绝不能发给学生**，
  否则学生可以自行伪造签名，HMAC 这一层防御即告失效。
- 私盐每学期轮换一次，轮换时要**同时**更新插件端（`src/crypto.js` 的 `_S` 数组）与教师端，
  两端不同盐会导致全班被判"签名失败"。配套的插件源码工程提供了一键轮换命令并带一致性门禁。
- 旧学期的文件必须用**旧盐**验证，请按学期保留对应版本的验证工具。
- 也可用环境变量覆盖私盐而不用改代码：`set SXLOG_SALT=你的盐` 后再运行。

## 环境要求

- Python 3.8+（Windows 上建议使用自带 tkinter 的官方 Python，右键弹窗与图形界面依赖它）
- 只依赖标准库：`hashlib / hmac / difflib / json / csv / tkinter / winreg`

## 命令速查

| 命令 | 说明 |
|---|---|
| `sxlog-teacher install-hook` | 注册文件夹右键菜单（HKCU，免管理员） |
| `sxlog-teacher uninstall-hook` | 删除右键菜单 |
| `sxlog-teacher status` | 查看右键菜单注册状态并回读校验 |
| `sxlog-teacher verify <路径>` | 命令行批量验证 |
| `sxlog-teacher gui [目录]` | 图形化批量验证 |
| `sxlog-teacher doctor` | 环境自检 |
| `sxlog-teacher hook-run <路径…>` | 右键菜单实际调用的入口（支持多选文件夹） |

## 关于"能否自动解密"

学生的记录文件（`.txt`）**不是加密文件**，而是"可读内容 + 签名保护"：正文是明文 JSON 的 base64，
教师端验证的是一次性验签与验链，不需要也不应该"解密"。这样设计有两个好处：
① 出现争议时任何一方都能直接查看原文，不需要密钥；
② 伪造成本远高于诚实提交（缺私盐无法重签）。验证过程全部在本地离线完成，不联网。
