61 lines
4.5 KiB
Markdown
61 lines
4.5 KiB
Markdown
---
|
||
name: spec-script-path
|
||
description: JSC plugins 共用「plugin 內腳本路徑解析」規範：Claude Code 用 `${CLAUDE_PLUGIN_ROOT}`、其他助理用 skill 載入時提示的 base directory 往上兩層推導出 plugin 根目錄，絕不可用相對路徑呼叫腳本，解析不到就回報並停止。當其他 skill 內文引用 spec-script-path 或 /jsc-shared:spec-script-path、或需要呼叫 plugin 內 `scripts/` 下的腳本時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-script-path — 共用 plugin 內腳本路徑解析
|
||
|
||
skill 執行時的工作目錄是**使用者的專案目錄**，不是 plugin 根目錄，因此**絕不可用相對路徑呼叫 plugin 內的腳本**。所有 JSC skill 呼叫 `scripts/` 下的腳本前，一律先依本節解析出 plugin 根目錄，再組成絕對路徑。
|
||
|
||
## 核心規則：plugin 根目錄解析
|
||
|
||
| 環境 | plugin 根目錄 |
|
||
| --- | --- |
|
||
| Claude Code | `${CLAUDE_PLUGIN_ROOT}` |
|
||
| 其他助理 | 本 skill 載入時提示的 base directory（形如 `.../skills/<skill-name>`）往上兩層 |
|
||
|
||
- Claude Code 有現成環境變數可直接取用；其他助理沒有這個變數，只能從「skill 被載入時系統提示的 base directory」往上推導——`skills/<skill-name>` 往上兩層即為 plugin 根目錄（`<base>/../..`）。
|
||
- 兩種環境推導出的路徑**指向同一個 plugin 根目錄**，只是取得方式不同，接到 `scripts/...` 之後即為腳本絕對路徑。
|
||
|
||
## 鐵則：絕不用相對路徑重試
|
||
|
||
- 一律使用上面解析出的絕對路徑呼叫腳本；**不可**因為解析失敗就退回用相對路徑（例如 `./scripts/xxx` 或 `../scripts/xxx`）試著呼叫——工作目錄是使用者專案目錄，相對路徑幾乎必定指向錯誤位置，靜默失敗或誤動作都比明確報錯更危險。
|
||
- 解析出的路徑要實際指向存在的目錄／檔案才算解析成功，不可只組出字串就當作可用。
|
||
|
||
## 解析不到時的標準錯誤處理
|
||
|
||
解析不到 plugin 根目錄，或組出的路徑下不存在對應的 `scripts/` 內容時：
|
||
|
||
1. 回報「plugin 目錄未包含 scripts/xxx，本 skill 在此環境不可用」（`xxx` 替換為實際缺少的腳本或目錄名）。
|
||
2. 停止該 skill 的後續流程，不要改用相對路徑重試，也不要臆測其他路徑。
|
||
|
||
## 兩種合規寫法
|
||
|
||
以下兩種表達方式都符合本規範，各 skill 可依自身複雜度（是否只呼叫一個固定 CLI、或需要組多個腳本路徑）自由選用。
|
||
|
||
### 寫法一：多行版（適合需要說明推導細節、或腳本路徑本身會被多處引用的 skill）
|
||
|
||
```bash
|
||
# Claude Code
|
||
WORKLOG_DIR="${CLAUDE_PLUGIN_ROOT}/scripts/worklog"
|
||
|
||
# 其他助理：以 skill base directory 推導（<base>/../.. 即 plugin 根）
|
||
WORKLOG_DIR="<skill base directory>/../../scripts/worklog"
|
||
```
|
||
|
||
之後全文以 `${WORKLOG_DIR}` 表示該目錄，不重複解析。若解析不到或該目錄不存在，回報「plugin 目錄未包含 scripts/worklog，本 skill 在此環境不可用」並停止。
|
||
|
||
（範例出處：`doc/skills/worklog/SKILL.md` 的「腳本路徑解析（重要）」一節。）
|
||
|
||
### 寫法二：單行 CLI 宣告版（適合整個 skill 只圍繞單一 CLI 腳本的情況）
|
||
|
||
```
|
||
**CLI**：路徑與呼叫慣例見 `/jsc-shared:spec-script-path`（本 skill 為 `node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs"`，一律帶 `--session <PERSONA_SESSION>`）。
|
||
```
|
||
|
||
之後全文的指令範例一律以 `node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" <子指令>` 的形式呈現；其他助理讀到這行時，依核心規則表格自行把 `${CLAUDE_PLUGIN_ROOT}` 換成 base directory 往上兩層推導出的路徑。這一行只點出「本 skill 實際用哪支腳本、需不需要額外參數（如 `--session`）」，推導規則與絕不用相對路徑等鐵則一律回頭看本節，不在每個 skill 裡重複解釋。
|
||
|
||
（範例出處：`persona/skills/persona-chat/SKILL.md`、`persona/skills/persona-create/SKILL.md` 等 12 個 persona skill 開頭的 `**CLI**：` 宣告行，皆已收斂為此單行格式。）
|
||
|
||
兩種寫法本質是同一套「Claude Code 用環境變數、其他助理用 base directory 推導」規則的不同表達密度——寫法一把推導過程完整展開並存進一個變數方便全文引用，寫法二把推導過程收進一行宣告、後續直接照抄同一行指令模板。兩者都必須保留「絕不用相對路徑」與「解析不到就回報並停止」這兩條鐵則，不可省略。
|