homework-template/README.md

phomework - 作业模板系统

使用 Typst 和 AI 辅助生成作业的自动化工具。

目录结构

├── data/              # 作业数据（图片、题目、答案）
├── templates/          # Typst 模板文件
├── scripts/           # Python 脚本
│   ├── img2typ.py     # 图片转 typst 格式
│   ├── fix_typ.py     # 修复 typst 语法
│   ├── solve.py       # AI 答题
│   ├── gen_index.py   # 生成 index.typ
│   └── common.py      # 共用模块
├── index.typ          # 生成的作业文件
└── index.pdf          # 编译后的 PDF

工作流程

1. 图片转题目 (just img2typ)

   • 扫描 data/ 中的图片
   • 使用 AI 将图片内容转换为 typst 格式
   • 生成 questions.json 题目列表

2. AI 答题 (just solve)

   • 读取 questions.json
   • 调用 AI 生成答案
   • 输出 data/A_*.md 答案文件

3. 生成作业 (just generate)

   • 读取题目和答案
   • 生成 index.typ
   • 可编译为 PDF

快速开始

1. 准备数据

将作业图片放入 data/ 目录，文件名格式：

• P15.png - P15 题目
• R7.png - R7 题目
• P40_img1.png - P40 的附件

2. 配置

API 配置从以下位置按优先级读取：

1. scripts/.env (本地)
2. ~/.config/phomework/.env (全局)

方式一：全局配置（推荐）

mkdir -p ~/.config/phomework
cp scripts/.env.example ~/.config/phomework/.env
# 编辑 ~/.config/phomework/.env

方式二：本地配置

cp scripts/.env.example scripts/.env
# 编辑 scripts/.env

.env 文件内容：

# API 端点（OpenAI 兼容）
IMG2TYP_API_ENDPOINT=https://api.openai.com/v1/chat/completions

# API 密钥
IMG2TYP_API_KEY=your-api-key-here

# 模型名称（默认 qwen-vl-plus）
IMG2TYP_MODEL=qwen-vl-plus

3. 运行

just img2typ  # 图片转题目
just solve    # AI 答题
just generate # 生成 index.typ
typst compile index.typ index.pdf

如需修复 .typ 文件语法（可选）：

just fix

命令行参数

fix_typ.py

-f, --file      # 指定单个 .typ 文件
--dry-run       # 干跑，不调用 AI 或写入文件
--verbose       # 调试日志
-n N            # 并发数（默认 3）

img2typ.py

-f, --file      # 指定单个图片文件
--dry-run       # 干跑，不调用 AI 或写入文件
--verbose       # 调试日志
--retry N       # 重试次数（默认 3）
-n N            # 并发数（默认 3）

solve.py

-q, --question  # 指定题目 ID
--dry-run       # 干跑
--verbose       # 调试日志
--retry N       # 重试次数（默认 3）
-n N            # 并发数（默认 3）

gen_index.py

--dry-run       # 预览生成内容
--force         # 强制覆盖 index.typ

开发

# 安装依赖
pip install requests python-dotenv rich aiohttp

# 代码检查
ruff check scripts/
ruff format scripts/