bank-ingest

name	bank-ingest
version	1.0.0
description	把官方專科醫師考題 PDF 解析成題庫,推進 hema-2026 的匯入暫存區,供管理員在網站上審閱後發布新年份。當使用者說「加入新年份」「匯入 115 年」「/bank-ingest」或帶著考題 PDF 要建題庫時使用。

bank-ingest — 新增一個年份的題庫

把官方考題 PDF 變成題庫。你(Claude)負責跑指令、問使用者一個關鍵問題、必要時 補寫詳解;真正的發布由使用者在網站上按下去。

先把本技能目錄設進變數:

SKILL="<貼上這段指令開頭的 Base directory for this skill>"

這個工具能做什麼、不能做什麼

它帶的金鑰只能寫匯入暫存區。它不能發布、不能改既有題目、不能刪東西。 推上去的題目在使用者於網站按下「發布」之前,學員完全看不到。

所以流程一定是:解析 → 推送 → 回瀏覽器發布。你不要試圖用指令完成最後一步, 那是刻意設計成做不到的。

步驟

0. 環境自檢(第一次用,或換過機器)

cd "$SKILL" && uv sync && uv run python scripts/doctor.py

跑通會印 ✓ ready,網頁精靈的 Step 2 會跟著變綠。

若印出「金鑰無效或已被撤銷」,請使用者回精靈重新下載 bank-ingest.skill 覆蓋整個資料夾 —— 不要嘗試自己修 .env。

1. 確認素材

使用者要準備一個資料夾,每個科別一個 PDF,檔名須包含科別名稱:

~/bank-115/
  內科.pdf
  共同.pdf

檔名對不上科別的檔案會被略過並印出警告。

2. 解析

cd "$SKILL" && uv run python scripts/parse.py 115 ~/bank-115

產物是 ~/bank-115/parsed.json。把輸出裡的這幾項唸給使用者聽:

• 每個檔解析出幾題、對應到全域哪一段題號
• 缺答案的題號(這些題發布前一定要有人指定答案)
• 缺詳解的題數

3. 問使用者詳解要怎麼處理 — 用 AskUserQuestion

這一步一定要問,不要自己決定。三個選項:

選項	意思
只抽取來源詳解(預設)	只送 PDF 裡本來就有的詳解。最可信,因為那是人寫的。
抽取 + AI 補缺	由你替沒有詳解的題目補寫,資料庫會標記來源為 AI 以便日後辨識。
不匯入詳解	只進題目與答案,詳解留給站上共筆慢慢長。

4.（只有選「AI 補缺」才做）補寫詳解

直接編輯 ~/bank-115/parsed.json,把 explanation_md 是空字串的項目填上 markdown。規則:

• 用繁體中文寫,對象是準備專科考試的血液腫瘤科醫師
• 說明為什麼正解對、其他選項各錯在哪,不要只複述選項
• 沒有把握就留空,不要編造。留空的題目站上會顯示成待共筆,那是可接受的結果; 一段自信而錯誤的詳解會被二十個人讀進去,那不是。
• 不要動 answer、number、options 任何一個欄位

5. 推送

依使用者第 3 步的選擇加上 --explain:

cd "$SKILL" && uv run python scripts/push.py 115 ~/bank-115 --explain source
cd "$SKILL" && uv run python scripts/push.py 115 ~/bank-115 --explain ai
cd "$SKILL" && uv run python scripts/push.py 115 ~/bank-115 --explain none

被伺服器退回的題目會列出來。如實轉述,不要當成雜訊 —— 退回的題會讓年份 不完整,發布時會被擋下來。

6. 交回瀏覽器

告訴使用者:回網站的「加入新年份」精靈,Step 5 逐題審閱,把缺答案的題補上, 然後按發布。你到這裡就結束了。

答案是怎麼抓到的

官方 PDF 的答案是白色的字,不是被白色方塊蓋住 —— 答案欄每題都有一個 color=#ffffff 的字母,印出來看不見,但文字層有。所以:

• 「題目版」PDF 本身就含有答案,不需要另外去要答案顯示版
• 但 pdftotext 會把隱藏層和可見層都吐出來,答案在純文字裡出現兩次卻分不清 誰是誰,所以解析器用 PyMuPDF 讀 span 顏色,不用純文字工具

偵測鏈逐級降信心:答案欄白字(1.0)→ 答案欄可見字(1.0)→ 內文「答案:X」 (0.9)→ 放棄(0.0,交給人)。答案欄的座標是從版面推導的,不是寫死的。

實測:114 年官方兩份 PDF 共 100 題,全數以信心 1.0 抓到答案。

邊界

• 只吃 PDF。 舊年份那種 .docx/.pptx 詳解檔不在範圍內 —— 那些格式的眉角 記在 repo 的 years/AGENT_SPEC.md,走那條路。
• 只新增年份,不覆蓋。 已經在題庫裡的年份會在第一步就被伺服器擋下來。 既有題目的錯字走站上的回報按鈕,答案爭議走 answer challenge。
• 不要繞過暫存區。 沒有「直接寫進題庫」的指令,那是設計,不是缺漏。