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
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# jsc-log — 工作日誌與統計
|
||||
|
||||
jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算；首碼若是數字或 `A`／`B`／`C`，改成 `H` 加上原前 7 碼；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 `LEARN_{HASH}`，供下次執行前查閱。
|
||||
jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算，取 `{owner}/{repo}` 的完整 SHA-1 四十碼、a-f 轉大寫，不截短也不加前綴；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 `LEARN_{HASH}`，供下次執行前查閱。目錄頁（`LOG_CONTENTS`、`LEARN_CONTENTS`、`REPORT_CONTENTS`）另住一個專用存取庫，與內容頁分開。
|
||||
|
||||
## 安裝、更新、移除
|
||||
|
||||
@@ -24,7 +24,7 @@ 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）。`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/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` 代表期間內沒有條目，全零結果照樣印出來 |
|
||||
@@ -40,7 +40,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
每完成一個任務就寫一筆日誌。任務有三種：一個工作包、一輪 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` 保留。
|
||||
每筆蒐集十項資訊（存取庫、分支、計畫連結、工作包連結、花費時間、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`
|
||||
|
||||
@@ -48,11 +48,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
### `learn`
|
||||
|
||||
技能執行後把教訓（日期、技能、CLI、情境、教訓、下次做法）附加到 `LEARN_{HASH}` 並更新 `LEARN_CONTENTS`；技能執行前查閱同兩頁，套用相符的「下次做法」。
|
||||
技能執行後把教訓（日期、技能、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` 列出的所有日誌頁後，交給 `tools/log-aggregate.sh` 算出條目數、涵蓋存取庫、花費時間、各 CLI token 用量與狀態計數，填進範本後寫入 wiki `REPORT_{HASH}`（`HASH` 取 `{owner}/{repo}/{期間}`，這裡的 `{owner}/{repo}` 取 REPORT wiki 存取庫，不是程式碼存取庫——本頁其他 `HASH` 取的是程式碼存取庫，只有這一處不同），同一期間重跑只換掉那一節。年報的教訓頁另解 `JSC_WIKI_REPO_LEARN`，不沿用日誌頁的存取庫。單筆工作紀錄請用 `worklog`。
|
||||
把工作日誌總結成年報、月報、週報或日報。期間由 `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 -->
|
||||
|
||||
@@ -74,7 +74,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
## 環境變數
|
||||
|
||||
Wiki 位置：日誌頁用 `JSC_WIKI_REPO_LOG`、教訓頁用 `JSC_WIKI_REPO_LEARN`、報表頁用 `JSC_WIKI_REPO_REPORT`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。先讀目前 shell 繼承的環境變數，缺值才詢問。
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user