jiantw83
8bb1effb93
助理要知道每一支技能能不能交給它代跑，但那份盤點目前只存在於一份待辦文件的表格裡。技能組每天在動，手工盤點只會過期，而且過期得無聲無息——今天就有三件事栽在這上面：照舊版資訊列的待辦白列了、一份文件寫著「8 碼」而工具早就改用 40 碼、一份技能文件描述的路徑家族已經不存在。 判準寫成 references 一份文件，四支技能異動技能共用。內容是判定決策樹的五題與四種結論各自的必填欄位。 判定結果寫成 tools 底下一份 TSV，一支技能一列，十一個欄位。作法沿用設定規格表那一套：註解檔頭說明每一欄的意思與可填值、TAB 分隔、空值寫短橫。技能名分成 domain 與 name 兩欄，形狀跟技能清單工具的輸出一致，比對時直接取前兩欄就好。 初始 35 列依既有盤點種入，來源欄標 seed，代表還沒正式走過決策樹、待複核。技能有異動時就地走一次決策樹再轉成 judged。 檢核腳本比對清單與實際技能：缺列或多列算缺失，必填欄位空著也算缺失——切片交與條件式交沒填「留在人手上的那一半」，助理下一輪會把整支技能當成可交的一路跑完。版本號落後與來源是 seed 都只印提示、不影響結束碼，理由寫進腳本註解：版本號是 domain 層級，同 domain 改一支技能其餘技能也會被標到，當成缺失的話每次發版整個 domain 都亮紅，提示很快就會被當成雜訊忽略。 種入時有一支改判。體檢那一支在既有盤點裡是無條件的切片交，實測確認它呼叫自家腳本走的是帶版本號的路徑，那種路徑進不了允許清單，無人值守的每一輪都會無聲卡在第一支腳本，所以改判條件式交，把條件與條件不成立時的行為都寫進去。留成切片交的話，下一個實作定期健檢的人會看到一列寫著可以交，然後重演一次。 這一輪只建地基。四支技能異動技能還沒引用這份判準與這支腳本，例行稽核也還沒把它排進檢查群組，接線另外一輪做。
116 lines
6.6 KiB
Markdown
116 lines
6.6 KiB
Markdown
# 技能委派判準
|
|
|
|
本文件是「一支技能能不能交給背景助理」的唯一判準來源。`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` 只列成提示 | 清單慢慢與實際脫節，回到手工盤點會過期的老問題 |
|
|
|
|
## 助理要跟著更新
|
|
|
|
清單改動之後，助理的內建定期檢查項要重建一次。
|
|
|
|
- 清單新增可交項目，待辦簿加一筆，來源標成助理內建。
|
|
- 清單移除或改成不交，待辦簿移除對應那筆，不留孤兒。
|
|
- 使用者自己交辦的項目一律不動。助理不會因為一支技能改判就把使用者交辦的事刪掉。
|