📚 作业记录助手（通用版）

从班级群作业照片中识别作业内容，整理成按学科分类的可勾选清单，写入腾讯智能文档。支持多日期管理、进度查询。

> ⚠️ 首次使用必须完成初始化配置！ 详见下方「初始化流程」章节。

🚀 初始化流程（首次使用必读）

前置条件

已安装并配置 腾讯文档 MCP Server（tencent-docs）
账号已开通腾讯文档 超级会员（MCP API 调用需要）
已安装 Playwright + Chromium（用于读取勾选状态）

Step 1：创建或关联腾讯文档

首次使用时，询问用户以下信息：

📋 欢迎使用作业记录助手！

请提供以下信息完成初始化：

1. 📝 文档标题：（例如"小明作业记录本"，默认"作业记录本"）
2. 🔗 是否已有腾讯智能文档？
   - 有 → 请发送文档链接，我来获取 file_id
   - 没有 → 我帮你新建一个

Step 2：根据用户选择执行

情况 A — 用户有现有文档

从用户提供的链接中提取 file_id
用 smartcanvas.read 验证文档可访问
将配置写入本地配置文件

情况 B — 用户新建文档

使用 create_smartcanvas_by_mdx 创建新的智能文档
设置文档标题为用户指定的名称
将返回的 file_id 和文档链接保存到本地配置

Step 3：保存配置

将初始化结果写入配置文件（Skill 安装目录下的 config.json）：

> 配置文件位置：.workbuddy/skills/homework-tracker/config.json

> （与 SKILL.md 同目录，每个 workspace 独立一份）

{
  "doc_title": "作业记录本",
  "file_id": "用户的file_id",
  "doc_url": "https://docs.qq.com/aio/XXXXXX",
  "student_name": "",
  "initialized_at": "2026-04-17",
  "version": "2.0"
}

> 隐私说明：config.json 存储在用户本地 workspace 中，不会随 Skill 分享泄露。

Step 4：确认初始化完成

向用户展示：

✅ 初始化完成！

📄 文档标题：{doc_title}
🔗 文档链接：{doc_url}
📝 文档ID：{file_id}

现在可以：
• 发送作业照片 → 自动识别并写入文档
• 说"作业进度" → 查看勾选完成情况
• 说"更新作业" → 刷新最新进度

触发条件

当以下任一情况发生时，加载此技能：

用户发送了图片（疑似作业照片）
用户提到"作业"、"homework"、"更新作业"、"记录作业"
用户要求把照片中的内容整理到文档
用户要求查看/汇报作业完成情况

工作流程

Step 1：检查初始化状态

每次触发时，先检查配置文件是否存在：

✅ 配置存在 → 直接读取 file_id 等信息，继续后续流程
❌ 配置不存在 → 立即进入初始化流程（见上方），不要跳过！

Step 2：接收并识别图片

接收用户发来的作业照片（微信转发或直接发送）
如果用户一次发送多张照片，全部接收后合并处理
使用视觉模型读取并识别图片中的文字内容
提取以下信息：

日期：图片上是否有日期标注？
科目：语文/数学/英语/地理/历史/道法/生物/物理/化学等
作业内容：每项具体要做什么

Step 3：确认日期

图片上有明确的日期 → 直接使用该日期
图片上没有日期 → 主动询问用户："这是哪天的作业？"

Step 4：整理作业数据（多张合并）

将所有图片识别出的作业按科目汇总去重，然后按以下格式规范整理：

格式规范

| # | 规则 | 说明 |

|---|------|------|

| 1 | 标题 | 使用用户初始化时设置的文档标题 |

| 2 | 学科分类 | 按科目分组（语文/数学/英语等） |

| 3 | 科目标题格式 | ⚠️ 只能用 Markdown 双星号加粗！禁止 标签 |

| 4 | 序号规则 | 每天序号独立从1开始（不跨日期延续） |

| 5 | 日期排序 | 最新的日期在最上面（倒序排列） |

⚠️ 格式陷阱（踩坑经验）

科目标题格式（最重要！）

✅ 正确：<Paragraph>**📖 语文</Paragraph>
❌ 错误：<Paragraph><strong>📖 语文</strong></Paragraph>  ← 会原样显示标签文字！

日期排序铁律

⚠️⚠️ INSERT_BEFORE 的目标永远是文档第一个日期 Heading！
❌ 不要按"日历时间顺序"插在中间！（如4月15日在14日和13日之间是错的）
✅ 正确做法：新日期 → INSERT_BEFORE → 第一个日期的 Heading ID
💡 简单记忆法：越新的越在上面，像微信聊天记录一样倒序排列

MDX 内容示例

<Heading level="2">4月16日 作业</Heading>

<Paragraph>**🌍 英语**</Paragraph>
<Todo>1、背诵第1个听力文本</Todo>
<Todo>2、练习册U5SA-1</Todo>

<Paragraph>**📐 数学**</Paragraph>
<Todo>3、课练因式分解二</Todo>

<Divider />

Step 5：统计并向用户汇报

识别完成后，先汇报再写入：

📊 {日期} 作业统计
├── 📚 学科数：X 科
├── 📝 总项数：X 项
├── （如有多张照片）本次合并 X 张照片
└── 即将写入文档...

Step 6：写入腾讯文档

核心原则：始终在同一个文档上操作！使用配置文件中的 file_id。

操作方式

| 操作类型 | 方法 | 说明 |

|----------|------|------|

| 追加新日期 | smartcanvas.edit + INSERT_BEFORE | 在第一个日期标题前插入新日期 |

| 修改已有内容 | smartcanvas.edit + UPDATE | 修改指定 Block 的内容 |

| 🚫 禁止 | create_smartcanvas_by_mdx | 初始化之后绝对不能用来新建文档！ |

新增日期流程

用 smartcanvas.read 读取文档顶部，找到第一个日期 Heading 及其 ID
用 smartcanvas.edit + action=INSERT_BEFORE 在该 Heading 之前插入新日期数据
保留所有原有数据不变
用 smartcanvas.find 搜索 自检格式
更新时间戳 Block

Step 7：确认完成

向用户返回：

✅ {日期}作业已写入！

📋 本次操作：
├── 📸 图片识别：X科Y项
├── 📅 日期：{date}
├── 🔢 序号：1~N
├── 🏷️ 格式自检：✅ 通过
├── 📍 排序：最新在上
└── ⏰ 时间戳：已更新

👉 文档链接：{doc_url}

🔄 进度查询流程

当用户说"更新一下"、"查看作业"、"作业进度"、"更新作业"、"完成情况"时：

Step 1：确定查询日期

用户明确指定了日期 → 使用该日期
用户未指定 → 默认查当天，无记录则查最近日期 + 提示询问

Step 2：读取勾选状态

⚠️ smartcanvas/read/find/get_content 等 API 都无法返回 Todo 勾选状态！

唯一可靠方式：使用 Playwright 无头浏览器打开文档页面，从 DOM 提取 checkbox 的 checked 属性。

执行方式

用户需要在本地准备一个 Playwright 脚本（参考 references/playwright-guide.md），脚本需满足：

用 Playwright 打开 {doc_url}（来自配置文件）
等待页面渲染完成
从 DOM 中提取所有 .dui-checkbox-normal > input[type=checkbox] 的 checked 状态
将 checkbox 与对应的作业文本一一关联
输出结构化的完成情况

Step 3：报告模板

📅 {YYYY年M月D日} 作业进度

| # | 科目 | 作业内容 | 状态 |
|---|------|----------|:----:|
| 1 | 📖 语文 | xxx | ✅/⬜ |

├── 📚 学科数：X 科
├── 📝 总项数：X 项
├── ✅ 已完成：X 项
├── ⬜ 待完成：X 项
└── 📊 完成度：XX%

自检验证（每次报告后必做）

✅ 逐个点数已完成数量
✅ 逐个点数待完成数量
✅ 验证总和 = 总项数

🎨 学科图标对照表

| 科目 | 图标 | 备注 |

|------|------|------|

| 语文 | 📖 | |

| 数学 | 📐 | |

| 英语 | 🌍 | |

| 物理 | ⚛️ | |

| 化学 | 🧪 | |

| 生物 | 🧬 | |

| 历史 | 📜 | |

| 地理 | 🗺️ | |

| 政治/道法 | ⚖️ | |

| 音乐 | 🎵 | |

| 体育 | ⚽ | |

| 美术 | 🎨 | |

| 其他 | 📝 | 默认 |

⚠️ 注意事项与限制

必须具备的条件

| 条件 | 说明 |

|------|------|

| 视觉模型 | 必须使用支持图片理解的模型来识别手写作业照片 |

| 超级会员 | 腾讯文档 MCP API 调用需要账号开通超级会员 |

| Playwright | 读取勾选状态需要 Playwright + Chromium |

| 文档权限 | 文档需设为"所有人可查看"（方便手机端访问）|

腾讯文档不支持的功能

❌ 勾选后自动联动状态变化
❌ 颜色字体（font color / span style 不生效）
❌ 自动计算进度百分比公式
❌ 勾选后自动记录时间戳
❌ 导出功能（智能文档不支持 export_file）

API 使用注意

避免短时间内大量调用，可能触发速率限制
DELETE 操作后部分 block 会变为 disabled 状态，无法再次操作
find 搜索在新插入内容后可能需要短暂延迟才能索引到

家庭作业跟进器

概述