doctor 與 setup 補上路徑守則，腳本呼叫一律改成字面絕對路徑 #63

2026-09-03T05:34:02Z

jiantw83 commented

2026-09-03 05:34:02 +00:00

摘要

需求描述：doctor 與 setup 的腳本呼叫原本全是裸相對路徑，整份文件沒有任何路徑守則。相對路徑會對著操作者當下的工作目錄解，而那裡從來不是外掛根目錄，所以每一個呼叫點都是模型就地猜前綴的地方。兩支各補路徑守則與根目錄取得方式，範本與說明文件一併跟上。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`skills/doctor/SKILL.md`	新增路徑守則與前置步驟，18 處呼叫改成字面絕對路徑
`skills/setup/SKILL.md`	同上，20 處
`templates/check-contents.md`	5 處路徑改寫，並補一段路徑寫法說明。這份範本是技能在同一輪讀的，而且指示寫入
`templates/check-page.md`	2 處路徑改寫，補一行說明
`references/behaviors.md`	兩支技能的四列跟著改，並補上可稽核的路徑跡象
`README.md`	三處描述跟上，否則會與剛改好的兩份技能文件互相矛盾
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	版號 0.3.3 升到 0.3.4

設計重點

實際處數比預估多，多出來的兩類最危險。 預估 12 與 7，實際 18 與 20。多出來的是裸檔名的 Gitea 呼叫，以及被當成參數傳的資料檔（規格表、範本檔）。後者解錯地方不會報錯——它會拿另一份規格表去評這台機器，每一列都像真的發現。
兩支都不靠 current 底下那條 jsc-cli 連結，但理由各自不同。 部署那一支的理由是「第一次建起那條連結的正是這一輪」，那個理由不適用於這兩支，所以各自找了自己的：
- 體檢：它正是機器可疑時才跑的技能。觸發時機本身就是連結可能出錯的那幾個時刻——裝完或更新完、技能因設定或接線問題失敗、交接前。部署收尾若是 degraded，代表刷新連結那幾行回了 fail 或 skip，而接下來就輪到體檢。連結指著舊版時拿到的是舊的掃描腳本與舊的規格表，掃出來的每一列都像真的發現，不會有任何錯誤訊息。體檢若能靜靜地錯，就比沒有體檢更糟，因為沒有人會懷疑它。
- 修復：它寫檔，而且它要修的其中一列正是那個決定連結位置的變數。那種機器上根目錄根本解不出來，而修它要用的腳本掛在外掛基底目錄底下、不依賴那個變數，所以解不出來既不停這一輪也不擋那一項修復。另外，拿舊的寫入腳本改設定檔，再用同一份舊腳本重驗，兩邊當然對得上，整輪會報成已修——自洽地錯。
失敗分支也與部署不同。 部署解不出根目錄就停手。這兩支都不停：體檢把它記成一項發現，然後跑完不需要跨外掛的檢查——唯讀體檢中途停掉，操作者什麼都拿不到；修復把它當成待修的那一項，修好再重解一次。
自家腳本的路徑帶版本號，會跳核准詢問，這在這兩支可以接受。 兩支都是人在現場跑的：體檢印五個區塊與待修表給人看，修復逐項問過才動手。文件裡明寫這個分支不得照抄到排程跑的技能。
範本補掉兩個原本沒看到的路徑洞。 一是指向範本自己的佔位符原本沒有路徑，模型得自己發明一個；二是一個連目錄都沒有的裸檔名。
README.md 的兩處在自動同步區塊內，但同步工具會保留既有小節原文，所以這次的改動不會被下次同步洗掉。這一點在改之前確認過。

測試結果

lint-scripts.sh、check-behaviors.sh、ste100-lint.sh 對這個存放庫都回結束碼 0。
第一輪 ste100-lint.sh 抓到兩處半形逗號緊接中文詞，已改寫成不讓中文字後面接 ASCII 標點。
三個檔案都無 BOM，技能文件維持英文，行為契約維持繁體中文與全形標點。
這一批只改文件與範本，沒有可執行的腳本變動，所以沒有自動化測試可跑。改後複查兩份技能文件全文，呼叫點已無裸相對路徑。

給審閱者的一則提醒

待辦文件的 D-08 與 E-01 提議讓背景助理定期觸發 jsc-cli:doctor，理由是「doctor 本來就唯讀，只差沒人定期觸發」。

那個理由踩在一個危險的簡化上。 唯讀跟能不能無人值守跑是兩回事。這次寫進 doctor 的自家路徑分支明確接受一次核准詢問，因為操作者在現場；一旦改由排程觸發，每一輪都會停在第一支自家腳本，而且是無聲的——正是背景助理先前心跳斷掉的同一種死法。

動工前要先解掉這一項：給體檢一條不帶版本、它可以信任的連結，或是為外掛快取路徑想一套允許規則策略。警語已經寫進待辦文件的那兩列底下。setup 不受影響，它本來就維持有人值守。

前置 Push Request

無

## 摘要 - 需求描述：`doctor` 與 `setup` 的腳本呼叫原本全是裸相對路徑，整份文件沒有任何路徑守則。相對路徑會對著操作者當下的工作目錄解，而那裡從來不是外掛根目錄，所以每一個呼叫點都是模型就地猜前綴的地方。兩支各補路徑守則與根目錄取得方式，範本與說明文件一併跟上。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/doctor/SKILL.md` | 新增路徑守則與前置步驟，18 處呼叫改成字面絕對路徑 | | `skills/setup/SKILL.md` | 同上，20 處 | | `templates/check-contents.md` | 5 處路徑改寫，並補一段路徑寫法說明。這份範本是技能在同一輪讀的，而且指示寫入 | | `templates/check-page.md` | 2 處路徑改寫，補一行說明 | | `references/behaviors.md` | 兩支技能的四列跟著改，並補上可稽核的路徑跡象 | | `README.md` | 三處描述跟上，否則會與剛改好的兩份技能文件互相矛盾 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 版號 0.3.3 升到 0.3.4 | ## 設計重點 - **實際處數比預估多，多出來的兩類最危險。** 預估 12 與 7，實際 18 與 20。多出來的是裸檔名的 Gitea 呼叫，以及被當成參數傳的資料檔（規格表、範本檔）。後者解錯地方**不會報錯**——它會拿另一份規格表去評這台機器，每一列都像真的發現。 - **兩支都不靠 `current` 底下那條 `jsc-cli` 連結，但理由各自不同。** 部署那一支的理由是「第一次建起那條連結的正是這一輪」，那個理由不適用於這兩支，所以各自找了自己的： - **體檢**：它正是機器可疑時才跑的技能。觸發時機本身就是連結可能出錯的那幾個時刻——裝完或更新完、技能因設定或接線問題失敗、交接前。部署收尾若是 `degraded`，代表刷新連結那幾行回了 `fail` 或 `skip`，而接下來就輪到體檢。連結指著舊版時拿到的是舊的掃描腳本與**舊的規格表**，掃出來的每一列都像真的發現，不會有任何錯誤訊息。體檢若能靜靜地錯，就比沒有體檢更糟，因為沒有人會懷疑它。 - **修復**：它寫檔，而且它要修的其中一列正是那個決定連結位置的變數。那種機器上根目錄根本解不出來，而修它要用的腳本掛在外掛基底目錄底下、不依賴那個變數，所以解不出來既不停這一輪也不擋那一項修復。另外，拿舊的寫入腳本改設定檔，再用同一份舊腳本重驗，兩邊當然對得上，整輪會報成已修——自洽地錯。 - **失敗分支也與部署不同。** 部署解不出根目錄就停手。這兩支都不停：體檢把它記成一項發現，然後跑完不需要跨外掛的檢查——唯讀體檢中途停掉，操作者什麼都拿不到；修復把它當成待修的那一項，修好再重解一次。 - **自家腳本的路徑帶版本號，會跳核准詢問，這在這兩支可以接受。** 兩支都是人在現場跑的：體檢印五個區塊與待修表給人看，修復逐項問過才動手。文件裡明寫這個分支**不得照抄到排程跑的技能**。 - **範本補掉兩個原本沒看到的路徑洞。** 一是指向範本自己的佔位符原本沒有路徑，模型得自己發明一個；二是一個連目錄都沒有的裸檔名。 - **`README.md` 的兩處在自動同步區塊內，但同步工具會保留既有小節原文**，所以這次的改動不會被下次同步洗掉。這一點在改之前確認過。 ## 測試結果 - `lint-scripts.sh`、`check-behaviors.sh`、`ste100-lint.sh` 對這個存放庫都回結束碼 0。 - 第一輪 `ste100-lint.sh` 抓到兩處半形逗號緊接中文詞，已改寫成不讓中文字後面接 ASCII 標點。 - 三個檔案都無 BOM，技能文件維持英文，行為契約維持繁體中文與全形標點。 - 這一批只改文件與範本，沒有可執行的腳本變動，所以沒有自動化測試可跑。改後複查兩份技能文件全文，呼叫點已無裸相對路徑。 ## 給審閱者的一則提醒待辦文件的 D-08 與 E-01 提議讓背景助理定期觸發 `jsc-cli:doctor`，理由是「doctor 本來就唯讀，只差沒人定期觸發」。 **那個理由踩在一個危險的簡化上。** 唯讀跟能不能無人值守跑是兩回事。這次寫進 `doctor` 的自家路徑分支明確接受一次核准詢問，因為操作者在現場；一旦改由排程觸發，每一輪都會停在第一支自家腳本，而且是無聲的——正是背景助理先前心跳斷掉的同一種死法。動工前要先解掉這一項：給體檢一條不帶版本、它可以信任的連結，或是為外掛快取路徑想一套允許規則策略。警語已經寫進待辦文件的那兩列底下。`setup` 不受影響，它本來就維持有人值守。 ## 前置 Push Request - 無

jiantw83 added 2 commits 2026-09-03 05:34:03 +00:00

fix(doctor,setup): 兩支技能補上路徑守則，呼叫一律字面絕對路徑 5b0eb784b4

這兩支技能的腳本呼叫原本全是裸相對路徑，整份文件沒有任何路徑守則。相對路徑會對著操作者當下的工作目錄解，而那裡從來不是外掛根目錄，所以每一個呼叫點都是模型就地猜前綴的地方。部署技能原本三處相對路徑被補成帶變數路徑，就是同一個機制。

實際掃到的處數比預估多：體檢 18 處、修復 20 處。多出來的是兩類原本沒想到的——裸檔名的 Gitea 呼叫，以及被當成參數傳的資料檔。後者同樣會解錯地方，而且解錯了不會報錯。

兩支各補路徑守則與前置步驟，解出兩條根目錄：跨外掛走 current 那一層（解到那一層就停，再往下解會落到帶版本號的快取路徑，那種路徑進不了允許清單），技能自己的腳本與範本走 CLI 載入技能時講明的外掛基底目錄。

兩支都不靠 current 底下那條 jsc-cli 連結，但理由各自不同，不是照抄部署那一支的。體檢不能靠，因為它正是機器可疑時才跑的技能——觸發時機本身就是連結可能出錯的那幾個時刻，而連結指著舊版時拿到的是舊的掃描腳本與舊的規格表，掃出來的每一列都像真的發現，不會有任何錯誤訊息。修復更不能靠，因為它寫檔，而且它要修的其中一列正是那個決定連結位置的變數：那種機器上根目錄根本解不出來，而修它要用的腳本掛在外掛基底目錄底下、不依賴那個變數，所以解不出來既不停這一輪也不擋那一項修復。何況拿舊的寫入腳本改設定檔，再用同一份舊腳本重驗，兩邊當然對得上，整輪會報成已修。

失敗分支也與部署不同。部署解不出根目錄就停手；這兩支都不停——體檢把它記成一項發現然後跑完不需要跨外掛的檢查，因為唯讀體檢中途停掉操作者什麼都拿不到；修復把它當成待修的那一項，修好再重解一次。

兩份範本與說明文件一併改。範本是這兩支技能在同一輪一起讀的，而且指示寫入，留著裸路徑等於留一個繞過新規則的入口。範本裡另外補掉兩個路徑洞：指向範本自己的佔位符原本沒有路徑，以及一個連目錄都沒有的裸檔名。

行為契約四列跟著改，並補上可稽核的跡象：回報裡的腳本路徑全是字面絕對路徑，跨外掛的路徑中間是 current 那一層而不是帶版本號的快取路徑。

chore(plugin): 三份 manifest 升版至 0.3.4 56dbffa25c

兩支技能的路徑守則要靠版號才傳得到機器端。

三份 manifest 由 sync-skill-manifest.sh 同步，只動版本欄位。

admin merged commit 07c1c44e5a into develop

2026-09-03 05:35:25 +00:00

admin deleted branch fix/literal-paths-for-doctor-and-setup

2026-09-03 05:35:25 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/cli#63