potato-skill：用 Claude Code、Codex 或 Cursor 構建標註研究

potato-skill 把一段平實的標註研究描述變成可以執行的 Potato 任務。它附帶 28 份參考檔案和九個輔助指令碼，覆蓋寫配置之前的設計決策、標註者看到的介面，以及用來發現"配置能通過校驗、任務卻不可用"的檢查。它可以安裝到 Claude Code、Codex 和 Cursor 中，以 GPL-3.0-or-later 許可釋出。

安裝這個技能

Claude Code 從外掛市場安裝它，兩條命令即可：

/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potato

Codex 和 Cursor 用 skills CLI 安裝，它會把這個技能複製到你正在開發的項目裡：

npx skills add davidjurgens/potato-skill --agent codex cursor

智慧體在哪裡執行命令，Potato 就必須裝在哪裡，因為這九個輔助指令碼會匯入它的登錄檔並呼叫 potato 命令：

pip install potato-annotation

Codex 或 Cursor 的安裝包含什麼

skills CLI 會寫出 .agents/skills/potato-skill/，其中包含 SKILL.md、全部 28 份參考檔案和全部九個指令碼，所以 Codex 或 Cursor 項目拿到的材料與 Claude Code 安裝拿到的相同。它不會改動 AGENTS.md 和 .cursor/rules，而各個工具如何發現該目錄下的技能，由工具自己決定。

倉庫根目錄還帶有一個 AGENTS.md，Codex 和 Cursor 按檔名讀取它，不需要任何安裝步驟。相對於參考檔案合計約 79,000 詞的內容，這個檔案是一份簡短的摘要，而且它指向的參考檔案和指令碼只有完整安裝才會落到磁碟上。如果你希望智慧體拿到"交付前先檢查"的迴圈和那些真正起作用的規則，就用它；如果你還想要這些規則背後的參考材料，就用 skills CLI。

技能不問就定下的預設值

一個決定如果做錯了、改起來很便宜，它就自己定；如果做錯了代價高昂、不可逆，或者本來就不該由智慧體來定，它就交回給你。改一個鍵盤快捷鍵沒有任何成本，而因為標註單位選錯了要重新標 5,000 個條目，則要消耗掉研究的預算。以下是它自己採用的預設值，交付任務時它會把每一條都列為假設：

它交還給你的決定

有五個決定會在一條彙總訊息裡交還給研究者，每一個都附帶一個建議答案，所以你一個詞就能確認：

• 標註單位，在資料本身定不下來的時候。一份按段落組織的檔案，而問題其實是關於句子的，這就是研究的一個分岔口，兩邊的選擇都可能意味著重做。
• 每個條目的標註者人數，在需要報告一致性的時候。三名標註者的成本是一名的三倍，所以這個技能會提出一個數字並說明理由，而不是替你把預算花掉。
• 知情同意的措辭。 它會根據你描述的內容起草，並直接說明這份草稿需要替換成你所在倫理委員會批准的文本。
• 沒有地方安放疑難情況的標籤集。 三個標籤，既沒有"不確定"也沒有"都不是"，通常是疏漏；標註者於是把真正有歧義的條目隨便塞進某一類，而下游沒有任何環節能看出這件事發生過。這個技能會指出它認為無處安放的那些條目。
• 任何會向標註者展示使用者名稱、人臉或地理位置的內容。

這些都不會阻塞構建。技能會說明自己的假設，構建任務，驗證它，並在你已經可以點開試用的東西旁邊提出這些問題。

交付前的檢查

配置通過校驗，說明伺服器能啟動，但完全說明不了人能不能完成這項工作。所以技能要求智慧體把任務渲染出來，然後去看它：

potato validate config.yaml --strict
potato preview config.yaml --screenshot shot-01.png

--strict 把無法識別的配置鍵從警告變成失敗。沒有它，拼寫錯誤會被接受、被忽略，你以為打開了的功能其實一直沒開，這正是"配置讀起來沒問題、實際什麼都沒發生"的常見原因。

--screenshot 會啟動一個真實的 Potato 伺服器，用無頭 Playwright 驅動它，記錄控制台錯誤、未捕獲的頁面異常，以及 400 及以上的 HTTP 響應。只有這三份列表都為空時它才以 0 退出。這一步能抓住校驗抓不住的東西，因為標註介面的大部分是在 HTML 到達之後由 JavaScript 構建的。最典型的情況是一個看不見的單選按鈕：標籤文字照常渲染，問題乍看之下完全正常。

圍繞這兩條命令的迴圈是指引，而不是自動化。參考材料告訴智慧體每輪只改一處，把每次渲染寫到一個新的檔名下，這樣前後兩張圖就能顯示這次改動做了什麼，並且在自定義佈局上要預期三到四輪。它還告訴智慧體：display_logic 之後的任何內容都不會出現在第一次渲染裡，而它的缺席什麼也證明不了，所以要把條件註釋掉、渲染一次、再放回去。

九個輔助腳本里有三個，把可以測量而非需要判斷的部分自動化了。check_ui.py 在 1280x900 下測量即時佈局，報告落到首屏以下的標註方案或"下一個"按鈕、空的媒體控制元件，以及重複的快捷鍵。boot_and_check.py 啟動伺服器，報告每一項配置了卻什麼都沒載入的功能，比如載入了零個培訓條目的培訓環節。walk_task.py 像標註者那樣走一遍正在執行的任務，並報告它停在哪裡。

標註者開始之後，哪些改動安全、哪些不安全

標註研究中出問題的地方，大多出在標註者已經開始之後，而真正要緊的失效模式不會產生任何錯誤資訊。這個技能收錄了其中兩種。

研究進行到一半改問題的名字是最尖銳的一種。沒有任何報錯，隨後三個介面會報出三種不同的結果：管理員總覽說研究已 100% 完成，一致性報告說那個標註方案有零個條目，而 CSV 匯出裡帶的是舊的列名，因為匯出由已儲存的內容驅動，而不是由配置驅動。整張安全網只有啟動日誌裡的一行 WARNING。新增問題是同一個問題的安靜版本，因為 Potato 只按條目跟蹤完成度，從不按問題跟蹤，所以後來加上的問題永遠到不了已經標完整個語料的人那裡。

第二種是身份驗證。預設後端把賬戶儲存在記憶體裡，所以停掉伺服器會把每一個標註者的登入賬號一併帶走，而標註資料仍然安全地留在磁碟上。標註者回來後用同一個使用者名稱重新註冊，就會被重新接回自己的工作，這把問題掩蓋了起來，直到有人輸入了另一個使用者名稱，以第二個人的身份把語料又標了一遍。設定 authentication.user_config_path 會把賬戶連同加鹽雜湊一起寫出來。它在最容易被忘記的地方最要緊，因為 Render 和 Hugging Face Spaces 會自行重啟容器。

對於已經在進行中的研究，study_status.py 會讀取管理路由，取得進度、每位標註者的速率、每個問題的一致性、誰沒通過注意力檢查，以及誰佔著自己已經放棄的條目。然後技能會說明哪些修改仍然安全，哪些會破壞你已經付過錢的答案。

Potato 的 MCP 伺服器

Potato 自帶兩個 MCP 伺服器，它們讓智慧體不必呼叫外部命令就能得到同樣的答案。potato mcp serve --root . 暴露 12 個創作工具，它們讀取的登錄檔和 CLI 一樣，其中包括 render_task_screenshot，它把渲染好的頁面作為圖片返回。potato mcp connect 橋接一項正在執行的研究，再加上 12 個即時工具，涵蓋狀態、進度、標註者、一致性、任務分配和匯出。這個橋接需要配置裡有一個 mcp 塊來列出要暴露的工具，還需要一個由 potato mcp issue-token 簽發的令牌。

手寫標註工具及其代價

要把幾百個條目標完，常見的做法是讓程式設計智慧體寫一個簡易標註工具，比如一個 Streamlit 或 Flask 頁面，一次顯示一個條目，把每個答案追加到 CSV 裡。如果只是一個人花一個下午標一批資料，做這樣一個工具是合理的。代價會在研究需要下面這些東西時出現：每位標註者一個登入賬號；每個條目三名標註者，並把每個條目分派給合適的人；一輪培訓和注意力檢查；一致性統計；Prolific 的完成碼；以下一個指令碼所期望的格式匯出；或者下個月還要有一項執行方式相同的研究。這裡的每一項，都是需要有人在一個為單次研究而建的工具裡編寫、測試和除錯的功能，而 Potato 已經全部具備。

兩者在"研究結束之後還剩下什麼"上也不同。手寫的標註工具通常綁在某個倉庫裡的某個資料集上，而 Potato 任務是一個裝著配置和資料的資料夾，任何裝了 Potato 的人都能啟動它。展示頁收錄了 400 多個這樣的任務，大多取自已發表的論文，find_design.py 會在其中搜索與你描述接近的設計。

這個技能能搭起來的研究

下面五個例子展示了它的覆蓋範圍，每一個都從一段簡短的描述開始，最後得到一個可以執行的任務：

• 由眾包工作者標註立場。 每條帖子三名標註者、一輪培訓、注意力檢查、一個 Prolific 完成碼，標籤收齊後計算一致性。參見開展眾包研究和衡量標註者間一致性。
• 比較兩個聊天機器人的回答。 並排佈局，配上偏好量表和自由文本的理由欄。參見成對模型比較和 RLHF 偏好資料。
• 標出智慧體軌跡中出錯的那一步。 軌跡一步一步地展開，任務會記錄標註者標出的步驟和他們的解釋。參見智慧體軌跡標註。
• 繼續一個 CVAT 項目。 potato import 能讀 20 種格式，所以已有的邊界框會連同標籤一起匯入，研究再以 COCO 格式匯出。參見衡量邊界框上的一致性。
• 兩名編碼員和一本編碼手冊。 編碼手冊變成編碼介面，兩名編碼員都會被分配到每一條回答，由裁決步驟處理分歧。參見裁決與分歧。

針對 Potato 登錄檔的測試

一個看著合理卻是錯的識別符號，比沒有文件更糟，因為智慧體真的會去用它。所以 28 份參考檔案裡有三份是由 Potato 自己的登錄檔生成的，不會與伺服器實際執行的內容產生偏差：全部 61 種標註類型，每一種都配有從真實項目裡取來的完整示例；有文件記載的頂層配置鍵；以及有文件記載的子鍵。

CI 覆蓋這個技能的核心檔案，檢查其中提到的每一種標註類型、展示類型、配置鍵、運算子、策略名和命令在 Potato 中確實存在。每一段 YAML 示例都會被拼進一份可用的配置，交給 Potato 真正的驗證器執行；完整示例會啟動一個真實的伺服器，它開啟的每一項功能都必須在日誌裡報出一個非零的計數。

參考材料釋出在 davidjurgens.github.io/potato-skill，所以你在安裝之前就能讀到這個技能會告訴智慧體什麼。Anthropic 建議先審閱任何技能。

常見問題

下面的問題涉及如何在 potato-skill 和手寫標註工具之間做選擇、技能在交付前檢查什麼，以及如何修改它構建的介面。

程式設計智慧體應該自己構建定製標註工具，還是使用現有工具？

只有當一個人把幾百個條目標註一次時，才值得構建定製工具。一個 Streamlit 或 Flask 頁面，一次顯示一個條目，把每個答案追加到 CSV 裡，就足以應付這種情況。一旦研究需要每個條目多名標註者、一輪培訓、注意力檢查、一致性統計或 Prolific 的完成碼，其中每一項都必須在一個為單次研究而建的工具裡編寫和測試，而 Potato 已經全部具備。potato-skill 正是因此建立在 Potato 之上，它產出的任務是一個資料夾，任何裝了 Potato 的人都能重新執行。

potato-skill 在交付任務之前會驗證什麼？

potato-skill 會讓智慧體在交回任務之前執行兩條 Potato 命令，另有三個輔助指令碼檢查這兩條命令檢查不到的東西。potato validate config.yaml --strict 遇到任何無法識別的配置鍵都會失敗。potato preview config.yaml --screenshot 會在無頭 Playwright 中啟動一個真實的伺服器，只有當頁面沒有產生控制台錯誤、沒有未捕獲的異常、也沒有 400 及以上的 HTTP 響應時，才以 0 退出。check_ui.py 報告落到首屏以下的標註問題或"下一個"按鈕，boot_and_check.py 報告配置了卻什麼都沒載入的功能，walk_task.py 像標註者那樣走一遍任務，並報告它停在哪裡。

我能定製 potato-skill 構建的介面嗎？

可以。任務就是一份普通的 Potato 配置，所以你可以手動編輯佈局，也可以讓智慧體來改。對於自定義佈局，potato-skill 要求智慧體每輪只改一處，把每次渲染寫到一個新的截圖檔案裡，這樣相鄰兩次渲染就能顯示這次改動做了什麼，並且要預期三到四輪。display_logic 之後的任何內容都不會出現在第一次渲染裡，所以智慧體會把條件註釋掉、渲染一次、再放回去。

延伸閱讀

• 使用程式設計智慧體快速入門，其中更詳細地講了安裝
• GitHub 上的 potato-skill，當前版本 v1.0.1
• 該技能的參考材料
• 展示頁，用來找到與你的研究接近的設計

參考文獻

David Jurgens, Michael Chen, and Lina Iyer (2026). Potato 2.0: A Comprehensive Annotation Platform with AI-in-the-Loop Support. Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations). https://aclanthology.org/2026.acl-demo.37/