# 技能委派判準

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

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

## 交出方式只有三種

超出這三種的一律不交。

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

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

## 判定決策樹

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

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

```mermaid
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` 欄。不交的技能也要填——不交講的是助理不代跑，跟「跑完之後該接什麼」無關。

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

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

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

## 每種結論的必填欄位

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

| 欄位 | 全交 | 切片交 | 條件式交 | 不交 |
| --- | --- | --- | --- | --- |
| `way` | 必填 | 必填 | 必填 | `-` |
| `slice` | `-` | 必填 | 必填，條件寫在這裡 | `-` |
| `human` | `-` | 必填 | 必填 | 必填，寫不交的理由 |
| `trigger` | 必填 | 必填 | 必填 | `-` |
| `recur` | 必填 | 必填 | 必填 | `-` |
| `next` | 必填 | 必填 | 必填 | 必填 |
| `version` | 必填 | 必填 | 必填 | 必填 |
| `origin` | 必填 | 必填 | 必填 | 必填 |

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

| 欄位 | 可填值 |
| --- | --- |
| `trigger` | `at:{ISO 時間}`，立刻要做寫 `at:now`；或 `after:{事件名}` |
| `recur` | `once`、`every:{間隔}`、`cron:{式子}` |

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

## 判定結果放哪裡

真實來源是 [`tools/delegate-spec.tsv`](../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` 欄那一題，全部照 `jsc-ask:ask` 問過，產出判定結果並寫進清單。**沒有判定結果不算建立完成** | 清單缺列，助理永遠不知道這支技能存在，也建議不到它 |
| 修改技能 | `skill-update` | 動到流程或 `description` 就重判；只改文案不動行為可沿用舊結論，但要更新清單上的版本號並註明沿用 | 技能從唯讀變成會寫檔，助理還照舊觸發它 |
| 刪除技能 | `skill-delete` | 刪掉清單那一列，並移除待辦簿裡引用它的內建項 | 助理會去觸發一支不存在的技能，而且失敗不會自動暫停，會一路重試 |
| 一次改多支 | `skillset-update` | 逐支重判，一支都不能跳 | 同上，而且範圍更大 |
| 例行稽核 | `skill-check` | 跑 `tools/check-delegate.sh`，檢查清單與實際技能一一對應。缺列與多列算缺失；版本號落後與 `seed` 只列成提示 | 清單慢慢與實際脫節，回到手工盤點會過期的老問題 |

## 助理要跟著更新

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

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