log/references/behaviors.md

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 的絕對網址並寫成 [{頁名}]({絕對網址})、把該網址交給 link-check.sh 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 GITEA_HOST、7 金鑰被拒就停下）、照 templates/learn-contents.md 組出一個 H2 區塊檔（## LEARN_{HASH} 加空行加各條 - {欄位名}：{值}）、同一輪跑 wiki-contents.sh upsert LEARN 2 LEARN_{HASH} 更新落在 CONTENTS 存取庫的 LEARN_CONTENTS（鍵是 H2 標題的頁名，不是那條帶主機名的連結；命令裡的 2 是 <key-col>，只在舊頁還是表格時用來認出哪一欄的文字當標題）、依它的退出碼分流（0 已寫、1 組不出內容或寫入失敗、2 參數錯、3 未設 JSC_WIKI_REPO_CONTENTS、4 缺範本、7 金鑰失效、8 其他 API 失敗）、寫入失敗重試一次；consult 模式算出 {HASH}、從 CONTENTS 存取庫讀 LEARN_CONTENTS、從 LEARN 存取庫讀 LEARN_{HASH}、依區塊裡「教訓紀錄」那一條的絕對網址讀頁、挑出「技能」欄相符的列、整理每一列的「下次做法」交給呼叫端；兩種模式都以 jsc-hooks/tools/report-status.sh skill-end jsc-log:learn {status} {結束碼} {detail} 收尾，腳本不在這台機器上就安靜跳過
外部呼叫	jsc-gitea/tools/hash-id、jsc-gitea/tools/gitea.sh wiki-repo LEARN 與 wiki-repo CONTENTS 與 wiki-url、jsc-gitea/tools/link-check.sh（寫入前驗證連結）、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} 上、該存取庫那個區塊在 LEARN_CONTENTS 上，原有的列與區塊一個不少，寫入前 link-check.sh 回 0，wiki-contents.sh 回 0 並印出 updated 或 added。link-check.sh 回 1 就不寫目錄頁，改回報 DEAD 清單。consult 模式要兩頁都讀到，或以退出碼 4 回報頁面不存在，或在 5、7、8 停止並回報狀態。收尾一定要寫一筆 skill-end 狀態事件：兩頁都成功是 ok，內容頁寫成功但目錄頁沒更新是 degraded，連結驗證回 1 或讀寫回 7、8 是 failed，雜湊工具缺席或 wiki 存取庫沒設定是 blocked，使用者中止或根本沒有可記的教訓是 aborted
可驗證跡象	LEARN 存取庫的 LEARN_{HASH} 表尾多一列教訓；CONTENTS 存取庫的 LEARN_CONTENTS 上標題為 LEARN_{HASH} 的那個區塊，「最後更新時間」那一條換新，「教訓紀錄」那一條是 [{頁名}]({絕對網址})，頁面上沒有 markdown 表格，也沒有 [[...]] 這種同 wiki 寫法。頁面原本不存在時，會新建 LEARN_{HASH} 或 LEARN_CONTENTS；LEARN_CONTENTS 建出來只有 H1 與 > 引言，範本的示範區塊不會留在上面。舊的表格式目錄頁會在同一輪整頁轉成區塊，別的存取庫那幾筆原樣轉過去。連結驗證不過就兩頁都沒有新內容，只有 DEAD 清單的回報。consult 模式在 wiki 上無寫入跡象，只有回報內容。兩種模式跑完，$JSC_HOME/usage/events.jsonl 都會多一筆 {kind:skill,phase:end} 事件，name 欄是 jsc-log:learn，status 欄是那五個值之一；jsc-hooks 不在這台機器上時沒有這一筆，技能本身照樣跑完

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）、章節內與目錄區塊的連結一律寫成 [{文字}]({絕對網址}) 並在寫入前全數交給 link-check.sh 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 GITEA_HOST、7 金鑰被拒就停下）、照 templates/report-contents.md 組出一個 H2 區塊檔（## REPORT_{HASH} 加空行加各條 - {欄位名}：{值}）、跑 wiki-contents.sh upsert REPORT 1 REPORT_{HASH} 更新落在 CONTENTS 存取庫的 REPORT_CONTENTS（鍵是 H2 標題的頁名，不是「報表頁」那條帶主機名的連結；命令裡的 1 是 <key-col>，只在舊頁還是表格時用來認出哪一欄的文字當標題）並依它的退出碼分流（0 已寫、1 組不出內容或寫入失敗、2 參數錯、3 未設 JSC_WIKI_REPO_CONTENTS、4 缺範本、7 金鑰失效、8 其他 API 失敗）、最後跑 jsc-hooks/tools/report-status.sh skill-end jsc-log:report {status} {結束碼} {detail} 記下本輪結果，腳本不在這台機器上就安靜跳過
外部呼叫	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/link-check.sh（寫入前驗證連結）、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那個區塊）、jsc-gitea:wiki、jsc-ask:ask、templates/report-{period}.md、templates/report-contents.md
完成條件	回報頁面 URL，或回報跳過寫入與它的原因，或在讀取回 7、8 時停下並回報狀態。每次寫入前 link-check.sh 要回 0，回 1 就不寫該頁並回報 DEAD 清單。wiki-contents.sh upsert 要回 0 並印出 updated 或 added，回 1、2、3、4、7、8 就照該碼回報且不得謊報已寫入。收尾要講出期間標籤、條目數、涵蓋的 repo、範本來源、頁面 URL、帶到下一期的未完成工作包清單，以及 ELAPSED_MISSING 與 TOKEN_MISSING。收尾一定要寫一筆 skill-end 狀態事件：章節與目錄區塊都到位是 ok（範圍內沒有條目、log-aggregate.sh 回 3 也算 ok，detail 帶 ENTRIES=0），報告本文交出去但 wiki 沒寫全是 degraded，連結驗證回 1 或讀寫回 7、8 是 failed，期間算不出來或範本與存取庫沒設定是 blocked，使用者中止是 aborted
可驗證跡象	REPORT 存取庫的 REPORT_{HASH}（雜湊取自 REPORT wiki 存取庫的 {owner}/{repo} 加期間，不是程式碼存取庫）多一個本期章節；CONTENTS 存取庫的 REPORT_CONTENTS 上標題為 REPORT_{HASH} 的那個區塊，「最新一期」、「期數」、「最後更新」三條換新，「報表頁」那一條是 [{頁名}]({絕對網址})、「HASH」那一條是不帶連結的裸 HASH，目錄頁上沒有 markdown 表格，兩頁也都找不到 [[...]] 這種同 wiki 寫法。連結驗證不過就沒有新章節，也沒有新的目錄區塊，只有 DEAD 清單的回報。重跑同一期間只換掉那個區塊，不會多出第二個；四種期間各自一個區塊，因為 HASH 帶著期間。舊的表格式目錄頁會在同一輪整頁轉成區塊，別人那幾筆原樣轉過去。本機留下工作日誌頁面內容的暫存檔，供 log-aggregate.sh 讀取。沒設定 REPORT wiki repo 時不寫 wiki，只印出報告本文；沒設定 JSC_WIKI_REPO_CONTENTS 時內容頁照寫，只有目錄頁那個區塊沒動。跑完 $JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 欄是 jsc-log:report，status 與 exit 兩欄對得上上一列講的判準；jsc-hooks 不在這台機器上時沒有這一筆，技能本身照樣跑完

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 參數被拒，改正參數後重跑、最後跑 jsc-hooks/tools/report-status.sh skill-end jsc-log:stats {status} {結束碼} {detail} 記下本輪結果，腳本不在這台機器上就安靜跳過
外部呼叫	tools/usage-stats.sh；資料由 jsc-hooks/hooks/skill-usage.sh 持續寫進 $JSC_HOME/usage/*.jsonl，這支技能只讀不寫
完成條件	讀到退出碼，並走完該退出碼指定的分支。收尾一定要寫一筆 skill-end 狀態事件：退出碼 0 是 ok（一行都沒印也是 ok，detail 帶 count=0），只答出一半的統計是 degraded，退出碼 2 是 failed（那一輪什麼都沒讀到，不得當成次數為零），統計腳本不在這台機器上是 blocked，使用者中止或問的其實是工時與 Token 是 aborted
可驗證跡象	統計本身無寫入跡象，只有回報內容。跑完 $JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 欄是 jsc-log:stats；jsc-hooks 不在這台機器上時沒有這一筆，技能本身照樣跑完

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 併入待寫內容（同時收編同一個 {HASH} 的「H 加前 7 碼」舊目錄）、跑 tools/worklog-pending.sh orphans 掃出現行規則定址不到的暫存目錄（0 就安靜帶過，4 就把每一列回報給使用者並繼續本輪）、讀 PAGE 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、寫入前把 MERGED 裡的每個連結交給 link-check.sh 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 GITEA_HOST、7 金鑰被拒就停下）、同一輪用 wiki-repo CONTENTS 解出目錄頁存取庫、取 wiki-url 的絕對網址並寫成 [{頁名}]({絕對網址})、同樣先過 link-check.sh、照 templates/log-contents.md 組出一個 H2 區塊檔（## LOG_{HASH} 加空行加各條 - {欄位名}：{值}）才跑 wiki-contents.sh upsert LOG 1 LOG_{HASH} 更新 LOG_CONTENTS（鍵是 H2 標題的頁名，不是「日誌頁」那條帶主機名的連結；命令裡的 1 是 <key-col>，只在舊頁還是表格時用來認出哪一欄的文字當標題）並依 0、1、2、3、4、7、8 各自分流（1 是組不出內容或寫入失敗，找不到區塊只是走附加，不算錯）、最後依成敗跑 worklog-pending.sh commit 或 abort、再跑 jsc-hooks/tools/report-status.sh skill-end jsc-log:worklog {status} {結束碼} {detail} 記下本輪結果，腳本不在這台機器上就安靜跳過
外部呼叫	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/link-check.sh（寫入前驗證連結）、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
完成條件	兩次寫入前 link-check.sh 都回 0，MERGED 的每一筆條目都在 PAGE 上，原有條目逐字不動，wiki-contents.sh upsert 回 0 且 CONTENTS 上標題為 LOG_{HASH} 的那個區塊帶著本週五日期、其他區塊不動，worklog-pending.sh 的 commit 或 abort 其中一個跑過並回報退出碼，orphans 也跑過且回 0 或已把孤兒清單回報出去。link-check.sh 回 1 或 upsert 回非 0 就照該碼回報，並把步驟七當成失敗處理，讓待寫內容留著。收尾一定要寫一筆 skill-end 狀態事件：兩頁都到位是 ok（orphans 掃到孤兒仍算 ok，但 detail 要帶筆數，因為孤兒屬於別的存取庫，不影響本輪結論），內容頁寫成功而 LOG_CONTENTS 沒更新是 degraded，連結驗證回 1 不寫是 failed，雜湊工具或日期運算缺席、wiki 存取庫沒設定是 blocked，使用者中止或這一輪根本沒有任務結束是 aborted
可驗證跡象	LOG 存取庫的 LOG_{HASH} 頁尾多一筆條目，條目裡的計畫名稱、工作包編號、PR 目標分支三欄都是 [{文字}]({絕對網址})；CONTENTS 存取庫的 LOG_CONTENTS 上標題為 LOG_{HASH} 的那個區塊，「條目數」與「最後更新」兩條換新，「日誌頁」那一條是 [{頁名}]({絕對網址})、「HASH」那一條是不帶連結的裸 HASH，目錄頁上沒有 markdown 表格，也沒有 [[...]] 這種同 wiki 寫法。連結驗證不過就兩頁都沒有新內容，待寫檔原樣保留。重跑同一頁只換掉那個區塊，不會多出第二個。舊的表格式目錄頁會在同一輪整頁轉成區塊，別的日誌頁那幾筆原樣轉過去。$JSC_HOME/worklog-pending/{HASH} 底下的待寫檔在 commit 後清空，abort 後原樣保留；該目錄名是 40 碼大寫十六進位，或尚未遷移的舊暫存那種 8 碼大寫十六進位、H 加 7 碼大寫十六進位；推得出對映的舊目錄會連同新目錄一起被清掉。暫存區留下非 40 碼的目錄時，該輪的回報上看得到 orphans 印出的那幾列。本機留下填好的條目檔。跑完 $JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 欄是 jsc-log:worklog，status 與 exit 兩欄對得上上一列講的判準，孤兒筆數落在 detail 欄；jsc-hooks 不在這台機器上時沒有這一筆，技能本身照樣跑完