jiantw83
aee17e45c7
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
8.7 KiB
8.7 KiB
jsc-log 技能行為清單
本頁記錄 jsc-log 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
learn
| 項目 | 內容 |
|---|---|
| 觸發時機 | 一次技能執行留下可重用的教訓時，用 record 模式記錄。要跑某支技能之前，用 consult 模式查過去的教訓。工時與 Token 紀錄不走這支，走 worklog |
| 關鍵步驟 | record 模式收齊日期、技能、CLI、情境、教訓、下次做法這六欄、從 git remote get-url origin 解出 {owner}/{repo}、用 hash-id 算出完整 40 碼大寫的 {HASH}、用 wiki-repo LEARN 解出教訓頁存取庫、開 sub agent 讀 LEARN_{HASH}、依 wiki-get 的退出碼分支（0 在表尾追加一列、4 才用 templates/learn-page.md 建頁、7 與 8 停止並回報）、取 wiki-url 的絕對網址、同一輪跑 wiki-contents.sh upsert LEARN 1 {owner}/{repo} 更新落在 CONTENTS 存取庫的 LEARN_CONTENTS、依它的退出碼分流（0 已寫、1 寫入失敗、2 參數錯、3 未設 JSC_WIKI_REPO_CONTENTS、4 缺範本、7 金鑰失效、8 其他 API 失敗）、寫入失敗重試一次；consult 模式算出 {HASH}、從 CONTENTS 存取庫讀 LEARN_CONTENTS、從 LEARN 存取庫讀 LEARN_{HASH}、挑出「技能」欄相符的列、整理每一列的「下次做法」交給呼叫端 |
| 外部呼叫 | jsc-gitea/tools/hash-id、jsc-gitea/tools/gitea.sh wiki-repo LEARN 與 wiki-repo CONTENTS 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-gitea:wiki（其餘 wiki 讀寫）、git remote get-url origin、templates/learn-page.md、templates/learn-contents.md |
| 完成條件 | record 模式要 sub agent 回報兩頁都寫入成功，主代理確認新列在 LEARN_{HASH} 上，原有的列一列不少，wiki-contents.sh 回 0 並印出 updated 或 added。consult 模式要兩頁都讀到，或以退出碼 4 回報頁面不存在，或在 5、7、8 停止並回報狀態 |
| 可驗證跡象 | LEARN 存取庫的 LEARN_{HASH} 表尾多一列教訓；CONTENTS 存取庫的 LEARN_CONTENTS 上該 repo 那一列的「最後更新時間」換新，且「教訓紀錄」欄是絕對網址，不是 [[頁名]]。頁面原本不存在時，會新建 LEARN_{HASH} 或 LEARN_CONTENTS。consult 模式無寫入跡象，只有回報內容 |
report
| 項目 | 內容 |
|---|---|
| 觸發時機 | 有人要一段期間的工作總結時用，期間分年、月、週、日四種。單一工作包的紀錄不走這支，走 worklog |
| 關鍵步驟 | 呼叫端沒指定期間就依 jsc-ask:ask 問、跑 tools/report-range.sh 取得起訖日與標籤、平行做四件事（tools/report-template.sh resolve 解出範本、從 CONTENTS 存取庫讀 LOG_CONTENTS 並照列上的絕對網址逐頁讀回工作日誌、年報另外讀 LEARN_CONTENTS 並用 wiki-repo LEARN 解出教訓內容頁的存取庫、解出 REPORT 的 wiki repo）、把頁面內容存成檔案後跑 tools/log-aggregate.sh 算出條目數、涵蓋 repo、花費時間、Token 用量、任務狀態、從存活條目挑出阻塞與未完成工作包、照範本的標題與表格填出報告、用 hash-id "{REPORT wiki 存取庫}/{period}" 算出完整 40 碼頁名、讀 REPORT_{HASH} 後把本期當成新章節追加在最前、取 wiki-url 的絕對網址並依它的退出碼分流（4 是頁還沒寫、5 是頁上沒有 html_url、7 與 8 一律停下並回報金鑰或 API 狀態，不得當成 4）、最後跑 wiki-contents.sh upsert REPORT 2 {HASH} 更新落在 CONTENTS 存取庫的 REPORT_CONTENTS（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結） |
| 外部呼叫 | tools/report-range.sh、tools/report-template.sh、tools/log-aggregate.sh、jsc-gitea/tools/gitea.sh wiki-repo（CONTENTS、LOG、LEARN、REPORT）與 hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-gitea:wiki、jsc-ask:ask、templates/report-{period}.md、templates/report-contents.md |
| 完成條件 | 回報頁面 URL，或回報跳過寫入與它的原因，或在讀取回 7、8 時停下並回報狀態。wiki-contents.sh upsert 要回 0，回 1、2、3、4、7、8 就照該碼回報且不得謊報已寫入。收尾要講出期間標籤、條目數、涵蓋的 repo、範本來源、頁面 URL、帶到下一期的未完成工作包清單，以及 ELAPSED_MISSING 與 TOKEN_MISSING |
| 可驗證跡象 | REPORT 存取庫的 REPORT_{HASH}（雜湊取自 REPORT wiki 存取庫的 {owner}/{repo} 加期間，不是程式碼存取庫）多一個本期章節；CONTENTS 存取庫的 REPORT_CONTENTS 該列的「最新一期」、「期數」、「最後更新」換新，且「報表頁」欄是絕對網址、「HASH」欄是不帶連結的裸 HASH。重跑同一期間只換掉那一列，不會多出第二列。本機留下工作日誌頁面內容的暫存檔，供 log-aggregate.sh 讀取。沒設定 REPORT wiki repo 時不寫 wiki，只印出報告本文；沒設定 JSC_WIKI_REPO_CONTENTS 時內容頁照寫，只有目錄頁那一列沒動 |
stats
| 項目 | 內容 |
|---|---|
| 觸發時機 | 使用者問某支技能用了幾次，或問技能之間的呼叫鏈用了幾次。Token 與工時統計不走這支，走 worklog |
| 關鍵步驟 | 直接跑 tools/usage-stats.sh skills 或 tools/usage-stats.sh chains、需要時加 --cli 篩選單一 CLI、先讀退出碼再看輸出、退出碼 0 就把每一行印成表格一列、一行都沒印也是退出碼 0，代表次數為零，要說明 jsc-hooks 還沒經 jsc-hooks:hooks-install 安裝接線且不出表、退出碼 2 代表子指令或 --cli 參數被拒，改正參數後重跑 |
| 外部呼叫 | tools/usage-stats.sh；資料由 jsc-hooks/hooks/skill-usage.sh 持續寫進 $JSC_HOME/usage/*.jsonl，這支技能只讀不寫 |
| 完成條件 | 讀到退出碼，並走完該退出碼指定的分支 |
| 可驗證跡象 | 無寫入跡象，只有回報內容 |
worklog
| 項目 | 內容 |
|---|---|
| 觸發時機 | implement 或 maintain 階段每結束一項任務就寫一筆。一項任務是一個工作包、一輪 PR 意見修正，或一次獨立的修正提交。下一項任務開始前就要寫完。規劃階段的筆記不走這支 |
| 關鍵步驟 | 全程由 sub agent 收集與寫入、平行取得十項事實（git remote get-url origin 的 repo、git branch --show-current 的分支、PLAN 頁絕對連結、ANALYZE 頁工作包絕對連結、session-timer.sh report 的花費時間、token-usage.sh 的各 CLI Token、任務狀態、細節與產出、困難與解法、PR 目標分支）、平行解出 LOG wiki repo（只供內容頁）與完整 40 碼大寫的 {HASH}、跑 tools/worklog-target.sh 取得頁名與本週五日期、用 templates/log-entry.md 填出單筆條目檔、跑 tools/worklog-pending.sh merge 併入待寫內容、讀 PAGE 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、同一輪用 wiki-repo CONTENTS 解出目錄頁存取庫、取 wiki-url 的絕對網址、跑 wiki-contents.sh upsert LOG 2 {HASH} 更新 LOG_CONTENTS（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結）並依 0、1、2、3、4、7、8 各自分流、最後依成敗跑 worklog-pending.sh commit 或 abort |
| 外部呼叫 | jsc-hooks/hooks/session-timer.sh report、tools/token-usage.sh、tools/worklog-target.sh、tools/worklog-pending.sh、jsc-gitea/tools/gitea.sh wiki-repo（LOG 與 CONTENTS）與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-gitea/tools/hash-id、jsc-gitea:wiki、jsc-ask:ask、git remote get-url origin、git branch --show-current、templates/log-entry.md、templates/log-contents.md |
| 完成條件 | MERGED 的每一筆條目都在 PAGE 上，原有條目逐字不動，wiki-contents.sh upsert 回 0 且 CONTENTS 該列帶著本週五日期、其他列不動，worklog-pending.sh 的 commit 或 abort 其中一個跑過並回報退出碼。upsert 回非 0 就照該碼回報，並把步驟七當成失敗處理 |
| 可驗證跡象 | LOG 存取庫的 LOG_{HASH} 頁尾多一筆條目；CONTENTS 存取庫的 LOG_CONTENTS 該列的「條目數」與「最後更新」換新，且「日誌頁」欄是絕對網址，不是 [[頁名]]，「HASH」欄是不帶連結的裸 HASH。重跑同一頁只換掉那一列，不會多出第二列。$JSC_HOME/worklog-pending/{HASH} 底下的待寫檔在 commit 後清空，abort 後原樣保留；該目錄名是 40 碼大寫十六進位，或尚未遷移的舊暫存那種 8 碼大寫十六進位、H 加 7 碼大寫十六進位。本機留下填好的條目檔 |