Xingyvan-Auto-Commenter 0.1.1

自动批注docx作业

Xingyvan Auto Commenter

一个面向 .docx 课程作业的自动批注工具。

它会读取指定目录中的 Word 作业，调用大模型生成批注内容，再通过 Microsoft Word 的 COM 接口把批注写回文档，并输出一份新的“批注后”文件。

适用场景

• 批量处理学生提交的 .docx 作业
• 基于统一提示词生成英文评语
• 保留原始文档，另存带批注版本

当前提示词内容针对《中国海洋大学“语言：认知与文化”课程作业》做了定制，但代码结构也适合继续改造成别的课程批注工具。

功能概览

• 扫描目标目录中的 .docx 文件
• 使用 docx2txt 提取正文文本
• 调用 DeepSeek 接口生成结构化批注 JSON
• 使用 Word 批注功能把评语写入文档
• 输出 原文件名-批注后.docx

运行要求

• Windows 系统
• 已安装 Microsoft Word
• Python >= 3.11
• 可访问 DeepSeek API
• 已设置环境变量 DEEPSEEK_API_KEY

之所以要求 Windows + Word，是因为项目依赖 pywin32 和 Word COM 自动化接口来写入批注。

安装

方式 1：使用 uv

uv sync

方式 2：使用 pip

pip install -e .

配置 API Key

PowerShell 示例：

$env:DEEPSEEK_API_KEY="your_api_key_here"

如果希望长期生效，可以把它写入系统或用户级环境变量。

使用方法

项目在 pyproject.toml 中注册了命令：

xyhwk <作业目录>

示例：

xyhwk .\homeworks

也可以直接通过模块入口运行：

python -m xingyvan_auto_commenter.main .\homeworks

输入与输出

输入：

• 一个目录
• 目录下的 .docx 作业文件

输出：

• 在原文件同目录下生成新文件
• 文件名格式为 原文件名-批注后.docx

例如：

• 输入：essay1.docx
• 输出：essay1-批注后.docx

当前处理流程

1. 读取目录中的 .docx 文件
2. 提取全文文本
3. 请求模型生成形如 [{ "location": "...", "content": "..." }] 的批注数据
4. 在 Word 中定位包含 location 片段的段落
5. 为该段落添加批注
6. 另存为新文件

项目结构

xingyvan-hwk/
├─ README.md
├─ pyproject.toml
├─ uv.lock
└─ xingyvan_auto_commenter/
   ├─ main.py
   ├─ AutoCommenter.py
   └─ utils/
      ├─ AIAsker.py
      └─ DocxTool.py

各文件职责：

• xingyvan_auto_commenter/main.py：命令行入口，遍历目录并执行批注
• xingyvan_auto_commenter/AutoCommenter.py：组织“抽取文本 -> 调模型 -> 写回批注”的主流程
• xingyvan_auto_commenter/utils/AIAsker.py：封装大模型请求
• xingyvan_auto_commenter/utils/DocxTool.py：Word 文档读取与批注写入

注意事项

• 当前只处理传入目录第一层中的 .docx 文件，不会递归处理子目录。
• 批注定位依赖模型返回的 location 文本片段；如果片段不够稳定，可能出现无法命中或命中不准的情况。
• 程序会调用本机 Word 打开并另存文档，运行时请尽量不要手动干预这些 Word 进程。
• AIAsker.py 当前固定使用 https://api.deepseek.com 和模型名 deepseek-v4-pro。

适合后续补强的方向

• 增加命令行参数校验与 --help
• 支持递归扫描子目录
• 支持自定义模型、提示词和输出文件名
• 提升批注定位精度，避免整段批注
• 增加失败重试和日志输出

License

This project is licensed under the MIT License. See LICENSE.