例行稽核新增腳本路徑檢核，判文件裡寫的路徑解不解得出來 #74

2026-09-04T02:56:13Z

jiantw83 commented

2026-09-04 02:56:13 +00:00

摘要

需求描述：lint-scripts.sh 掃的是 tools/ 與 hooks/ 目錄裡的檔案，它證明得了「這個存取庫裡有這支腳本、語法沒問題」，卻證明不了「文件裡寫的那條路徑解得出那支腳本」。這張 PR 補上後者，並接進例行稽核的第一組。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/check-skill-paths.sh`	新增。掃 `skills//SKILL.md` 與 `references/.md`，解析每一條 `tools/…` 與 `hooks/…` 路徑，三種判定
`skills/skill-check/SKILL.md`	第一組新增一項並重新編號，步驟六的複跑與完成條件一併接上，`description` 的檢核清單補一支
`references/behaviors.md`	`skill-check` 那一節的關鍵步驟、外部呼叫、可驗證跡象三欄同步
三份 manifest	版號升到 0.3.7

這道縫是怎麼被發現的

2026-09-04 開 PR 時實際踩到：一份技能本文把自家腳本寫成不帶前綴的相對路徑，而那支技能的基底目錄是 skills/{名稱}/，照字面解出來的位置沒有那個檔案，結束碼 127。

真正的問題不是那個 127，是它為什麼一直沒被抓到。 例行稽核本來就有一項要人確認「本文點名的每一支腳本，呼叫端有沒有分流它宣告的每一個結束碼」，而那一項的前提寫著「lint-scripts.sh 已經證明腳本存在」。人照著讀，就會去看目錄底下有沒有那個檔名——有，於是過了。覆核的問題本身問錯了，所以錯幾次都不會被發現。

新那一項刻意擺在舊那一項前面，並把這段理由寫進本文，免得下一輪有人把兩項看成重複的而刪掉一項。

三種判定，以及為什麼只有一種算缺失

類別	意思	算不算缺失
`missing`	路徑指到不存在的檔案	算
`unrooted`	不帶 domain 名，但檔案在這個存取庫底下	只算提示
`unknown`	跨 domain，但那個存取庫不在這台機器上	只算提示

unrooted 為什麼不算缺失：不帶 domain 名的相對路徑會相對於當下的工作目錄解。在自己那個存取庫裡跑剛好解得對，換一個工作目錄就解到別人的 tools/ 底下，或者解不出來。兩種都沒有明確的錯誤訊息，前者更糟——它會跑起來，跑的是另一支腳本。無人值守那一輪還多一層：相對路徑進不了權限允許清單，會被靜靜擋掉。

話說回來，這是整套技能組共通的寫法，實測共 378 處。判成缺失會讓每一個存取庫同時亮紅，而一份全紅的報告跟沒有報告一樣。所以先量出來、指得出是哪幾行，改不改由人決定。技能本文也明寫這兩種提示不得升級成決策樹項目——比照委派清單檢核的待複核與版本落後那兩種提示。

unknown 為什麼不算缺失：這台機器沒裝那個 domain，跟路徑寫錯，是兩件事。

判定範圍與其極限

只認 tools/ 與 hooks/ 兩個目錄底下的 .sh。templates/ 與 references/ 底下的檔案不在範圍內——那些是資料不是入口，指錯了不會變成一支跑起來的別的程式。

README.md 不掃：那裡的路徑是給人看的目錄，不是叫誰去跑的入口。

有一類已知的誤判講白：文件在解釋「不要用不帶前綴的寫法」時，會把那個錯誤寫法原樣寫出來當例子，這一支會把那一行也算進提示。實際遇到一次，處置是改寫那句話、描述後果而不照抄寫法——那樣讀起來也更準。

測試結果

自建一個假存取庫逐一驗七種情況：自家帶前綴檔案在（過）、自家帶前綴檔案不在（missing）、自家不帶前綴檔案在（unrooted）、自家不帶前綴檔案不在（missing）、跨 domain 存取庫在且檔案在（過）、跨 domain 存取庫在但檔案不在（missing）、跨 domain 存取庫不在（unknown）。七種全部符合預期，有缺失時退出 1。
結束碼四條路各驗一次：無參數與兩個參數都回 2，路徑不存在回 3，空存取庫回 3。
對十二個存取庫全掃一輪：一條 missing 都沒有，378 條 unrooted，0 條 unknown。
這一支上線當天就抓到一處真的漏改：另一個存取庫剛送出的路徑修正只改了技能本文，references/behaviors.md 的關鍵步驟與外部呼叫兩欄還留著八處舊寫法，而那兩欄正是別人拿來確認一支技能會呼叫誰的地方。已經在那一邊補上。
lint-scripts.sh、lint-frontmatter.sh、check-behaviors.sh、ste100-lint.sh、check-link-format.sh 對這個存取庫都回結束碼 0。

前置 Push Request

plugins/meta 的委派清單修正那一張。兩張都動到三份 manifest 的版號，而那一張要緊——它拿掉一個會讓內建項每輪失敗的值，該先走。這一張讓到 0.3.7，等它先合併才不會撞版號。程式碼本身互不相依。

## 摘要 - 需求描述：`lint-scripts.sh` 掃的是 `tools/` 與 `hooks/` 目錄裡的檔案，它證明得了「這個存取庫裡有這支腳本、語法沒問題」，卻證明不了「文件裡寫的那條路徑解得出那支腳本」。這張 PR 補上後者，並接進例行稽核的第一組。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/check-skill-paths.sh` | 新增。掃 `skills/*/SKILL.md` 與 `references/*.md`，解析每一條 `tools/…` 與 `hooks/…` 路徑，三種判定 | | `skills/skill-check/SKILL.md` | 第一組新增一項並重新編號，步驟六的複跑與完成條件一併接上，`description` 的檢核清單補一支 | | `references/behaviors.md` | `skill-check` 那一節的關鍵步驟、外部呼叫、可驗證跡象三欄同步 | | 三份 manifest | 版號升到 0.3.7 | ## 這道縫是怎麼被發現的 2026-09-04 開 PR 時實際踩到：一份技能本文把自家腳本寫成不帶前綴的相對路徑，而那支技能的基底目錄是 `skills/{名稱}/`，照字面解出來的位置沒有那個檔案，結束碼 127。 **真正的問題不是那個 127，是它為什麼一直沒被抓到。** 例行稽核本來就有一項要人確認「本文點名的每一支腳本，呼叫端有沒有分流它宣告的每一個結束碼」，而那一項的前提寫著「`lint-scripts.sh` 已經證明腳本存在」。人照著讀，就會去看目錄底下有沒有那個檔名——有，於是過了。**覆核的問題本身問錯了，所以錯幾次都不會被發現。** 新那一項刻意擺在舊那一項前面，並把這段理由寫進本文，免得下一輪有人把兩項看成重複的而刪掉一項。 ## 三種判定，以及為什麼只有一種算缺失 | 類別 | 意思 | 算不算缺失 | | --- | --- | --- | | `missing` | 路徑指到不存在的檔案 | 算 | | `unrooted` | 不帶 domain 名，但檔案在這個存取庫底下 | 只算提示 | | `unknown` | 跨 domain，但那個存取庫不在這台機器上 | 只算提示 | `unrooted` 為什麼不算缺失：不帶 domain 名的相對路徑會相對於**當下的工作目錄**解。在自己那個存取庫裡跑剛好解得對，換一個工作目錄就解到別人的 `tools/` 底下，或者解不出來。兩種都沒有明確的錯誤訊息，前者更糟——它會跑起來，跑的是另一支腳本。無人值守那一輪還多一層：相對路徑進不了權限允許清單，會被靜靜擋掉。話說回來，**這是整套技能組共通的寫法，實測共 378 處**。判成缺失會讓每一個存取庫同時亮紅，而一份全紅的報告跟沒有報告一樣。所以先量出來、指得出是哪幾行，改不改由人決定。技能本文也明寫這兩種提示不得升級成決策樹項目——比照委派清單檢核的待複核與版本落後那兩種提示。 `unknown` 為什麼不算缺失：這台機器沒裝那個 domain，跟路徑寫錯，是兩件事。 ## 判定範圍與其極限只認 `tools/` 與 `hooks/` 兩個目錄底下的 `.sh`。`templates/` 與 `references/` 底下的檔案不在範圍內——那些是資料不是入口，指錯了不會變成一支跑起來的別的程式。 `README.md` 不掃：那裡的路徑是給人看的目錄，不是叫誰去跑的入口。有一類已知的誤判講白：文件在解釋「不要用不帶前綴的寫法」時，會把那個錯誤寫法原樣寫出來當例子，這一支會把那一行也算進提示。實際遇到一次，處置是改寫那句話、描述後果而不照抄寫法——那樣讀起來也更準。 ## 測試結果 - 自建一個假存取庫逐一驗七種情況：自家帶前綴檔案在（過）、自家帶前綴檔案不在（`missing`）、自家不帶前綴檔案在（`unrooted`）、自家不帶前綴檔案不在（`missing`）、跨 domain 存取庫在且檔案在（過）、跨 domain 存取庫在但檔案不在（`missing`）、跨 domain 存取庫不在（`unknown`）。七種全部符合預期，有缺失時退出 1。 - 結束碼四條路各驗一次：無參數與兩個參數都回 2，路徑不存在回 3，空存取庫回 3。 - 對十二個存取庫全掃一輪：一條 `missing` 都沒有，378 條 `unrooted`，0 條 `unknown`。 - **這一支上線當天就抓到一處真的漏改**：另一個存取庫剛送出的路徑修正只改了技能本文，`references/behaviors.md` 的關鍵步驟與外部呼叫兩欄還留著八處舊寫法，而那兩欄正是別人拿來確認一支技能會呼叫誰的地方。已經在那一邊補上。 - `lint-scripts.sh`、`lint-frontmatter.sh`、`check-behaviors.sh`、`ste100-lint.sh`、`check-link-format.sh` 對這個存取庫都回結束碼 0。 ## 前置 Push Request - `plugins/meta` 的委派清單修正那一張。兩張都動到三份 manifest 的版號，而那一張要緊——它拿掉一個會讓內建項每輪失敗的值，該先走。這一張讓到 0.3.7，等它先合併才不會撞版號。程式碼本身互不相依。

jiantw83 added 2 commits 2026-09-04 02:56:13 +00:00

feat(檢核): 新增腳本路徑檢核，判文件裡寫的路徑解不解得出來 763709ed7b

lint-scripts.sh 掃的是 tools/ 與 hooks/ 目錄裡的檔案，它證明得了「這個存取庫
裡有這支腳本」，卻證明不了「文件裡寫的那條路徑解得出那支腳本」。兩件事差
很遠，而中間那道縫剛好放得下一整類缺失。

2026-09-04 實際踩到：一份技能本文把自家腳本寫成不帶前綴的相對路徑，而那支
技能的基底目錄是 skills/{名稱}/，照字面解出來的位置沒有那個檔案，結束碼 127。
人工覆核看的是「tools/ 底下有沒有這支」，有，於是每一輪都過。覆核的問題本身
問錯了，所以錯幾次都不會被發現。

三種判定：指到不存在的檔案算缺失；不帶 domain 名但檔案在這個存取庫底下只算
提示；跨 domain 而那個存取庫不在這台機器上也只算提示。中間那一種為什麼不算
缺失——全套技能組有三百多處那樣寫，判成缺失會讓每個存取庫同時亮紅，而一份
全紅的報告跟沒有報告一樣。先量出來、指得出是哪幾行，改不改由人決定。

跨 domain 的路徑靠 plugins-root.sh 找別的存取庫，推不出來的那幾筆印成提示，
不當缺失：這台機器沒裝，跟路徑寫錯，是兩件事。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

feat(skill-check): 例行稽核第一組接上腳本路徑檢核 99871cd24f

檢核腳本沒人叫等於不存在，所以同一批把它接進第一組、接進步驟六的複跑，也
接進完成條件。

它擺在原本那一項的前面，而原本那一項正是抓不到這類缺失的理由：那一項要人
確認「本文點名的每一支腳本，呼叫端有沒有分流它宣告的每一個結束碼」，前提
寫著「lint-scripts.sh 已經證明腳本存在」。人照著讀，就會去看目錄底下有沒有
那個檔名，而不會去問那條路徑解不解得出來。這一段理由寫進了新那一項的本文，
免得下一輪有人把兩項看成重複的而刪掉一項。

unrooted 與 unknown 兩種提示明寫不得升級成決策樹項目。整套技能組有三百多處
不帶 domain 名的寫法，一次全變成待決議項會把真的缺失蓋掉——比照委派清單檢核
的待複核與版本落後那兩種提示，同樣的處置。

三份 manifest 版號從 0.3.4 升到 0.3.6，跳過中間那一號留給還沒合併的另一張。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

jiantw83 added a new dependency 2026-09-04 02:56:19 +00:00

#73 委派清單加一欄記唯讀盤點的實際指令，19 項逐項回存放庫核對

jiantw83 added 1 commit 2026-09-04 03:17:14 +00:00

chore(plugin): 版號讓到 0.3.7 2ab643c6bd

0.3.6 讓給另一張還沒合併的清單修正。那一張要緊——它拿掉一個會讓內建項每輪
失敗的值，該先走；這一張是新增檢核，晚一步沒有代價。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

jiantw83 added a new dependency 2026-09-04 03:17:20 +00:00

#75 唯讀盤點那一欄改掉一個不存在的子命令，補送上一輪沒趕上的修正

jiantw83 added 1 commit 2026-09-04 03:29:02 +00:00

Merge develop 9df303a377

三份 manifest 取分支上的較高版號：develop 那邊到 0.3.6，這條分支本來就是為了
讓開那一號才升到 0.3.7，取低的等於把版號往回退。

行為清單第 10 行兩邊各改了同一行的不同地方，合起來留：develop 加的是委派
清單檢核多判一種填錯的 probe、以及修法要回該技能的存取庫核對過再改寫；這條
分支加的是第一組多跑一項腳本路徑檢查。兩件事互不相干，取任一邊都會弄丟另
一邊。外部呼叫那一行 develop 沒動過，直接取分支上的。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

admin merged commit 58413ab808 into develop

2026-09-04 03:33:15 +00:00

admin deleted branch feat/check-skill-script-paths-resolve

2026-09-04 03:33:15 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

#73 委派清單加一欄記唯讀盤點的實際指令，19 項逐項回存放庫核對

plugins/meta

#75 唯讀盤點那一欄改掉一個不存在的子命令，補送上一輪沒趕上的修正

plugins/meta

Reference: plugins/meta#74