添加 README

PRD_SCRIPT.md

@@ -1,66 +0,0 @@
-请在 `./scripts/` 文件夹下写一个 `img2typ.py` 脚本，达成下面的要求。
-
-## 流程
-
-遍历当前所在目录下的文件（不深入到子目录）。
-
-找到所有的 `\S\s?[\d\.]+` 的文件名的图片。且最开头的 `\S` 不能是 `答` 或者 `A` 或者 `a`
-
-- 这里只是大概的描述，你可能需要调整正则，或者不使用正则
-- 例如，`问 13.png` `Q3.1.jpg` `R1.1.5.PNG` 等等的文件名都是合法的
-
-检测有没有对应的 `.typ` 文件。即，看有没有后缀名改成 `typ` 的文件。
-
-如果没有，则用 `./scripts/img2typ.prompt.txt` 为提示词，调用一个支持图片的 OpenAI 兼容 API。这个提示词文件在未来会改动，请在程序执行时动态读取它。API 的 API 端点和 API Key 应该使用一个 `.env` 文件定义，这个文件将会置放在 `./scripts/` 文件夹下。
-
-对输出结果，如果有 Markdown 代码块包裹，则去除（可能需要你写正则或者其他任何机制）
-
-接着，保存为对应的 `.typ` 文件。
-
-最后，整理所有符合条件的 `.typ` 文件（包括生成失败的），整理成一个列表后，在当前根目录写入（可覆盖）`questions.json`，是一个 JSON 列表，列表的每一个项目都是一个 JSON Object。形如：
-
-```json
-[
-    {
-        "question": "Q3.1",
-        "format": "typst",
-        "target": "Q3.1.typ"
-    },
-    {
-        "question": "R1.1.5",
-        "format": "typst",
-        "target": "R1.1.5.typ"
-    }
-]
-```
-
-## 细节
-
-调用 API 时，如果失败，则重试。最多重试 3 次（或者可定义），真的失败了不能 panic，只是在 stderr 中汇报。
-
-## 规范
-
-代码应该是人类可维护的。你可以（而且最好）使用 python 的比较常用的现代语法，例如直接的类型注解（使用 `list` 而不是 `typing.List`），以及尽量使用 `pathlib.Path` 而不是字符串。
-
-这个应用是面向过程的。你应该首先对流程做拆解，然后以子函数的形式声明整个函数。每个函数都应该有 docstring。对于 AI 等一些比较重要的东西，你再使用面向对象的方式去应对。
-
-你可以给我要求，让我依赖一些更多的外置库。当前环境有 `requests`、`dotenv`、`rich`、`tqdm` 可用。
-
-程序往 `stderr` 的输出应该是可审计的。应该汇报：
-
-- 将要处理的文件清单。
-- 调用了什么 API，调用情况如何，输入输出多少 tokens。
-- 写入了什么文件。
-
-程序往 `stderr` 的输出应该是良好可视化的，就是说，有颜色区分，但是不要加 emoji。或者说，你应该使用自带的日志库 + 一定的格式化。
-
-## 额外功能添补
-
-这个脚本应该可以作为 cli 调用，支持以下参数：
-
-- `--file` 或 `-f` 后接文件名，可重复这个参数。当存在这个参数，则解析对应的图片，而不是扫描当前目录
-- `--dry-run` 不调用 AI，也不写入文件
-- `--verbose` 在基础上反馈 AI 调用的输出，相当于 log level 是 `DEBUG`
-- `--retry` 接数字，重试次数，默认为 3
-- `-n` 接数字，并发数量，默认为 3
-

README.md

@@ -0,0 +1,96 @@
+# phomework - 作业模板系统
+
+使用 Typst 和 AI 辅助生成作业的自动化工具。
+
+## 目录结构
+
+```
+├── data/              # 作业数据（图片、题目、答案）
+├── templates/          # Typst 模板文件
+├── scripts/           # Python 脚本
+│   ├── img2typ.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. 配置
+
+```bash
+cp scripts/.env.example scripts/.env
+# 编辑 .env，填入 API 配置
+```
+
+### 3. 运行
+
+```bash
+just img2typ   # 图片转题目
+just solve     # AI 答题
+just generate  # 生成 index.typ
+typst compile index.typ index.pdf
+```
+
+## 命令行参数
+
+### img2typ.py
+```bash
+-f, --file      # 指定单个图片文件
+--dry-run       # 干跑，不调用 AI 或写入文件
+--verbose       # 调试日志
+--retry N       # 重试次数（默认 3）
+-n N            # 并发数（默认 3）
+```
+
+### solve.py
+```bash
+-q, --question  # 指定题目 ID
+--dry-run       # 干跑
+--verbose       # 调试日志
+--retry N       # 重试次数（默认 3）
+-n N            # 并发数（默认 3）
+```
+
+### gen_index.py
+```bash
+--dry-run       # 预览生成内容
+--force         # 强制覆盖 index.typ
+```
+
+## 开发
+
+```bash
+# 安装依赖
+pip install requests python-dotenv rich aiohttp
+
+# 代码检查
+ruff check scripts/
+ruff format scripts/
+```