Metadata-Version: 2.1
Name: sxlog-student
Version: 1.0.7
Summary: 一键安装超星 AI 交互记录插件：探测默认浏览器、写入学号姓名、自动准备扩展目录，并带完整的加载状态诊断（status / repair）。
Home-page: https://pypi.org/project/sxlog-student/
Author: 吴振谦（宁波大学科学技术学院）
Maintainer: 吴振谦（宁波大学科学技术学院）
License: LicenseRef-Proprietary
Keywords: chaoxing,超星,extension,chrome,edge,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-student/
Description-Content-Type: text/markdown

# SXLOG 学生端 · 超星 AI 交互过程记录助手

> **一句话**：把「学生与 AI 的交互过程」如实记录下来，导出一份带防篡改校验的 `.sxlog` 文件，
> 由学生本人提交、教师端独立验证 —— **数据全程不离开学生自己的电脑**。

当作业允许使用 AI 时，教师需要看到的不只是最终答案，还有**抵达答案的过程**：
你问了什么、AI 回了什么、哪些内容是你自己敲的、哪些是从别处粘贴进来的。
一份纯由 AI 生成后粘贴的报告，和一份反复追问、甄别、修改后形成的报告，
看最终文件可能一模一样 —— 本工具就是为让后者的过程**留下证据**而做的。

**作者**：吴振谦 · 宁波大学科学技术学院（详见 [作者与项目信息](#作者与项目信息)）

---

## 快速了解

| 项目 | 说明 |
|---|---|
| **做什么** | 记录学生在超星平台内的 AI 提问与回复、打字与粘贴行为、页面点击与会话过程 |
| **给谁用** | 允许使用 AI 的课程作业、项目实践、过程性评价 |
| **跑在哪** | 学生本机：Windows + Chrome / Edge（Chromium 系，Manifest V3） |
| **数据去哪** | **只在学生浏览器本地**，不存在任何服务器；由学生本人导出并提交给教师 |
| **凭什么可信** | 哈希链 + HMAC 签名 + 行为取证 + 跨文件设备查重（定位见下方「诚实说明」） |
| **配套组件** | [`sxlog-teacher`](https://pypi.org/project/sxlog-teacher/) —— 教师端批量验证与班级汇总 |

---

## 它是什么，不是什么

| 它是 | 它不是 |
|---|---|
| 一个**过程留痕**工具：记录你与 AI 的交互，供作业评价参考 | ❌ 不是考试监控软件，不截屏、不录屏、不采集其它网站 |
| 数据**只在你本机**浏览器里，由你决定何时导出 | ❌ 不会后台上传、不会联网回传任何内容 |
| 支持自检：你可以自己验证记录有没有被改动 | ❌ 不是绝对防作弊方案，它的定位是**让作弊成本远高于自己做** |

---

## 作者与项目信息

| 项目 | 信息 |
|---|---|
| **作者** | **吴振谦**（Wu Zhenqian） |
| **单位** | **宁波大学科学技术学院** |
| **教学场景** | 《电子系统项目开发与实践》等课程的过程性评价与作业追溯 |
| **项目定位** | 教学用途工具，遵循「最小必要采集」原则；非商业软件 |
| **配套包** | `sxlog-teacher`（教师端：验签、验链、行为取证、班级汇总） |
| **许可** | 教学用途专有许可（LicenseRef-Proprietary） |

**这个工具为什么会出现**

在允许使用 AI 的作业与项目实践中，评价的难点从「做得对不对」变成了
「**过程是否真实、思考是否发生在学生身上**」。仅看最终提交的文件，无法区分
「学生主导、用 AI 做辅助」与「AI 生成、学生只做搬运」这两种情形，
而这两者的教学意义完全不同。本工具提供的是**可验证的过程证据**：
它不评价好坏，只如实记录发生了什么，把判断权留给教师。

**技术路线**

插件端（浏览器扩展，采集与本地留存）+ 工具端（Python，安装、诊断、验证）。
采集范围严格限定在超星域名内，记录进入哈希链后由教师持有的密钥签名；
教师端可离线完成验签、验链、行为取证与跨文件查重。
设计取舍、失败模式与已知局限均如实写在下文，不夸大防护强度。

---

## 功能

- **提问与回复留痕**：记录你在超星里向 AI 提出的问题、AI 的回复内容与响应时长
- **作答捕获（含单字符答案）**：键盘输入、回车/点击发送/点击选项/输入框清空等触发方式，击键数与节奏特征
- **页面点击**：记录你点击了什么（元素文本 / aria-label / 类名 / 位置路径），点击选项作答会被识别为一次作答
- **粘贴/复制行为**：区分「自己打字」与「从外部 AI 复制粘贴」——两者在报告里都会被如实标注
- **只记录当前激活的标签页**：切到别的标签页后自动暂停，不会记录后台页面
- **防篡改**：每条记录都进哈希链，导出时整体 HMAC 签名，改动任何一处都会被验出
- **设备指纹短码**：导出时在文件末尾附一段 ≤100 字节的本机标识，用于区分不同学生的提交
- **文件名自动命名**：`学号_AI工具名_日期.sxlog`，避免交上来一堆「未命名.sxlog」
- **本地自检**：导出前自动校验哈希链完整性，异常会中止导出而不是交出坏数据

---

## 安装

需要 Python 3.8 或更高版本（建议从 [python.org](https://www.python.org/) 安装官方版本）。

```bash
pip install sxlog-student
```

然后运行：

```bash
sxlog-student
```

首次运行会弹出一个窗口，让你填写**学号、姓名**（可选填课程/班级），并确认知情同意。
填完它会自动完成后续步骤。

> **如果 `sxlog-student` 提示找不到命令**，改用：`python -m sxlog_student`
>
> **如果弹不出窗口**，说明你的 Python 缺少 tkinter（部分精简安装包会这样），
> 工具会自动改用命令行问答，功能完全一样。

---

## 一分钟上手

安装完成后，你会看到它做了这些事：

1. **探测你的默认浏览器**（Chrome 或 Edge），并把插件复制到一个固定目录
2. **写入你的学号姓名**，插件第一次启动时会自动读取，你不需要再手填
3. **在桌面留一份可见副本**：`超星AI记录插件（装插件时选这个文件夹）`
4. **把插件目录放进剪贴板**，并**自动打开扩展管理页**
5. 生成一份《使用说明.txt》放在插件目录旁边

接下来：打开浏览器 → 地址栏输入 `chrome://extensions`（Edge 是 `edge://extensions`）→
打开右上角「开发者模式」→ 点「加载已解压的扩展程序」→ 在文件夹选择框里按 `Ctrl+V` → 回车。

看到「AI交互过程记录助手（超星）」这张卡片就成功了，**以后永久有效**。

> 为什么要手动点这几下？因为 Chrome 从 137 版起**禁止第三方工具自动安装插件**
> （该能力长期被恶意软件滥用）。这是浏览器的安全设计，任何工具都绕不过去。
> 本工具的作用是把「找目录、填信息、配环境」这些麻烦事全部做完，只留最后一步给你。

---

## ⚠️ 装完在浏览器里看不到插件？

**先跑这两条命令，不要自己猜：**

```bash
sxlog-student status     # 看状态：加载了没、能不能自动加载、有没有异常
sxlog-student repair     # 一站式分诊：按证据告诉你是哪类问题、该怎么修
```

`status` 会检测一类**在浏览器界面上完全看不出来**的故障：浏览器被带着下面这样的参数启动。

| 参数 | 后果（都是静默的） |
|---|---|
| `--disable-extensions-except` | **禁用白名单之外的所有扩展**，包括你刚加载好的那个 → 表现为「加载了却看不到」 |
| `--load-extension`（Chrome ≥137） | 被**直接忽略**，插件根本没加载，但浏览器看起来一切正常 |

这类问题只能从进程命令行里看出来，扩展页不会有任何提示。一旦发现，
`status` 会直接打印修法（通常是**完全退出浏览器后正常重开** —— 加载记录往往已经写好了）。

**三个常见小情况：**

- 扩展页要按 **F5 刷新**才会显示新加载的扩展
- 「开发者模式」必须**开着**，关闭时开发者扩展会被隐藏
- Chrome 和 Edge 的扩展互不相通，在哪个浏览器里加载的，就要在哪个浏览器里用

**最快的自证方法**：打开超星 AI 页面，右下角会出现浮标；**看到浮标就说明插件在工作**。

---

## 命令一览

| 命令 | 作用 |
|---|---|
| `sxlog-student` | 安装并启动（默认行为） |
| `sxlog-student status` | 查看安装与加载状态（看不到插件时**先跑这个**） |
| `sxlog-student repair` | 一键排查并修复「看不到插件」 |
| `sxlog-student start` | 已装过，只启动浏览器 |
| `sxlog-student where` | 显示插件与配置目录的实际位置 |
| `sxlog-student doctor` | 环境自检（浏览器探测、tkinter、权限等） |
| `sxlog-student guide` | 打开使用说明所在目录 |
| `sxlog-student uninstall` | 删除插件文件与配置目录 |

**常用参数**

| 参数 | 说明 |
|---|---|
| `--sid 2024030118 --name 张三` | 非交互安装（供批量部署脚本调用） |
| `--yes` | 视为已同意记录范围（配合 `--sid/--name` 使用） |
| `--browser edge` | 强制指定浏览器 |
| `--mode sxlog` | 用独立浏览器配置启动（零点击加载插件，详见下节） |
| `--no-launch` | 只安装，不启动浏览器 |

### 想完全不用点那几下？

```bash
sxlog-student start --mode sxlog
```

它会用一个**独立的浏览器配置**启动，并通过调试通道自动加载插件 —— 不用找目录、不用点击。
代价是：那个窗口需要登录一次超星，而且**浏览器完全退出后需要再跑一次这条命令**
（命令行加载是会话级的，这是浏览器的机制，不是本工具的缺陷）。

想一次搞定、永久免操作，仍然推荐前面的手动加载一次。

---

## 记录什么，不记录什么

**会记录**（仅在超星域名内，且必须你点了「开始记录」之后）

| 类别 | 具体内容 |
|---|---|
| **你的作答** | 键盘输入内容（含单字符答案如 A/B/C/D）、触发方式（回车 / 点击发送 / 点击选项 / 输入框被清空）、击键数、平均击键间隔、输入法组合次数 |
| **页面点击** | 你点击的元素：可见文本 / aria-label / 类名 / CSS 路径 —— 用于还原完整操作过程（同目标 1.5 秒内去重、每秒最多 5 条，避免刷屏） |
| AI 的回复 | 回复正文、字符数、响应时长、是否为流式输出 |
| 剪贴板行为 | 粘贴的内容与长度、复制的内容与来源 |
| 页面与会话 | 进入/切换页面、标签页是否在前台、会话开始与结束、你点击开始/暂停记录的时刻 |
| 设备标识 | 一段 ≤100 字节的本机特征短码（时区、屏幕、语言、平台等 + 随机安装 ID 的哈希） |

**不会记录**

- ❌ 超星域名之外的任何网站
- ❌ 账号密码、Cookie 等任何凭据
- ❌ 屏幕截图、摄像头、麦克风
- ❌ WebGL / Canvas / 字体指纹（**刻意不采集**：唯一性由随机安装 ID 提供，隐私代价小得多）
- ❌ 空白区域的点击（既无文本也无 aria-label / 类名，没有可描述的信息）
- ❌ 后台标签页的任何内容（切走即暂停）

**数据的去向**：全部保存在你浏览器的 `chrome.storage.local` 里。
只有当你点击「导出」时，才会生成一个文件下载到你的电脑，由你本人上传给老师。
工具**没有任何联网回传逻辑**。

### 关于「只记录当前激活的标签页」

插件只在**当前可见（激活）的标签页**产生记录。你切到别的标签页时：

- 页面内容不再被扫描，也不再产生记录（省电、省内存，也避免记录你看不到的内容）
- **例外**：你提问后立刻切走、AI 回复仍在流式生成的情况仍会被记录 —— 那属于真实交互
- 回到前台时，会补记一条状态：**离开了多久、期间有多少事件因不在前台而未记录**

最后这条很重要：教师端会看到「期间 N 个事件未记录」，而不会把你离开的时间误读成
「这段时间什么都没做」。**数据的诚实比数据的连续更重要。**

---

## 为什么记录是可信的

| 机制 | 作用 |
|---|---|
| **哈希链** | 每条记录都包含前一条的哈希；改动任何一条，后续全部对不上 |
| **HMAC 签名** | 导出时用教师持有的密钥对整份文件签名；学生无法伪造（签名密钥不在插件里） |
| **本地自检** | 导出前自动验证链路完整性，异常则中止导出 |
| **跨文件查重** | 教师端可发现「同一份记录交给多人」与「同一台设备提交不同学号」 |
| **行为取证** | 粘贴占比、零击键长文、AI 回复到提交的时间间隔等，构成独立于密码学的第二道防线 |

> **诚实说明**：这是一套「提高作弊门槛」的方案，不是绝对防护。
> 插件代码需要分发到学生机器上，理论上可被逆向。请把它的定位理解为
> **让如实记录成为最省事的选择**，而不是考试级监控。

---

## 权限说明

插件申请的每一项权限都对应具体功能，没有多余申请：

| 权限 | 用途 |
|---|---|
| `storage` / `unlimitedStorage` | 在本机保存记录（长会话可能积累较多内容） |
| `downloads` | 导出 `.sxlog` 文件时触发下载 |
| `offscreen` | 在后台用 Blob 方式生成下载文件（比 data URL 更可靠） |
| `alarms` | 定时把内存中的记录落盘，避免浏览器崩溃丢数据 |
| 站点访问 `*://*.chaoxing.com/*` | 仅在该域名内注入采集脚本，**不申请任何其它站点权限** |

---

## 常见问题

**Q：装完之后超星页面上没有浮标？**
A：先确认插件已加载（跑一次 `sxlog-student status`），再刷新超星页面。
浮标只会在超星域名内出现，且默认**不记录** —— 需要你点浮标里的「开始记录」。

**Q：为什么提示「尚未配置」？**
A：需要先填学号姓名并勾选知情同意（安装时已自动写入，若被跳过可点「打开设置」补填）。

**Q：我换了浏览器 / 重装了系统怎么办？**
A：重新跑一次 `pip install sxlog-student && sxlog-student` 即可。
已导出的 `.sxlog` 文件不受影响（它是独立文件）。

**Q：能把我导出的文件改一改再交吗？**
A：可以改，但改动会被教师端验出。这正是哈希链与签名存在的意义。

**Q：升级后旧记录还在吗？**
A：在。但如果你打算重新开始，建议在插件设置页点「清空本机记录」，
避免把升级修复前产生的无效数据一起交上去。

**Q：我点选项/点按钮，会被记录吗？**
A：会。每次点击都会记下"点了什么"（元素文本 / aria-label / 类名 / 位置路径），并且**点击作答**（如选项 A/B/C/D、对/错、数字）会额外记一条作答记录 —— 这类页面常常不打字，只点击，所以点击路径是还原过程的关键信息。

**Q：只输入一个字母（比如答题选 A）也会被记录吗？**
A：会。单字符也是合法作答，插件对这类输入有专门的兜底捕获，不会因为"太短"而漏记。

**Q：记录会不会拖慢浏览器？**
A：不会。采集只在超星页面运行，事件驱动 + 节流，且标签页不在前台时完全停止扫描。

---

## 配套教师端

教师端是另一个独立安装包（**不在本文档所述的学生包里**）：

```bash
pip install sxlog-teacher
sxlog-teacher install-hook
```

安装后，**右键装着学生作业的文件夹**即可批量验证，输出班级汇总报告（HTML + CSV），
包含每人风险等级、粘贴占比、设备指纹与跨文件查重结果。

---

## 卸载

```bash
sxlog-student uninstall
```

然后到 `chrome://extensions` 里移除那张扩展卡片。
已导出到磁盘的 `.sxlog` 文件不会被删除，需要你手动处理。

---

## 环境要求

| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11（主要支持）；macOS / Linux 可手动加载插件 |
| Python | 3.8 或以上 |
| 浏览器 | Chrome 或 Edge（Chromium 系，Manifest V3） |
| 网络 | 安装时需要联网（从 PyPI 下载）；**使用过程中不需要** |

---

## 版本策略

- **插件与工具包版本独立但配套**：升级学生端工具后，建议同时在扩展页点一次「重新加载」
- **签名密钥每学期轮换**：教师会随学期发布新版本，学生自动获得新配置
- **旧学期文件用旧密钥验证**：历史数据始终可以复核

---

## 许可与说明

本工具为教学用途开发（作者：吴振谦，宁波大学科学技术学院）。
记录与验证的设计遵循「最小必要采集」原则：只采集评价所必需的交互信息，
不采集与评价无关的个人数据；所有数据默认本地留存，由学生本人决定提交内容。

遇到问题时，请把 `sxlog-student status` 的输出提供给任课教师，绝大多数问题能据此定位。
