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:
Claude Sonnet 5
@@ -0,0 +1,15 @@
|
||||
# {{PLUGIN_NAME}} — 共用 Skills（跨 AI 助理）
|
||||
|
||||
本 repo 是一組以 **Agent Skills（`SKILL.md`）** 標準撰寫的共用 skills，可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。
|
||||
|
||||
## 給 AI 助理的指引
|
||||
|
||||
- 所有可用的 skills 位於本 repo 的 `skills/<name>/SKILL.md`。
|
||||
- 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
|
||||
- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `{{CLI_PREFIX}}<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `{{CLI_PREFIX}}` 前綴，不需強制加。
|
||||
- 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
|
||||
{{EXTRA_BULLETS}}
|
||||
## 慣例
|
||||
|
||||
- 新增 skill 一律放在 `skills/<name>/`，且 `<name>` 使用小寫與連字號。
|
||||
- `description` 要寫清楚觸發條件（何時用、何時不用），這是跨助理自動載入的唯一依據。
|
||||
@@ -0,0 +1,70 @@
|
||||
# 5 份 manifest 產生規則 — 給 `gen-plugin-files.mjs` 的權威參照
|
||||
|
||||
來源：目標 repo 根目錄的 `plugin.meta.json`。以下規則把 `plugin.meta.json` 的欄位映射成五份實體檔案。所有規則已在 `gen-plugin-files.mjs` 的 `build*()` 函式中實作；本檔只作為人工審核時的對照文件，不是產生器實際讀取的樣板（manifest 用字串組裝，不走 `.tmpl` 檔案）。
|
||||
|
||||
## 共通欄位
|
||||
|
||||
| meta 欄位 | 用途 |
|
||||
| --- | --- |
|
||||
| `name` | 三份 `plugin.json` 的 `name`（`jsc-<shortName>`） |
|
||||
| `shortName` | 兩份 `marketplace.json` 的 `name`，以及安裝 token `<plugin>@<marketplace>` 的 `<marketplace>` 部分 |
|
||||
| `version` | 三份 `plugin.json` 的 `version`，**逐字複製，產生器不改版號** |
|
||||
| `descriptionCore` | 三份 `plugin.json` description 的共同語意基底 |
|
||||
| `assistants` | 助理清單，順序即統一決議順序：Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot CLI |
|
||||
| `cliPrefix` | 例如 `/jsc-code:` |
|
||||
| `callPrefixAssistants.root` / `.claudePlugin` | root、`.claude-plugin` 的 description 結尾呼叫句要指名哪個助理 |
|
||||
| `codexNote` | `.codex-plugin` description 的專屬補充資訊（可為空字串） |
|
||||
| `codexNoteAnchor`（可選） | `codexNote` 要插入 `descriptionCore` 的哪個子字串之後；缺省則整句附加在 `descriptionCore` 尾端 |
|
||||
| `skillsPath` | 三份 `plugin.json` 的 `skills` 欄位，統一不帶尾斜線 `./skills` |
|
||||
| `author` / `homepage` / `repository` / `keywords` | 原樣搬進 `.claude-plugin/plugin.json`；`repository` 也用於 `.agents/plugins/marketplace.json` 的 `source.url` |
|
||||
| `marketplace.repoDescription` | `.claude-plugin/marketplace.json` 的頂層 `description` |
|
||||
| `marketplace.pluginSummary` | `.claude-plugin/marketplace.json` 的 `plugins[0].description` |
|
||||
|
||||
## root `plugin.json`（Antigravity）
|
||||
|
||||
```
|
||||
description = strip trailing "。" of descriptionCore
|
||||
+ "；於 " + callPrefixAssistants.root + " 以 " + cliPrefix + " 前綴呼叫。"
|
||||
skills = skillsPath
|
||||
```
|
||||
|
||||
## `.claude-plugin/plugin.json`
|
||||
|
||||
1. 在 `descriptionCore` 的第一個「，」或「：」之前插入 `（<assistants.join(' / ')>）`。
|
||||
2. 去掉尾端「。」，補上「；於 `<callPrefixAssistants.claudePlugin>` 以 `<cliPrefix>` 前綴呼叫。」。
|
||||
|
||||
## `.codex-plugin/plugin.json`
|
||||
|
||||
- `codexNote` 為空字串 → `description = descriptionCore`（不加助理清單、不加呼叫句，Codex 用 `$name` 不用前綴）。
|
||||
- `codexNote` 非空、有 `codexNoteAnchor` → 在 `descriptionCore` 中該子字串**之後**插入 `codexNote`。
|
||||
- `codexNote` 非空、無 `codexNoteAnchor` → `description = descriptionCore + codexNote`（附加在句尾）。
|
||||
|
||||
## `.claude-plugin/marketplace.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": shortName,
|
||||
"description": marketplace.repoDescription,
|
||||
"owner": { "name": author.name },
|
||||
"plugins": [
|
||||
{ "name": name, "source": "./", "description": marketplace.pluginSummary }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## `.agents/plugins/marketplace.json`（Codex）
|
||||
|
||||
```json
|
||||
{
|
||||
"name": shortName,
|
||||
"plugins": [
|
||||
{ "name": name, "source": { "source": "url", "url": repository } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 已知例外／已裁決的差異（不要「修正」掉）
|
||||
|
||||
- `doc` 的 `codexNoteAnchor = "並追加到 Gitea wiki"`：`codexNote`「（自動 Stop hook 僅相容 hook 環境支援）」要插在這句之後、句尾之前，不是整句附加在最後。
|
||||
- `persona`／`code`／`shared` 的 `codexNote` 目前分別非空／空／空，依上表規則處理，不要假設四個 repo 都一樣。
|
||||
- **`marketplace` 名稱一律等於 `shortName`**（`jsc-persona@persona`，不是 `jsc-persona@jsc-plugins`）。`shared/skills/spec-plugin-cli/SKILL.md` 目前文中寫「persona 例外，marketplace 名是 `jsc-plugins`」是**過期資訊**（persona README 已明文停用 `jsc-plugins` 這個舊名），套用本規則產生器不採用該例外，此差異已回報人工覆核，是否修正 `spec-plugin-cli/SKILL.md` 由人工決定。
|
||||
@@ -0,0 +1,12 @@
|
||||
## 安裝 / 更新 / 移除（各助理）
|
||||
{{INSTALL_NOTES}}
|
||||
> 完整的安裝／更新／移除指令（Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot CLI 五種助理），一律以 [`/jsc-shared:spec-plugin-cli`](https://gitea.jsc.idv.tw/plugins/shared/src/branch/master/skills/spec-plugin-cli/SKILL.md) 為唯一權威版本，套用時代入下列佔位符：
|
||||
>
|
||||
> | 佔位符 | 值 |
|
||||
> | --- | --- |
|
||||
> | `<host>` | `{{HOST}}` |
|
||||
> | `<name>` | `{{NAME}}` |
|
||||
> | `<plugin>` | `{{PLUGIN}}` |
|
||||
> | `<marketplace>` | `{{MARKETPLACE}}` |
|
||||
> | `<token>`（= `<plugin>@<marketplace>`） | `{{TOKEN}}` |
|
||||
> | `<url>` | `{{URL}}` |
|
||||
@@ -0,0 +1,19 @@
|
||||
# README 共通章節樣板說明 — passthrough 類
|
||||
|
||||
`gen-plugin-files.mjs` 對 README.md 的五個共通章節中，以下三節目前**只重新包裝標記、內容原樣保留**（不做內容轉換），因為這三節的內文本質是各 repo 特有事實（skills 清單、目錄樹、範例指令），沒有可安全泛化的共同結構；改為由產生器在目標 repo 現有 README.md 中就地讀出整節內容，重新包在同一個章節標題下寫回，藉此仍納入「產生器管理範圍」（未來要調整寫法時，只要改產生器的抽取/重寫邏輯，不必手動改四份 README），同時保證這一步 dry-run 不會顯示非預期差異。
|
||||
|
||||
## 章節與標題（標記＝標題本身）
|
||||
|
||||
| 章節 | 標題文字（預設） | 備註 |
|
||||
| --- | --- | --- |
|
||||
| 目錄結構 | `## 目錄結構` | 含目錄樹 code block 與任何附帶的 blockquote／子章節，四個 repo 皆同標題 |
|
||||
| 用 CLI 直接執行 skill | `## 用 CLI 直接執行 skill（headless / 一次性）` | 四個 repo 皆同標題 |
|
||||
| 新增一個 skill | `## 新增一個 skill` 或 `## 新增／修改 skill` | persona 用「新增／修改 skill」，其餘三個 repo 用「新增一個 skill」；標題文字存在 `plugin.meta.json` 的 `readmeHeadings.addSkill`（省略則預設「新增一個 skill」） |
|
||||
|
||||
## 抽取規則
|
||||
|
||||
一個章節的範圍 = 從標題行開始，到下一個獨立一行的 `---` 分隔線（不含）或下一個 `## ` 標題（不含）或檔尾，取先到者。抽取後原樣寫回同一位置；只要來源 README 這三節目前的內容本身不變，dry-run 就不會顯示差異。
|
||||
|
||||
## 何時需要真正改寫
|
||||
|
||||
若某個 repo 這三節的內容需要實質變更（例如新增/刪除一個 skill 導致目錄樹要更新），仍照舊由人工編輯該 repo 的 README.md（`funcs`／`新增一個 skill` 流程本來就是手動維護這幾節）；產生器目前的職責只是「安裝章節精簡＋manifest／AGENTS.md 一致性」，不接管這三節的實質內容維護。
|
||||
@@ -0,0 +1,11 @@
|
||||
## 前綴與呼叫方式
|
||||
|
||||
| 助理 | 安裝方式 | 呼叫 | `{{CLI_PREFIX}}` 前綴 |
|
||||
| --- | --- | --- | --- |
|
||||
| Claude Code | `claude plugin`（marketplace） | `{{CLI_PREFIX}}<name>` 或自動觸發 | ✅ |
|
||||
| Codex | `codex plugin`（marketplace） | `$<name>` 或 `/skills` 選單 | ❌（用 `$name`） |
|
||||
| Antigravity | `agy plugin install` | `{{CLI_PREFIX}}<name>` 或自動觸發 | ✅ |
|
||||
| OpenCode | {{OPENCODE_INSTALL_METHOD}} | 描述需求自動觸發 | ❌（依名稱） |
|
||||
| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `{{CLI_PREFIX}}` 前綴） |
|
||||
|
||||
> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。
|
||||
Reference in New Issue
Block a user