智慧树自动化学习脚本常见异常排查与修复指南
一、 运行环境与依赖配置异常
1. 解释器版本冲突
故障现象：执行自动化脚本时，控制台抛出 SyntaxError 或提示找不到特定标准库。
修复方案：该工具链要求 Python 3.7 或更高版本。建议通过以下指令验证当前环境的解释器版本：
python3 -c "import sys; print(f'当前版本: {sys.version_info.major}.{sys.version_info.minor}')"2. 第三方库缺失或安装中断
故障现象：启动时触发 ModuleNotFoundError: No module named 'xxx'。
修复方案：使用 pip 模块重新构建依赖环境。为提升下载速率，建议指定国内云厂商的 PyPI 镜像：
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/二、 网络通信与鉴权障碍
1. 接口请求超时或连接重置
故障现象：日志中频繁出现 ReadTimeout 或 ConnectionRefusedError。
修复方案：
- 验证本地网络连通性及目标平台服务器的可用性。
- 若处于受限网络环境，需在
network/config.py中注入 HTTP/HTTPS 代理节点。
图：核心 API 请求载荷结构，包含 courseId 与 uuid 等鉴权字段。
2. 图形验证码自动化识别失效
故障现象：登录阶段无法绕过图形验证，导致流程中断。
修复方案：
- 检查
captcha/ocr_engine.py中的模型权重是否过期，必要时重新拉取最新模型。 - 在配置文件中开启
manual_captcha_fallback = True，允许在自动识别失败时降级为人工干预模式。
三、 会话状态与课程数据同步问题
1. 身份认证被拒绝
故障现象：凭证无误，但接口返回 401 Unauthorized 或提示登录态失效。
修复方案：
- 排查目标账号是否触发了异地登录保护或设备指纹风控。
- 清理本地持久化的 Cookie 与 Token 缓存，强制重新获取会话：
import os
import shutil
cache_dir = os.path.expanduser("~/.zhs_automation/session_cache")
if os.path.exists(cache_dir):
shutil.rmtree(cache_dir)
print("会话缓存已清除")2. 课程列表拉取为空或进度停滞
故障现象：控制台输出"未检测到有效课程"或学习时长未累加。
修复方案：
- 校验
config/courses.json中的课程标识符是否准确。 - 确保
crypto/api_decrypt.py中的解密逻辑与平台最新接口匹配。 - 附加
--force-sync参数以忽略本地缓存，强制从服务端拉取最新课程树：
python3 main.py --force-sync
图：服务端响应头分析，HTTP 200 状态码表明数据拉取请求已成功处理。
四、 核心执行逻辑与逆向解析异常
1. 心跳包发送阻塞
故障现象：学习进度百分比长时间无变化，心跳接口无响应。
修复方案：
- 审查
utils/signature.py中的请求签名生成算法，确认时间戳与盐值拼接规则未被平台修改。 - 调高日志输出等级，捕获底层 HTTP 客户端的详细交互过程：
import logging
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)2. 前端混淆脚本解析崩溃
故障现象：抛出 JSDecryptionError 或无法提取关键的加密参数。
修复方案：
- 同步
reverse/js_deobfuscator.py中的 AST（抽象语法树）还原规则。 - 清空本地存储的混淆代码缓存，防止读取到旧版脏数据：
find ./cache/js_snapshots -type f -name "*.js" -delete
图：平台前端高度混淆的 JavaScript 代码片段，需通过 AST 转换进行逆向还原。
五、 进阶配置与运维问答
Q: 自动化行为是否会触发平台的风控系统？
A: 脚本内置了随机休眠与鼠标轨迹模拟机制以拟合真人行为。建议在 settings.yaml 中调大 min_interval 参数，避免高频并发请求导致 IP 被封禁。
Q: 如何将本地代码库与上游仓库保持同步？
A: 推荐使用硬重置方式覆盖本地修改，并重新构建依赖环境：
git fetch origin
git reset --hard origin/main
python3 -m pip install -r requirements.txt --upgradeQ: 是否支持多课程并发处理？
A: 支持。在 config/courses.json 的 target_ids 数组中填入多个课程 ID 即可实现队列化或并发执行。
