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

5.2 KiB

Raw Permalink Blame History

name, description

name	description
spec-subagent	JSC plugins 共用「Subagent 派工規範」：一個明確目標派一個 subagent、subagent 只讀不寫（除非該 skill 明確授權寫入並聲明例外）、回傳結構化結果供主 agent 判讀而非直接面向使用者、派工 prompt 需帶入 /jsc-shared:spec-output 規範、不得改動原始碼與不得直接寫外部系統。當其他 skill 內文引用 spec-subagent 或 /jsc-shared:spec-subagent、或需要派 subagent／Agent 工具執行任務時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

name

description

spec-subagent

JSC plugins 共用「Subagent 派工規範」：一個明確目標派一個 subagent、subagent 只讀不寫（除非該 skill 明確授權寫入並聲明例外）、回傳結構化結果供主 agent 判讀而非直接面向使用者、派工 prompt 需帶入 /jsc-shared:spec-output 規範、不得改動原始碼與不得直接寫外部系統。當其他 skill 內文引用 spec-subagent 或 /jsc-shared:spec-subagent、或需要派 subagent／Agent 工具執行任務時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-subagent — 共用 Subagent 派工規範

所有 JSC skills 需要用 Agent／Task 工具派出 subagent 執行任務時，一律遵守以下規範。

一個明確目標派一個 subagent

派工前先把任務拆成一組明確且彼此獨立的目標（例如：一個 function、一個指令檔、一個議題、一個實作階段），再對每一個目標各派一個 subagent。
不要把多個不相關目標塞進同一個 subagent 的 prompt（例如同時要求它「分析議題 A 又順便處理議題 B」「產生文件草稿又順便改標籤」）；目標之間有明確依賴或必須共用同一份上下文時才可合併，且合併前要先確認這仍是同一個目標的不同面向，而不是把兩件事湊在一起圖方便。
目標數量不固定時（例如依議題清單、依 function 清單動態展開），一律逐一展開後才派工，不得為了省事而幾個目標共用一個 subagent。

subagent 只讀不寫

subagent 預設只讀：只讀取程式碼、設定檔、議題、留言等既有內容，不落地任何檔案、不修改任何工作目錄的原始碼。
只有在該 skill 明確授權的情況下，subagent 才可以寫入，且必須符合下列兩種之一，不得無宣告地擴大寫入範圍：
1. 寫草稿檔：僅限寫入該 skill 指定的草稿目錄（例如 .docs/ 底下），不可覆蓋或修改原始碼、原始指令檔。
2. 回傳結構化結果：不落地任何檔案，把結果整理成結構化內容回傳給主 agent（見下一節）。
派工的 skill 本身必須在文件中明確聲明subagent 被授權寫入的範圍（寫哪個目錄、哪些檔案），沒有聲明就一律視為只讀。

回傳結構化結果，不是直接面向使用者的訊息

subagent 的回傳內容是給主 agent 判讀的結構化資料（例如：判斷結果、建議異動、草稿內容、需人工確認項目清單），不是直接顯示給使用者的最終訊息。
面向使用者的輸出（回報、確認詢問、劇場模式對白等）一律由主 agent 統一組織：主 agent 收齊所有 subagent 的回傳後，才彙整、檢查、排序，最後產出面向使用者的內容。
subagent 不得自行決定要不要通知使用者、也不得自行對使用者發言（除非該 skill 明確定義 subagent 本身就是對話的一方，例如人格扮演情境下的發言）。

派工 prompt 需帶入輸出規範

派工的 prompt 內必須帶入 /jsc-shared:spec-output 的規範內容（或明確引用它），讓 subagent 知道回傳內容的語言／編碼／呈現慣例（繁體中文為主英文為輔、UTF-8 不含 BOM、優先用表格與 Mermaid 呈現、個資（PII）去識別化）。
不得省略這一步：subagent 若沒被告知輸出規範，容易產生語言混雜、編碼錯誤或洩漏個資的回傳內容，主 agent 事後才發現就必須整批重派。

subagent 不得改動原始碼

subagent 不得修改任何工作目錄內的原始碼、設定檔或既有文件，即使它判斷該怎麼改也只能在回傳內容中描述建議，交由主 agent（或使用者確認後由主 agent）實際落地。
唯一例外是該 skill 明確授權subagent 直接改動原始碼（例如某個 skill 的設計就是「派 subagent 逐項實作」），此時該 skill 文件必須清楚聲明這項例外與授權範圍，不得含糊帶過。

subagent 不得直接寫外部系統

subagent 不得直接呼叫外部系統的寫入操作，包括但不限於：Gitea（議題正文／留言／標籤／PR／看板欄位）、Wiki、以及其他任何會對外產生不易復原變更的 API。
這類寫入一律收斂到主 agent 統一執行，且必須先經使用者確認（例如透過 AskUserQuestion）才能執行；subagent 只負責讀取與分析，把「建議要寫入什麼」整理進結構化回傳內容即可。
subagent 需要讀取外部系統（例如讀議題、讀 Gitea 標籤清單）供分析用時不受此限，此節只限制寫入。

快速檢查表

檢查項目	通過條件
目標拆分	每個 subagent 對應一個明確、獨立的目標
讀寫範圍	預設只讀；若可寫，該 skill 已明確聲明授權範圍
回傳格式	結構化內容，供主 agent 判讀，非面向使用者的最終訊息
輸出規範	prompt 已帶入或引用 `/jsc-shared:spec-output`
原始碼	未改動，或該 skill 已明確授權例外
外部系統	未直接寫入 Gitea／Wiki 等，寫入交由主 agent 且已經使用者確認

5.2 KiB Raw Permalink Blame History Unescape Escape