Metadata-Version: 2.4
Name: Xingyvan-Auto-Commenter
Version: 0.1.1
Summary: 自动批注docx作业
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docx2txt>=0.9
Requires-Dist: json-repair>=0.59.5
Requires-Dist: openai>=2.33.0
Requires-Dist: pywin32>=311
Dynamic: license-file

# 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`

```powershell
uv sync
```

### 方式 2：使用 `pip`

```powershell
pip install -e .
```

## 配置 API Key

PowerShell 示例：

```powershell
$env:DEEPSEEK_API_KEY="your_api_key_here"
```

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

## 使用方法

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

```powershell
xyhwk <作业目录>
```

示例：

```powershell
xyhwk .\homeworks
```

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

```powershell
python -m xingyvan_auto_commenter.main .\homeworks
```

## 输入与输出

输入：

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

输出：

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

例如：

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

## 当前处理流程

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

## 项目结构

```text
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`.
