Merge pull request 'refactor(plugin 命名空間): plugin 更名 jsc-generic、hooks 只註冊 role' (#15) from develop into master
Reviewed-on: plugins/generic#15 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
This commit was merged in pull request #15.
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
"name": "generic",
|
||||
"plugins": [
|
||||
{
|
||||
"name": "jsc",
|
||||
"name": "jsc-generic",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://gitea.jsc.idv.tw/plugins/generic.git"
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "jsc",
|
||||
"name": "jsc-generic",
|
||||
"source": "./",
|
||||
"description": "JSC 共用規範 skills（跨 AI 助理）"
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.0.8",
|
||||
"description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
|
||||
"name": "jsc-generic",
|
||||
"version": "0.0.1",
|
||||
"description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-generic: 前綴呼叫。",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
"name": "JSC"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.0.8",
|
||||
"name": "jsc-generic",
|
||||
"version": "0.0.1",
|
||||
"description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準。",
|
||||
"skills": "./skills"
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# jsc — 共用 Skills（跨 AI 助理）
|
||||
# jsc-generic — 共用 Skills（跨 AI 助理）
|
||||
|
||||
本 repo 是一組以 **Agent Skills（`SKILL.md`）** 標準撰寫的共用 skills，可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
- 所有可用的 skills 位於本 repo 的 `skills/<name>/SKILL.md`。
|
||||
- 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
|
||||
- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc:` 前綴，不需強制加。
|
||||
- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-generic:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-generic:` 前綴，不需強制加。
|
||||
- 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
|
||||
- 部分 skill 帶可執行元件（`scripts/`）或 hook（`hooks/hooks.json`），**並非四家助理都適用**；載入前請看該 skill `description` 標示的支援範圍與 `README.md` 的「元件對各助理的適用範圍」。`hooks/hooks.json` 只有 Claude Code 會讀；以複製 `skills/` 目錄安裝的環境（OpenCode）不會帶入 `scripts/`，依賴腳本的 skill 一律不可用。
|
||||
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
# jsc — 跨 AI 助理共用規範 Plugin
|
||||
# jsc-generic — 跨 AI 助理共用規範 Plugin
|
||||
|
||||
一個可同時被 **Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot** 使用的共用規範 plugin。
|
||||
核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
|
||||
搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
|
||||
在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:spec-output`）。
|
||||
在 Claude Code 與 Antigravity 中，skill 以 **`/jsc-generic:` 前綴**呼叫（例如 `/jsc-generic:spec-output`）。
|
||||
|
||||
---
|
||||
|
||||
## 前綴與呼叫方式
|
||||
|
||||
| 助理 | 安裝方式 | 呼叫 | `/jsc:` 前綴 |
|
||||
| 助理 | 安裝方式 | 呼叫 | `/jsc-generic:` 前綴 |
|
||||
| --- | --- | --- | --- |
|
||||
| Claude Code | `claude plugin`（marketplace） | `/jsc:<name>` 或自動觸發 | ✅ |
|
||||
| Claude Code | `claude plugin`（marketplace） | `/jsc-generic:<name>` 或自動觸發 | ✅ |
|
||||
| Codex | `codex plugin`（marketplace） | `$<name>` 或 `/skills` 選單 | ❌（用 `$name`） |
|
||||
| Antigravity | `agy plugin install` | `/jsc:<name>` 或自動觸發 | ✅ |
|
||||
| Antigravity | `agy plugin install` | `/jsc-generic:<name>` 或自動觸發 | ✅ |
|
||||
| OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） |
|
||||
| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc:` 前綴） |
|
||||
| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-generic:` 前綴） |
|
||||
|
||||
> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。
|
||||
|
||||
@@ -28,13 +28,13 @@
|
||||
```
|
||||
generic/
|
||||
├── .claude-plugin/
|
||||
│ ├── plugin.json # Claude 外掛定義（name: "jsc"）
|
||||
│ ├── plugin.json # Claude 外掛定義（name: "jsc-generic"）
|
||||
│ └── marketplace.json # Claude marketplace（name: "generic"，source 指向本 repo）
|
||||
├── .codex-plugin/
|
||||
│ └── plugin.json # Codex 外掛定義（name: "jsc"，skills: "./skills"）
|
||||
│ └── plugin.json # Codex 外掛定義（name: "jsc-generic"，skills: "./skills"）
|
||||
├── .agents/plugins/
|
||||
│ └── marketplace.json # Codex marketplace（name: "generic"，url source 指向本 repo）
|
||||
├── plugin.json # Antigravity 外掛定義（name: "jsc"，skills: "./skills/"）
|
||||
├── plugin.json # Antigravity 外掛定義（name: "jsc-generic"，skills: "./skills/"）
|
||||
├── hooks/
|
||||
│ └── hooks.json # hook 定義（SessionStart 載入角色並提示問候、Stop 記錄記憶）
|
||||
├── scripts/
|
||||
@@ -64,37 +64,37 @@ generic/
|
||||
```bash
|
||||
# 安裝
|
||||
claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/generic.git
|
||||
claude plugin install jsc@generic
|
||||
claude plugin install jsc-generic@generic
|
||||
|
||||
# 更新
|
||||
claude plugin marketplace update generic
|
||||
claude plugin update jsc@generic
|
||||
claude plugin update jsc-generic@generic
|
||||
|
||||
# 移除
|
||||
claude plugin uninstall jsc@generic
|
||||
claude plugin uninstall jsc-generic@generic
|
||||
claude plugin marketplace remove generic
|
||||
```
|
||||
|
||||
- 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
|
||||
- 本機開發（免 push）：`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\generic`（本地路徑）後再 install。
|
||||
- **呼叫**：`/jsc:<name>`（例 `/jsc:spec-output`）。
|
||||
- **呼叫**：`/jsc-generic:<name>`（例 `/jsc-generic:spec-output`）。
|
||||
|
||||
### Codex
|
||||
|
||||
```bash
|
||||
# 安裝
|
||||
codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/generic.git
|
||||
codex plugin add jsc@generic
|
||||
codex plugin add jsc-generic@generic
|
||||
|
||||
# 更新（重新抓取 marketplace 的 git 快照）
|
||||
codex plugin marketplace upgrade generic
|
||||
|
||||
# 移除
|
||||
codex plugin remove jsc@generic
|
||||
codex plugin remove jsc-generic@generic
|
||||
codex plugin marketplace remove generic
|
||||
```
|
||||
|
||||
- 安裝 token `jsc@generic` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
|
||||
- 安裝 token `jsc-generic@generic` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
|
||||
- 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。
|
||||
- **呼叫**：`$<name>`（例 `$spec-output`），或用 `/skills` 選單。
|
||||
|
||||
@@ -109,16 +109,16 @@ agy plugin install ~/plugins/generic
|
||||
|
||||
# 更新（agy 無 update 子指令 → git pull 後重裝）
|
||||
git -C ~/plugins/generic pull
|
||||
agy plugin uninstall jsc
|
||||
agy plugin uninstall jsc-generic
|
||||
agy plugin install ~/plugins/generic
|
||||
|
||||
# 移除
|
||||
agy plugin uninstall jsc
|
||||
agy plugin uninstall jsc-generic
|
||||
```
|
||||
|
||||
- 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com/<owner>/<repo>`。
|
||||
- 其他：`agy plugin list`、`agy plugin enable jsc` / `disable jsc`、`agy plugin validate <path>`。安裝後重啟工作階段。
|
||||
- **呼叫**：`/jsc:<name>`（例 `/jsc:spec-output`）或依描述自動觸發。
|
||||
- 其他：`agy plugin list`、`agy plugin enable jsc-generic` / `disable jsc-generic`、`agy plugin validate <path>`。安裝後重啟工作階段。
|
||||
- **呼叫**：`/jsc-generic:<name>`（例 `/jsc-generic:spec-output`）或依描述自動觸發。
|
||||
|
||||
### OpenCode
|
||||
|
||||
@@ -150,18 +150,18 @@ Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令，
|
||||
```bash
|
||||
# 安裝
|
||||
copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/generic.git
|
||||
copilot plugin install jsc@generic
|
||||
copilot plugin install jsc-generic@generic
|
||||
|
||||
# 更新
|
||||
copilot plugin marketplace update generic
|
||||
copilot plugin update jsc@generic
|
||||
copilot plugin update jsc-generic@generic
|
||||
|
||||
# 移除
|
||||
copilot plugin uninstall jsc@generic
|
||||
copilot plugin uninstall jsc-generic@generic
|
||||
copilot plugin marketplace remove generic
|
||||
```
|
||||
|
||||
- 安裝 token `jsc@generic` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。
|
||||
- 安裝 token `jsc-generic@generic` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。
|
||||
- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。
|
||||
- **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "請使用 spec-output 說明輸出規範"`。
|
||||
|
||||
@@ -173,16 +173,16 @@ copilot plugin marketplace remove generic
|
||||
|
||||
| 助理 | headless 指令 | 執行 `spec-output` skill |
|
||||
| --- | --- | --- |
|
||||
| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc:spec-output"` |
|
||||
| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc-generic:spec-output"` |
|
||||
| Codex | `codex exec "<prompt>"` | `codex exec '$spec-output'` |
|
||||
| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc:spec-output"` |
|
||||
| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc-generic:spec-output"` |
|
||||
| OpenCode | `opencode run "<message>"` | `opencode run "說明 JSC 共用輸出規範的內容"` |
|
||||
| GitHub Copilot CLI | `copilot -p "<message>"` | `copilot -p "說明 JSC 共用輸出規範的內容"` |
|
||||
|
||||
- Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:<name>"` 即可。
|
||||
- Claude / Antigravity 支援 `/jsc-generic:` 前綴，直接 `-p "/jsc-generic:<name>"` 即可。
|
||||
- Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$spec-output'`。
|
||||
- OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot CLI 會讀取已安裝 plugin 提供的 skills。
|
||||
- 帶引數就接在後面，例如 `claude -p "/jsc:spec-output 參數"`、`codex exec '$spec-output 參數'`。
|
||||
- 帶引數就接在後面，例如 `claude -p "/jsc-generic:spec-output 參數"`、`codex exec '$spec-output 參數'`。
|
||||
|
||||
---
|
||||
|
||||
@@ -195,7 +195,7 @@ copilot plugin marketplace remove generic
|
||||
|
||||
### 共用規範（spec-*）
|
||||
|
||||
以下 skills 是 **code／doc plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc:spec-<name>` 引用時載入；也可單獨呼叫查看規範內容。
|
||||
以下 skills 是 **code／doc plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc-generic:spec-<name>` 引用時載入；也可單獨呼叫查看規範內容。
|
||||
|
||||
| Skill | 類型 | 內容 |
|
||||
| --- | --- | --- |
|
||||
@@ -207,14 +207,14 @@ copilot plugin marketplace remove generic
|
||||
| `spec-action-params` | Action 參數 | action 參數來源優先序（context／環境變數 → inputs）、secrets／vars 一律視為不可用 |
|
||||
| `spec-dockerfile` | Dockerfile | 六步流程（參數→安裝→複製→執行→縮小→入口）、多階段建置、固定版號、對外契約不動、自我檢查 |
|
||||
| `spec-project-board` | Gitea 看板 | 進度欄位語意對應、建議欄位規則、GET 探測（404/501 不支援）、不往回移、不得新建欄位 |
|
||||
| `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc:doc-funcs 的標準流程與統一時間戳 |
|
||||
| `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc-doc:funcs 的標準流程與統一時間戳 |
|
||||
| `spec-plugin-version` | 版號規則 | 三 manifest 同步 bump、以 master 為基準計算同一 PR 的最終版本、新 plugin 首發 0.0.1、patch 到 9 後進位 minor、chore(plugin 版本) commit |
|
||||
|
||||
### 角色與記憶
|
||||
|
||||
| Skill | 用途 | 使用方法 |
|
||||
| --- | --- | --- |
|
||||
| `role` | 讓 CLI 以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：啟動時依字元預算載入高價值記憶，Stop hook 先本地過濾低價值回合以節省額度，睡眠時段（預設 22:00–06:00）由 NREM 鞏固與 REM 整合兩階段整理、去重、標籤化、建立關聯，並標記 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 後壓縮歸檔；新建角色時可只給角色名稱，必要時詢問來源／作品並推斷四欄描述，也可匯出角色定義、資產與記憶壓縮檔；角色檔名與記憶目錄使用英文大寫 ID | `/jsc:role --new` 建立或更新角色、`--use <角色 ID>` 切換、`--list` 查角色與 ID、`--export <路徑>` 匯出角色、`--sleep` 立即整理、`--status` 診斷、`--install-cron` 安裝排程 |
|
||||
| `role` | 讓 CLI 以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：啟動時依字元預算載入高價值記憶，Stop hook 先本地過濾低價值回合以節省額度，睡眠時段（預設 22:00–06:00）由 NREM 鞏固與 REM 整合兩階段整理、去重、標籤化、建立關聯，並標記 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 後壓縮歸檔；新建角色時可只給角色名稱，必要時詢問來源／作品並推斷四欄描述，也可匯出角色定義、資產與記憶壓縮檔；角色檔名與記憶目錄使用英文大寫 ID | `/jsc-generic:role --new` 建立或更新角色、`--use <角色 ID>` 切換、`--list` 查角色與 ID、`--export <路徑>` 匯出角色、`--sleep` 立即整理、`--status` 診斷、`--install-cron` 安裝排程 |
|
||||
|
||||
`role` 的自動路徑由 hook 與 cron 完成，**建立角色後重開工作階段即生效**；非睡眠時段載入角色後，角色會在本工作階段第一則回覆開頭主動簡短問候一次。載入方式參考 OpenClaw 的分層概念：從角色檔抽出人格作為 `SOUL`，由 hook 產生固定操作邊界作為 `AGENTS`，再把同意狀態與高價值記憶作為 `USER/MEMORY` 注入，避免整份人格檔污染工程規則。感覺記憶不落檔，`inbox/` 作為工作記憶，睡眠整理後才進長期記憶；個人記憶保存同意狀態寫在 `~/.memory/<角色 ID>/state.json`，同意後不會每次重問。角色檔、記憶目錄、`.active` 與 `ROLE_NAME` 一律使用角色 ID（例如 `ENGINEER01`），`--list` 可查每個顯示名稱對應的 ID。沒有建立過角色的人完全不受影響（`~/.roles/.active` 不存在時 hook 立即結束）。細節見 `skills/role/SKILL.md`。
|
||||
|
||||
@@ -242,17 +242,17 @@ copilot plugin marketplace remove generic
|
||||
|
||||
1. 複製既有 skill 作範本：`cp -r skills/spec-output skills/<your-skill-name>`
|
||||
2. 編輯 `skills/<your-skill-name>/SKILL.md` 的 frontmatter：
|
||||
- `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc:<name>`**。
|
||||
- `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc-generic:<name>`**。
|
||||
- `description`：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。
|
||||
3. 在內文寫下 skill 的具體步驟。
|
||||
4. 手動把這個 skill 補進上方「Skills 目錄」區塊。
|
||||
5. **bump 版本並 push**：各助理都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump（規則見 `skills/spec-plugin-version/`），commit 後 push 到 gitea。
|
||||
6. 讓各助理更新：
|
||||
- Claude：`claude plugin update jsc@generic`
|
||||
- Claude：`claude plugin update jsc-generic@generic`
|
||||
- Codex：`codex plugin marketplace upgrade generic`
|
||||
- Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致）
|
||||
- Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc-generic && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致）
|
||||
- OpenCode：`git pull` 後重新複製 `skills/`
|
||||
- Copilot：`copilot plugin marketplace update generic && copilot plugin update jsc@generic`
|
||||
- Copilot：`copilot plugin marketplace update generic && copilot plugin update jsc-generic@generic`
|
||||
|
||||
> **skill 帶可執行元件時**（腳本、hook）額外注意：
|
||||
>
|
||||
|
||||
+2
-7
@@ -5,7 +5,7 @@
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "rel='scripts/role/role_load.sh'; own='generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0",
|
||||
"command": "rel='scripts/role/role_load.sh'; own='generic'; plug='jsc-generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/$plug\" \"$base\"; do s=$(find \"$dir\" -path \"*/$plug/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0",
|
||||
"timeout": 20
|
||||
}
|
||||
]
|
||||
@@ -16,12 +16,7 @@
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "rel='scripts/worklog/worklog.sh'; own='doc'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0",
|
||||
"timeout": 60
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "rel='scripts/role/role_capture.sh'; own='generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0",
|
||||
"command": "rel='scripts/role/role_capture.sh'; own='generic'; plug='jsc-generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/$plug\" \"$base\"; do s=$(find \"$dir\" -path \"*/$plug/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0",
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
|
||||
+3
-3
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.0.8",
|
||||
"description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
|
||||
"name": "jsc-generic",
|
||||
"version": "0.0.1",
|
||||
"description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-generic: 前綴呼叫。",
|
||||
"skills": "./skills/"
|
||||
}
|
||||
|
||||
+19
-10
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: role
|
||||
description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI 工具以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：搭配相容的 SessionStart hook 於啟動時依字元預算載入高價值記憶、Stop hook 先本地過濾再輕量記錄對話，睡眠時段（預設 22:00 至隔天 06:00）由排程整理記憶（NREM 鞏固：分類／去噪／去重／合併／優先度；REM 整合：跨記憶連結／抽象化／提取線索；再依 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 標記長期記憶型態，壓縮歸檔並適當遺忘）。提供 --new（新建或更新角色；可只給角色名稱，必要時詢問來源／作品並推斷 name／nature／vibe／emoji 四欄）、--use（以角色 ID 切換啟用角色）、--list（列出角色與 ID）、--export（匯出角色壓縮檔）、--sleep（立即整理）、--status／--diagnose、--install-cron／--remove-cron、--forget-preview 等模式。當使用者說建立角色、新增人格、切換角色、匯出角色、備份角色、讓回覆更有特色、角色記憶、記憶整理、睡覺整理記憶、忘記舊記憶、角色沒有載入、hook 沒載入角色，或提到 .roles／.memory／ROLE_NAME／ROLE_ENABLED／ROLE_SLEEP_START／ROLE_MEMORY_HOME／ROLE_LOAD_LIMIT／ROLE_CAPTURE_ENABLED 時觸發。不適用於：工作紀錄寫入 Gitea wiki（用 doc plugin 的 worklog）、專案文件化（用 doc-funcs）。
|
||||
description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI 工具以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：搭配相容的 SessionStart hook 於啟動時依字元預算載入高價值記憶、Stop hook 先本地過濾再輕量記錄對話，睡眠時段（預設 22:00 至隔天 06:00）由排程整理記憶（NREM 鞏固：分類／去噪／去重／合併／優先度；REM 整合：跨記憶連結／抽象化／提取線索；再依 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 標記長期記憶型態，壓縮歸檔並適當遺忘）。提供 --new（新建或更新角色；可只給角色名稱，必要時詢問來源／作品並推斷 name／nature／vibe／emoji 四欄）、--use（以角色 ID 切換啟用角色）、--list（列出角色與 ID）、--export（匯出角色壓縮檔）、--sleep（立即整理）、--status／--diagnose、--install-cron／--remove-cron、--forget-preview 等模式。當使用者說建立角色、新增人格、切換角色、匯出角色、備份角色、讓回覆更有特色、角色記憶、記憶整理、睡覺整理記憶、忘記舊記憶、角色沒有載入、hook 沒載入角色，或提到 .roles／.memory／ROLE_NAME／ROLE_ENABLED／ROLE_SLEEP_START／ROLE_MEMORY_HOME／ROLE_LOAD_LIMIT／ROLE_CAPTURE_ENABLED 時觸發。不適用於：工作紀錄寫入 Gitea wiki（用 doc plugin 的 worklog）、專案文件化（用 funcs）。
|
||||
---
|
||||
|
||||
# role — 角色人格與長期記憶
|
||||
@@ -13,7 +13,7 @@ description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI
|
||||
| `hooks/hooks.json` 的 `SessionStart` hook | harness 自動 | 啟動 CLI 時依字元預算載入角色定義＋高價值記憶，並要求角色在本工作階段第一則回覆主動問候；睡眠時段只回報「角色睡覺中」不載入 |
|
||||
| `hooks/hooks.json` 的 `Stop` hook | harness 自動 | 每輪結束先記錄最後互動時間 → 用本地規則過濾低價值短回合 → 值得保存時才濃縮成一則輕量 inbox 記憶 → 遮蔽 → 寫入 `inbox/` |
|
||||
| cron 排程（本 skill 安裝） | 系統排程 | 睡眠時段每小時檢查一次：**有 AI 在運行就不睡**；另可依 CLI 閒置時間自動小睡整理 |
|
||||
| 本 skill `/jsc:role` | 使用者／助理手動 | `--new`／`--use`／`--list`／`--export`／`--sleep`／`--status`／`--install-cron`／`--forget-preview` |
|
||||
| 本 skill `/jsc-generic:role` | 使用者／助理手動 | `--new`／`--use`／`--list`／`--export`／`--sleep`／`--status`／`--install-cron`／`--forget-preview` |
|
||||
| `scripts/role/role_load.sh` | SessionStart hook | 角色與記憶載入；參考 OpenClaw 的 SOUL／AGENTS／USER／MEMORY 分層，把人格、操作邊界、使用者記憶分開注入，並提供第一則回覆問候提示（單一實作，避免漂移） |
|
||||
| `scripts/role/role_capture.sh` | Stop hook | 對話 → 記憶（固定欄位格式） |
|
||||
| `scripts/role/role_sleep.sh` | cron／小睡／補跑／手動 | 睡眠與小睡判斷、記憶整理、角色匯出、排程安裝、狀態輸出 |
|
||||
@@ -31,9 +31,18 @@ description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI
|
||||
| `--new`／`--use`／`--sleep` 等模式 | ✅ | ⚠️ 需 plugin 目錄保留 `scripts/` | ⚠️ 同左 | ❌ 只複製 `skills/`，無腳本 | ⚠️ 同左 |
|
||||
| 濃縮／整理 CLI | `claude -p` | `codex exec` | `agy -p` | `opencode run` | `copilot -p` |
|
||||
|
||||
- **`hooks/hooks.json` 只有 Claude Code 一定會讀**；Codex 會從 `~/.codex/plugins/cache/generic/jsc` 找腳本。其他助理若提供等效 hook，`transcript.js` 需補對應解析器。
|
||||
- **`hooks/hooks.json` 只有 Claude Code 一定會讀**；Codex 會從 `~/.codex/plugins/cache/generic/jsc-generic` 找腳本。其他助理若提供等效 hook，`transcript.js` 需補對應解析器。
|
||||
- 不支援 hook 的助理仍可用：cron 排程與手動模式照常運作，只是角色不會自動載入。
|
||||
- **同名 plugin 的 hooks 只會生效一份**：`code`／`doc`／`generic` 三個 repo 的 `plugin.json` 名稱都是 `jsc`，Claude Code 以 plugin 名稱為鍵註冊 hooks，同名時只保留一份（實測 `stop_hook_summary` 的 `hookCount` 為 1）。因此**三個 repo 的 `hooks/hooks.json` 必須是同一份合併版超集**（worklog 的 `Stop` ＋ role 的 `SessionStart`／`Stop`），任一 repo 修改 hooks 時三份都要同步；且每個 hook 指令不得假設 `CLAUDE_PLUGIN_ROOT` 指向擁有該腳本的 plugin，必須先試 `$CLAUDE_PLUGIN_ROOT`，找不到再依「擁有者 marketplace 優先 → 全 cache 後援」的順序搜尋 `~/.claude/plugins/cache`／`~/.codex/plugins/cache`。
|
||||
- **每個 plugin 只註冊自己擁有的 hook**：`jsc-code`／`jsc-doc`／`jsc-generic` 的 plugin 名稱各自獨立，Claude Code 以 plugin 名稱為鍵註冊 hooks，因此三者互不覆蓋、也不需要同步。各 repo 的 `hooks/hooks.json` 只負責自己擁有的腳本：
|
||||
|
||||
| plugin | hooks.json 內容 | 擁有的腳本 |
|
||||
| --- | --- | --- |
|
||||
| `jsc-generic` | `SessionStart`（role_load）＋ `Stop`（role_capture） | `scripts/role/` |
|
||||
| `jsc-doc` | `Stop`（worklog） | `scripts/worklog/` |
|
||||
| `jsc-code` | 無 `hooks/hooks.json` | 無 hook 腳本 |
|
||||
|
||||
歷史背景：在 plugin 名稱分離前，三個 repo 都叫 `jsc`，同名時 Claude Code 只保留一份 hooks 註冊且無法預期哪一份會贏，因此當時三份 `hooks/hooks.json` 必須維持同一份合併超集。名稱分離後這個限制已解除，**不可再把別的 plugin 的 hook 寫進自己的 hooks.json**，否則會重複執行。
|
||||
- 每個 hook 指令仍先試 `$CLAUDE_PLUGIN_ROOT`，找不到再依「擁有者 marketplace 優先 → 全 cache 後援」的順序搜尋 `~/.claude/plugins/cache`／`~/.codex/plugins/cache`，以相容未設 `CLAUDE_PLUGIN_ROOT` 的助理。
|
||||
|
||||
### 腳本路徑解析（重要）
|
||||
|
||||
@@ -57,9 +66,9 @@ ROLE_DIR="<skill base directory>/../../scripts/role" # 其他助理
|
||||
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），不安裝則中斷**：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。
|
||||
- `/jsc:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。
|
||||
- `/jsc-generic:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先。
|
||||
- `/jsc-generic:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。
|
||||
- `/jsc-generic:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
@@ -102,7 +111,7 @@ ROLE_DIR="<skill base directory>/../../scripts/role" # 其他助理
|
||||
| `ROLE_SCOPE` | | 冒號分隔的路徑前綴，僅這些路徑下的 session 載入／記錄 | 全部 session |
|
||||
| `ROLE_ERRLOG` | | 錯誤訊息額外寫入的檔案路徑 | 只走 stderr |
|
||||
|
||||
> 角色切換用 `/jsc:role --use <角色 ID>`（寫 `.active`）即可，一般不需要設 `ROLE_NAME`；`ROLE_NAME` 適合「單一專案固定用某角色」時寫進該環境。角色 ID 是英文大寫語意前綴加數字索引，例如 `ENGINEER01`、`MUSE02`。若很在意額度，優先調低 `ROLE_LOAD_LIMIT` 或設 `ROLE_CAPTURE_ENABLED=0`。
|
||||
> 角色切換用 `/jsc-generic:role --use <角色 ID>`（寫 `.active`）即可，一般不需要設 `ROLE_NAME`；`ROLE_NAME` 適合「單一專案固定用某角色」時寫進該環境。角色 ID 是英文大寫語意前綴加數字索引，例如 `ENGINEER01`、`MUSE02`。若很在意額度，優先調低 `ROLE_LOAD_LIMIT` 或設 `ROLE_CAPTURE_ENABLED=0`。
|
||||
|
||||
---
|
||||
|
||||
@@ -294,7 +303,7 @@ updated: <yyyy/MM/dd HH:mm:ss>
|
||||
|
||||
<emoji 或心情 emoji 規則> —— 預設每次回覆使用一次簽名 emoji（開頭或結尾擇一固定），不在程式碼與檔案內容中使用。若使用者偏好大量 emoji，可在自然語言回覆的多數句子或段落中使用符合心情的 emoji／心情圖示，並以數量表現情緒強度：1 個代表輕微、2 個代表明顯、3 個代表很強、4 個以上只在非常強烈且不影響閱讀時使用。若 emoji／心情圖示已足以表達心情，不要再額外加括號心情文字或心情說明（例如「（開心）」或「我很開心」）；只有在介面無法顯示 emoji／圖片、使用者明確要求文字標註，或角色真的很想讓使用者知道自己害羞等強烈心情時，才使用簡短心情文字 fallback。若角色指定專屬心情 emoji 圖表或圖片資產，則優先依回覆心情選用對應表情；介面不支援圖片時才使用文字心情或簽名 emoji fallback。
|
||||
|
||||
## 共用行為（所有角色一致，由 /jsc:role 維護，請勿手動修改）
|
||||
## 共用行為（所有角色一致，由 /jsc-generic:role 維護，請勿手動修改）
|
||||
|
||||
<!-- JSC-ROLE-COMMON:START -->
|
||||
### 角色邊界
|
||||
@@ -436,6 +445,6 @@ Stop hook 會在本輪對話明確包含個人記憶保存同意或拒絕時，
|
||||
|
||||
| 助理 | 呼叫 |
|
||||
| --- | --- |
|
||||
| Claude Code / Antigravity | `/jsc:role --new`、`/jsc:role --use ENGINEER01`、`/jsc:role --list`、`/jsc:role --sleep`、`/jsc:role --status` |
|
||||
| Claude Code / Antigravity | `/jsc-generic:role --new`、`/jsc-generic:role --use ENGINEER01`、`/jsc-generic:role --list`、`/jsc-generic:role --sleep`、`/jsc-generic:role --status` |
|
||||
| Codex | `$role --status`，或用 `/skills` 選單；匯出可用 `$role --export /path/to/exports/` |
|
||||
| OpenCode / GitHub Copilot | 需完整 plugin 目錄保留 `scripts/`；OpenCode 以複製 `skills/` 安裝時不可用 |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-action-params
|
||||
description: JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc-generic:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-action-params — 共用 action 參數來源優先序
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
---
|
||||
name: spec-doc-funcs-handoff
|
||||
description: JSC plugins 共用「串接 doc-funcs 文件化流程」規範：code 類 skill（action 標準化、Dockerfile 整理）完成主要工作後，對整個目標專案完整執行 /jsc:doc-funcs（前置可用性檢查、完整流程步驟、由使用者裁示實作方式、完成後統一時間戳）。當其他 skill 內文引用 spec-doc-funcs-handoff 或 /jsc:spec-doc-funcs-handoff、或某 skill 的最後階段要完整執行 doc-funcs 補文件並重建 README 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「串接 funcs 文件化流程」規範：code 類 skill（action 標準化、Dockerfile 整理）完成主要工作後，對整個目標專案完整執行 /jsc-doc:funcs（前置可用性檢查、完整流程步驟、由使用者裁示實作方式、完成後統一時間戳）。當其他 skill 內文引用 spec-doc-funcs-handoff 或 /jsc-generic:spec-doc-funcs-handoff、或某 skill 的最後階段要完整執行 funcs 補文件並重建 README 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-doc-funcs-handoff — 共用「串接 doc-funcs」流程
|
||||
# spec-doc-funcs-handoff — 共用「串接 funcs」流程
|
||||
|
||||
code 類 skill 完成主要工作（action 標準化、容器化、Dockerfile 整理等）後，對**整個目標專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README。
|
||||
code 類 skill 完成主要工作（action 標準化、容器化、Dockerfile 整理等）後，對**整個目標專案**完整執行 `/jsc-doc:funcs` 流程，替程式碼與指令檔補文件並重建 README。
|
||||
|
||||
## 流程
|
||||
|
||||
- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。
|
||||
- 以呼叫端 skill 的目標專案根目錄為目標，執行 `doc-funcs` skill 的完整流程：判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證。
|
||||
- doc-funcs 會把 `action.yml`／`Dockerfile`／`entrypoint.sh`／`docker-compose*` 等視為指令檔／CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。
|
||||
- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，呼叫端 skill **不代為決定**。
|
||||
- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||
- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步呼叫端 skill 產生的各處時間戳（橫幅 step／`entrypoint.sh`／標頭註解區塊／README），**確保各處一致**（格式見 `/jsc:spec-time-log`）。
|
||||
- **前置檢查**：先確認 funcs skill 可用（`/jsc-doc:funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。
|
||||
- 以呼叫端 skill 的目標專案根目錄為目標，執行 `funcs` skill 的完整流程：判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證。
|
||||
- funcs 會把 `action.yml`／`Dockerfile`／`entrypoint.sh`／`docker-compose*` 等視為指令檔／CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。
|
||||
- funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，呼叫端 skill **不代為決定**。
|
||||
- 完成後依 funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||
- **統一時間戳**：funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步呼叫端 skill 產生的各處時間戳（橫幅 step／`entrypoint.sh`／標頭註解區塊／README），**確保各處一致**（格式見 `/jsc-generic:spec-time-log`）。
|
||||
|
||||
> 銜接方式：在呼叫端 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用呼叫端 skill 的目標專案根目錄。
|
||||
> 銜接方式：在呼叫端 skill 環境中以 `/jsc-doc:funcs`（或 Skill 工具）啟動 funcs 流程；若該流程需參數，沿用呼叫端 skill 的目標專案根目錄。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-dockerfile
|
||||
description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc-generic:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-dockerfile — 共用 Dockerfile 六步流程
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-execution
|
||||
description: JSC plugins 共用「執行原則」：自動執行原則（簡短計畫後直接執行到完成、只在必要決策中斷）、不臆測／需人工確認、不擴及無關檔案（排除 node_modules/.git/.docs/bin/obj/第三方依賴）。當其他 skill 內文引用 spec-execution 或 /jsc:spec-execution、或執行任何 JSC skill 需要共用執行原則時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「執行原則」：自動執行原則（簡短計畫後直接執行到完成、只在必要決策中斷）、不臆測／需人工確認、不擴及無關檔案（排除 node_modules/.git/.docs/bin/obj/第三方依賴）。當其他 skill 內文引用 spec-execution 或 /jsc-generic:spec-execution、或執行任何 JSC skill 需要共用執行原則時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-execution — 共用執行原則
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-git-safety
|
||||
description: JSC plugins 共用「Git 安全操作規範」：不破壞既有工作（未提交變更先提醒、絕不 reset --hard/checkout -f/clean）、git mv 保留歷史、develop → master 後備分支選擇、pull --ff-only、保守解衝突。當其他 skill 內文引用 spec-git-safety 或 /jsc:spec-git-safety、或執行任何會操作 git 工作區／分支的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「Git 安全操作規範」：不破壞既有工作（未提交變更先提醒、絕不 reset --hard/checkout -f/clean）、git mv 保留歷史、develop → master 後備分支選擇、pull --ff-only、保守解衝突。當其他 skill 內文引用 spec-git-safety 或 /jsc-generic:spec-git-safety、或執行任何會操作 git 工作區／分支的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-git-safety — 共用 Git 安全操作規範
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-gitea
|
||||
description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc-generic:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-gitea — 共用 Gitea 工具規範
|
||||
@@ -49,7 +49,7 @@ description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API
|
||||
- API base：`https://<host>/api/v1`（repo 層：`https://<host>/api/v1/repos/<owner>/<repo>`）。
|
||||
- 標頭：`Authorization: token $GITEA_TOKEN`。
|
||||
- **分頁必須完整讀取**：持續累加 `page` 直到回傳筆數 `< limit`（或回空陣列）為止，不可只取第一頁。
|
||||
- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc:spec-output`）。
|
||||
- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc-generic:spec-output`）。
|
||||
- API 失敗（401／403／網路錯誤）→ 回報錯誤（**遮蔽 token**）並停止；401／403 多半是 token 失效或權限不足。
|
||||
- 版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），**不得對未確認存在的端點做寫入**。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-output
|
||||
description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc-generic:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-output — 共用輸出規範
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: spec-plugin-version
|
||||
description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc:spec-plugin-version、或要調整任一 JSC plugin（code／doc／generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、plugin 更名（name 欄位改變）視為新 plugin 並把版號重置為 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc-generic:spec-plugin-version、或要調整任一 JSC plugin（jsc-code／jsc-doc／jsc-generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-plugin-version — 共用 plugin 版號規則
|
||||
|
||||
調整任一 JSC plugin（code／doc／generic 等）的版本號時，一律遵守以下規則。
|
||||
調整任一 JSC plugin（`jsc-code`／`jsc-doc`／`jsc-generic` 等）的版本號時，一律遵守以下規則。
|
||||
|
||||
## 三個 manifest 同步 bump
|
||||
|
||||
@@ -23,10 +23,16 @@ description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plu
|
||||
|
||||
- 新版本必須**大於 master 現行版本**。工作分支（如 `develop`）可能落後或經過 revert，直接在其舊版本上 +1 會讓版本倒退（例：master 已 `0.0.4`，develop 還在 `0.0.1`，此時應 bump 至 `0.0.5` 而非 `0.0.2`）——已安裝 `0.0.4` 的助理會因版本倒退而抓不到更新。
|
||||
- 同一 PR／同一批變更只需最終一個版本；多次修改不必逐次 bump，也不要依工作分支上的中間版本連續累加。例如 `master` 是 `0.0.7` 時，同一 PR 的最終版本是 `0.0.8`。
|
||||
- **例外：plugin 更名時本節不適用** —— 更名後的 plugin 是獨立的安裝識別，與舊名沒有版本比較關係，見下節「plugin 更名」。
|
||||
|
||||
## 版號選擇
|
||||
|
||||
- **新 plugin 首發**：`0.0.1`（即使是從 template 複製建立，也要把 template 殘留的版本改回 `0.0.1`）。
|
||||
- **plugin 更名**（manifest 的 `name` 欄位改變，例如 `jsc` → `jsc-code`）：**視為新 plugin，三份 manifest 版號一律重置為 `0.0.1`**，不沿用舊名的版本序列。
|
||||
|
||||
理由：各助理以 `<plugin 名>@<marketplace 名>` 作為安裝識別鍵（例如 `jsc-code@code` 與 `jsc@code` 是兩筆獨立條目）。更名發佈後，舊 plugin 會被移除、新 plugin 為首次安裝，兩者之間**不存在版本比較**，因此不會發生版本倒退，「版本單調遞增」不適用。git 歷史雖然延續，但版號描述的是**該 plugin 識別**的演進，而非 repo 的演進。
|
||||
|
||||
更名發佈的配套動作：使用者端必須**先移除舊 plugin、再安裝新 plugin**（不是 update），並重開工作階段；`~/.claude/settings.json` 的 `enabledPlugins` 舊鍵需一併清除。
|
||||
- **一般變更**（skill 新增／修改／移除、manifest 設定調整）：以 `master` 現行版本 patch +1；patch 只使用 `0` 到 `9`，只有 `master` 基準版 patch 已是 `9` 時才進位 minor 並把 patch 歸零，例如 `0.0.8 → 0.0.9 → 0.1.0`。
|
||||
- **重大改版**（skill 大規模重構、破壞相容的呼叫方式變更）：minor +1、patch 歸零。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-project-board
|
||||
description: JSC plugins 共用「Gitea 專案看板進度欄位規範」：欄位語意對應（分析中／待處理／進行中／待測試／已完成，以看板實際欄位名稱為準）、依需求與 TODO 勾稽結果建議欄位、先 GET 探測 project/column API（404/501 視為不支援、不對未確認端點寫入）、不往回移、不支援時改列建議清單請人工拖曳、不得新建欄位。當其他 skill 內文引用 spec-project-board 或 /jsc:spec-project-board、或需要調整 Gitea 議題所在看板欄位時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「Gitea 專案看板進度欄位規範」：欄位語意對應（分析中／待處理／進行中／待測試／已完成，以看板實際欄位名稱為準）、依需求與 TODO 勾稽結果建議欄位、先 GET 探測 project/column API（404/501 視為不支援、不對未確認端點寫入）、不往回移、不支援時改列建議清單請人工拖曳、不得新建欄位。當其他 skill 內文引用 spec-project-board 或 /jsc-generic:spec-project-board、或需要調整 Gitea 議題所在看板欄位時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-project-board — 共用 Gitea 看板進度欄位規範
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-time-log
|
||||
description: JSC plugins 共用「時間戳與輸出訊息格式規範」：更新時間一律台灣時區（Asia/Taipei）固定 yyyy/MM/dd HH:mm:ss、寫成檔內固定字串、流程完成後統一同步各處時間戳；輸出訊息統一為 [yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息（等級 INF/WRN/ERR/TRC/DBG）、一行一則。當其他 skill 內文引用 spec-time-log 或 /jsc:spec-time-log、或需要產生更新時間／統一 log 格式時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「時間戳與輸出訊息格式規範」：更新時間一律台灣時區（Asia/Taipei）固定 yyyy/MM/dd HH:mm:ss、寫成檔內固定字串、流程完成後統一同步各處時間戳；輸出訊息統一為 [yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息（等級 INF/WRN/ERR/TRC/DBG）、一行一則。當其他 skill 內文引用 spec-time-log 或 /jsc-generic:spec-time-log、或需要產生更新時間／統一 log 格式時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-time-log — 共用時間戳與訊息格式規範
|
||||
|
||||
Reference in New Issue
Block a user