docs(behaviors): 說明文件與行為清單跟上目錄頁的條列版面
存取庫說明與技能行為清單裡講到目錄頁的段落一律改口：一筆一個大標題區塊、 標題就是內容頁頁名也就是鍵、欄位是標題底下的一層條列，頁上不留表格。 三個目錄頁的範本與三支技能的敘述都換了版面，說明文件卻還寫著「一列」與 「表格」。文件與範本各說一套，照文件手工補紀錄的人會補出一列表格，那一列 在條列頁上讀不成一筆紀錄，而且下一輪工具重寫時也不會被當成既有那一筆換掉。 只改敘述，行為與呼叫參數都不動；欄位語意與寫入語意的正本仍在各自的範本 引言裡，這裡只指向它，不重述細節。 範圍是說明文件與技能行為清單裡的目錄頁敘述。
This commit is contained in:
+12
-12
@@ -7,20 +7,20 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 一次技能執行留下可重用的教訓時，用 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 金鑰被拒就停下）、同一輪跑 `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-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}` 上，原有的列一列不少，寫入前 `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` 上該 repo 那一列的「最後更新時間」換新，且「教訓紀錄」欄是 `[{頁名}]({絕對網址})`，頁面上沒有 `[[...]]` 這種同 wiki 寫法。頁面原本不存在時，會新建 `LEARN_{HASH}` 或 `LEARN_CONTENTS`。連結驗證不過就兩頁都沒有新內容，只有 DEAD 清單的回報。consult 模式在 wiki 上無寫入跡象，只有回報內容。兩種模式跑完，`$JSC_HOME/usage/events.jsonl` 都會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-log:learn`，`status` 欄是那五個值之一；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完 |
|
||||
| 關鍵步驟 | 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 金鑰被拒就停下）、最後跑 `wiki-contents.sh upsert REPORT 2 {HASH}` 更新落在 CONTENTS 存取庫的 `REPORT_CONTENTS`（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結）、最後跑 `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，回 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` 該列的「最新一期」、「期數」、「最後更新」換新，且「報表頁」欄是 `[{頁名}]({絕對網址})`、「HASH」欄是不帶連結的裸 HASH，兩頁都找不到 `[[...]]` 這種同 wiki 寫法。連結驗證不過就沒有新章節，也沒有新的目錄列，只有 DEAD 清單的回報。重跑同一期間只換掉那一列，不會多出第二列。本機留下工作日誌頁面內容的暫存檔，供 `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` 不在這台機器上時沒有這一筆，技能本身照樣跑完 |
|
||||
| 關鍵步驟 | 呼叫端沒指定期間就依 `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
|
||||
|
||||
@@ -37,7 +37,7 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 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` 才跑 `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/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` 該列帶著本週五日期、其他列不動，`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` 該列的「條目數」與「最後更新」換新，且「日誌頁」欄是 `[{頁名}]({絕對網址})`，頁面上沒有 `[[...]]` 這種同 wiki 寫法，「HASH」欄是不帶連結的裸 HASH。連結驗證不過就兩頁都沒有新內容，待寫檔原樣保留。重跑同一頁只換掉那一列，不會多出第二列。`$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` 不在這台機器上時沒有這一筆，技能本身照樣跑完 |
|
||||
| 關鍵步驟 | 全程由 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` 不在這台機器上時沒有這一筆，技能本身照樣跑完 |
|
||||
|
||||
Reference in New Issue
Block a user