meta/references/delegate-criteria.md

技能委派判準

本文件是「一支技能能不能交給背景助理」的唯一判準來源。skill-new、skill-update、skill-delete、skillset-update 四支技能異動技能共用這一份，不各自抄一套。

判定結果一律寫進 tools/delegate-spec.tsv，由 tools/check-delegate.sh 檢核。本文件只寫判準，不放判定結果。

交出方式只有三種

超出這三種的一律不交。

代號	方式	邊界
invoke	觸發	呼叫既有技能，內容照那支技能自己的流程走。助理只決定「什麼時候跑」，不改那支技能的判斷
patrol	巡檢	跑既有的唯讀腳本或讀既有狀態，產出現況。一個字都不改，讀完寫進監控頁
remind	提醒	把巡檢結果留到前景會話提出來。不代替使用者決定，也不自己動手

一支技能可以同時用多種方式，例如先巡檢再提醒。

判定決策樹

一支技能照順序回答五個問題，答完就得到結論。

題號	問題	答「是」往哪走
一	本體會改檔案，或對外不可逆？	是就跳到第四題
二	本體需要使用者決策？	需要就跳到第四題
三	輸出穩定，跑兩次結果一致？	是就結論「全交」，方式填觸發
四	切得出唯讀盤點或提醒的一段？	切得出就結論「切片交」
五	要加條件才切得出？	是就結論「條件式交」，切不出就結論「不交」

flowchart TD
    S[一支技能] --> Q1{本體會改檔案，<br/>或對外不可逆？}
    Q1 -->|會| Q4
    Q1 -->|不會| Q2{本體需要使用者決策？}
    Q2 -->|需要| Q4
    Q2 -->|不需要| Q3{輸出穩定、跑兩次結果一致？}
    Q3 -->|是| R1[全交：觸發]
    Q3 -->|否| Q4
    Q4{切得出唯讀盤點<br/>或提醒的一段？} -->|切得出| R2[切片交]
    Q4 -->|要加條件才切得出| R3[條件式交]
    Q4 -->|切不出| R4[不交]

結論之外還要多填兩項。

一是這支技能跑完之後建議接哪一支，寫進清單的 next 欄。不交的技能也要填——不交講的是助理不代跑，跟「跑完之後該接什麼」無關。

二是那一段唯讀盤點實際要跑哪一個指令，寫進清單的 probe 欄。只有交出方式是巡檢或提醒的那幾列要填：那幾列在待辦簿上的動作原本一律退回只提醒，有指令才有事情做。交出方式含觸發的列與不交的列一律填減號，理由見下一節。

四種結論，每一種都要留一列

結論	verdict	要記什麼
全交	full	交出方式、預設 trigger 與 recur
切片交	slice	交出的那一段、方式、留在人手上的那一半
條件式交	cond	條件講清楚，連同條件不成立時的行為
不交	none	不交的理由。不交也要留一列，否則下次分不出「判過決定不交」與「還沒判」

「留在人手上的那一半」是切片交的必填欄位。少了它，助理下一輪會把整支技能當成可交的一路跑完。

每種結論的必填欄位

- 代表這一格填一個減號，不是留白。TSV 沒有空格這種值，留白會被檢核判成缺欄位。

欄位	全交	切片交	條件式交	不交
way	必填	必填	必填	-
slice	-	必填	必填，條件寫在這裡	-
human	-	必填	必填	必填，寫不交的理由
trigger	必填	必填	必填	-
recur	必填	必填	必填	-
next	必填	必填	必填	必填
version	必填	必填	必填	必填
origin	必填	必填	必填	必填
probe	-	way 不含 invoke 才必填	同左	-

trigger 與 recur 是兩個獨立欄位，四種組合都成立，登錄時不可以壓成兩種。

欄位	可填值
trigger	at:{ISO 時間}，立刻要做寫 at:now；或 after:{事件名}
recur	once、every:{間隔}、cron:{式子}
probe	一行指令、pending:{理由}，或 -

事件名只認固定詞彙表：worklog-written、wp-merged、stage-entered、analyze-completed、hook-error、session-start、session-end。填一個永遠不會發生的事件名，那一筆就永遠不到期，而且看不出壞在哪。

唯讀指令欄怎麼填

probe 記的是「那一段唯讀盤點實際要跑什麼」。助理拿它當待辦簿上的動作，所以它是一個指令，不是說明文字。

寫法	什麼時候用
一行指令	那一段有現成的唯讀入口，跑起來一個字都不改
pending:{理由}	那一段切得出唯讀盤點，入口還沒接上。冒號後面寫不接的理由，不可以留白
-	這一列沒有唯讀盤點入口

指令的路徑一律寫成 {root}/jsc-{domain}/… 開頭。三個代入點由助理代入，別的大括號一律算填錯：

代入點	代入什麼
{root}	種入那一支拿到的字面絕對根目錄
{cli}	助理偵測到的 CLI 代號，一支跑一次
{repo}	助理掃到的存取庫工作目錄，一個跑一次

指令裡不可以出現金錢符號或波浪號：那兩種寫法在無人值守那一輪解不出來，也進不了允許清單，會被靜靜擋掉。要帶環境變數就寫在指令最前面。

唯讀旗標帶不帶，逐支確認，不要照抄別列。 有些腳本靠環境變數才進唯讀模式，例如接線那一支設了 JSC_READONLY=1 會讓它的破壞性子命令回結束碼 6；那一列就要把旗標寫進指令。沒有唯讀模式的腳本不要憑空補一個變數名，補了不會生效，卻讓下一個人以為有護欄。巡檢那一輪是無人值守的，帶錯旗標會讓唯讀盤點變成實際動手。

交出方式含觸發的列一律填 -。 觸發的意思是呼叫整支技能，內容照那支技能自己的流程走。這一欄填了指令，助理會改拿指令當動作，於是整支交出變成只跑一支腳本，那支技能該寫的頁一頁都不會寫，而且看起來完全正常。

要連網的先寫 pending。 連網要金鑰，金鑰一過期就讓那一項每輪失敗，或每輪靜靜回報沒事——後者更難查。純本機讀取本來一輪都不會失敗。先填會連網的那一種，等於用一批每輪報錯的項目把真的發現蓋掉。等入口與金鑰都有著落再換成指令。

檢核怎麼看：pending 只印成待接線提示，不算缺失，判準同 origin=seed——它是「判過、知道還沒接」，不是漏填。填錯欄位、指到不存在的腳本、用了認不得的代入點，都算缺失。

判定結果放哪裡

真實來源是 tools/delegate-spec.tsv，一支技能一列。作法沿用 jsc-cli/tools/config-spec.tsv 那套：TSV 加一支檢核腳本，能被腳本比對，不靠人讀。

判定結果不寫進 SKILL.md 的 frontmatter。name 與 description 之外的自訂欄位有被各 CLI 的技能驗證擋掉的風險。

「過舊」的判準是比 plugin 版本號：清單上記的版本號落後該 domain 現行版本，就是要複判。版本號是 domain 層級，所以同 domain 改一支技能，其餘技能也會被標成要複判——這只是提示，不算稽核缺失。當成缺失的話，每次發版整個 domain 都亮紅，提示很快就被當雜訊忽略。

origin 欄記這一列怎麼來的：

值	意思	檢核怎麼看
seed	依既有盤點種入，還沒正式走過決策樹	印成待複核提示，不算缺失
judged	正式走過決策樹判定	不印

種入的那一批先掛 seed。之後那支技能有異動時就地走一次決策樹，把它轉成 judged。

各種異動要做的事

異動	技能	要做的事	沒做的後果
新增技能	skill-new	決策樹五題、next 欄那一題，再加 probe 欄那一題，全部照 jsc-ask:ask 問過，產出判定結果並寫進清單。沒有判定結果不算建立完成	清單缺列，助理永遠不知道這支技能存在，也建議不到它
修改技能	skill-update	動到流程或 description 就重判，probe 一併重確認——技能換了呼叫的腳本，那一欄就指到不存在的東西；只改文案不動行為可沿用舊結論，但要更新清單上的版本號並註明沿用	技能從唯讀變成會寫檔，助理還照舊觸發它
刪除技能	skill-delete	刪掉清單那一列、把指到它的 next 改指別支，並檢查有沒有別列的 probe 指到這次一起刪掉的腳本；另移除待辦簿裡引用它的內建項	助理會去觸發一支不存在的技能，而且失敗不會自動暫停，會一路重試
一次改多支	skillset-update	逐支重判，一支都不能跳	同上，而且範圍更大
例行稽核	skill-check	跑 tools/check-delegate.sh，檢查清單與實際技能一一對應。缺列、多列與 probe 填錯算缺失；版本號落後、seed 與 probe 的 pending 只列成提示	清單慢慢與實際脫節，回到手工盤點會過期的老問題

助理要跟著更新

清單改動之後，助理的內建定期檢查項要重建一次。

• 清單新增可交項目，待辦簿加一筆，來源標成助理內建。
• 清單移除或改成不交，待辦簿移除對應那筆，不留孤兒。
• 使用者自己交辦的項目一律不動。助理不會因為一支技能改判就把使用者交辦的事刪掉。