plugins/log
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aee17e45c7ce5e547204e9ad61729987eae45ed8
log/README.md
T
jiantw83 aee17e45c7 feat(wiki): 三個目錄頁改走專用存取庫，比對鍵改用裸 HASH 
What：LOG_CONTENTS、LEARN_CONTENTS、REPORT_CONTENTS 改由 wiki-repo CONTENTS
解析並透過 wiki-contents.sh upsert 寫入，內容頁仍各走自己的型別。LOG 與 REPORT
的目錄頁新增一欄裸 HASH 當比對鍵。

Why：比對鍵原本是含網址的儲存格，換主機、換存取庫或 URL 編碼有差就比對不到，
upsert 會走附加分支，同一頁多出第二列而舊列永遠不再更新。REPORT 更脆：存取庫一換，
雜湊與網址同時變，四個期間的列會一次全部重複。

How：worklog-pending.sh 的 valid_hash 放寬成 40 碼、8 碼與 H 加 7 碼三種形狀。
放寬的是長度不是字元集——先剝字元再比長度的順序保留，路徑穿越與換行注入照樣擋下。
年報不得沿用日誌存取庫那條規則收斂到內容頁，目錄頁同住一庫是另一回事。

Who：jsc-log
2026-09-02 11:02:21 +08:00

88 lines
11 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`）另住一個專用存取庫，與內容頁分開。
## 安裝、更新、移除
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 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`。
<!-- 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 內解得開，跨庫就是死連結。
## 相關 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