refactor(generic 規範): 移除 worklog 並補 Copilot 說明

2026-07-27 16:24:53 +08:00
parent c2239dd97d
commit 497dc55b61
10 changed files with 42 additions and 995 deletions
@@ -1,6 +1,6 @@
-# jsc — 跨 AI 助理 Plugin 模板
+# jsc — 跨 AI 助理共用規範 Plugin

-一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的 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`）。
@@ -15,8 +15,9 @@
 | Codex | `codex plugin`（marketplace） | `$<name>` 或 `/skills` 選單 | ❌（用 `$name`） |
 | Antigravity | `agy plugin install` | `/jsc:<name>` 或自動觸發 | ✅ |
 | OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） |
+| GitHub Copilot | repository instructions（`AGENTS.md` / `.github/copilot-instructions.md`） | 描述需求並要求讀取對應 `SKILL.md` | ❌（依指示檔） |

-> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫。兩者皆**不強制**前綴。
+> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 與 Copilot 由模型依描述與指示檔觸發。三者皆**不強制**前綴。

 ---

@@ -34,37 +35,17 @@ generic/
 ├── .agents/plugins/
 │   └── marketplace.json     # Codex marketplace（name: "generic"，url source 指向本 repo）
 ├── plugin.json              # Antigravity 外掛定義（name: "jsc"，skills: "./skills/"）
-├── hooks/
-│   └── hooks.json           # Claude Code hooks（Stop → worklog；其他助理不吃此檔）
-├── scripts/
-│   └── worklog/             # worklog 自動記錄的可執行元件（skill 與 hook 共用）
-│       ├── worklog.sh       # 主流程：抽本輪 → 濃縮 → 遮蔽 → 追加到 wiki
-│       ├── wiki_api.py      # Gitea wiki 讀寫、token 解析、append 重試、週頁命名
-│       └── transcript.py    # transcript 本輪抽取與機密遮蔽
 ├── skills/                  # ★ 唯一真實來源：所有 skills
-│   ├── spec-*/SKILL.md      # 共用規範 skills（一規範一目錄）
-│   └── worklog/SKILL.md     # 工作證明自動記錄的操作與維護
+│   └── spec-*/SKILL.md      # 共用規範 skills（一規範一目錄）
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
 ```

-> generic 的定位是「**共用規範 ＋ 全域自動化**」：`skills/spec-*` 是純規範文件（四家助理通用），`hooks/` 與 `scripts/` 是可執行元件。
-
-### 元件對各助理的適用範圍
-
-| 元件 | Claude Code | Codex | Antigravity | OpenCode |
-| --- | --- | --- | --- | --- |
-| `skills/spec-*`（十個共用規範） | ✅ | ✅ | ✅ | ✅ |
-| `skills/worklog` 的手動模式 | ✅ | ⚠️ 需安裝後保留 `scripts/`（請實測一次） | ⚠️ 同左 | ❌ 不支援 |
-| `hooks/hooks.json`（`Stop` 自動記錄） | ✅ | ❌ | ❌ | ❌ |
-
- **`hooks/hooks.json` 只有 Claude Code 會讀**。且 `scripts/worklog/worklog.sh` 解析的是 **Claude Code 專屬的 transcript JSONL 結構**，即使其他助理提供等效 hook，自動記錄也不能直接沿用。
- **OpenCode 不支援 worklog**：OpenCode 以「複製 `skills/` 目錄」安裝，不會帶入 `scripts/`，worklog 的所有模式都無法執行（已在該 skill 的 `description` 標明）。
- Claude Code 的 plugin cache 是完整 repo clone，`scripts/`（含 `100755` 執行權限）與 `hooks/` 都會帶入；Codex／Antigravity 的安裝目錄是否同樣保留 `scripts/` 尚未實測，第一次安裝後請跑 `/jsc:worklog --diagnose` 確認。
+> generic 的定位是「**共用規範**」：`skills/spec-*` 是 code／doc plugins 共用的流程與安全規範。工作紀錄自動化 `worklog` 已移到 `doc` plugin。

 ---

-## 安裝 / 更新 / 移除（各家原生 plugin CLI）
+## 安裝 / 更新 / 移除（各助理）

 > 指令中的 repo 網址換成你的：`https://gitea.jsc.idv.tw/plugins/generic.git`
 >
@@ -152,12 +133,32 @@ cp -r ~/plugins/generic/skills/* ~/.config/opencode/skills/
 for s in ~/plugins/generic/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$(basename "$s")"; done
 ```

-> **worklog 在 OpenCode 不可用**：上面的複製只帶 `skills/`，不含 `scripts/`，worklog 的所有模式都會失敗。請不要在 OpenCode 觸發該 skill（其 `description` 已標明不支援）。
-
 > **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。

 - **呼叫**：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。

+### GitHub Copilot
+
+GitHub Copilot 目前不是這類 `SKILL.md` plugin 的原生執行環境；安裝方式是把本 repo 作為 repository instructions 的來源，讓 Copilot 讀 `AGENTS.md` 與對應 `SKILL.md`。
+
+```bash
+# 安裝到目標 repo（把 generic plugin vendored 進 .github/jsc-plugins/generic）
+git clone https://gitea.jsc.idv.tw/plugins/generic.git .github/jsc-plugins/generic
+cp .github/jsc-plugins/generic/AGENTS.md AGENTS.md
+
+# 更新
+git -C .github/jsc-plugins/generic pull
+cp .github/jsc-plugins/generic/AGENTS.md AGENTS.md
+
+# 移除
+git rm -r .github/jsc-plugins/generic
+# 若 AGENTS.md 只供此 plugin 使用，再移除；若已有其他內容，請只刪除 JSC generic 相關段落
+# git rm AGENTS.md
+```
+
+- 也可把既有 `.github/copilot-instructions.md` 改成引用 `AGENTS.md` 與 `.github/jsc-plugins/generic/skills/<skill>/SKILL.md`。
+- **呼叫**：在 Copilot Chat／Coding Agent 任務中描述需求，例如「請依 `.github/jsc-plugins/generic/skills/spec-output/SKILL.md` 說明輸出規範」。
+
 ---

 ## 用 CLI 直接執行 skill（headless / 一次性）
@@ -170,10 +171,11 @@ for s in ~/plugins/generic/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$
 | Codex | `codex exec "<prompt>"` | `codex exec '$spec-output'` |
 | Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc:spec-output"` |
 | OpenCode | `opencode run "<message>"` | `opencode run "說明 JSC 共用輸出規範的內容"` |
+| GitHub Copilot | Copilot Chat / Coding Agent 任務 | `請依 .github/jsc-plugins/generic/skills/spec-output/SKILL.md 說明輸出規範` |

 - Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:<name>"` 即可。
 - Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$spec-output'`。
- OpenCode 沒有前綴，用自然語言描述需求，模型會自動透過 skill 工具呼叫。
+- OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot 任務中請明確指出要讀取的 `SKILL.md`。
 - 帶引數就接在後面，例如 `claude -p "/jsc:spec-output 參數"`、`codex exec '$spec-output 參數'`。

 ---
@@ -202,12 +204,6 @@ for s in ~/plugins/generic/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$
 | `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc:doc-funcs 的標準流程與統一時間戳 |
 | `spec-plugin-version` | 版號規則 | 三 manifest 同步 bump、對照 master 確保單調遞增、新 plugin 首發 0.0.1、chore(plugin 版本) commit |

-### 全域自動化
-
-| Skill | 類型 | 內容 |
-| --- | --- | --- |
-| `worklog` | 工作證明記錄 | 每輪工作濃縮成條目追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）；`--init`／`--tune`（Claude Code 專屬）／`--diagnose`／`--append`／`--show` 五個模式；自動記錄由 Claude Code `Stop` hook 完成，**OpenCode 不支援**（見上方適用範圍表） |
-
 <!-- JSC-SKILLS:END -->

 ---
@@ -226,6 +222,7 @@ for s in ~/plugins/generic/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$
   - Codex：`codex plugin marketplace upgrade generic`
   - Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致）
   - OpenCode：`git pull` 後重新複製 `skills/`
+   - GitHub Copilot：更新 `.github/jsc-plugins/generic` 後同步 `AGENTS.md` 或 `.github/copilot-instructions.md`

 > **skill 帶可執行元件時**（腳本、hook）額外注意：
 >