jiantw83
fee4185966
- What：Claude、Codex 與根目錄三份 plugin 清單同步補上 jsc-ask 與 jsc-hooks 的最低版本需求， 並把版號往前推一版。 - Why：技能早就呼叫 jsc-ask 的決策樹問期間與任務狀態，也讀 jsc-hooks 的計時器與用量紀錄取數字， 清單卻只宣告 gitea。缺宣告時，部署到只裝一半的機器上不會被擋，要跑到一半才失敗， 而且失敗訊息指向 wiki 或計時器，看不出真正缺的是哪個外掛。 - How：三份清單的 requires 一起改，三份內容保持一致，免得不同 CLI 讀到不同的相依。 - Who：log 技能組的安裝與部署檢查。
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）。friday [yyyy-MM-dd] 印出該工作週的週五，週界向 report-range.sh weekly 取得，這裡只加四天——跨月、跨年那一週交給人算就會差一天 |
tools/worklog-pending.sh |
待寫入日誌的暫存區，存放於 $JSC_HOME/worklog-pending/{HASH}/。add {HASH} {檔案} 存一段內容（jsc-sdlc 的階段回報發現沒寫日誌時會呼叫），cat {HASH} 依時間印出全部、list 列路徑、clear 清掉全部。寫日誌走三段式：merge {HASH} {本次條目檔} 合成「暫存內容在前、本次條目在後」並印出 MERGED=、CLAIM=、PENDING=；wiki 寫入成功後 commit {HASH} {CLAIM} 只清掉併入清單上那幾個檔；寫入失敗就 abort {HASH} {CLAIM}，暫存一個都不刪。結束碼 3 代表沒有暫存內容（merge 沒暫存仍是 0）。清除只發生在寫進 wiki 成功之後，先清再寫會兩邊都沒有 |
tools/report-range.sh |
算報表期間：report-range.sh {daily|weekly|monthly|yearly} [yyyy-MM-dd] 印出「起訖標籤期間」，含頭含尾。週採 ISO-8601（週一起算），標籤如 2026-W35。日期運算交給系統的 date，不自己算閏年 |
tools/report-template.sh |
解析報表範本位置：resolve {period} 印出「路徑project|skill」，list 一次列四種期間。工作目錄的 .jsc/templates/report-{period}.md 優先於技能自帶的 templates/ |
tools/log-aggregate.sh |
把日誌頁彙總成報表數字：log-aggregate.sh {起} {訖} [日誌頁檔案 ...]（省略檔案就讀標準輸入），印出 ENTRIES=、REPOS=、REPO=、ELAPSED_MINUTES=、ELAPSED_ENTRIES=、ELAPSED_MISSING=、TOKEN=、TOKEN_MISSING=、STATUS=。「無資料不估算」寫在腳本裡：沒填花費時間的條目不進總和，只進 ELAPSED_MISSING；整段期間都沒有時間就印「無資料」，不印 0。結束碼 3 代表期間內沒有條目，全零結果照樣印出來 |
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 描述需求自動觸發。
worklog
每完成一個任務就寫一筆日誌。任務有三種：一個工作包、一輪 PR 留言修正、一個獨立的修正提交。下一個任務開始前先把這一筆寫完，同一個工作包跑五輪留言修正就是五筆，各自帶自己的花費時間與 token 用量，附加到同一頁 LOG_{HASH}——連「試了卻沒改到檔案」的那一輪也留下來，那段時間才看得見。
每筆蒐集十項資訊（存取庫、分支、計畫連結、工作包連結、花費時間、token 用量、任務狀態、執行細節、困難與解決、PR 目標分支）。計畫連結、工作包連結、花費時間、token 用量四項來源互不相依，併行取得；存取庫解析與 HASH 計算也併行。用 tools/worklog-target.sh 產生目標頁，工作週的週五由同一支的 friday 子命令算出，套範本後附加到 LOG_{HASH} 與 LOG_CONTENTS。寫入前跑 tools/worklog-pending.sh merge {HASH} {本次條目檔}：之前有階段跑完沒寫日誌，內容暫存在那裡，這次一併寫進去；wiki 寫入成功才 commit 清掉暫存，失敗就 abort 保留。
stats
統計本技能組各技能的使用次數與呼叫鏈使用次數，資料來源為 jsc-hooks 記錄的 skills.jsonl 與 chains.jsonl。
learn
技能執行後把教訓（日期、技能、CLI、情境、教訓、下次做法）附加到 LEARN_{HASH} 並更新 LEARN_CONTENTS；技能執行前查閱同兩頁，套用相符的「下次做法」。
report
把工作日誌總結成年報、月報、週報或日報。期間由 tools/report-range.sh 算出（週次採 ISO-8601），範本由 tools/report-template.sh 解析——工作目錄的 .jsc/templates/report-{period}.md 優先，沒有才用技能自帶的那份。範本解析、日誌頁讀取、教訓頁讀取三線併行，各頁也一頁一個 sub agent 同時讀。讀 LOG_CONTENTS 列出的所有日誌頁後，交給 tools/log-aggregate.sh 算出條目數、涵蓋存取庫、花費時間、各 CLI token 用量與狀態計數，填進範本後寫入 wiki REPORT_{HASH}（HASH 取 {owner}/{repo}/{期間}，這裡的 {owner}/{repo} 取 REPORT wiki 存取庫，不是程式碼存取庫——本頁其他 HASH 取的是程式碼存取庫，只有這一處不同），同一期間重跑只換掉那一節。年報的教訓頁另解 JSC_WIKI_REPO_LEARN，不沿用日誌頁的存取庫。單筆工作紀錄請用 worklog。
範本
| 檔案 | 用途 |
|---|---|
templates/log-entry.md |
單筆工作日誌（十欄位） |
templates/log-contents.md |
日誌目錄 LOG_CONTENTS |
templates/learn-page.md |
教訓紀錄頁 LEARN_{HASH}（六欄表格，逐列附加） |
templates/learn-contents.md |
教訓目錄 LEARN_CONTENTS |
templates/report-daily.md |
日報：當天產出、卡住的地方、明天接著做 |
templates/report-weekly.md |
週報：本週產出、用時分布、困難與解法、滾到下週的項目 |
templates/report-monthly.md |
月報：本月成果、逐週推進、重複出現的困難、月底未結 |
templates/report-yearly.md |
年報：全年總覽、逐月推進、里程碑、全年教訓、年底未結 |
templates/report-contents.md |
報表目錄 REPORT_CONTENTS |
工作目錄放一份同名的 .jsc/templates/report-{period}.md，就會蓋過技能自帶的範本，不必改技能。
環境變數
Wiki 位置：日誌頁用 JSC_WIKI_REPO_LOG、教訓頁用 JSC_WIKI_REPO_LEARN、報表頁用 JSC_WIKI_REPO_REPORT，未設定退回 JSC_WIKI_REPO，再未設定就詢問（見 jsc-gitea）。先讀目前 shell 繼承的環境變數，缺值才詢問。