QQ群作业整理

QQ群作业整理（QQGroupHomeworkSummarizer）

将 QQ 群「群作业」中某一天的内容（文字 + 图片）抓取出来，自动排成一页 A4 的 Word 文档， 并按需发送到邮箱或微信。

适用场景

• 整理某一天（或某段时间）的群作业成文档
• 导出作业并保留老师上传的图片附件
• 把作业文档发到邮箱或微信

核心约束（务必先理解）

接口细节、参数、返回结构见 references/api.md。

---

流程

0. 环境准备（首次）

# ⚠️ 必须指定官方源：国内镜像常滞后，装到旧版会直接导致协议不兼容
pip install --index-url https://pypi.org/simple --upgrade qqbrowser-skill
qqbrowser-skill install          # 安装/校验 QQ 浏览器本体
pip install python-docx pillow   # 文档生成依赖

qqbrowser-skill serve --daemon   # 启动 daemon
qqbrowser-skill status           # 确认 Daemon is running 且 Connected clients: 1

1. 探测 bkn 并确认登录 ⏸️ 需人工介入

python scripts/qq_hw.py bkn --gid <群号>

• 成功 → 输出 bkn = xxxxx，自动写入 qq_hw.json
• 提示未探测到 bkn → 浏览器内未登录 QQ：
  1. 告知用户："请在弹出的 QQ 浏览器窗口中登录 QQ（扫码即可）"
  2. 保持会话等待，不重试、不切换方案
  3. 用户确认登录后，重新执行本命令

2. 拉取作业列表

python scripts/qq_hw.py list --size 100      # → hw_list.json

3. 拉取指定日期详情（含图片 URL）

python scripts/qq_hw.py day 2026-05-11       # → hw_day_2026-05-11.json

列表过期时加 --refresh。

4. 生成单页 docx

python scripts/qq_hw.py docx 2026-05-11      # → 作业_2026-05-11.docx

5. 校验页数（必做）

python scripts/qq_hw.py pages 作业_2026-05-11.docx

• PAGES=1 → 完成
• PAGES=2 → 加大 --scale（默认 1.15，试 1.3～1.5）后重新生成：

python scripts/qq_hw.py docx 2026-05-11 --scale 1.4

---

排版规范

单页约束的关键：必须在样式层把 Normal / Heading 2 / List Number 的 space_before/after 归零、line_spacing 设为 1.0（样式自带 1.15 倍行距会撑到第二页）； 页边距 0.8cm；表格单元格边距清零。

---

发送

邮箱（Agent Mail 连接器）

1. mcp__agent-mail__upload_attachment(file_path)  →  file_id
2. mcp__agent-mail__SendMessage(to, subject, body, file_refs=[{file_id}])

⚠️ 发信会返回 CONFIRMATION_REQUIRED：必须先向用户展示收件人 / 主题 / 附件并征得明确同意， 再带 confirmation_token 重试。严禁未经确认自动发送。

微信（企业微信 wecom 连接器）

加载 wecomcli-message skill 发送消息；需先上传文件时用 wecomcli-media 换取 media_id。

---

脚本

scripts/qq_hw.py 单入口，子命令：bkn / list / day / docx / pages。 scripts/count_pages.ps1 供 pages 子命令调用（需本机装有 Word）。

示例 Prompt

• 「把 <群号> 群 5月14日的作业整理成 Word，一页，发到我邮箱 xxx@xx.com」
• 「帮我把 QQ 群里今天的作业导成文档，图片要保留，然后微信发给我」
• 「某天的作业文档超过一页了，把图片缩小点重新生成」

故障排查

见 references/troubleshooting.md，覆盖： 会话协议不兼容、pip 镜像滞后、CLI 输出双重转义、Word COM 页数统计、单页约束失效等。