jiantw83
f2332f965c
切片交的那幾支，助理現在只會提醒不會動手，因為沒有東西記得下「那一段唯讀盤點到底要跑什麼」。清單加第十二欄記具體指令，種入那一支有值就拿它當動作、沒值才退回只提醒。 只認三種寫法。一行指令，路徑一律寫成代入點開頭，由種入那一支代進字面絕對根目錄；指令裡不可以出現金錢符號或波浪號，那兩種在無人值守那一輪解不出來也進不了允許清單，會被靜靜擋掉。要標未接線就寫理由，留白的話下一輪分不出是刻意還是漏填。沒有唯讀入口的寫減號。 觸發型與不交的列一律填減號。觸發的意思是呼叫整支技能，這一欄填了指令會讓種入那一支改拿指令當動作，於是整支交出降級成只跑一支腳本，該寫的頁一頁都不會寫，而且看起來完全正常。這條由檢核腳本擋。 逐項回各存放庫核對，不照抄既有盤點的措辭，因而抓到五處對不上實際腳本的地方。 最要緊的一處：既有盤點點名的那支工具腳本要三個參數，其中兩個無人值守那一輪根本拿不到，而且它是唯一會去問遠端的一方。改用同一件事的本機那一半，而那個子命令剛好在閘門腳本「免讀標準輸入」的清單裡。這一點非確認不可：同一支腳本的另一個子命令不在那份清單上，標準輸入是管線又沒人關閉時會一直等，實測會無限卡住。腳本自己的註解就記著這個坑，說工具腳本轉呼叫時曾經整支卡死——那正是先前心跳斷掉的同一種死法。 另一處：既有盤點點名的同步子命令會寫檔，不是唯讀。那一列剛好是觸發型所以填減號、衝突沒落地，但措辭本身是錯的。 七項標成未接線，理由都是要連網要金鑰。連網那一種一過期就讓那一項每輪失敗，或每輪靜靜回報沒事——後者更難查；而純本機讀取本來一輪都不會失敗。先填會連網的，等於用一批每輪報錯的項目把真的發現蓋掉。 還記下一件接線那天要注意的事：查遠端版本那一支永遠回成功，查不到就安靜放行，所以金鑰失效時它會靜靜回報沒有新版。接線要用另一個子命令，那個有「查不出來」這第三種結論。 檢核腳本從四項檢查改成五項。填錯欄位、指到不存在的腳本、用了認不得的代入點都算缺失；標未接線只印提示，那是判過知道還沒接，不是漏填；指到的 domain 本機沒裝也只提示，那是機器少裝一套不是清單填錯，算缺失會讓半套機器每輪亮紅。 五支技能異動流程一併改：寫清單時要問到並寫下這一欄，重判時要一併重問，刪除時要檢查別列有沒有指到一起刪掉的腳本，一次改多支時要注意跨存放庫搬腳本是這一欄最容易過期的地方。
150 lines
9.7 KiB
Markdown
150 lines
9.7 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` 欄。不交的技能也要填——不交講的是助理不代跑，跟「跑完之後該接什麼」無關。
|
|
|
|
二是**那一段唯讀盤點實際要跑哪一個指令**，寫進清單的 `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`](../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` 只列成提示 | 清單慢慢與實際脫節，回到手工盤點會過期的老問題 |
|
|
|
|
## 助理要跟著更新
|
|
|
|
清單改動之後，助理的內建定期檢查項要重建一次。
|
|
|
|
- 清單新增可交項目，待辦簿加一筆，來源標成助理內建。
|
|
- 清單移除或改成不交，待辦簿移除對應那筆，不留孤兒。
|
|
- 使用者自己交辦的項目一律不動。助理不會因為一支技能改判就把使用者交辦的事刪掉。
|