Files

T

jiantw83andClaude Sonnet 5 1030f9d403 feat(shared): 新增14個共用spec、models/todo工具與樣板產生器，收斂跨repo重複規範

依 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>

2026-08-11 06:02:30 +00:00

4.2 KiB

Raw Blame History

name, description

name	description
spec-script-path	JSC plugins 共用「plugin 內腳本路徑解析」規範：Claude Code 用 `${CLAUDE_PLUGIN_ROOT}`、其他助理用 skill 載入時提示的 base directory 往上兩層推導出 plugin 根目錄，絕不可用相對路徑呼叫腳本，解析不到就回報並停止。當其他 skill 內文引用 spec-script-path 或 /jsc-shared:spec-script-path、或需要呼叫 plugin 內 `scripts/` 下的腳本時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

name

description

spec-script-path

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/ 內容時：

回報「plugin 目錄未包含 scripts/xxx，本 skill 在此環境不可用」（xxx 替換為實際缺少的腳本或目錄名）。
停止該 skill 的後續流程，不要改用相對路徑重試，也不要臆測其他路徑。

兩種合規寫法

以下兩種表達方式都符合本規範，各 skill 可依自身複雜度（是否只呼叫一個固定 CLI、或需要組多個腳本路徑）自由選用。

寫法一：多行版（適合需要說明推導細節、或腳本路徑本身會被多處引用的 skill）

# 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 推導」規則的不同表達密度——寫法一把推導過程完整展開並存進一個變數方便全文引用，寫法二把推導過程收進一行宣告、後續直接照抄同一行指令模板。兩者都必須保留「絕不用相對路徑」與「解析不到就回報並停止」這兩條鐵則，不可省略。

4.2 KiB Raw Blame History Unescape Escape