plugins/log
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee32bfd2eca8efe2fc42e437d91aaefa7872f9ff
log/README.md
T
jiantw83 18d12bbbe2 docs(behaviors): 說明文件與行為清單跟上目錄頁的條列版面 
存取庫說明與技能行為清單裡講到目錄頁的段落一律改口：一筆一個大標題區塊、
標題就是內容頁頁名也就是鍵、欄位是標題底下的一層條列，頁上不留表格。

三個目錄頁的範本與三支技能的敘述都換了版面，說明文件卻還寫著「一列」與
「表格」。文件與範本各說一套，照文件手工補紀錄的人會補出一列表格，那一列
在條列頁上讀不成一筆紀錄，而且下一輪工具重寫時也不會被當成既有那一筆換掉。

只改敘述，行為與呼叫參數都不動；欄位語意與寫入語意的正本仍在各自的範本
引言裡，這裡只指向它，不重述細節。

範圍是說明文件與技能行為清單裡的目錄頁敘述。
2026-09-02 17:22:33 +08:00

88 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# jsc-log — 工作日誌與統計
jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算，取 `{owner}/{repo}` 的完整 SHA-1 四十碼、a-f 轉大寫，不截短也不加前綴；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 `LEARN_{HASH}`，供下次執行前查閱。目錄頁（`LOG_CONTENTS`、`LEARN_CONTENTS`、`REPORT_CONTENTS`）另住一個專用存取庫，與內容頁分開。目錄頁的版面是「H1 加 `>` 引言，再一筆一個 H2 區塊」：H2 標題就是那一筆的內容頁頁名，也就是鍵，欄位寫成標題底下的 `- {欄位名}：{值}` 條列，頁上不留 markdown 表格。
## 安裝、更新、移除
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]` 印出「起<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 目錄
呼叫方式：Claude / Antigravity `/jsc-log:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
<!-- JSC-SKILLS:START -->
### `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 1 LOG_{HASH}` 單一區塊寫回：鍵是 H2 標題的頁名 `LOG_{HASH}`，「日誌頁」那一條的絕對網址（`gitea.sh wiki-url` 給的）只給人點。網址帶主機名，拿它當鍵換主機就比不到，同一頁會多一個區塊；頁名只由 `{owner}/{repo}` 決定，不受影響。命令裡的 `1` 是 `<key-col>`，只在舊頁還是表格時用來認出哪一欄的文字當 H2 標題。寫入前跑 `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 2 LEARN_{HASH}` 更新 `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 1 REPORT_{HASH}` 寫回，鍵同樣是 H2 標題的頁名。年報的教訓「內容頁」另解 `JSC_WIKI_REPO_LEARN`，不沿用日誌頁的存取庫；目錄頁同住 CONTENTS 存取庫是另一回事，兩者別混。單筆工作紀錄請用 `worklog`。
<!-- 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` |
| `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 才寫。
## 相關 domain
- [`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)：期間、任務狀態、困難等要問使用者時的決策樹
Reference in New Issue View Git Blame Copy Permalink