plugins/assist
2
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

feat(assist): 樣板改成 jsc-assist domain，加上 status 技能

Browse Source 
What：
- 三份 manifest 的 name 由 jsc-template 改成 jsc-assist，version 設為 0.0.1，description 改寫成助理的定位，並加上 jsc.requires 宣告對 jsc-cli、jsc-gitea、jsc-hooks、jsc-log 的最低版本。
- README.md 與 AGENTS.md 依 meta domain 的格式重寫，AGENTS.md 多一節「助理的界線」。
- 刪掉樣板的 hello 技能，新增 status 技能與 references/behaviors.md 行為清單。

Why：
- 這個存取庫原本整份是 template 的樣板，四份 manifest 都還叫 jsc-template。名字沒改，marketplace 認不出它是獨立的 domain，各 CLI 也裝不上。
- 助理的閘門、心跳與巡檢要有落點，前提是存取庫先認得出自己。
- 樣板的 hello 技能只是安裝驗證用，留著會讓助理的技能清單從第一天就帶著一支沒有用途的技能。換成唯讀的 status，行為檢查與 frontmatter 檢查也才有掃描對象。

How：
- status 全程唯讀：讀心跳檔判斷助理在不在跑，判準只看時間戳距現在是否不到 300 秒，不看 pid 存活——五支 CLI 與容器裡的行程互相看不到彼此的 pid。
- 心跳檔不存在時印「助理未運行」，這是正常結果，不以非 0 結束。
- 這支不新增 tools/ 腳本。讀兩個路徑印一張表還不到抽腳本的門檻，助理主體落地時再一併評估。
- 三份 manifest 的 version 由 sync-skill-manifest.sh 同步，README 的技能目錄區塊一起更新。

Who：
助理 domain 落地的第一步，後續的閘門、心跳與排程都接在這個基礎上。
This commit is contained in:
jiantw83
2026-09-01 11:20:52 +08:00
parent 7790283920
commit 6e18a373f3
8 changed files with 177 additions and 273 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+44 -210
View File
@@ -1,228 +1,62 @@
# jsc-template — 跨 AI 助理 Plugin 模板
# jsc-assist — 技能助理
一個可同時被 **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-template:` 前綴**呼叫（例如 `/jsc-template:hello`）。
jsc 技能組的 assist domain：技能與 hook 每跑一次就留下事件，助理負責把事件收攏、判斷健康狀態、寫進 wiki 的監控頁（`MONITOR_{HASH}`）。
---
助理只做三件事：**觸發**既有技能、**巡檢**既有的唯讀腳本與狀態檔、把結果**提醒**給前景會話。它不做決策、不改程式碼、不覆寫 wiki。完整界線見 `AGENTS.md` 的「助理的界線」。
## 前綴與呼叫方式
## 安裝、更新、移除
| 助理 | 安裝方式 | 呼叫 | `/jsc-template:` 前綴 |
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-assist@jsc`。每個指令一行：
| CLI | 安裝 | 更新 | 移除 |
| --- | --- | --- | --- |
| Claude Code | `claude plugin`（marketplace） | `/jsc-template:<name>` 或自動觸發 | ✅ |
| Codex | `codex plugin`（marketplace） | `$<name>` 或 `/skills` 選單 | ❌（用 `$name`） |
| Antigravity | `agy plugin install` | `/jsc-template:<name>` 或自動觸發 | ✅ |
| OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） |
| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-template:` 前綴） |
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-assist@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-assist@jsc` | `claude plugin uninstall jsc-assist@jsc` |
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-assist@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-assist@jsc` |
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-assist@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-assist@jsc` | `copilot plugin uninstall jsc-assist@jsc` |
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/assist.git ~/plugins/assist && agy plugin install ~/plugins/assist` | `git -C ~/plugins/assist pull && agy plugin uninstall jsc-assist && agy plugin install ~/plugins/assist` | `agy plugin uninstall jsc-assist` |
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-assist@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-assist@jsc` | `kiro-cli plugin uninstall jsc-assist@jsc` |
> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。
---
## 目錄結構
同一個 repo 同時帶四種 manifest，彼此以路徑隔離、互不干擾；各助理都讀同一份 `skills/`。
```
template/
├── .claude-plugin/
│ ├── plugin.json # Claude 外掛定義（name: "jsc-template"）
│ └── marketplace.json # Claude marketplace（name: "template"，source 指向本 repo）
├── .codex-plugin/
│ └── plugin.json # Codex 外掛定義（name: "jsc-template"，skills: "./skills"）
├── .agents/plugins/
│ └── marketplace.json # Codex marketplace（name: "template"，url source 指向本 repo）
├── plugin.json # Antigravity 外掛定義（name: "jsc-template"，skills: "./skills/"）
├── skills/ # ★ 唯一真實來源：所有 skills
│ └── hello/SKILL.md
├── AGENTS.md # 跨助理共用指引
└── README.md
```
---
## 安裝 / 更新 / 移除（各助理）
> 指令中的 repo 網址換成你的：`https://gitea.jsc.idv.tw/plugins/template.git`
>
> **Claude / Codex 從 git URL 安裝（會 clone 遠端），請先把本 repo `push` 到 gitea。**
> **Antigravity 的 `agy plugin install <url>` 目前只支援 github.com**；gitea 請改用「clone + 本地路徑」（見 Antigravity 節）。
> 本機/離線：Claude 可用本地路徑加 marketplace；Antigravity 用本地路徑安裝。
> **⚠ 從 0.0.1 升上來的人請先移除再安裝。** 0.0.2 起 marketplace 名由 `jsc-plugins` 改為 `template`
> （舊名與 `jsc-persona` 的 marketplace 撞名）。各助理以 `<plugin 名>@<marketplace 名>` 當安裝識別鍵，
> 改名後是兩筆獨立條目，**不能用 update 遷移**：
>
> ```bash
> claude plugin uninstall jsc-template@jsc-plugins
> claude plugin marketplace remove jsc-plugins # 若你沒有裝 jsc-persona 才移除，它也用這個名字
> claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git
> claude plugin install jsc-template@template
> ```
>
> 移除後記得清掉 `~/.claude/settings.json` 裡 `enabledPlugins` 的舊鍵 `jsc-template@jsc-plugins`，
> 並重開工作階段。Codex／Copilot 同理（`remove`／`uninstall` 後重新 `add`＋`install`）。
### Claude Code
```bash
# 安裝
claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git
claude plugin install jsc-template@template
# 更新
claude plugin marketplace update template
claude plugin update jsc-template@template
# 移除
claude plugin uninstall jsc-template@template
claude plugin marketplace remove template
```
- 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
- 本機開發（免 push）：`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\template`（本地路徑）後再 install。
- **呼叫**：`/jsc-template:<name>`（例 `/jsc-template:hello`）。
### Codex
```bash
# 安裝
codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git
codex plugin add jsc-template@template
# 更新（重新抓取 marketplace 的 git 快照）
codex plugin marketplace upgrade template
# 移除
codex plugin remove jsc-template@template
codex plugin marketplace remove template
```
- 安裝 token `jsc-template@template` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
- 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。
- **呼叫**：`$<name>`（例 `$hello`），或用 `/skills` 選單。
### Antigravity（`agy`）
> `agy plugin install <url>` 目前**只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，請先 `git clone` 再用**本地路徑**安裝。
```bash
# 安裝：clone 後用本地路徑
git clone https://gitea.jsc.idv.tw/plugins/template.git ~/plugins/template
agy plugin install ~/plugins/template
# 更新（agy 無 update 子指令 → git pull 後重裝）
git -C ~/plugins/template pull
agy plugin uninstall jsc-template
agy plugin install ~/plugins/template
# 移除
agy plugin uninstall jsc-template
```
- 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com/<owner>/<repo>`。
- 其他：`agy plugin list`、`agy plugin enable jsc-template` / `disable jsc-template`、`agy plugin validate <path>`。安裝後重啟工作階段。
- **呼叫**：`/jsc-template:<name>`（例 `/jsc-template:hello`）或依描述自動觸發。
### OpenCode
OpenCode 的「plugin」是 TypeScript/npm 套件，不適用於 skill 包；skills 改用**目錄安裝**。
OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`）。
```bash
# 安裝
git clone https://gitea.jsc.idv.tw/plugins/template.git ~/plugins/template
mkdir -p ~/.config/opencode/skills
cp -r ~/plugins/template/skills/* ~/.config/opencode/skills/
# 更新
git -C ~/plugins/template pull
cp -r ~/plugins/template/skills/* ~/.config/opencode/skills/
# 移除
rm -rf ~/.config/opencode/skills/hello
```
> **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 CLI
Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令，可直接從 marketplace 安裝、更新與移除本 plugin。
```bash
# 安裝
copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git
copilot plugin install jsc-template@template
# 更新
copilot plugin marketplace update template
copilot plugin update jsc-template@template
# 移除
copilot plugin uninstall jsc-template@template
copilot plugin marketplace remove template
```
- 安裝 token `jsc-template@template` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。
- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。
- **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "跑 hello 確認 plugin 裝好了"`。
---
## 用 CLI 直接執行 skill（headless / 一次性）
安裝好之後，不必進互動介面，一行指令就能叫某個 skill 跑完並印出結果：
| 助理 | headless 指令 | 執行 `hello` skill |
| --- | --- | --- |
| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc-template:hello"` |
| Codex | `codex exec "<prompt>"` | `codex exec '$hello'` |
| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc-template:hello"` |
| OpenCode | `opencode run "<message>"` | `opencode run "用 hello skill 打個招呼"` |
| GitHub Copilot CLI | `copilot -p "<message>"` | `copilot -p "用 hello skill 打個招呼"` |
- Claude / Antigravity 支援 `/jsc-template:` 前綴，直接 `-p "/jsc-template:<name>"` 即可。
- Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$hello'`。
- OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot CLI 會讀取已安裝 plugin 提供的 skills。
- 帶引數就接在後面，例如 `claude -p "/jsc-template:hello 參數"`、`codex exec '$hello 參數'`。
---
> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。
## Skills 目錄
> 此區塊列出本 plugin 內含的所有 skills（名稱／描述／使用方法）。
> 新增或修改 skill 後，請同步手動更新標記之間的內容。
呼叫方式：Claude / Antigravity `/jsc-assist:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
<!-- JSC-SKILLS:START -->
### `hello`
### `status`
範例 skill，用來驗證 jsc plugin 是否安裝成功，也是新增 skill 的範本。當使用者輸入 hello、想測試 plugin、或想看 skill 模板長什麼樣子時觸發；回覆一句問候並簡述此 plugin 的用途。
- **Claude Code / Antigravity**：`/jsc-template:hello`
- **Codex**：`$hello`，或用 `/skills` 選單
- **OpenCode / GitHub Copilot CLI**：描述需求自動觸發
查助理現在的狀況，全程唯讀。讀心跳檔判斷助理是不是還在跑——檔案在、而且 `ts` 距現在不到 300 秒才算新鮮，過期就是沒在跑；接著列出待辦簿裡的每一筆，印成一張現況表。心跳檔不存在時印「助理未運行」，不當成錯誤。這支不寫檔、不寫 wiki、不碰閘門。
<!-- JSC-SKILLS:END -->
---
## 相依
## 新增一個 skill
| Plugin | 最低版本 | 用途 |
| --- | --- | --- |
| `jsc-cli` | `>=0.2.7` | CLI 偵測與委派 |
| `jsc-gitea` | `>=0.2.0` | 監控頁的所有 wiki 讀寫，一律經 `tools/gitea.sh` |
| `jsc-hooks` | `>=0.3.4` | 心跳、閘門與事件來源（`$JSC_HOME` 底下的狀態檔） |
| `jsc-log` | `>=0.1.4` | 使用統計與工作日誌的資料來源 |
1. 複製範本：`cp -r skills/hello skills/<your-skill-name>`
2. 編輯 `skills/<your-skill-name>/SKILL.md` 的 frontmatter：
- `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc-template:<name>`**。
- `description`：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。
3. 在內文寫下 skill 的具體步驟。
4. 手動把這個 skill 補進上方「Skills 目錄」區塊。
5. **bump 版本並 push**：各助理都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump，commit 後 push 到 gitea。
6. 讓各助理更新：
- Claude：`claude plugin update jsc-template@template`
- Codex：`codex plugin marketplace upgrade template`
- Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc-template && agy plugin install ~/jsc-plugin`
- OpenCode：`git pull` 後重新複製 `skills/`
- Copilot：`copilot plugin marketplace update template && copilot plugin update jsc-template@template`
## 參考與工具
| 檔案 | 用途 |
| --- | --- |
| `references/behaviors.md` | 本 domain 的技能行為清單：一支技能一節，五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，供稽核與驗證比對。格式合約見 `plugins/meta` 的 `references/guidelines.md`「技能行為清單」 |
## 助理的狀態檔
全部放在 `$JSC_HOME/assistant/` 底下，一律純文字 key=value：
| 路徑 | 內容 |
| --- | --- |
| `heartbeat` | 心跳檔，欄位 `ts`、`pid`、`cli`、`session`。判準只看 `ts`，不看 pid 存活——五支 CLI 與容器裡的行程互相看不到彼此的 pid |
| `tasks/{id}` | 待辦簿，一筆一檔。一筆一檔是為了讓並行寫入不互相覆寫 |
## 相關 domain
- [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：閘門與心跳，跟 hook 一起裝
- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫的唯一入口
- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：使用統計與工作日誌
- [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：環境健檢與跨 CLI 委派