jiantw83
2c085d68ef
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與 「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上 看起來像普通文字或死連結，巡不到也修不了。 連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API， 不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把 好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁 整批判死。
jsc-log — 工作日誌與統計
jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（LOG_{HASH}，HASH 依共享規則計算，取 {owner}/{repo} 的完整 SHA-1 四十碼、a-f 轉大寫，不截短也不加前綴；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 LEARN_{HASH}，供下次執行前查閱。目錄頁（LOG_CONTENTS、LEARN_CONTENTS、REPORT_CONTENTS）另住一個專用存取庫，與內容頁分開。
安裝、更新、移除
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}/。{HASH} 只收三種：40 碼大寫十六進位（現行），或 8 碼大寫十六進位、H 加 7 碼大寫十六進位（尚未遷移的舊暫存；舊規則把首碼落在 0-9ABC 的 hash 改寫成 H 加原前 7 碼，所以舊暫存大多長這樣），其餘一律 2——這道格式檢查擋的是路徑穿越。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 住在 JSC_WIKI_REPO_CONTENTS 解出的專用存取庫，與 LOG_{HASH} 不同 wiki，改由 jsc-gitea/tools/wiki-contents.sh upsert LOG 2 {HASH} 單列寫回：鍵取第 2 欄的裸 HASH，第 1 欄的絕對網址（gitea.sh wiki-url 給的）只給人點。網址帶主機名，換主機就比不到鍵，同一頁會多一列。寫入前跑 tools/worklog-pending.sh merge {HASH} {本次條目檔}：之前有階段跑完沒寫日誌，內容暫存在那裡，這次一併寫進去；wiki 寫入成功才 commit 清掉暫存，失敗就 abort 保留。
stats
統計本技能組各技能的使用次數與呼叫鏈使用次數，資料來源為 jsc-hooks 記錄的 skills.jsonl 與 chains.jsonl。
learn
技能執行後把教訓（日期、技能、CLI、情境、教訓、下次做法）附加到 LEARN_{HASH}，並用 jsc-gitea/tools/wiki-contents.sh upsert 更新 LEARN_CONTENTS；技能執行前查閱同兩頁，套用相符的「下次做法」。兩頁分屬不同存取庫：LEARN_{HASH} 取 JSC_WIKI_REPO_LEARN，LEARN_CONTENTS 取 JSC_WIKI_REPO_CONTENTS，列裡的連結用絕對網址。
report
把工作日誌總結成年報、月報、週報或日報。期間由 tools/report-range.sh 算出（週次採 ISO-8601），範本由 tools/report-template.sh 解析——工作目錄的 .jsc/templates/report-{period}.md 優先，沒有才用技能自帶的那份。範本解析、日誌頁讀取、教訓頁讀取三線併行，各頁也一頁一個 sub agent 同時讀。目錄頁 LOG_CONTENTS 取 JSC_WIKI_REPO_CONTENTS 的專用存取庫，它列出的日誌頁用絕對網址逐頁讀回；讀完交給 tools/log-aggregate.sh 算出條目數、涵蓋存取庫、花費時間、各 CLI token 用量與狀態計數，填進範本後寫入 wiki REPORT_{HASH}（HASH 取 {owner}/{repo}/{期間} 的完整 40 碼，這裡的 {owner}/{repo} 取 REPORT wiki 存取庫，不是程式碼存取庫——本頁其他 HASH 取的是程式碼存取庫，只有這一處不同），同一期間重跑只換掉那一節。REPORT_CONTENTS 那一列改由 jsc-gitea/tools/wiki-contents.sh upsert REPORT 2 {HASH} 寫回，鍵同樣取裸 HASH 那一欄。年報的教訓「內容頁」另解 JSC_WIKI_REPO_LEARN，不沿用日誌頁的存取庫；目錄頁同住 CONTENTS 存取庫是另一回事，兩者別混。單筆工作紀錄請用 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 位置分兩層：內容頁一頁型一個變數——日誌頁 LOG_{HASH} 用 JSC_WIKI_REPO_LOG、教訓頁 LEARN_{HASH} 用 JSC_WIKI_REPO_LEARN、報表頁 REPORT_{HASH} 用 JSC_WIKI_REPO_REPORT；目錄頁三頁共用一個變數——LOG_CONTENTS、LEARN_CONTENTS、REPORT_CONTENTS 一律用 JSC_WIKI_REPO_CONTENTS。
以上每個變數未設定都退回 JSC_WIKI_REPO，再未設定就詢問（見 jsc-gitea）。先讀目前 shell 繼承的環境變數，缺值才詢問。
目錄頁與內容頁從此分屬不同存取庫，兩件事跟著改：JSC_WIKI_REPO_CONTENTS 不會退回頁型變數，JSC_WIKI_REPO_LOG 之類也頂不了目錄頁的位；連結一律寫成 [{文字}]({連結})，網址取 gitea.sh wiki-url 印出的絕對網址，不自己組路徑。同 wiki 的雙括號寫法一概不用：它只在自己那個 wiki 內解得開，跨庫就是死連結，畫面上還看不出壞掉。連結寫進頁面前先過 gitea.sh 旁邊的 link-check.sh，結束碼 0 才寫。