fix/skill-check-compliance-and-flow #22

2026-08-31T03:08:24Z

jiantw83 commented

2026-08-31 03:08:24 +00:00

摘要

需求描述：修掉 log 技能組的三類問題。第一類是覆蓋風險，六處把「讀失敗」與「頁面不存在」混為一談，金鑰失效就會蓋掉整份日誌；第二類是合規，report 讀錯 wiki 存取庫，多支腳本沒有結束碼宣告；第三類是流程效率，報表彙總與工作週週五下放給腳本，多來源改成併行取得。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/log-aggregate.sh`	新檔。報表數字原本靠模型逐頁自己數，只有一筆填了花費時間時容易被攤成四筆的工時。把彙總寫成腳本，並把「無資料不估算」寫死在程式裡：沒填時間的條目只進 ELAPSED_MISSING，整段期間都沒有時間就印「無資料」，不印 0
`tools/worklog-target.sh`	新增 friday 子命令。工作週的週五原本由人或模型當場算，跨月、跨年那一週會差一天。週界向 report-range.sh weekly 取得，這裡只加四天，週的定義維持單一來源。檔頭同時補上結束碼宣告
`skills/worklog/SKILL.md`	讀日誌頁只認結束碼 4 為「頁面不存在」，7 與 8 一律中止。原本讀失敗也會建新頁，等於用這一筆條目取代整份日誌。同時把四項來源改成併行取得，週五改呼叫腳本，暫存區的三個結束碼各自列出處理方式
`skills/learn/SKILL.md`	教訓頁與教訓目錄頁的兩處讀取改成同一套分流，只有 4 才從樣板建頁。原本讀失敗會把既有教訓清成空表。wiki 存取庫改走 gitea.sh wiki-repo LEARN，不再自己解環境變數
`skills/report/SKILL.md`	三處讀取分流改寫，讀不到不再算成「零筆」，否則會產出一份說「這段期間沒有工作」的假報表。教訓頁另解 LEARN 存取庫，不再沿用日誌頁的。彙總改呼叫 log-aggregate.sh，範本、日誌頁、教訓頁三線併行，目錄列改成先讀再更新那一列
`skills/stats/SKILL.md`	補上結束碼分流。原本不看結束碼就讀輸出，參數錯誤時一行都沒有，會被讀成「零次」。現在 0 才是零次，2 是參數錯誤，要改參數重跑
`templates/log-contents.md`	補寫入語意：一列代表一個日誌頁，先讀整頁，找得到就更新那一列，找不到才新增，禁止整頁覆蓋
`templates/learn-contents.md`	同上，一列代表一個存取庫，且不得改動別人的列
`templates/report-contents.md`	同上，一列代表一個存取庫的一種期間
`tools/usage-stats.sh`	參數護欄從 `${1:?}` 改成明確回傳結束碼 2，訊息改成繁體中文，檔頭補上結束碼宣告，並寫明資料檔不存在為什麼算成功
`tools/token-usage.sh`	檔頭補上結束碼宣告。原本只寫「護欄回傳 2」，沒說來源讀不到印 N/A 也算成功，接手的人會把它當故障追
`README.md`	工具表補進彙總腳本並補記 friday 子命令，worklog 與 report 兩節改寫成新流程，相依清單補上 jsc-ask
`plugin.json`	補上 jsc-ask 與 jsc-hooks 的最低版本需求並更新版號。技能早就用到這兩個外掛，清單卻只宣告 gitea
`.claude-plugin/plugin.json`	同上，三份清單保持一致
`.codex-plugin/plugin.json`	同上，三份清單保持一致

設計重點

覆蓋風險的修法是「只有一個結束碼可以建新頁」。六處讀取全部改成看 gitea.sh wiki-get 的結束碼再決定動作：0 表示既有內容在手上，只能附加；4 表示頁面真的不存在，才可以從樣板建頁；5、7、8 一律中止，不寫任何一頁。
為什麼非分不可：金鑰失效回的是 7，不是 4。原本兩者同路，技能會判斷「這頁還沒有」，照樣板建一份新頁覆蓋回去。整份工作日誌會被這一筆條目取代，既有教訓會被清成空表，報表會產出全空的假數字。這些內容只活在 wiki 上，覆蓋之後救不回來。
目錄頁一律先讀整頁再改自己那一列，其他列一個字都不動。三份 contents 樣板把這條寫進頁面本身，讓下一個寫入者也看得到。
內容頁與目錄頁分兩次寫，內容頁先寫。目錄列指向一個寫失敗的頁面，比缺一列更難查。
「無資料不估算」從散文變成程式。log-aggregate.sh 讓沒填時間的條目只進 ELAPSED_MISSING，整段期間都沒有時間就印「無資料」。印 0 會被讀成「花了 0 分鐘」，那是另一個假數字。
週的定義只留一個來源。friday 向 report-range.sh weekly 取週一，自己只加四天，兩邊各算一次就會在跨月、跨年那一週各走各的。
併行只用在互不相依的來源：worklog 的四項資訊各走各的來源，report 的範本、日誌頁、教訓頁三線同時跑，日誌頁再一頁一個 sub agent。

測試結果

sh -n 語法檢查 tools 底下七支腳本，全數通過。
worklog-target.sh friday 印出 2026-09-04，與本週相符。friday 2026-12-31 印出 2027-01-01，跨年那一週正確落在隔年。friday 2026-13 回結束碼 2 並印出日期格式訊息。
worklog-target.sh {HASH} all 仍印出 PAGE 與 CONTENTS 兩行，原有行為未受影響。
log-aggregate.sh 護欄：無參數回 2 並印用法，起訖顛倒回 2，指到不存在的檔案回 4。
log-aggregate.sh 樣本測試，三筆條目中兩筆落在期間內：印出 ENTRIES=2、REPOS=2、ELAPSED_MINUTES=90、ELAPSED_ENTRIES=1、ELAPSED_MISSING=1、TOKEN=claude 1000/200、TOKEN_MISSING=1、STATUS 完成 1 與部分完成 1。期間外那筆的五小時沒有被算進總和。
無資料不估算實測：全部條目都沒填時間時，印 ELAPSED_MINUTES=無資料，不是 0；期間內沒有任何條目時，全零結果照樣印出並回結束碼 3。
usage-stats.sh 三種參數錯誤（沒給子命令、子命令不認得、--cli 沒帶值）都印用法並回 2；usage-stats.sh skills 正常列出既有統計。
token-usage.sh nope 回結束碼 2，與新檔頭宣告一致。
未測項目：wiki 讀取回 7 與 8 的分流寫在技能文件裡，本機沒有可造出 401 或 API 失敗的環境，本輪未實測，靠文件表格與人工複核把關。

前置 Push Request

無

## 摘要 - 需求描述：修掉 log 技能組的三類問題。第一類是覆蓋風險，六處把「讀失敗」與「頁面不存在」混為一談，金鑰失效就會蓋掉整份日誌；第二類是合規，report 讀錯 wiki 存取庫，多支腳本沒有結束碼宣告；第三類是流程效率，報表彙總與工作週週五下放給腳本，多來源改成併行取得。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/log-aggregate.sh` | 新檔。報表數字原本靠模型逐頁自己數，只有一筆填了花費時間時容易被攤成四筆的工時。把彙總寫成腳本，並把「無資料不估算」寫死在程式裡：沒填時間的條目只進 ELAPSED_MISSING，整段期間都沒有時間就印「無資料」，不印 0 | | `tools/worklog-target.sh` | 新增 friday 子命令。工作週的週五原本由人或模型當場算，跨月、跨年那一週會差一天。週界向 report-range.sh weekly 取得，這裡只加四天，週的定義維持單一來源。檔頭同時補上結束碼宣告 | | `skills/worklog/SKILL.md` | 讀日誌頁只認結束碼 4 為「頁面不存在」，7 與 8 一律中止。原本讀失敗也會建新頁，等於用這一筆條目取代整份日誌。同時把四項來源改成併行取得，週五改呼叫腳本，暫存區的三個結束碼各自列出處理方式 | | `skills/learn/SKILL.md` | 教訓頁與教訓目錄頁的兩處讀取改成同一套分流，只有 4 才從樣板建頁。原本讀失敗會把既有教訓清成空表。wiki 存取庫改走 gitea.sh wiki-repo LEARN，不再自己解環境變數 | | `skills/report/SKILL.md` | 三處讀取分流改寫，讀不到不再算成「零筆」，否則會產出一份說「這段期間沒有工作」的假報表。教訓頁另解 LEARN 存取庫，不再沿用日誌頁的。彙總改呼叫 log-aggregate.sh，範本、日誌頁、教訓頁三線併行，目錄列改成先讀再更新那一列 | | `skills/stats/SKILL.md` | 補上結束碼分流。原本不看結束碼就讀輸出，參數錯誤時一行都沒有，會被讀成「零次」。現在 0 才是零次，2 是參數錯誤，要改參數重跑 | | `templates/log-contents.md` | 補寫入語意：一列代表一個日誌頁，先讀整頁，找得到就更新那一列，找不到才新增，禁止整頁覆蓋 | | `templates/learn-contents.md` | 同上，一列代表一個存取庫，且不得改動別人的列 | | `templates/report-contents.md` | 同上，一列代表一個存取庫的一種期間 | | `tools/usage-stats.sh` | 參數護欄從 `${1:?}` 改成明確回傳結束碼 2，訊息改成繁體中文，檔頭補上結束碼宣告，並寫明資料檔不存在為什麼算成功 | | `tools/token-usage.sh` | 檔頭補上結束碼宣告。原本只寫「護欄回傳 2」，沒說來源讀不到印 N/A 也算成功，接手的人會把它當故障追 | | `README.md` | 工具表補進彙總腳本並補記 friday 子命令，worklog 與 report 兩節改寫成新流程，相依清單補上 jsc-ask | | `plugin.json` | 補上 jsc-ask 與 jsc-hooks 的最低版本需求並更新版號。技能早就用到這兩個外掛，清單卻只宣告 gitea | | `.claude-plugin/plugin.json` | 同上，三份清單保持一致 | | `.codex-plugin/plugin.json` | 同上，三份清單保持一致 | ## 設計重點 - 覆蓋風險的修法是「只有一個結束碼可以建新頁」。六處讀取全部改成看 gitea.sh wiki-get 的結束碼再決定動作：0 表示既有內容在手上，只能附加；4 表示頁面真的不存在，才可以從樣板建頁；5、7、8 一律中止，不寫任何一頁。 - 為什麼非分不可：金鑰失效回的是 7，不是 4。原本兩者同路，技能會判斷「這頁還沒有」，照樣板建一份新頁覆蓋回去。整份工作日誌會被這一筆條目取代，既有教訓會被清成空表，報表會產出全空的假數字。這些內容只活在 wiki 上，覆蓋之後救不回來。 - 目錄頁一律先讀整頁再改自己那一列，其他列一個字都不動。三份 contents 樣板把這條寫進頁面本身，讓下一個寫入者也看得到。 - 內容頁與目錄頁分兩次寫，內容頁先寫。目錄列指向一個寫失敗的頁面，比缺一列更難查。 - 「無資料不估算」從散文變成程式。log-aggregate.sh 讓沒填時間的條目只進 ELAPSED_MISSING，整段期間都沒有時間就印「無資料」。印 0 會被讀成「花了 0 分鐘」，那是另一個假數字。 - 週的定義只留一個來源。friday 向 report-range.sh weekly 取週一，自己只加四天，兩邊各算一次就會在跨月、跨年那一週各走各的。 - 併行只用在互不相依的來源：worklog 的四項資訊各走各的來源，report 的範本、日誌頁、教訓頁三線同時跑，日誌頁再一頁一個 sub agent。 ## 測試結果 - `sh -n` 語法檢查 tools 底下七支腳本，全數通過。 - `worklog-target.sh friday` 印出 2026-09-04，與本週相符。`friday 2026-12-31` 印出 2027-01-01，跨年那一週正確落在隔年。`friday 2026-13` 回結束碼 2 並印出日期格式訊息。 - `worklog-target.sh {HASH} all` 仍印出 PAGE 與 CONTENTS 兩行，原有行為未受影響。 - `log-aggregate.sh` 護欄：無參數回 2 並印用法，起訖顛倒回 2，指到不存在的檔案回 4。 - `log-aggregate.sh` 樣本測試，三筆條目中兩筆落在期間內：印出 ENTRIES=2、REPOS=2、ELAPSED_MINUTES=90、ELAPSED_ENTRIES=1、ELAPSED_MISSING=1、TOKEN=claude 1000/200、TOKEN_MISSING=1、STATUS 完成 1 與部分完成 1。期間外那筆的五小時沒有被算進總和。 - 無資料不估算實測：全部條目都沒填時間時，印 ELAPSED_MINUTES=無資料，不是 0；期間內沒有任何條目時，全零結果照樣印出並回結束碼 3。 - `usage-stats.sh` 三種參數錯誤（沒給子命令、子命令不認得、--cli 沒帶值）都印用法並回 2；`usage-stats.sh skills` 正常列出既有統計。 - `token-usage.sh nope` 回結束碼 2，與新檔頭宣告一致。 - 未測項目：wiki 讀取回 7 與 8 的分流寫在技能文件裡，本機沒有可造出 401 或 API 失敗的環境，本輪未實測，靠文件表格與人工複核把關。 ## 前置 Push Request - 無

jiantw83 added 4 commits 2026-08-31 03:08:25 +00:00

fix(overwrite): 只有頁面真的不存在才建新頁 7d803245a5

- What：worklog、learn、report 三支技能共六處讀取分流改寫，只有結束碼 4 才建新頁；
  結束碼 7 與 8 一律中止，一個字都不寫。三份目錄頁樣板補上寫入語意，明寫禁止整頁覆蓋、
  不得改動別人的列。usage-stats.sh 的參數護欄改成明確回傳結束碼 2。
- Why：原本把「讀失敗」與「頁面不存在」當成同一件事。金鑰失效時讀取回 7，技能卻讀成
  「這頁還沒有」，於是照樣板建一份新頁蓋回去。整份工作日誌會被這一筆條目取代，
  既有教訓會被清成空表，報表則產出一份說「這段期間沒有工作」的假數字。
  這些內容只活在 wiki 上，蓋掉就救不回來，所以這是本輪最要緊的一項。
- How：每一處讀取都先看結束碼再決定動作，並在技能文件裡列成表格：
  0 接在既有內容後面附加，4 才從樣板建頁，5 缺網址就中止，7 金鑰或權限問題就中止，
  8 其他 API 失敗就中止。目錄頁一律先讀整頁再改那一列。
  stats 也補上分流，參數錯誤不再被讀成「零次」。
- Who：worklog、learn、report、stats 四支技能的 wiki 讀寫與統計輸出。

feat(tools): 報表彙總與工作週週五都交給腳本算 1bec87b047

- What：新增 tools/log-aggregate.sh，把日誌頁彙總成報表數字；
  tools/worklog-target.sh 新增 friday 子命令，印出該工作週的週五。
- Why：彙總與日期原本只寫在技能散文裡，每次跑都靠模型自己數。
  四個條目只有一個填了花費時間時，模型容易把它攤到每一筆，得出一個沒人做過的工時。
  週五同理，跨月、跨年那一週用手算就會差一天。規則寫進程式，每次跑才會一樣。
- How：log-aggregate.sh 讀日誌條目的固定版型，依條目標題的日期取範圍內的條目，
  印出條目數、存取庫、花費時間、各 CLI 的 token 用量與狀態計數。
  「無資料不估算」寫死在程式裡：沒填時間的條目不進總和，只進 ELAPSED_MISSING；
  整段期間都沒有時間就印「無資料」，不印 0，因為 0 會被讀成「花了 0 分鐘」。
  friday 的週界向 report-range.sh weekly 取得，這裡只做「週一加四天」，不自己定義週的起點。
- Who：report 技能的數字彙總，worklog 技能的日誌頁週次。

docs(log): 補上工具結束碼宣告與新流程說明 04f28d4505

- What：README 的工具表補進彙總腳本，並改寫 worklog 與 report 兩節；
  tools/token-usage.sh 的檔頭改寫成完整的結束碼宣告。
- Why：README 還停在舊流程，讀的人會以為報表數字仍由技能自己數，也不知道週五已經有腳本可用。
  token-usage.sh 原本只寫「護欄回傳 2」，沒說來源讀不到時印 N/A 也算成功，
  接手的人容易把那個情況當成故障，白追一輪。
- How：工具表加一列，寫出彙總腳本的輸出欄位與「無資料不估算」；
  worklog 一節寫出四項來源併行取得、週五由腳本算；
  report 一節寫出三線併行、彙總改走腳本，以及教訓頁另解自己的 wiki 存取庫。
  相依清單補上 jsc-ask 一列，說明它負責問期間與任務狀態。
- Who：整個 log 技能組的說明文件。

chore(manifest): 宣告 jsc-ask 與 jsc-hooks 相依並更新版號 fee4185966

- What：Claude、Codex 與根目錄三份 plugin 清單同步補上 jsc-ask 與 jsc-hooks 的最低版本需求，
  並把版號往前推一版。
- Why：技能早就呼叫 jsc-ask 的決策樹問期間與任務狀態，也讀 jsc-hooks 的計時器與用量紀錄取數字，
  清單卻只宣告 gitea。缺宣告時，部署到只裝一半的機器上不會被擋，要跑到一半才失敗，
  而且失敗訊息指向 wiki 或計時器，看不出真正缺的是哪個外掛。
- How：三份清單的 requires 一起改，三份內容保持一致，免得不同 CLI 讀到不同的相依。
- Who：log 技能組的安裝與部署檢查。

admin merged commit a0336e733d into develop

2026-08-31 03:16:13 +00:00

admin deleted branch fix/skill-check-compliance-and-flow

2026-08-31 03:16:13 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/log#22