\r \r

AI Question — 资料出题 Skill\r

\r 在含 run.py 的 QuizAI 仓库根目录 使用本 skill（FastAPI 刷题应用 + 本技能包）。\r \r

安装与路径\r

\r | 环境 | Skill 目录 |\r |------|------------|\r | ClawHub / OpenClaw（推荐发布源） | skills/ai-question |\r | Cursor | .cursor/skills/ai-question（联接至 skills/ai-question） |\r | Claude Code | .claude/skills/ai-question 或 ~/.claude/skills/ai-question |\r \r

• 下文命令均在仓库根目录执行，脚本路径统一为 skills/ai-question/scripts/。\r
• 发布到 ClawHub：clawhub skill publish skills/ai-question --slug ai-question --name "AI Question" --version \x3Csemver> --changelog "..."（需先 clawhub login）。\r
• 本地安装：clawhub install ai-question（安装到 workdir 的 ./skills/）。\r \r

四大功能\r

\r | 功能 | 命令标识 | 方式 |\r |------|----------|------|\r | 生成题库 | generate-question-bank | 对话框模型出题 + 脚本导出 |\r | 规范题库 | normalize-question-bank | scripts/normalize_question_bank.py |\r | 启动服务 | start-question-service | scripts/start_question_service.ps1 |\r | 暂停服务 | stop-question-service | scripts/stop_question_service.ps1 |\r \r 用户 @ 本 skill 或说明上述功能时，按对应章节执行。\r \r ---\r \r

1. 生成题库（generate-question-bank）\r

\r

目标\r

\r 根据用户上传的学习资料，由当前对话框中的模型阅读资料并出题，再导出为标准 Excel（格式见 reference.md）。\r \r

核心原则\r

\r

禁止调用 app/services/ai_generator.py 本地模板出题。 \r 必须由 Agent 在对话中阅读资料、生成题目 JSON，再用脚本导出 Excel。\r \r 详细规范见 generation-guide.md（执行本功能前必须先读）。\r \r

强规则\r

\r

1. 题目严格基于资料，不得编造\r
2. 题干不含「第 1 题」「第 2 题」等序号\r
3. 题型顺序：单选题 → 判断题 → 多选题\r
4. 解析紧扣资料，点明对错原因与核心知识点，不冗余\r
5. 判断题 A=正确、B=错误（固定顺序不打乱），解析与答案字母一致\r
6. 单选/多选导出时脚本会随机打乱选项（模型生成时可先把正确答案放 A）\r \r

工作流\r

\r

Task Progress:\r
- [ ] 读取 generation-guide.md\r
- [ ] 运行 extract_material.py 提取资料文本\r
- [ ] 在对话中阅读资料，按规范生成题库 JSON\r
- [ ] 将 JSON 写入 data/generated-bank.json（或用户指定路径）\r
- [ ] 运行 export_question_bank.py 导出 xlsx\r
- [ ] 确认输出文件存在、题量正确、题干无序号前缀\r
- [ ] 询问用户是否导入刷题系统；若确认，运行 import_bank_to_db.py\r
```\r
\r
### Step 1：提取资料\r
\r
```bash\r
python skills/ai-question/scripts/extract_material.py "资料.docx" -o data/material-extract.txt\r
```\r
\r
### Step 2：对话框模型出题\r
\r
Agent 阅读 `data/material-extract.txt`（或用户 @ 的文件），按 [generation-guide.md](generation-guide.md) 生成 JSON，写入：\r
\r
```\r
data/generated-bank.json\r
```\r
\r
### Step 3：导出 Excel\r
\r
```bash\r
python skills/ai-question/scripts/export_question_bank.py data/generated-bank.json -o "输出题库.xlsx"\r
```\r
\r
### Step 4：询问是否导入刷题系统\r
\r
Excel 导出成功后，**必须**询问用户：\r
\r
> 题库已生成。是否导入到刷题系统（写入本地数据库）？\r
\r
- **用户同意**：运行 `import_bank_to_db.py`（优先用 JSON，与 Excel 选项打乱一致）\r
- **用户拒绝**：结束，告知 xlsx 路径即可\r
\r
```bash\r
python skills/ai-question/scripts/import_bank_to_db.py data/generated-bank.json\r
```\r
\r
导入成功后告知：题库 ID、我的题库 `http://127.0.0.1:8000/banks`、刷题 `http://127.0.0.1:8000/practice/{id}`。若服务未启动，提示先执行 `start-question-service`。\r
\r
### 辅助脚本\r
\r
| 脚本 | 作用 |\r
|------|------|\r
| `extract_material.py` | 从 pdf/doc/docx/txt/md 提取文本 |\r
| `export_question_bank.py` | JSON → 规范 xlsx（含选项打乱、题型排序） |\r
| `import_bank_to_db.py` | JSON / Excel → 写入 `data/quizai.db` |\r
| `generate_question_bank.py` | 仅提取资料并提示后续步骤；或 `--json` 直接导出 |\r
\r
若 JSON 已生成，可一步导出：\r
\r
```bash\r
python skills/ai-question/scripts/generate_question_bank.py "资料.pdf" -o "输出.xlsx" --json data/generated-bank.json\r
```\r
\r
---\r
\r
## 2. 规范题库（normalize-question-bank）\r
\r
用户上传的文件**本身就是题库**但格式不规范时，运行：\r
\r
```bash\r
python skills/ai-question/scripts/normalize_question_bank.py "原始题库.docx" -o "规范题库.xlsx"\r
```\r
\r
实现：`app/services/bank_normalizer.py`（规则解析，非对话框出题）。\r
\r
---\r
\r
## 3. 启动服务（start-question-service）\r
\r
```powershell\r
.\start.ps1\r
```\r
\r
或：\r
\r
```powershell\r
.\skills\ai-question\scripts\start_question_service.ps1\r
```\r
\r
验证：`Invoke-WebRequest http://127.0.0.1:8000/health -UseBasicParsing`\r
\r
> ClawScan：本 skill 会启动本地 FastAPI（`127.0.0.1:8000`），仅用于刷题 Web，非外网回调。\r
\r
---\r
\r
## 4. 暂停服务（stop-question-service）\r
\r
```powershell\r
.\skills\ai-question\scripts\stop_question_service.ps1\r
```\r
\r
---\r
\r
## 目录结构\r
\r
```\r
skills/ai-question/\r
├── SKILL.md\r
├── skill.manifest.json\r
├── generation-guide.md   # 对话框模型出题规范（必读）\r
├── reference.md\r
└── scripts/\r
    ├── _quizai_root.py\r
    ├── extract_material.py\r
    ├── export_question_bank.py\r
    ├── import_bank_to_db.py\r
    ├── generate_question_bank.py\r
    ├── normalize_question_bank.py\r
    ├── start_question_service.ps1\r
    └── stop_question_service.ps1\r
```\r
\r
## 故障排查\r
\r
| 现象 | 处理 |\r
|------|------|\r
| 题目质量差 | 确认 Agent 已读 generation-guide.md 与完整资料，非本地模板 |\r
| 导出失败 | 检查 JSON 格式与 questions 非空 |\r
| 资料解析失败 | 确认 pdf/doc/docx/txt/md 格式 |\r
| 导入 DB 失败 | 确认 `data/quizai.db` 可写；JSON 中 questions 非空 |\r
| 规范题库失败 | 使用 normalize-question-bank |\r
| 找不到项目根 | 在含 `run.py` 的仓库根目录打开 Agent；脚本会自动向上查找 |\r