Potato 標註任務
一個 Potato 任務由一個 YAML 設定檔加上一個資料檔案組成。建構一個任務包含三個步驟：決定要問什麼以及如何問、正確地將其寫下來、以及持續運行直到你觀察到有人從登入畫面順利完成整個研究。第二步是唯一一個背後有驗證器的步驟，這也是為什麼人們很容易從這裡開始並結束。但它也是最不可能導致研究中斷的地方。
如果專案根目錄中有 AGENTS.md，請閱讀它——它包含了在此之上更進一步的專案慣例。
如果你被呼叫時沒有描述任務
如果有人輸入了 /potato-tasks 但對話中沒有任何簡要說明。請不要開始建構，也不要以「你想做什麼？」開頭——一個未使用過 Potato 的研究人員無法有意義地回答這個問題。
請要求對方用一句話說明，然後據此提出一個設計，最後只確認你必須猜測的部分。 references/interviewing.md 是問題庫：開場提問、四行提案、然後兩輪選擇題，涵蓋模態、單位、回應格式、每個項目的標註者人數、品質控制、匯出目標以及誰可以登入——接著第三輪提供七個能力集群作為選單，並只深入探討被選中的部分。
有兩件事需要特別強調。每次都要問資料的模態：它決定了顯示方式、方案家族以及指定媒體檔案存放位置的家族金鑰，而且搞錯了也不會有任何錯誤提示。另外，不要急著加入階段——consent、training 和 prestudy 是協定層面的決定，大多數任務都不需要它們，而需要這些階段的研究人員自己就會知道。
在基於已知假設而非等待的前提下進行建構的常規仍然有效——一旦訪談有了可供假設的依據，就可以應用了。在完全沒有上下文的情況下，提出四個結構化的問題對研究人員來說，遠比你可能做出的任何猜測都要快。
安裝 Potato
此技能的大部分功能都依賴於 potato 指令以及匯入 Potato 的註冊表。如果套件未安裝在你執行指令的環境中，兩者都無法運作。
potato --version || pip install potato-annotation
scripts/walk_task.py 中的瀏覽器操作還需要 Playwright：pip install 'potato-annotation[preview]' && playwright install chromium。
此技能中的腳本
由於以下七個程序透過手動執行容易出錯，而且是你會反覆執行的操作，因此它們被實作為腳本而非說明。它們與此檔案一起位於 scripts/ 目錄下。
| 腳本 | 功能 |
|---|---|
boot_and_check.py config.yaml -p 8000 | 啟動伺服器，等待 200 回應，並列出所有已設定但未載入任何內容的功能 |
walk_task.py --url … --config … --task-dir . | 註冊一個標註者，走完整個研究流程，並檢查答案是否已寫入 user_state.json |
estimate_effort.py config.yaml --rate 15 | 計算項目數、所需標註者數、每人分鐘數、總工時和成本 |
find_design.py --type span --with-instructions | 在 Potato Showcase 中搜尋 440 個已發表的任務設計 |
handover.py config.yaml --confirm | 移除你測試時建立的帳號，並寫入 RUNNING.md |
check_ui.py --url … --config config.yaml | 渲染每個頁面，並報告摺疊以下的方案、空白的媒體、空白的選擇圖塊、沒有控制項可回應的方案、未收集任何內容的答案、小工具報錯的內容、按鍵綁定衝突以及從未出現的方案。--phase poststudy 可用於測量 walk 無法觸及的頁面 |
study_status.py --url … --task-dir . | 報告正在執行中研究的進度、每位標註者的速度、一致性，以及看起來有問題的部分 |
每個腳本都支援 --help，而 boot_and_check、walk_task、check_ui 和 study_status 支援 --json，當你想根據結果採取行動而非僅閱讀時可以使用。
循環
potato validate config.yaml --strict # 檢查結構和未知的鍵
potato preview config.yaml # 顯示表單宣告的內容
potato preview config.yaml --screenshot out.png # 渲染一個頁面，並回報瀏覽器錯誤
nohup potato start config.yaml -p 8000 > server.log 2>&1 & # 啟動它並讀取日誌
前三項指令會立即回傳。第四項永遠不會回傳——請在背景執行它，透過 curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ 輪詢直到收到 200 回應，然後閱讀 server.log。
potato --help 會將這些指令列在其他指令下方，位於 start 參數之後。每個指令都有自己的語法，因此 potato validate --help 和 potato preview --help 是查詢其選項的地方。
每個步驟能捕捉不同類型的失敗
| 步驟 | 能捕捉 | 無法發現 |
|---|---|---|
validate --strict | 缺少必要鍵、錯誤的型別、1–2 層內的未知鍵 | 側邊檔案、階段類型、方案條目內部的任何內容 |
preview | 設定檔宣告了哪些方案和按鍵綁定 | 這些東西是否能成功渲染 |
preview --screenshot | 在單一頁面上未捕捉的例外狀況、console.error、失敗的請求 | 低於 900px 的所有內容、每個條件式小工具、所有其他階段 |
| 啟動並讀取日誌 | 側邊檔案格式、階段組合、子系統初始化 | 實際上看起來如何 |
| 在瀏覽器中實際操作 | 實際的研究流程 | — |
跳過最後兩步，就是一個任務在驗證通過、螢幕截圖乾淨，但卻遺失了訓練階段、注意力檢查和三分之一項目的原因。
及早啟動伺服器
啟動日誌才是真正的驗證器。它是唯一能報告 validate 從未開啟的設定部分是否正常運作的東西：
grep -E "ERROR|Traceback|Loaded [0-9]+|phase|missing required" server.log
在一個包含訓練和注意力檢查的任務中，健康的啟動日誌會顯示 Loaded 3 training instances 和 Loaded 2 attention check items，而不會提及階段。任何其他情況都代表某個功能被設定了但處於關閉狀態。
一旦設定檔能解析就立即啟動——在介面完成前、在說明文件寫好前就啟動。running-a-task.md 提供了背景執行的配方、就緒檢查、日誌行表格，以及在編輯後應刪除哪些產生的檔案。
三種無聲的失敗模式
啟用不代表正在執行。 如果 attention_checks.enabled: true 搭配了一個格式錯誤的項目檔案，它會記錄一個警告，然後顯示 Loaded 0 attention check items，接著在品質控制關閉的情況下執行整個研究。請檢查計數，而不是設定。
--strict 無法檢查所有東西。 它只檢查頂層以及大多數區塊內的一層。它不會檢查 phases、surveyflow、quality_control、crowdsourcing、publish、automatic_assignment、ui、ui_config 內部，也不會檢查 annotation_schemes 或 instance_display.fields 的任何條目內部。將 key_binding 誤寫為 key_value 可以通過驗證但不產生任何作用。一個不存在的階段 type: 也是如此。
螢幕截圖是視口，不是頁面。 --screenshot 會輸出 1280×900 的影像。在一個帶有說明橫幅的任務中，這可能只顯示了橫幅和一半的項目——完全看不到問題。因此，僅靠這個工具無法遵循「查看 PNG 並檢查「下一步」按鈕是否在摺疊以上」的建議。請在瀏覽器中實際操作，並使用 full_page=True 進行截圖。
了解他們已有的東西
一個簡要說明加上一個資料檔案是常見情況，但不是唯一的情況。在設計任何東西之前，詢問以下四件事，因為每件事背後都有一個指令，而且如果在設定檔寫好之後才發現這些問題，代價會很高：
| 問題 | 原因 |
|---|---|
| 資料是什麼格式，媒體檔案在哪裡？ | 逐字稿和對話語料庫有自己的轉換器 |
| 你已經有標註了嗎？ | potato import 可以讀取十四種格式並寫出一個可運行的專案 |
| 最終需要產出什麼？ | 有二十九種匯出格式。在任何人開始標註之前檢查目標格式 |
| 交接後由誰運行，以及運行多久？ | 決定主機、登入方式和允許清單 |
potato import --list-formats # coco, cvat, labelme, labelbox, via, …
potato transcripts interviews/ -r --dry-run # whisper, srt, vtt, textgrid, eaf, …
potato convokit reddit-corpus-small --unit conversation --emit-config
references/importing-existing-work.md 涵蓋了所有三項，包括最重要的一個決定：匯入的標註是作為人類修正的預先標註，還是作為標記該項目已完成的 --seed-user 工作。
不明確的簡要說明
在撰寫設定檔之前，請閱讀 references/asking-the-experimenter.md。當出錯的成本很低時，可以自行決定；但當成本高、不可逆或不屬於你時（例如標註的單位、標註者預算、同意書措辭，以及任何涉及可識別個人的事項），則必須詢問。
永遠不要等待答案。在已知假設的基礎上進行建構，將問題寫入 QUESTIONS.md，並附上一個可以運行的東西，同時說明你會優先重新審視哪個假設。
在自行建構之前，先尋找現有功能
Potato 內建的功能比設定檔參考文件所顯示的要多得多。最昂貴的錯誤不是發明一個不存在的類型名稱——驗證會捕捉到這點。而是手動組合 Potato 已經實現的功能。
references/modes-and-subsystems.md 是一個路由表，說明了研究人員的描述對應到哪個功能區塊：QDA 與編碼簿、單人模式、房間、仲裁、審查工作流程、會話、口袋、主動學習、評審、群眾外包、發布、遙測。在撰寫一個聽起來像是變通方案的方案之前，請先查閱此表。
它開頭列出了七個集群——材料、答案、單位、人員、信任、模型輔助、輸出——這與訪談中提供的選單是同一張地圖。將其作為清單對照簡要說明進行檢查：簡要說明從未提及的集群，正是研究人員最可能遺漏他們想要的功能的地方。最多提出其中兩個，並且只在它們重要的時候提出；其餘的則寫入 QUESTIONS.md。
研究人員最常遺漏的集群是答案。他們要求 radio 和 likert 就停了下來，而 soft_label、range_slider、semantic_differential、constant_sum 和 confidence 從來沒有被考慮到。
設計
references/designing-a-task.md 涵蓋了每個任務背後的七個決定：單位、問題、回應格式、每個項目的標註者人數、項目順序、品質控制以及前後的階段。
路由表涵蓋了常見的需求並止步於此。 有十一種類型在生成的參考文件中未被命名，因此它們從未被考慮過：multirate（在一個尺度上進行十次評分，而不是十個 likert 方案）、hierarchical_multiselect（一個可摺疊、可搜尋的分類法）、select、soft_label（一個分佈而非強迫選擇）、range_slider、semantic_differential、conjoint、card_sort、extractive_qa、multi_document_event、code_review。每種都有一個可運行的範例，並在 designing-a-task.md 中有一行說明。
有兩個很容易出錯且代價高昂的問題：
- 回應格式決定了一致性指標。 Potato 會根據 schema 的種類來選擇指標。一個儲存為
radio的 1–5 分評分會被視為無序進行評分，因此「1 vs 2」和「1 vs 5」會被視為相同。這是一個測量誤差，而非表面問題。請參閱references/assignment-and-agreement.md中的表格。 num_annotators_per_item設定目標，max_annotations_per_user則決定了一個人實際看到的數量。 如果未設定上限，則預設為項目總數，因此所有人都會看到整個語料庫。如果將其設定得低於項目總數，標註者只會提前停止，而且沒有任何提示說明原因。automatic_assignment.instance_per_annotator看起來像是這個功能的設定鍵，但它實際上完全不被讀取。
設計記錄與成本
在設定檔旁邊的兩個檔案，設定檔本身無法容納這些資訊：
DESIGN.md— 標註的單位及其原因、選擇每種回應格式的原因、每個項目的標註者人數、品質控制的目的，以及一份獨立且明確的清單，列出你因為簡要說明沒有提及而做出的假設。最後一段是讓這個文件值得被打開的原因。QUESTIONS.md— 你完全無法決定的部分。永遠不要等待答案；在提出問題的同時，交付一個可以運行的東西。
python .claude/skills/potato-tasks/scripts/estimate_effort.py config.yaml --rate 15
這個指令會報告設計所需的標註者人數、每人工作時長、總工時和成本。在撰寫說明文件之前執行它——這是最便宜的、能及早發現無人能負擔的設計的方法。
references/recording-decisions.md 提供了 DESIGN.md 的模板，以及哪些因素會影響成本估算。
從已發表的設計開始
在從欄位列表開始撰寫方案之前，先搜尋是否有其他人已經執行過的設計：
python .claude/skills/potato-tasks/scripts/find_design.py --query "stance" --with-instructions
python .claude/skills/potato-tasks/scripts/find_design.py --show text/argumentation-stance/argument-quality
Potato Showcase 包含 440 個標註任務設計，大多數是根據已發表的論文建構的，帶有真實的標籤集和真實的問題措辭——並且其中281 個附帶了書面說明。它們中沒有一個包含 phases 區塊、同意書頁面或訓練輪次，因此請從那裡獲取問題，並從 worked-example.md 獲取圍繞它們的研究結構。references/finding-a-design.md 涵蓋了在重用一個設計之前需要更改的內容。
撰寫說明文件
設定檔背後有一個驗證器。但標註者讀取的文字沒有，而這正是最終資料集中大多數不一致的來源。
references/writing-guidelines.md 涵蓋了標註者面向的文字可以存在的四個表面（instructions 階段、annotation_instructions 橫幅、annotation_codebook_url 以及每個方案的 description）、一個標籤定義必須包含什麼才能解決爭論、打破平局的規則、包含邊界案例的實際範例，以及如何根據試驗階段的不一致性來迭代指南。examples/advanced/long-guidelines/ 是一個包含所有這些要素的可運作模型。
有兩件事需要正確處理，無需進一步閱讀：
- 橫幅不是編碼簿。
annotation_instructions會出現在每個頁面上，但你的說明文件應該遠比它所能容納的詳細。編碼簿是你透過annotation_codebook_url連結的獨立文件。 - 如果聽起來像是一個例子，那就把它寫成一個例子。 說明文件中最有價值的句子是「在這個資料集中，『X』意味著……」，而最常見的錯誤是只定義正面案例。邊界案例解決的爭論是正面案例的兩倍。