gaokao-volunteer-system/INSTALL.md

安装指南

📦 系统要求

必要环境

• 操作系统: Linux / macOS / Windows (WSL2)
• Python: >= 3.10
• Git: >= 2.0
• 磁盘空间: >= 500MB

推荐环境

• Python: 3.11+
• 操作系统: Ubuntu 22.04+ / macOS 14+
• 内存: >= 4GB

---

🚀 快速安装

方式1：直接克隆项目

# 进入项目目录
cd /home/long/project/gaokao-volunteer-system

# 确认目录结构
ls -la

方式2：复制到Skills目录（在Hermes中使用）

# 复制4个Skills到Hermes
ln -s /home/long/project/gaokao-volunteer-system/skills/gaokao-college-advisor ~/.hermes/skills/
ln -s /home/long/project/gaokao-volunteer-system/skills/gaokao-spec-checker ~/.hermes/skills/
ln -s /home/long/project/gaokao-volunteer-system/skills/zhangxuefeng-skillset ~/.hermes/skills/
ln -s /home/long/project/gaokao-volunteer-system/skills/gaokao-counselor-long ~/.hermes/skills/

方式3：复制脚本到可执行路径

# 创建软链接到 ~/.local/bin
ln -s /home/long/project/gaokao-volunteer-system/scripts/gaokao-checker ~/.local/bin/
ln -s /home/long/project/gaokao-volunteer-system/scripts/gaokao-quick-3min.py ~/.local/bin/
ln -s /home/long/project/gaokao-volunteer-system/scripts/gaokao-visual-report-v2.py ~/.local/bin/

# 确保可执行
chmod +x ~/.local/bin/gaokao-checker

---

🐍 Python依赖安装

安装必要包

# 基础依赖
pip3 install --user --break-system-packages \
    weasyprint \
    jinja2 \
    markdown

# 可选依赖（用于开发和测试）
pip3 install --user --break-system-packages \
    pytest \
    black \
    flake8

验证安装

# 检查Python版本
python3 --version

# 检查必要包
python3 -c "import weasyprint; print('weasyprint OK')"
python3 -c "import jinja2; print('jinja2 OK')"

# 检查脚本
which gaokao-checker
gaokao-checker --help

---

⚙️ 配置

1. 配置Hermes（可选）

如果你使用Hermes，需要确保Skills能被加载：

# 检查Hermes配置
hermes skills list

# 如果Skills未显示，可能需要刷新
hermes skills reload

2. 配置邮件（可选）

如果需要邮件发送功能：

# 配置环境变量
export QQ_EMAIL_PASSWORD="your-password"

# 或写入 ~/.bashrc
echo 'export QQ_EMAIL_PASSWORD="your-password"' >> ~/.bashrc

3. 配置浏览器（可选）

用于生成PDF：

# 安装wkhtmltopdf
sudo apt-get install wkhtmltopdf

---

🧪 验证安装

运行测试

# 进入项目目录
cd /home/long/project/gaokao-volunteer-system

# 运行自动化测试
python3 tests/test_all.py

# 预期输出：所有测试通过

手动测试

# 测试规范检查器
python3 ~/.local/bin/gaokao-checker tests/cases/hunan-578.md

# 测试可视化报告
python3 ~/.local/bin/gaokao-visual-report-v2.py

# 测试问卷
python3 ~/.local/bin/gaokao-quick-3min.py

---

🐛 常见问题

Q1: 找不到 gaokao-checker 命令

原因: 路径未添加到PATH

解决:

# 添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证
which gaokao-checker

Q2: pip3 install 失败

原因: 权限问题或系统包限制

解决:

# 使用 --user 参数
pip3 install --user weasyprint jinja2 markdown

# 或使用虚拟环境
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt

Q3: Skills 在 Hermes 中不显示

原因: Hermes 未扫描到

解决:

# 刷新Skills列表
hermes skills reload

# 或重启 Hermes

Q4: PDF 生成失败

原因: weasyprint 依赖缺失

解决:

# 安装系统依赖
sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0

# 重新安装 weasyprint
pip3 install --user --break-system-packages --force-reinstall weasyprint

Q5: Git 提交失败

原因: 身份未配置

解决:

git config user.name "Your Name"
git config user.email "your.email@example.com"

---

🔄 更新

更新项目

# 进入项目目录
cd /home/long/project/gaokao-volunteer-system

# 拉取最新代码（如果有远程仓库）
git pull

# 查看更新日志
cat CHANGELOG.md | head -50

更新依赖

# 更新Python包
pip3 install --user --break-system-packages --upgrade \
    weasyprint jinja2 markdown

---

📋 卸载

完全卸载

# 删除Skills软链接
rm ~/.hermes/skills/gaokao-college-advisor
rm ~/.hermes/skills/gaokao-spec-checker
rm ~/.hermes/skills/zhangxuefeng-skillset
rm ~/.hermes/skills/gaokao-counselor-long

# 删除脚本软链接
rm ~/.local/bin/gaokao-checker
rm ~/.local/bin/gaokao-quick-3min.py
rm ~/.local/bin/gaokao-visual-report-v2.py

# 删除项目目录
rm -rf /home/long/project/gaokao-volunteer-system

# 卸载Python包（可选）
pip3 uninstall weasyprint jinja2 markdown

---

📞 获取帮助

• 文档: TUTORIAL.md
• 开发: DEVELOPMENT.md
• 测试: python3 tests/test_all.py
• FAQ: FAQ.md

---

版本: v2.0
最后更新: 2026-06-11