jiantw83
5070863063
- What：新建 `references/` 目錄，加入 `references/behaviors.md`。內含 learn、report、stats、worklog 四節，每節一張五列表，欄位為觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象。 - Why：技能驗證原本沒有基準，只能靠人逐份比對 SKILL.md，10 個 domain 每次稽核都要重做，還會漏。把每支技能的行為寫成清單，驗證就有可比對的正本。技能改了行為、清單沒跟著改，兩邊就漂移，所以規定日後任何技能異動都要在同一個 PR 內同步更新這一頁。 - How：逐支讀 `skills/*/SKILL.md`，把流程拆成五個固定欄位。節名與技能目錄名逐字相同，節序照目錄名字典序排。格式不靠人看，由 `jsc-meta/tools/check-behaviors.sh` 在程式層檢查六項合約。清單放在本 repo 而不是集中到 meta，這樣技能改動與清單在同一個 PR，不會漂移，也不用跨 repo 開兩條 PR 互卡。 - Who：屬於技能行為清單功能，是 jsc 技能組技能驗證基準的 jsc-log 部分。
6.3 KiB
6.3 KiB
jsc-log 技能行為清單
本頁記錄 jsc-log 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
learn
| 項目 | 內容 |
|---|---|
| 觸發時機 | 一次技能執行留下可重用的教訓時，用 record 模式記錄。要跑某支技能之前，用 consult 模式查過去的教訓。工時與 Token 紀錄不走這支，走 worklog |
| 關鍵步驟 | record 模式收齊日期、技能、CLI、情境、教訓、下次做法這六欄、從 git remote get-url origin 解出 {owner}/{repo}、用 hash-id 算出 {HASH}、開 sub agent 讀 LEARN_{HASH}、依 wiki-get 的退出碼分支（0 在表尾追加一列、4 才用 templates/learn-page.md 建頁、7 與 8 停止並回報）、同一輪更新 LEARN_CONTENTS、寫入失敗重試一次；consult 模式算出 {HASH}、讀 LEARN_CONTENTS 與 LEARN_{HASH}、挑出「技能」欄相符的列、整理每一列的「下次做法」交給呼叫端 |
| 外部呼叫 | jsc-gitea/tools/hash-id、jsc-gitea/tools/gitea.sh wiki-repo LEARN、jsc-gitea:wiki（全部 wiki 讀寫）、git remote get-url origin、templates/learn-page.md、templates/learn-contents.md |
| 完成條件 | record 模式要 sub agent 回報兩頁都寫入成功，主代理確認新列在 LEARN_{HASH} 上，原有的列一列不少。consult 模式要兩頁都讀到，或以退出碼 4 回報頁面不存在，或在 5、7、8 停止並回報狀態 |
| 可驗證跡象 | wiki 的 LEARN_{HASH} 表尾多一列教訓，LEARN_CONTENTS 上該 repo 那一列的「最後更新時間」換新。頁面原本不存在時，會新建 LEARN_{HASH} 或 LEARN_CONTENTS。consult 模式無寫入跡象，只有回報內容 |
report
| 項目 | 內容 |
|---|---|
| 觸發時機 | 有人要一段期間的工作總結時用，期間分年、月、週、日四種。單一工作包的紀錄不走這支，走 worklog |
| 關鍵步驟 | 呼叫端沒指定期間就依 jsc-ask:ask 問、跑 tools/report-range.sh 取得起訖日與標籤、平行做四件事（tools/report-template.sh resolve 解出範本、讀 LOG_CONTENTS 與它列出的每一頁工作日誌、年報另外讀 LEARN_CONTENTS、解出 REPORT 的 wiki repo）、把頁面內容存成檔案後跑 tools/log-aggregate.sh 算出條目數、涵蓋 repo、花費時間、Token 用量、任務狀態、從存活條目挑出阻塞與未完成工作包、照範本的標題與表格填出報告、讀 REPORT_{HASH} 後把本期當成新章節追加在最前、更新 REPORT_CONTENTS |
| 外部呼叫 | tools/report-range.sh、tools/report-template.sh、tools/log-aggregate.sh、jsc-gitea/tools/gitea.sh wiki-repo（LOG、LEARN、REPORT）與 hash-id、jsc-gitea:wiki、jsc-ask:ask、templates/report-{period}.md、templates/report-contents.md |
| 完成條件 | 回報頁面 URL，或回報跳過寫入與它的原因，或在讀取回 7、8 時停下並回報狀態。收尾要講出期間標籤、條目數、涵蓋的 repo、範本來源、頁面 URL、帶到下一期的未完成工作包清單，以及 ELAPSED_MISSING 與 TOKEN_MISSING |
| 可驗證跡象 | wiki 的 REPORT_{HASH}（雜湊取自 {owner}/{repo}/{period}）多一個本期章節，REPORT_CONTENTS 該列的「最新一期」、「期數」、「最後更新」換新。本機留下工作日誌頁面內容的暫存檔，供 log-aggregate.sh 讀取。沒設定 REPORT wiki repo 時不寫 wiki，只印出報告本文 |
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 與 {HASH}、跑 tools/worklog-target.sh 取得頁名與本週五日期、用 templates/log-entry.md 填出單筆條目檔、跑 tools/worklog-pending.sh merge 併入待寫內容、讀 PAGE 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、同一輪更新 CONTENTS、最後依成敗跑 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 與 wiki-url、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 上，原有條目逐字不動，CONTENTS 該列帶著本週五日期且其他列不動，worklog-pending.sh 的 commit 或 abort 其中一個跑過並回報退出碼 |
| 可驗證跡象 | wiki 的 LOG_{HASH} 頁尾多一筆條目，LOG_CONTENTS 該列的「條目數」與「最後更新」換新。$JSC_HOME/worklog-pending/{HASH} 底下的待寫檔在 commit 後清空，abort 後原樣保留。本機留下填好的條目檔 |