Merge pull request 'fix: plugins-install agy flow' (#42) from develop into master

Reviewed-on: #42
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-shared",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / GitHub Copilot CLI / Antigravity / OpenCode），並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準；於 Claude Code 以 /jsc-shared: 前綴呼叫。",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-shared",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "JSC 跨 AI 助理共用規範 skills plugin，`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準。",
   "skills": "./skills/"
 }

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-shared",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "JSC 跨 AI 助理共用規範 skills plugin，`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準。",
   "skills": "./skills/"
 }

skills/plugins-install/SKILL.md

@@ -38,7 +38,7 @@ argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins
 - `--assistant <清單>`：要操作的助理，**可以多個**，以逗號分隔（`claude,codex,copilot,agy,opencode`），或用 `all` 代表本機找得到的全部。**省略時**依階段 A1 判斷（只有一個就直接用，多個就讓使用者多選）。
 - `--plugins code,doc,persona,shared`：要處理的 plugin（以逗號分隔，用 repo 短名）。**省略時預設四個全做**。
 - `--host <gitea 主機>`：gitea 主機，省略時預設 `gitea.jsc.idv.tw`。
-- `--clone-dir <目錄>`：Antigravity／其他會用到本機 clone 的工具的根目錄。**省略時**，`agy` 預設用 `~/.gemini/plugins`，`opencode` 預設用 `~/plugins`；若兩者同時選中而且要共用同一個 clone root，必須由使用者明確指定 `--clone-dir`。
+- `--clone-dir <目錄>`：Antigravity／其他會用到本機 clone 的工具的根目錄。`agy` 預設用 `~/.gemini/plugins`，`opencode` 預設用 `~/plugins`；若兩者同時選中而且要共用同一個 clone root，必須由使用者明確指定 `--clone-dir`。
 - `--yes`：全自動，不做確認式詢問（必要決策仍會中斷）。
 
 ---
@@ -152,14 +152,15 @@ copilot plugin update <token>
 
 ### Antigravity（`agy`）
 
-> `agy plugin install <url>` 目前只支援 github.com；gitea 一律走「clone + 本地路徑」。`agy` 沒有 update 子指令，更新＝`git pull` 後重裝。**預設 clone root 在 `~/.gemini/plugins`，不要偷用 `~/plugins` 的開發工作區。**
+> `agy plugin install <url>` 目前只支援 github.com；gitea 一律走「clone + 本地路徑」。`agy` 沒有 update 子指令，更新＝`git pull` 後重裝。**預設 clone root 在 `~/.gemini/plugins`，不要偷用目前工作目錄或 `~/plugins` 的開發工作區。**
 
 ```bash
-# 取得或更新本機 clone（目錄已存在就 pull，不要無條件 clone）
+# 取得或更新本機 clone（只看 clone root 內的 repo；新 clone 用 master，已存在就把 master 拉到最新）
 if [ -d "<clone-dir>/<repo>/.git" ]; then
-  git -C <clone-dir>/<repo> pull --ff-only
+  git -C <clone-dir>/<repo> switch master
+  git -C <clone-dir>/<repo> pull --ff-only origin master
 else
-  git clone <url> <clone-dir>/<repo>
+  git clone --branch master --single-branch <url> <clone-dir>/<repo>
 fi
 
 # 安裝
@@ -171,8 +172,8 @@ agy plugin install <clone-dir>/<repo>
 ```
 
 - **不可無條件 `git clone`**：clone 目錄已經存在（很常見——開發者自己就 clone 在那裡）時，`git clone` 會以 `fatal: destination path already exists` 中止。階段 B 的判定只看「有沒有裝進 agy」，所以「目錄在、但 agy 沒裝」這個狀態會落進安裝分支，必須靠上面的 `if` 擋掉。
-- `git pull --ff-only` 失敗（本機有未提交變更或分支分岔）→ **停在該 plugin**，回報現況讓使用者裁示，不得 `reset --hard`／`clean`，其餘 plugin 照常繼續。
-- **先確認 clone 在哪個分支**：`git -C <clone-dir>/<repo> branch --show-current`。若不是發佈分支（`master`），代表要裝進去的是未合併的內容——先告訴使用者，由他決定要換分支還是照裝。預設的 `~/plugins` 很可能就是開發者自己的工作區。
+- `git -C <clone-dir>/<repo> switch master` 或 `git pull --ff-only origin master` 失敗（本機有未提交變更、分支分岔，或本機 repo 無法切到 master）→ **停在該 plugin**，回報現況讓使用者裁示，不得 `reset --hard`／`clean`，其餘 plugin 照常繼續。
+- **先確認 clone 在哪個分支**：`git -C <clone-dir>/<repo> branch --show-current`。這裡檢查的是 `clone root` 裡的 repo，不是目前工作目錄的任何專案。`agy` 的本機 clone 應以 `master` 為準；若不是，先切回 `master`，再把 `master` 拉到最新。
 
 ### 無 plugin 匯入指令但可使用 skill 的助理