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>
This commit is contained in:
2026-08-11 06:02:30 +00:00
co-authored by Claude Sonnet 5
parent d49ae1085d
commit 1030f9d403
38 changed files with 2329 additions and 139 deletions
+55
View File
@@ -0,0 +1,55 @@
---
name: spec-subagent
description: 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 且已經使用者確認 |