From de9e342d773f7c03b46fae1208ce2ba054eb75b5 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Fri, 21 Aug 2026 13:08:43 +0800
Subject: [PATCH] =?UTF-8?q?feat(log):=20=E5=8C=AF=E5=85=A5=20jsc-log=20?=
 =?UTF-8?q?=E6=8A=80=E8=83=BD=E7=B5=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 skills/stats/SKILL.md     | 21 ++++++++++++++++++
 skills/worklog/SKILL.md   | 45 +++++++++++++++++++++++++++++++++++++++
 templates/log-contents.md |  7 ++++++
 templates/log-entry.md    | 27 +++++++++++++++++++++++
 tools/usage-stats.sh      | 32 ++++++++++++++++++++++++++++
 5 files changed, 132 insertions(+)
 create mode 100644 skills/stats/SKILL.md
 create mode 100644 skills/worklog/SKILL.md
 create mode 100644 templates/log-contents.md
 create mode 100644 templates/log-entry.md
 create mode 100755 tools/usage-stats.sh

diff --git a/skills/stats/SKILL.md b/skills/stats/SKILL.md
new file mode 100644
index 0000000..1f54f83
--- /dev/null
+++ b/skills/stats/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: stats
+description: Report usage counts of every jsc skill and every skill call chain, aggregated by tools/usage-stats.sh from $JSC_HOME/usage/*.jsonl recorded by jsc-hooks. Supports --cli filtering. Use when the user asks how often skills or chains are used; not for token or time stats (see worklog).
+---
+
+# stats — 技能與呼叫鏈使用統計
+
+資料由 `jsc-hooks/hooks/skill-usage.sh` 持續記錄在 `$JSC_HOME/usage/`（預設 `~/.jsc/usage/`）。
+
+## 操作
+
+| 統計 | 指令 | 輸出 |
+| --- | --- | --- |
+| 各技能使用次數 | `tools/usage-stats.sh skills` | `次數<TAB>技能名`，降冪 |
+| 各呼叫鏈使用次數 | `tools/usage-stats.sh chains` | `次數<TAB>from -> to`，降冪 |
+| 依 CLI 過濾 | 加 `--cli claude`（或 codex / copilot / antigravity / kiro） | 同上 |
+
+## 呈現
+
+1. 直接執行工具，把輸出整理成表格回覆。
+2. 沒有資料時說明：需先安裝 `jsc-hooks` 並執行 `jsc-hooks:hooks-install` 接線。
diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md
new file mode 100644
index 0000000..ffbd01c
--- /dev/null
+++ b/skills/worklog/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: worklog
+description: After finishing a work package, collect ten facts (repo, branch, plan link, work package link, elapsed time from session-timer, token usage per CLI, status, details, difficulties, PR target) and append a templated entry to wiki LOG_{yyyyMM}_W{week} plus LOG_CONTENTS. Week number is derived from the Friday of the work week. Trigger at the end of implement or maintain; not for planning notes.
+---
+
+# worklog — 工作日誌
+
+工作完成後蒐集以下十項資訊，套用 `templates/log-entry.md` 附加到 wiki 日誌頁。蒐集與寫入**必須以 sub agent 執行**。
+
+## 蒐集項目
+
+| # | 項目 | 來源 |
+| --- | --- | --- |
+| 1 | 存取庫名稱 | `git remote get-url origin` 解析出 `{owner}/{repo}` |
+| 2 | 分支名稱 | `git branch --show-current` |
+| 3 | 計畫名稱 | 連結到計畫頁 `[[PLAN_{...}]]` |
+| 4 | 工作包編號 | 連結到分析頁的工作包標題 `[[ANALYZE_{...}#WP-xx]]` |
+| 5 | 花費時間 | `jsc-hooks/hooks/session-timer.sh report {session_id}`（秒，換算 h/m） |
+| 6 | token 用量 | 見下表，各 CLI 取法不同；不可得填 `N/A` |
+| 7 | 任務狀態 | 完成 / 部分完成 / 阻塞（附原因） |
+| 8 | 執行細節與產出 | 摘要改了什麼、產出哪些檔案或頁面 |
+| 9 | 遇到的困難 + 解決方式 | 一行一組 |
+| 10 | PR 的目標分支 | 連結到 PR 頁 |
+
+### token 用量取得方式
+
+| CLI | 取法 |
+| --- | --- |
+| claude | transcript JSONL（`~/.claude/projects/**/*.jsonl`）的 `usage` 欄位加總，或 `claude -p --output-format json` 的 `usage` |
+| codex | `~/.codex/sessions/**` 的 token 計數，或工作階段內 `/status` |
+| copilot | 工作階段內 `/usage` |
+| antigravity | 介面顯示值；無法讀取時 `N/A` |
+| kiro | 無公開來源，填 `N/A` |
+
+## 目標頁與週數計算
+
+- 頁名：`LOG_{yyyyMM}_W{週數}`，兩者都取自**本工作週的週五**：
+  ```sh
+  dow=$(date +%u)
+  if [ "$dow" -ge 6 ]; then f=$(date -d 'last friday' +%Y%m%d); else f=$(date -d 'friday' +%Y%m%d); fi
+  yyyyMM=$(printf '%s' "$f" | cut -c1-6)
+  W=$(( ( $(printf '%s' "$f" | cut -c7-8 | sed 's/^0//') - 1 ) / 7 + 1 ))   # 該週五是當月第幾個週五
+  ```
+- 經由 `jsc-gitea:wiki` 讀取該頁；不存在就以 `templates/log-contents.md` 說明的結構新建，存在就把新條目**附加**在文末。
+- 同步更新 `LOG_CONTENTS`（套用 `templates/log-contents.md`，該週的列不存在就新增）。
diff --git a/templates/log-contents.md b/templates/log-contents.md
new file mode 100644
index 0000000..46dedcc
--- /dev/null
+++ b/templates/log-contents.md
@@ -0,0 +1,7 @@
+# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個日誌頁一列；週數 = 該週五是當月第幾個週五。
+
+| 日誌頁 | 週五日期 | 條目數 | 最後更新 |
+| --- | --- | --- | --- |
+| [[LOG_{yyyyMM}_W{週數}]] | {yyyy-MM-dd} | {n} | {yyyy-MM-dd HH:mm} |
diff --git a/templates/log-entry.md b/templates/log-entry.md
new file mode 100644
index 0000000..5cb6207
--- /dev/null
+++ b/templates/log-entry.md
@@ -0,0 +1,27 @@
+# 工作日誌頁 — LOG_{yyyyMM}_W{週數}
+
+> 由 `jsc-log:worklog` 維護。每完成一項工作附加一個條目在文末。
+> `{yyyyMM}` 與 `{週數}` 取自本工作週的週五：週數 = 該週五是當月第幾個週五。
+
+---
+
+## {yyyy-MM-dd HH:mm} {工作摘要一句話}
+
+| 欄位 | 內容 |
+| --- | --- |
+| 存取庫名稱 | {owner}/{repo} |
+| 分支名稱 | {branch} |
+| 計畫名稱 | [[PLAN_{yyyyMMdd}_{HHmmss}_{HASH}|{計畫名稱}]] |
+| 工作包編號 | [[ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}#wp-{編號}|WP-{編號} {工作包標題}]] |
+| 花費時間 | {h} 小時 {m} 分（session-timer report） |
+| token 用量 | {CLI}: {input}/{output}（不可得填 N/A） |
+| 任務狀態 | 完成 / 部分完成 / 阻塞（{原因}） |
+| PR 目標分支 | [{base 分支}]({PR URL}) |
+
+### 執行細節與產出
+
+- {做了什麼、產出哪些檔案或頁面}
+
+### 遇到的困難與解決方式
+
+- {困難} → {解決方式}
diff --git a/tools/usage-stats.sh b/tools/usage-stats.sh
new file mode 100755
index 0000000..b89d029
--- /dev/null
+++ b/tools/usage-stats.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env sh
+# usage-stats.sh — 聚合 jsc-hooks 記錄的技能用量。
+# 用法:
+#   usage-stats.sh skills [--cli <name>]   # 每個 skill 的使用次數（降冪）
+#   usage-stats.sh chains [--cli <name>]   # 每條 from -> to 呼叫鏈的次數（降冪）
+# 資料: $JSC_HOME/usage/skills.jsonl、chains.jsonl（預設 $HOME/.jsc）
+set -u
+JSC_HOME="${JSC_HOME:-$HOME/.jsc}"
+cmd="${1:?usage: usage-stats.sh skills|chains [--cli <name>]}"; shift
+cli=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --cli) cli="${2:?--cli needs a value}"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+by_cli() { # 依 --cli 過濾；未指定就原樣輸出
+  if [ -n "$cli" ]; then grep "\"cli\":\"$cli\""; else cat; fi
+}
+rank() { sort | uniq -c | sort -rn | sed 's/^ *\([0-9][0-9]*\) /\1\t/'; }
+
+case "$cmd" in
+  skills)
+    f="$JSC_HOME/usage/skills.jsonl"; [ -f "$f" ] || exit 0
+    by_cli < "$f" | sed -n 's/.*"skill":"\([^"]*\)".*/\1/p' | rank ;;
+  chains)
+    f="$JSC_HOME/usage/chains.jsonl"; [ -f "$f" ] || exit 0
+    by_cli < "$f" | sed -n 's/.*"from":"\([^"]*\)".*"to":"\([^"]*\)".*/\1 -> \2/p' | rank ;;
+  *)
+    echo "unknown command: $cmd" >&2; exit 2 ;;
+esac