JefferyandClaude Opus 5
265dd14a2b
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
135 lines
7.7 KiB
Markdown
135 lines
7.7 KiB
Markdown
---
|
||
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）。
|
||
---
|
||
|
||
# worklog — 工作證明自動記錄
|
||
|
||
把「每輪做了什麼」濃縮成一則條目，追加到 Gitea wiki 的當週工作紀錄頁。**自動記錄由 Claude Code 的 `Stop` hook 完成，不需使用者同意、不需人工觸發**；本 skill 負責自動路徑之外的人工操作：初始化、模型判定、診斷、補寫、回顧。
|
||
|
||
| 元件 | 觸發者 | 職責 |
|
||
| --- | --- | --- |
|
||
| `hooks/hooks.json` 的 `Stop` hook | harness 自動 | 每輪結束抽本輪內容 → 濃縮 → 遮蔽 → 追加到當週頁 |
|
||
| 本 skill `/jsc:worklog` | 使用者／助理手動 | `--init`／`--tune`／`--diagnose`／`--append`／`--show` |
|
||
| `scripts/worklog/worklog.sh` | 上述兩者共用 | 主流程（單一實作，避免漂移） |
|
||
| `scripts/worklog/wiki_api.py` | 上述兩者共用 | token 解析、wiki 讀寫、append 重試、週頁命名 |
|
||
| `scripts/worklog/transcript.py` | 上述兩者共用 | 抽本輪片段、機密遮蔽 |
|
||
|
||
> `Stop` hook **只有 Claude Code 支援**。Codex／Antigravity／OpenCode 匯入本 plugin 時，只有 skill 可用，自動記錄不會啟動。
|
||
|
||
---
|
||
|
||
## 共用規範（必要前置）
|
||
|
||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），不安裝則中斷**：
|
||
|
||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先、**寫入外部系統不得洩漏 PII**。
|
||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。
|
||
- `/jsc:spec-gitea`：token 機密保護（不 echo、遮蔽、不落地）、API 分頁、host 決定順序。
|
||
- `/jsc:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。
|
||
|
||
本 skill 特有補充：
|
||
|
||
- **工作內容不落地**：transcript 片段以 pipe 傳遞、wiki 走 API 不 clone，全程不產生暫存檔。唯一允許落地的是**模型快取檔** `~/.claude/worklog/model`（僅含模型 id 與判定時間，不含任何工作內容）。
|
||
- **絕不阻斷**：hook 路徑任何失敗都以 exit 0 結束，只在 stderr 留訊息。
|
||
|
||
---
|
||
|
||
## 環境變數
|
||
|
||
| 變數 | 必要 | 說明 | 未設定 |
|
||
| --- | --- | --- | --- |
|
||
| `WORKLOG_ENABLED` | ✅ | 總開關，設為 `1` 才啟用 | hook 立即結束，完全不動作 |
|
||
| `WORKLOG_HOST` | ✅ | Gitea 主機，如 `gitea.housefun.com.tw` | 不啟用 |
|
||
| `WORKLOG_REPO` | ✅ | wiki 所在 repo，如 `H3285/WorkLog` | 不啟用 |
|
||
| `WORKLOG_MODEL` | | 強制指定摘要模型 | 讀快取檔 → 保底 `claude-haiku-4-5-20251001` |
|
||
| `WORKLOG_SCOPE` | | 冒號分隔的路徑前綴，僅這些路徑下的 session 才記 | 全部 session 都記 |
|
||
| `WORKLOG_ERRLOG` | | 錯誤訊息額外寫入的檔案路徑（只記錯誤、不含工作內容） | 只走 stderr |
|
||
|
||
**token 不需另設變數**，依固定優先序自動解析並實際驗證：
|
||
|
||
```
|
||
GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host 的 token → ~/.git-credentials
|
||
```
|
||
|
||
---
|
||
|
||
## 模式
|
||
|
||
### `--init`
|
||
|
||
1. 執行 `python3 scripts/worklog/wiki_api.py probe`，回報 token 來源、Gitea 版本、當週頁狀態。
|
||
2. 當週頁不存在 → 執行 `wiki_api.py init` 建立（wiki 尚未初始化時一併初始化）。
|
||
3. 以表格印出應寫入 `~/.bashrc` 的 `WORKLOG_*` 變數清單；**不自動改使用者的 shell profile**（需人工確認的狀態變更）。
|
||
|
||
### `--tune`
|
||
|
||
決定「目前最適合的摘要模型」並快取，`Stop` hook 只讀快取、**絕不自行呼叫 AI 判斷**（否則就變成雞生蛋，還會拖慢使用者的等待路徑）。
|
||
|
||
| 步驟 | 動作 |
|
||
| --- | --- |
|
||
| 1 | 以 Skill 工具載入 `claude-api` 取當下模型清單與定價，**不憑記憶** |
|
||
| 2 | 依本任務條件評分：延遲敏感（在使用者等待路徑上）、輸出極短（1～3 行中文）、需嚴守機密過濾指令、每輪都跑一次故成本敏感 |
|
||
| 3 | Smoke test：`WORKLOG_CHILD=1 claude -p "回 OK" --model <選定 id>` 確認該模型在此帳號可用 |
|
||
| 4 | 寫入 `~/.claude/worklog/model`（`model=<id>`、`tuned_at=<時間>`、`reason=<一行理由>`），並回報選擇與理由 |
|
||
|
||
快取超過 **30 天** 視為過期：hook 改用保底模型，並在條目標記 `(model: fallback)`，`--diagnose` 會提醒重跑 `--tune`。
|
||
|
||
### `--diagnose`
|
||
|
||
逐項檢查並以表格回報，用於「hook 沒有寫入 wiki」時定位：
|
||
|
||
| 檢查項 | 判準 |
|
||
| --- | --- |
|
||
| `python3`／`claude` CLI | `command -v` 是否找得到 |
|
||
| `WORKLOG_*` 變數 | 必要三項是否齊全、`WORKLOG_SCOPE` 是否把當前路徑排除 |
|
||
| token | `wiki_api.py probe` 的 token 來源與驗證結果 |
|
||
| wiki API | Gitea 版本、`repos/<repo>` 與當週頁狀態 |
|
||
| 模型快取 | 是否存在、是否過期、目前會用哪支模型 |
|
||
| hook 註冊 | `hooks/hooks.json` 是否存在且 plugin 已啟用 |
|
||
|
||
### `--append "<內容>"`
|
||
|
||
手動補寫一筆（hook 漏記、離線工作、或事後補充）。條目格式與自動路徑一致：
|
||
|
||
```
|
||
## <時間> — <專案> <!-- worklog:<時間戳>-manual -->
|
||
- <內容>
|
||
```
|
||
|
||
專案取當前工作目錄的 `<owner>/<repo>`；內容仍會過 `transcript.py redact` 遮蔽後才寫入。
|
||
|
||
### `--show`
|
||
|
||
讀當週頁（`wiki_api.py show`）並以表格摘要本週工作，用於回顧與週報。
|
||
|
||
---
|
||
|
||
## 條目與頁面格式
|
||
|
||
- 週頁名稱：`Worklog-<yyyy>-<MM>-W<該月第幾週>`，第幾週 ＝ `ceil(日/7)`（例：`2026/07/27` → `Worklog-2026-07-W4`）。
|
||
- 頁首標題：`# <yyyy> 年 <MM> 月 第 <週> 週工作紀錄`。
|
||
- 每筆條目：`## <時間> — <專案>` ＋ 1～3 個 bullet；標題行尾帶 HTML 註解 marker（`<!-- worklog:… -->`）供寫後驗證與去重，wiki 渲染時不顯示。
|
||
- 多 session 同時寫入：`append_entry` 採「讀取 → 合併 → 寫回 → 寫後讀取驗證 marker」，未落地則重讀最新內容重試，最多 3 次。
|
||
|
||
---
|
||
|
||
## 機密與 PII（兩道防線）
|
||
|
||
| 防線 | 位置 | 內容 |
|
||
| --- | --- | --- |
|
||
| 1 | 濃縮提示詞 | 明令不得輸出 token／密碼／API key／連線字串／Email／電話／姓名／身分證號 |
|
||
| 2 | `transcript.py redact` | 正則遮蔽：URL 內嵌憑證、40 字元 hex token、`gh?_`／`sk-` token、`token=`／`password=`、`Authorization:`、Email、台灣手機、身分證號 |
|
||
|
||
第二道防線不可移除 —— 模型有可能沒遵守指令，而 wiki 一旦寫入就留在 git 歷史裡。
|
||
|
||
---
|
||
|
||
## 呼叫方式
|
||
|
||
| 助理 | 呼叫 |
|
||
| --- | --- |
|
||
| 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 | 描述需求（如「幫我看這週的工作紀錄」）自動觸發 |
|