diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 12df680..a9b4e66 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1,75 +1,89 @@ { "name": "jsc", + "description": "jsc 跨 AI 助理技能組的統一 marketplace（claude / codex / copilot / antigravity / kiro）。", + "owner": { + "name": "JSC" + }, "plugins": [ { "name": "jsc-ask", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/ask.git" - } + }, + "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）" }, { "name": "jsc-cli", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/cli.git" - } + }, + "description": "CLI 偵測、模型能力標籤與技能庫批次部署" }, { "name": "jsc-git", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/git.git" - } + }, + "description": "Commit 分組認可與 Push Request 建立" }, { "name": "jsc-gitea", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/gitea.git" - } + }, + "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步" }, { "name": "jsc-hooks", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/hooks.git" - } + }, + "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄" }, { "name": "jsc-log", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/log.git" - } + }, + "description": "工作日誌（LOG_* wiki 頁）與技能使用統計" }, { "name": "jsc-meta", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/meta.git" - } + }, + "description": "技能組自我管理：新建、更新、刪除技能與技能準則" }, { "name": "jsc-pkg", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/pkg.git" - } + }, + "description": "套件批次更新（nodejs/python/dotnet），失敗還原" }, { "name": "jsc-review", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/review.git" - } + }, + "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組" }, { "name": "jsc-sdlc", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/sdlc.git" - } + }, + "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 28bb223..a9b4e66 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -59,7 +59,7 @@ "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/meta.git" }, - "description": "技能組自我管理：新建/更新/刪除技能與技能準則" + "description": "技能組自我管理：新建、更新、刪除技能與技能準則" }, { "name": "jsc-pkg", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index d8f0f52..51a0132 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "jsc-log", - "version": "0.0.2", - "description": "工作日誌（LOG_{HASH} wiki 頁）與技能使用統計", + "version": "0.0.4", + "description": "工作日誌（LOG_{HASH} wiki 頁）、技能使用統計與教訓紀錄（LEARN_{HASH} wiki 頁）", "skills": "./skills", "author": { "name": "JSC" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 7b7c716..c3fdd64 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-log", - "version": "0.0.2", - "description": "工作日誌（LOG_{HASH} wiki 頁）與技能使用統計", + "version": "0.0.4", + "description": "工作日誌（LOG_{HASH} wiki 頁）、技能使用統計與教訓紀錄（LEARN_{HASH} wiki 頁）", "skills": "./skills" } diff --git a/AGENTS.md b/AGENTS.md index 2b45841..d0d76cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # jsc-log — 給 AI 助理的指引 -本 repo 是 jsc 技能組的 `log` domain（工作日誌與技能使用統計，寫入 `LOG_{HASH}` wiki 頁），Claude Code / Codex / Copilot / Antigravity / Kiro 都能安裝使用。 +本 repo 是 jsc 技能組的 `log` domain（工作日誌、技能使用統計與教訓紀錄，寫入 `LOG_{HASH}`、`LEARN_{HASH}` wiki 頁），Claude Code / Codex / Copilot / Antigravity / Kiro 都能安裝使用。 ## 規則 diff --git a/README.md b/README.md index 2020976..c9e1151 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # jsc-log — 工作日誌與統計 -jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算；首碼若是數字或 `A`／`B`／`C`，改成 `H` 加上原前 7 碼；頁內仍按工作週週五整理），並統計技能使用次數與呼叫鏈次數。 +jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算；首碼若是數字或 `A`／`B`／`C`，改成 `H` 加上原前 7 碼；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 `LEARN_{HASH}`，供下次執行前查閱。 ## 安裝、更新、移除 @@ -21,7 +21,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 | 工具 | 用途 | | --- | --- | | `tools/usage-stats.sh` | 聚合 `$JSC_HOME/usage/*.jsonl`：`skills` 列技能使用次數、`chains` 列呼叫鏈次數（皆降冪），`--cli ` 過濾 | -| `tools/worklog-target.sh` | 依 `{owner}/{repo}` 產生 `LOG_{HASH}`、`LOG_CONTENTS` 與符合共享規則的 `HASH` | +| `tools/worklog-target.sh` | 接收已由 `jsc-gitea/tools/hash-id` 算好的 `HASH`，組出 `LOG_{HASH}`、`LOG_CONTENTS`（本身不再計算 SHA-1） | ## Skills 目錄 @@ -37,6 +37,10 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 統計本技能組各技能的使用次數與呼叫鏈使用次數，資料來源為 jsc-hooks 記錄的 `skills.jsonl` 與 `chains.jsonl`。 +### `learn` + +技能執行後把教訓（日期、技能、CLI、情境、教訓、下次做法）附加到 `LEARN_{HASH}` 並更新 `LEARN_CONTENTS`；技能執行前查閱同兩頁，套用相符的「下次做法」。 + ## 範本 @@ -45,10 +49,12 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 | --- | --- | | `templates/log-entry.md` | 單筆工作日誌（十欄位） | | `templates/log-contents.md` | 日誌目錄 `LOG_CONTENTS` | +| `templates/learn-page.md` | 教訓紀錄頁 `LEARN_{HASH}`（六欄表格，逐列附加） | +| `templates/learn-contents.md` | 教訓目錄 `LEARN_CONTENTS` | ## 環境變數 -Wiki 位置：`JSC_WIKI_REPO_LOG`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。 +Wiki 位置：日誌頁用 `JSC_WIKI_REPO_LOG`、教訓頁用 `JSC_WIKI_REPO_LEARN`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。先讀目前 shell 繼承的環境變數，缺值才詢問。 ## 相關 domain diff --git a/plugin.json b/plugin.json index f6ed7ea..449fce1 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-log", - "version": "0.0.2", - "description": "工作日誌（LOG_{HASH} wiki 頁）與技能使用統計", + "version": "0.0.4", + "description": "工作日誌（LOG_{HASH} wiki 頁）、技能使用統計與教訓紀錄（LEARN_{HASH} wiki 頁）", "skills": "./skills/" } diff --git a/skills/learn/SKILL.md b/skills/learn/SKILL.md new file mode 100644 index 0000000..a0e3610 --- /dev/null +++ b/skills/learn/SKILL.md @@ -0,0 +1,44 @@ +--- +name: learn +description: Record a lesson learned after a skill run to wiki LEARN_{HASH} plus LEARN_CONTENTS, or consult past lessons before a skill run. Each entry is one table row with date, skill, CLI, situation, lesson, and next-time approach. HASH follows the shared 8-char rule with the H-prefix fallback. Use when a skill run produced a reusable lesson, or before running a skill to consult past lessons; not for work-time logs (see worklog). +--- + +# learn — lessons learned + +Close the loop on skill runs: record what a run taught you, consult it before the next run. Two modes — `record` and `consult`. Page content is chart-first Traditional Chinese (STE100): markdown table entries, prose as the last resort. + +## Target pages + +- Directory page: `LEARN_CONTENTS`. Content page: `LEARN_{HASH}`, one page per repository. +- Compute `{HASH}` from `{owner}/{repo}` with `jsc-gitea/tools/hash-id` (shared wiki hash rule: first 8 uppercase SHA-1 hex chars; `H` plus the first 7 chars when the raw hash starts with `0-9`, `A`, `B`, or `C`). +- Wiki repo resolution: `JSC_WIKI_REPO_LEARN` first, then `JSC_WIKI_REPO`. Inspect the inherited shell environment variables first; ask the user per the `jsc-ask:ask` rules only when neither resolves. Never borrow another type's `JSC_WIKI_REPO_{TYPE}`. +- All wiki reads and writes go through `jsc-gitea:wiki`. + +## Mode: record + +Run after a skill run that produced a reusable lesson. + +1. Collect the six facts below. Done when every field has a value. + + | # | Field (page column) | Source | + | --- | --- | --- | + | 1 | 日期 | Today, `yyyy-MM-dd` | + | 2 | 技能 | The skill that ran, as `jsc-{domain}:{name}` | + | 3 | CLI | One of claude / codex / copilot / antigravity / kiro | + | 4 | 情境 | What was happening when the lesson appeared, one sentence | + | 5 | 教訓 | What the run taught, one sentence | + | 6 | 下次做法 | How to apply it on the next run, one sentence | + +2. Resolve `{owner}/{repo}` from `git remote get-url origin` and compute `{HASH}` with `jsc-gitea/tools/hash-id`. Done when the page name `LEARN_{HASH}` is known. +3. Write the entry. This step MUST run as a sub agent; the main agent only confirms the write succeeded. + - Read `LEARN_{HASH}` via `jsc-gitea:wiki`. If it does not exist, create it from `templates/learn-page.md`; otherwise APPEND the new row at the end of the table. Never overwrite existing rows. + - Update `LEARN_CONTENTS` in the same pass (apply `templates/learn-contents.md`; add the repo row if missing, otherwise refresh its 最後更新時間). + - Done when the sub agent reports both pages written and the main agent has confirmed the row exists on `LEARN_{HASH}`. + +## Mode: consult + +Run before a skill run, to apply past lessons. + +1. Resolve `{owner}/{repo}` and compute `{HASH}` as in record mode. Done when `LEARN_{HASH}` is known. +2. Read `LEARN_CONTENTS` and the repo's `LEARN_{HASH}` via `jsc-gitea:wiki`. When either page is missing (exit 4), report 「無教訓紀錄」 and let the caller proceed. Done when both pages are read or reported missing. +3. Surface every row whose 技能 matches the skill about to run, and summarize each matched 下次做法 for the caller to apply. Done when the matched rows (or 「無相符教訓」) are reported. diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index d52c831..b08c2c7 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -35,7 +35,8 @@ After work completes, collect the ten items below and append a `templates/log-en ## Target page and work week - Page name: `LOG_{HASH}`. -- Compute the target page by running `tools/worklog-target.sh "{owner}/{repo}" all`. Use `PAGE` for `LOG_{HASH}` and `CONTENTS` for `LOG_CONTENTS`. +- Compute `{HASH}` from `{owner}/{repo}` with `jsc-gitea/tools/hash-id` (shared wiki hash rule: first 8 uppercase SHA-1 hex chars; `H` plus the first 7 chars when the raw hash starts with `0-9`, `A`, `B`, or `C`). +- Compute the target page by running `tools/worklog-target.sh "{HASH}" all`. Use `PAGE` for `LOG_{HASH}` and `CONTENTS` for `LOG_CONTENTS`. - The work-week Friday still drives the page content and the row dates. - Read the page via `jsc-gitea:wiki`. If it does not exist, create it with the structure described in `templates/log-contents.md`; otherwise APPEND the new entry at the end. - Update `LOG_CONTENTS` in the same pass (apply `templates/log-contents.md`; add the row if missing). diff --git a/templates/learn-contents.md b/templates/learn-contents.md new file mode 100644 index 0000000..3b84991 --- /dev/null +++ b/templates/learn-contents.md @@ -0,0 +1,7 @@ +# 教訓目錄 + +> 由 `jsc-log:learn` 維護。這是教訓目錄頁 `LEARN_CONTENTS`。每個存取庫一列；`LEARN_{HASH}` 的 `{HASH}` 依共用 wiki hash 規則產生：先取 `{owner}/{repo}` 的 SHA-1 前 8 碼並轉成大寫；首碼若是 `0-9`、`A`、`B`、`C`，改用 `H` 加上原前 7 碼，總長維持 8 碼。 + +| 存取庫名稱 | 教訓紀錄 | 最後更新時間 | +| --- | --- | --- | +| {owner}/{repo} | [[LEARN_{HASH}]] | {yyyy-MM-dd HH:mm} | diff --git a/templates/learn-page.md b/templates/learn-page.md new file mode 100644 index 0000000..4b603b0 --- /dev/null +++ b/templates/learn-page.md @@ -0,0 +1,7 @@ +# 教訓紀錄 — {owner}/{repo} + +> 由 `jsc-log:learn` 維護。這是教訓紀錄頁 `LEARN_{HASH}`；`HASH` 依共用 wiki hash 規則產生。新教訓**附加**一列在表尾，不覆蓋舊列。執行技能前先查這頁，套用「下次做法」。 + +| 日期 | 技能 | CLI | 情境 | 教訓 | 下次做法 | +| --- | --- | --- | --- | --- | --- | +| {yyyy-MM-dd} | {jsc-domain:name} | {claude、codex、copilot、antigravity、kiro 五選一} | {當時發生什麼事} | {這次學到什麼} | {下次怎麼做} | diff --git a/tools/worklog-target.sh b/tools/worklog-target.sh index 0e0028b..f8b102f 100755 --- a/tools/worklog-target.sh +++ b/tools/worklog-target.sh @@ -1,47 +1,32 @@ #!/usr/bin/env sh -# worklog-target.sh: 產生 worklog wiki 目標頁。 +# worklog-target.sh: 由已算好的 hash 組出 worklog wiki 目標頁名稱。 +# hash 一律由 jsc-gitea/tools/hash-id 算出後傳入，本腳本不再自行計算 SHA-1。 # 用法: -# worklog-target.sh [hash|page|contents|all] +# worklog-target.sh [page|contents|all] set -eu usage() { - echo 'usage: worklog-target.sh [hash|page|contents|all]' >&2 + echo 'usage: worklog-target.sh [page|contents|all]' >&2 exit 2 } [ "$#" -ge 1 ] || usage [ "$#" -le 2 ] || usage -repo=$1 +hash=$1 field=${2:-page} -if [ -z "$repo" ]; then +if [ -z "$hash" ]; then usage fi -if command -v sha1sum >/dev/null 2>&1; then - raw=$(printf '%s' "$repo" | sha1sum | awk '{print $1}') -elif command -v shasum >/dev/null 2>&1; then - raw=$(printf '%s' "$repo" | shasum -a 1 | awk '{print $1}') -else - echo 'no SHA-1 helper found' >&2 - exit 1 -fi - -hash=$(printf '%s' "$raw" | cut -c1-8 | tr a-f A-F) -case "$hash" in - [0-9ABC]*) hash="H$(printf '%s' "$hash" | cut -c1-7)" ;; -esac - page="LOG_${hash}" contents='LOG_CONTENTS' case "$field" in - hash) printf '%s\n' "$hash" ;; page) printf '%s\n' "$page" ;; contents) printf '%s\n' "$contents" ;; all) - printf 'HASH=%s\n' "$hash" printf 'PAGE=%s\n' "$page" printf 'CONTENTS=%s\n' "$contents" ;;