From cad5be26b67e4a5ea8529d57724004b95dc9e73c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 27 Jul 2026 11:51:41 +0800 Subject: [PATCH] =?UTF-8?q?fix(worklog):=20=E6=94=B9=E7=94=A8=20plugin=20?= =?UTF-8?q?=E6=A0=B9=E7=B5=95=E5=B0=8D=E8=B7=AF=E5=BE=91=E5=91=BC=E5=8F=AB?= =?UTF-8?q?=E8=85=B3=E6=9C=AC=E4=B8=A6=E6=A8=99=E6=98=8E=E5=90=84=E5=8A=A9?= =?UTF-8?q?=E7=90=86=E6=94=AF=E6=8F=B4=E7=AF=84=E5=9C=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- skills/worklog/SKILL.md | 54 +++++++++++++++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index 0821533..b2ca641 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -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 推導（/../.. 即 plugin 根） +WORKLOG_DIR="/../../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/` 與當週頁狀態 | | 模型快取 | 是否存在、是否過期、目前會用哪支模型 | | hook 註冊 | `hooks/hooks.json` 是否存在且 plugin 已啟用 | @@ -97,11 +131,11 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host - <內容> ``` -專案取當前工作目錄的 `/`；內容仍會過 `transcript.py redact` 遮蔽後才寫入。 +專案取當前工作目錄的 `/`；內容仍會過 `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/`） |