jiantw83andClaude Opus 5
42ea0a305b
What：新增 tools/worklog-pending.sh，worklog 技能改成寫入前先併入暫存內容、寫成功後才清除。
Why：SDLC 階段跑完沒寫工作日誌時，內容如果只留在對話裡，換一個工作階段就補不回來了。
How：暫存放在 $JSC_HOME/worklog-pending/{HASH}/，檔名帶 UTC 時間與 pid，同一秒的兩個工作階段不會互相覆蓋。jsc-sdlc 的階段回報負責存入，worklog 負責併入與清除；清除排在 wiki 寫入成功之後，先清再寫會兩邊都沒有。
Who：用 jsc-sdlc 跑階段、事後要靠工作日誌回頭查的人。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
67 lines
5.1 KiB
Markdown
67 lines
5.1 KiB
Markdown
# jsc-log — 工作日誌與統計
|
||
|
||
jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算；首碼若是數字或 `A`／`B`／`C`，改成 `H` 加上原前 7 碼；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 `LEARN_{HASH}`，供下次執行前查閱。
|
||
|
||
## 安裝、更新、移除
|
||
|
||
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-log@jsc`。每個指令一行：
|
||
|
||
| CLI | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-log@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-log@jsc` | `claude plugin uninstall jsc-log@jsc` |
|
||
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-log@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-log@jsc` |
|
||
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-log@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-log@jsc` | `copilot plugin uninstall jsc-log@jsc` |
|
||
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/log.git ~/plugins/log && agy plugin install ~/plugins/log` | `git -C ~/plugins/log pull && agy plugin uninstall jsc-log && agy plugin install ~/plugins/log` | `agy plugin uninstall jsc-log` |
|
||
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-log@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-log@jsc` | `kiro-cli plugin uninstall jsc-log@jsc` |
|
||
|
||
> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。
|
||
|
||
> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
|
||
|
||
## 工具
|
||
|
||
| 工具 | 用途 |
|
||
| --- | --- |
|
||
| `tools/usage-stats.sh` | 聚合 `$JSC_HOME/usage/*.jsonl`：`skills` 列技能使用次數、`chains` 列呼叫鏈次數（皆降冪），`--cli <name>` 過濾 |
|
||
| `tools/worklog-target.sh` | 接收已由 `jsc-gitea/tools/hash-id` 算好的 `HASH`，組出 `LOG_{HASH}`、`LOG_CONTENTS`（本身不再計算 SHA-1） |
|
||
| `tools/worklog-pending.sh` | 待寫入日誌的暫存區，存放於 `$JSC_HOME/worklog-pending/{HASH}/`。`add {HASH} {檔案}` 存一段內容（`jsc-sdlc` 的階段回報發現沒寫日誌時會呼叫），`cat {HASH}` 依時間印出全部、`list` 列路徑、`clear` 清除。結束碼 `3` 代表沒有暫存內容。**寫進 wiki 成功之後才 clear**，先清再寫會兩邊都沒有 |
|
||
| `tools/token-usage.sh` | 讀單一 CLI 這次工作的 token 用量，印出「input(tab)output」；來源讀不到就印「N/A(tab)N/A」並正常結束。第二個參數傳 session id，就只讀該階段的 transcript，數字才會跟花費時間對得上。各 CLI 的取得方式寫在腳本開頭註解 |
|
||
|
||
## Skills 目錄
|
||
|
||
呼叫方式：Claude / Antigravity `/jsc-log:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
|
||
|
||
<!-- JSC-SKILLS:START -->
|
||
|
||
### `worklog`
|
||
|
||
工作完成後蒐集十項資訊（存取庫、分支、計畫連結、工作包連結、花費時間、token 用量、任務狀態、執行細節、困難與解決、PR 目標分支），用 `tools/worklog-target.sh` 產生目標頁，再套範本附加到 `LOG_{HASH}` 與 `LOG_CONTENTS`。寫入前先讀 `tools/worklog-pending.sh cat {HASH}`：之前有階段跑完沒寫日誌，內容會暫存在那裡，這次一併寫進去，**寫成功之後才清暫存**。
|
||
|
||
### `stats`
|
||
|
||
統計本技能組各技能的使用次數與呼叫鏈使用次數，資料來源為 jsc-hooks 記錄的 `skills.jsonl` 與 `chains.jsonl`。
|
||
|
||
### `learn`
|
||
|
||
技能執行後把教訓（日期、技能、CLI、情境、教訓、下次做法）附加到 `LEARN_{HASH}` 並更新 `LEARN_CONTENTS`；技能執行前查閱同兩頁，套用相符的「下次做法」。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 範本
|
||
|
||
| 檔案 | 用途 |
|
||
| --- | --- |
|
||
| `templates/log-entry.md` | 單筆工作日誌（十欄位） |
|
||
| `templates/log-contents.md` | 日誌目錄 `LOG_CONTENTS` |
|
||
| `templates/learn-page.md` | 教訓紀錄頁 `LEARN_{HASH}`（六欄表格，逐列附加） |
|
||
| `templates/learn-contents.md` | 教訓目錄 `LEARN_CONTENTS` |
|
||
|
||
## 環境變數
|
||
|
||
Wiki 位置：日誌頁用 `JSC_WIKI_REPO_LOG`、教訓頁用 `JSC_WIKI_REPO_LEARN`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。先讀目前 shell 繼承的環境變數，缺值才詢問。
|
||
|
||
## 相關 domain
|
||
|
||
- [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：花費時間（`session-timer.sh report`）與用量資料來源
|
||
- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫
|