jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
62 lines
4.2 KiB
Markdown
62 lines
4.2 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**：`node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs"`
|
||
（其他助理請改成本 plugin 目錄下的 `scripts/persona.mjs`；以下簡稱 `persona.mjs`）
|
||
```
|
||
|
||
之後全文的指令範例一律以 `node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" <子指令>` 的形式呈現；其他助理讀到這行時，依核心規則表格自行把 `${CLAUDE_PLUGIN_ROOT}` 換成 base directory 往上兩層推導出的路徑。
|
||
|
||
（範例出處：`persona/skills/persona-chat/SKILL.md`、`persona/skills/persona-create/SKILL.md` 開頭的 `**CLI**：` 宣告行。）
|
||
|
||
兩種寫法本質是同一套「Claude Code 用環境變數、其他助理用 base directory 推導」規則的不同表達密度——寫法一把推導過程完整展開並存進一個變數方便全文引用，寫法二把推導過程收進一行宣告、後續直接照抄同一行指令模板。兩者都必須保留「絕不用相對路徑」與「解析不到就回報並停止」這兩條鐵則，不可省略。
|