Compare commits
4
Commits
08455fb053
...
c25307b9b9
| Author | SHA1 | Date | |
|---|---|---|---|
 JefferyandClaude Opus 5
|
c25307b9b9 | ||
|
JefferyandClaude Opus 5
|
604656caa1 | ||
|
JefferyandClaude Opus 5
|
8521682583 | ||
|
JefferyandClaude Opus 5
|
cad5be26b6 |
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.0.2",
|
||||
"version": "0.0.3",
|
||||
"description": "JSC 跨 AI 助理共用 plugin 模板（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.0.2",
|
||||
"version": "0.0.3",
|
||||
"description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準。",
|
||||
"skills": "./skills"
|
||||
}
|
||||
|
||||
@@ -8,3 +8,7 @@ Thumbs.db
|
||||
# 暫存
|
||||
*.tmp
|
||||
*.log
|
||||
|
||||
# Python（scripts/ 內腳本被 import 時產生）
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
- 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
|
||||
- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc:` 前綴，不需強制加。
|
||||
- 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
|
||||
- 部分 skill 帶可執行元件（`scripts/`）或 hook（`hooks/hooks.json`），**並非四家助理都適用**；載入前請看該 skill `description` 標示的支援範圍與 `README.md` 的「元件對各助理的適用範圍」。`hooks/hooks.json` 只有 Claude Code 會讀；以複製 `skills/` 目錄安裝的環境（OpenCode）不會帶入 `scripts/`，依賴腳本的 skill 一律不可用。
|
||||
|
||||
## 慣例
|
||||
|
||||
|
||||
@@ -48,7 +48,19 @@ generic/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
> generic 的定位是「**共用規範 ＋ 全域自動化**」：`skills/spec-*` 是純規範文件（四家助理通用），`hooks/` 與 `scripts/` 是可執行元件。**`hooks/hooks.json` 只有 Claude Code 會讀**；Codex／Antigravity／OpenCode 匯入時只有 skill 可用，自動記錄不會啟動。
|
||||
> 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` 確認。
|
||||
|
||||
---
|
||||
|
||||
@@ -136,10 +148,12 @@ cp -r ~/plugins/generic/skills/* ~/.config/opencode/skills/
|
||||
git -C ~/plugins/generic pull
|
||||
cp -r ~/plugins/generic/skills/* ~/.config/opencode/skills/
|
||||
|
||||
# 移除
|
||||
rm -rf ~/.config/opencode/skills/spec-*
|
||||
# 移除（逐一移除本 plugin 帶入的 skill 目錄；勿只清 spec-*，否則其他 skill 會殘留）
|
||||
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 工具呼叫。
|
||||
@@ -192,7 +206,7 @@ rm -rf ~/.config/opencode/skills/spec-*
|
||||
|
||||
| Skill | 類型 | 內容 |
|
||||
| --- | --- | --- |
|
||||
| `worklog` | 工作證明記錄 | 每輪工作濃縮成條目追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）；`--init`／`--tune`／`--diagnose`／`--append`／`--show` 五個模式；自動記錄由 Claude Code `Stop` hook 完成 |
|
||||
| `worklog` | 工作證明記錄 | 每輪工作濃縮成條目追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）；`--init`／`--tune`（Claude Code 專屬）／`--diagnose`／`--append`／`--show` 五個模式；自動記錄由 Claude Code `Stop` hook 完成，**OpenCode 不支援**（見上方適用範圍表） |
|
||||
|
||||
<!-- JSC-SKILLS:END -->
|
||||
|
||||
@@ -210,5 +224,12 @@ rm -rf ~/.config/opencode/skills/spec-*
|
||||
6. 讓各助理更新：
|
||||
- Claude：`claude plugin update jsc@generic`
|
||||
- Codex：`codex plugin marketplace upgrade generic`
|
||||
- Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc && agy plugin install ~/jsc-plugin`
|
||||
- Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致）
|
||||
- OpenCode：`git pull` 後重新複製 `skills/`
|
||||
|
||||
> **skill 帶可執行元件時**（腳本、hook）額外注意：
|
||||
>
|
||||
> - 腳本放 `scripts/<skill-name>/`，**不要**放進 `skills/`；hook 定義放 `hooks/hooks.json`，command 用 `${CLAUDE_PLUGIN_ROOT}/...` 絕對路徑。
|
||||
> - 腳本要有執行權限並確實入 git（`git ls-files -s` 應顯示 `100755`）。
|
||||
> - `SKILL.md` **不可用相對路徑呼叫腳本** —— skill 執行時的工作目錄是使用者的專案目錄；請以 `${CLAUDE_PLUGIN_ROOT}`（其他助理用 skill base directory 往上兩層）組出絕對路徑。
|
||||
> - 在 `SKILL.md` 的 `description` 與上方適用範圍表標明支援哪幾家；OpenCode 因只複製 `skills/`，凡依賴 `scripts/` 的 skill 一律不支援。
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.0.2",
|
||||
"version": "0.0.3",
|
||||
"description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
|
||||
"skills": "./skills/"
|
||||
}
|
||||
+44
-10
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: worklog
|
||||
description: 工作證明自動記錄（worklog）的操作與維護 skill。搭配 Claude Code 的 Stop hook，把每輪工作內容濃縮成精簡條目並追加到 Gitea wiki 的當週工作紀錄頁（Worklog-yyyy-MM-W<週>），工作內容全程不落地。提供 --init（初始化週頁與環境變數指引）、--tune（判定並快取最適合的摘要模型）、--diagnose（診斷 hook 為何沒動作）、--append（手動補寫一筆）、--show（讀當週頁回顧）五個模式。當使用者說工作證明、工作紀錄、worklog、週報自動化、把工作內容寫到 wiki、記錄到 Gitea wiki、hook 沒有寫入 wiki、補寫工作紀錄、看本週做了什麼、重新判定摘要模型，或提到 WORKLOG_ENABLED／WORKLOG_HOST／WORKLOG_REPO／WORKLOG_MODEL／WORKLOG_SCOPE 時觸發。不適用於：Gitea 議題操作（用 doc-issues-sync／code-issues）、專案文件化（用 doc-funcs）。
|
||||
description: 工作證明自動記錄（worklog）的操作與維護 skill。搭配 Claude Code 的 Stop hook，把每輪工作內容濃縮成精簡條目並追加到 Gitea wiki 的當週工作紀錄頁（Worklog-yyyy-MM-W<週>），工作內容全程不落地。提供 --init（初始化週頁與環境變數指引）、--tune（判定並快取最適合的摘要模型）、--diagnose（診斷 hook 為何沒動作）、--append（手動補寫一筆）、--show（讀當週頁回顧）五個模式。當使用者說工作證明、工作紀錄、worklog、週報自動化、把工作內容寫到 wiki、記錄到 Gitea wiki、hook 沒有寫入 wiki、補寫工作紀錄、看本週做了什麼、重新判定摘要模型，或提到 WORKLOG_ENABLED／WORKLOG_HOST／WORKLOG_REPO／WORKLOG_MODEL／WORKLOG_SCOPE 時觸發。**僅支援 Claude Code／Codex／Antigravity（需 plugin 目錄保留 scripts/）；不支援 OpenCode**（skills 目錄安裝不會帶入 scripts/，且自動記錄依賴 Claude Code 的 transcript 格式）。不適用於：Gitea 議題操作（用 doc-issues-sync／code-issues）、專案文件化（用 doc-funcs）。
|
||||
---
|
||||
|
||||
# worklog — 工作證明自動記錄
|
||||
@@ -15,7 +15,38 @@ description: 工作證明自動記錄（worklog）的操作與維護 skill。搭
|
||||
| `scripts/worklog/wiki_api.py` | 上述兩者共用 | token 解析、wiki 讀寫、append 重試、週頁命名 |
|
||||
| `scripts/worklog/transcript.py` | 上述兩者共用 | 抽本輪片段、機密遮蔽 |
|
||||
|
||||
> `Stop` hook **只有 Claude Code 支援**。Codex／Antigravity／OpenCode 匯入本 plugin 時，只有 skill 可用，自動記錄不會啟動。
|
||||
### 各助理支援範圍
|
||||
|
||||
| 功能 | Claude Code | Codex | Antigravity | OpenCode |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `Stop` hook 自動記錄 | ✅ | ❌ 不讀 `hooks/hooks.json` | ❌ | ❌ |
|
||||
| `--init`／`--diagnose`／`--append`／`--show` | ✅ | ⚠️ 需 plugin 目錄保留 `scripts/`（安裝後請實測一次） | ⚠️ 同左 | ❌ 缺 `scripts/` |
|
||||
| `--tune` | ✅ | ❌ 無 `claude-api` skill 可載入 | ❌ 同左 | ❌ |
|
||||
|
||||
兩個限制的來源：
|
||||
|
||||
- **`Stop` hook 只有 Claude Code 讀取** `hooks/hooks.json`；且 `worklog.sh` 解析的是 **Claude Code 專屬的 transcript JSONL 結構**（`type` / `message.content` blocks），所以即使其他助理提供等效 hook 機制，自動記錄也不能直接沿用。
|
||||
- **OpenCode 以「複製 `skills/` 目錄」安裝**，不會帶入 `scripts/`，本 skill 的所有模式都無法執行 —— 在 OpenCode 環境請不要觸發本 skill。
|
||||
- 其他助理若要用 `--append`／`--show` 等純 wiki 操作，只需 `python3`（不需 `claude` CLI），但 `--tune` 必須改為手動設定 `WORKLOG_MODEL`。
|
||||
|
||||
### 腳本路徑解析（重要）
|
||||
|
||||
skill 執行時的工作目錄是**使用者的專案目錄**，不是 plugin 根目錄，因此**絕不可用相對路徑呼叫腳本**。先解析出 plugin 根目錄再組絕對路徑：
|
||||
|
||||
| 環境 | plugin 根目錄 |
|
||||
| --- | --- |
|
||||
| Claude Code | `${CLAUDE_PLUGIN_ROOT}` |
|
||||
| 其他助理 | 本 skill 載入時提示的 base directory（`.../skills/worklog`）往上兩層 |
|
||||
|
||||
```bash
|
||||
# Claude Code
|
||||
WORKLOG_DIR="${CLAUDE_PLUGIN_ROOT}/scripts/worklog"
|
||||
|
||||
# 其他助理：以 skill base directory 推導（<base>/../.. 即 plugin 根）
|
||||
WORKLOG_DIR="<skill base directory>/../../scripts/worklog"
|
||||
```
|
||||
|
||||
以下各模式的指令一律以 `${WORKLOG_DIR}` 表示該目錄。若解析不到或該目錄不存在，回報「plugin 目錄未包含 scripts/worklog，本 skill 在此環境不可用」並停止，不要改用相對路徑重試。
|
||||
|
||||
---
|
||||
|
||||
@@ -58,14 +89,16 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host
|
||||
|
||||
### `--init`
|
||||
|
||||
1. 執行 `python3 scripts/worklog/wiki_api.py probe`，回報 token 來源、Gitea 版本、當週頁狀態。
|
||||
2. 當週頁不存在 → 執行 `wiki_api.py init` 建立（wiki 尚未初始化時一併初始化）。
|
||||
1. 執行 `python3 "${WORKLOG_DIR}/wiki_api.py" probe`，回報 token 來源、Gitea 版本、當週頁狀態。
|
||||
2. 當週頁不存在 → 執行 `python3 "${WORKLOG_DIR}/wiki_api.py" init` 建立（wiki 尚未初始化時一併初始化）。
|
||||
3. 以表格印出應寫入 `~/.bashrc` 的 `WORKLOG_*` 變數清單；**不自動改使用者的 shell profile**（需人工確認的狀態變更）。
|
||||
|
||||
### `--tune`
|
||||
### `--tune`（Claude Code 專屬）
|
||||
|
||||
決定「目前最適合的摘要模型」並快取，`Stop` hook 只讀快取、**絕不自行呼叫 AI 判斷**（否則就變成雞生蛋，還會拖慢使用者的等待路徑）。
|
||||
|
||||
本模式需要 Claude Code 內建的 `claude-api` skill 與 `claude` CLI，**其他助理無法執行**：請改為手動設定 `WORKLOG_MODEL` 環境變數指定模型，或沿用保底模型。
|
||||
|
||||
| 步驟 | 動作 |
|
||||
| --- | --- |
|
||||
| 1 | 以 Skill 工具載入 `claude-api` 取當下模型清單與定價，**不憑記憶** |
|
||||
@@ -83,7 +116,8 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host
|
||||
| --- | --- |
|
||||
| `python3`／`claude` CLI | `command -v` 是否找得到 |
|
||||
| `WORKLOG_*` 變數 | 必要三項是否齊全、`WORKLOG_SCOPE` 是否把當前路徑排除 |
|
||||
| token | `wiki_api.py probe` 的 token 來源與驗證結果 |
|
||||
| `scripts/worklog` 目錄 | `${WORKLOG_DIR}` 是否解析成功且三支腳本存在（不存在＝此助理不支援） |
|
||||
| token | `python3 "${WORKLOG_DIR}/wiki_api.py" probe` 的 token 來源與驗證結果 |
|
||||
| wiki API | Gitea 版本、`repos/<repo>` 與當週頁狀態 |
|
||||
| 模型快取 | 是否存在、是否過期、目前會用哪支模型 |
|
||||
| hook 註冊 | `hooks/hooks.json` 是否存在且 plugin 已啟用 |
|
||||
@@ -97,11 +131,11 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host
|
||||
- <內容>
|
||||
```
|
||||
|
||||
專案取當前工作目錄的 `<owner>/<repo>`；內容仍會過 `transcript.py redact` 遮蔽後才寫入。
|
||||
專案取當前工作目錄的 `<owner>/<repo>`；內容仍會過 `python3 "${WORKLOG_DIR}/transcript.py" redact` 遮蔽後才寫入。
|
||||
|
||||
### `--show`
|
||||
|
||||
讀當週頁（`wiki_api.py show`）並以表格摘要本週工作，用於回顧與週報。
|
||||
讀當週頁（`python3 "${WORKLOG_DIR}/wiki_api.py" show`）並以表格摘要本週工作，用於回顧與週報。
|
||||
|
||||
---
|
||||
|
||||
@@ -119,7 +153,7 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host
|
||||
| 防線 | 位置 | 內容 |
|
||||
| --- | --- | --- |
|
||||
| 1 | 濃縮提示詞 | 明令不得輸出 token／密碼／API key／連線字串／Email／電話／姓名／身分證號 |
|
||||
| 2 | `transcript.py redact` | 正則遮蔽：URL 內嵌憑證、40 字元 hex token、`gh?_`／`sk-` token、`token=`／`password=`、`Authorization:`、Email、台灣手機、身分證號 |
|
||||
| 2 | `transcript.py` 的 `redact` | 正則遮蔽：URL 內嵌憑證、40 字元 hex token、`gh?_`／`sk-` token、`token=`／`password=`、`Authorization:`、Email、台灣手機、身分證號 |
|
||||
|
||||
第二道防線不可移除 —— 模型有可能沒遵守指令，而 wiki 一旦寫入就留在 git 歷史裡。
|
||||
|
||||
@@ -131,4 +165,4 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host
|
||||
| --- | --- |
|
||||
| Claude Code / Antigravity | `/jsc:worklog --init`、`/jsc:worklog --tune`、`/jsc:worklog --diagnose`、`/jsc:worklog --append "修正 X 的 Y 問題"`、`/jsc:worklog --show` |
|
||||
| Codex | `$worklog --diagnose`，或用 `/skills` 選單 |
|
||||
| OpenCode | 描述需求（如「幫我看這週的工作紀錄」）自動觸發 |
|
||||
| OpenCode | **不支援**（skills 目錄安裝不含 `scripts/`） |
|
||||
|
||||
Reference in New Issue
Block a user