docs(log): 補上工具結束碼宣告與新流程說明
- What：README 的工具表補進彙總腳本，並改寫 worklog 與 report 兩節； tools/token-usage.sh 的檔頭改寫成完整的結束碼宣告。 - Why：README 還停在舊流程，讀的人會以為報表數字仍由技能自己數，也不知道週五已經有腳本可用。 token-usage.sh 原本只寫「護欄回傳 2」，沒說來源讀不到時印 N/A 也算成功， 接手的人容易把那個情況當成故障，白追一輪。 - How：工具表加一列，寫出彙總腳本的輸出欄位與「無資料不估算」； worklog 一節寫出四項來源併行取得、週五由腳本算； report 一節寫出三線併行、彙總改走腳本，以及教訓頁另解自己的 wiki 存取庫。 相依清單補上 jsc-ask 一列，說明它負責問期間與任務狀態。 - Who：整個 log 技能組的說明文件。
This commit is contained in:
@@ -23,10 +23,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
| 工具 | 用途 |
|
||||
| --- | --- |
|
||||
| `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-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]` 印出「起<TAB>訖<TAB>標籤<TAB>期間」，含頭含尾。週採 ISO-8601（週一起算），標籤如 `2026-W35`。日期運算交給系統的 `date`，不自己算閏年 |
|
||||
| `tools/report-template.sh` | 解析報表範本位置：`resolve {period}` 印出「路徑<TAB>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 目錄
|
||||
@@ -39,7 +40,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
每完成一個任務就寫一筆日誌。任務有三種：一個工作包、一輪 PR 留言修正、一個獨立的修正提交。下一個任務開始前先把這一筆寫完，同一個工作包跑五輪留言修正就是五筆，各自帶自己的花費時間與 token 用量，附加到同一頁 `LOG_{HASH}`——連「試了卻沒改到檔案」的那一輪也留下來，那段時間才看得見。
|
||||
|
||||
每筆蒐集十項資訊（存取庫、分支、計畫連結、工作包連結、花費時間、token 用量、任務狀態、執行細節、困難與解決、PR 目標分支），用 `tools/worklog-target.sh` 產生目標頁，套範本後附加到 `LOG_{HASH}` 與 `LOG_CONTENTS`。寫入前跑 `tools/worklog-pending.sh merge {HASH} {本次條目檔}`：之前有階段跑完沒寫日誌，內容暫存在那裡，這次一併寫進去；wiki 寫入成功才 `commit` 清掉暫存，失敗就 `abort` 保留。
|
||||
每筆蒐集十項資訊（存取庫、分支、計畫連結、工作包連結、花費時間、token 用量、任務狀態、執行細節、困難與解決、PR 目標分支）。計畫連結、工作包連結、花費時間、token 用量四項來源互不相依，併行取得；存取庫解析與 `HASH` 計算也併行。用 `tools/worklog-target.sh` 產生目標頁，工作週的週五由同一支的 `friday` 子命令算出，套範本後附加到 `LOG_{HASH}` 與 `LOG_CONTENTS`。寫入前跑 `tools/worklog-pending.sh merge {HASH} {本次條目檔}`：之前有階段跑完沒寫日誌，內容暫存在那裡，這次一併寫進去；wiki 寫入成功才 `commit` 清掉暫存，失敗就 `abort` 保留。
|
||||
|
||||
### `stats`
|
||||
|
||||
@@ -51,7 +52,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
### `report`
|
||||
|
||||
把工作日誌總結成年報、月報、週報或日報。期間由 `tools/report-range.sh` 算出（週次採 ISO-8601），範本由 `tools/report-template.sh` 解析——工作目錄的 `.jsc/templates/report-{period}.md` 優先，沒有才用技能自帶的那份。讀 `LOG_CONTENTS` 列出的所有日誌頁，取工作日期落在期間內的條目，統計條目數、涵蓋存取庫、花費時間、token 用量、困難與未結項目，填進範本後寫入 wiki `REPORT_{HASH}`（`HASH` 取 `{owner}/{repo}/{期間}`），同一期間重跑只換掉那一節。單筆工作紀錄請用 `worklog`。
|
||||
把工作日誌總結成年報、月報、週報或日報。期間由 `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`。
|
||||
|
||||
<!-- JSC-SKILLS:END -->
|
||||
|
||||
@@ -79,3 +80,4 @@ Wiki 位置：日誌頁用 `JSC_WIKI_REPO_LOG`、教訓頁用 `JSC_WIKI_REPO_LEA
|
||||
|
||||
- [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：花費時間（`session-timer.sh report`）與用量資料來源
|
||||
- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫
|
||||
- [`jsc-ask`](https://gitea.jsc.idv.tw/plugins/ask)：期間、任務狀態、困難等要問使用者時的決策樹
|
||||
|
||||
@@ -3,7 +3,9 @@
|
||||
# 用法:
|
||||
# token-usage.sh <cli> [session-id] # cli = claude|codex|copilot|antigravity|kiro
|
||||
# 輸出: 一行「<input>(tab)<output>」。任何來源讀不到就印「N/A(tab)N/A」並 exit 0。
|
||||
# 護欄: 沒給 cli 或 cli 名稱不認得，回傳 2。
|
||||
#
|
||||
# 結束碼: 0=成功（含來源讀不到而印 N/A 的情況，那是「這個 CLI 沒有可讀數字」，不是故障）
|
||||
# 2=用法錯誤（沒給 cli，或 cli 名稱不在 claude|codex|copilot|antigravity|kiro 之內）
|
||||
#
|
||||
# 各 CLI 的取得方式（原本寫在 worklog 的 SKILL.md，現在收在這裡）:
|
||||
# claude 加總 transcript JSONL（`$CLAUDE_CONFIG_DIR` 或 `~/.claude` 底下的
|
||||
|
||||
Reference in New Issue
Block a user