腾讯问卷作业收集与自动批改流水线 (tencent-homework-pipeline)

学生作业「腾讯问卷收集 → 本地自动批改 → 腾讯文档成绩表」全流程 Skill v1.0。从 104 人 LaTeX 课程（科技论文写作基础 B0703063）的完整实战中沉淀，所有坑位都已踩过并给出绕法。

定位

为高校教师（尤其是 LaTeX 类课程、分组提交场景）提供一条已被实战验证的作业收集与批改路径：收集端只做"收"（腾讯问卷文件题），知识库只做"给资料"（ima 检索问答），批改在本地做（脚本不受平台格式限制）——三者各归各位。

核心能力

• 平台选型速查：ima / 腾讯文档收集表 / 腾讯问卷三平台能力边界实测结论（ima 协作成员上限 50 人且作业互见、收集表不支持 zip、问卷文件题白名单含 zip）
• 六阶段流程：需求澄清 → 名单建成绩册 → 建问卷 → 收集导出 → 本地自动批改 → 成绩写回
• 批改脚本：grade_homework.py（v3 规则，104 人实战版）——zip 组员解析、GBK 中文文件名兼容、四维度评分 + 兜底、异常状态标记、内置 4 组边界样例自检
• API 边界实录：腾讯问卷 API 能做什么/做不了什么（文件题必须网页端手工加、空白问卷无法接口加题）、腾讯文档写入坑位（前导零保真、先 schema 后 call、写入必回读）
• 成绩册工程规范：学号 STRING 保真、按学号定位覆盖（绝不按姓名、绝不追加行）、写入后回读校验

目录结构

tencent-homework-pipeline/
├── SKILL.md                        # 智能体主定义（六阶段流程 + 决策点）
├── scripts/
│   └── grade_homework.py           # 本地自动批改脚本（依赖 pypdf、openpyxl）
├── references/
│   ├── platform-matrix.md          # 平台选型矩阵与证据
│   ├── survey-api-notes.md         # 腾讯问卷 API 能力边界实测
│   └── tdocs-pitfalls.md           # 腾讯文档在线表格写入坑位
└── README.md

安装使用

1. 将本仓库下载或克隆到本地；
2. 把整个文件夹放入你的智能体平台技能目录（如 WorkBuddy 的 ~/.workbuddy/skills/tencent-homework-pipeline/）；
3. 对话中使用触发词唤起：作业收集、作业批改、成绩册、问卷收作业、组长上传、评分细则、缺交兜底等；
4. 批改脚本单独可用：python scripts/grade_homework.py --selftest 先自检，再传 --roster（名单）、--deadline（截止时间）、--dir（提交目录）批改。

适用与不适用

• 适用：高校课程作业收集与批改，尤其是 LaTeX 作业（.tex 源文件）、分组提交（组长收齐打包上传）、成绩需落腾讯文档在线表
• 不适用：学校已有教务系统 / Canvas 类 LMS（现成平台自带查重和成绩册）；单人非分组且只交 Word/PDF 的简单场景（收集表即可）

隐私说明

本技能包不含任何学生数据：无名单文件、无真实姓名与学号，文档与脚本中的「张三/李四」「07125101」均为示例占位，自检样例为程序合成。学生名单（--roster）由教师在使用时于本地临时提供，全程只写入教师自己的腾讯文档，不经过任何第三方存储。

已知局限

1. 数学正确性按论文页数评 = 评篇幅不评对错（作者知情选定，脚本预留 LLM 语义评分切换位）
2. 兜底规则（未交 60 / 已交最低 80，可参数化）会把分数压缩在 80-100 区间
3. 全自动批改建立在"评分规则全部可正则/可计数"之上；需语义判断时架构为脚本结构分 + LLM 语义评 + 教师复核

版本

版本	说明
v1.0.0	初版：六阶段流程 + v3 批改脚本 + 三平台选型实测 + 3 份参考文档（2026-09-03，104 人 LaTeX 课程实战沉淀）

许可证

MIT © 2026 关秀翠 (XiucuiGuan)

本技能基于腾讯 WorkBuddy 女娲/达尔文工作流创作优化；平台能力结论基于腾讯问卷 / 腾讯文档 / ima 2026 年实测。