jiantw83
7d803245a5
- What：worklog、learn、report 三支技能共六處讀取分流改寫，只有結束碼 4 才建新頁； 結束碼 7 與 8 一律中止，一個字都不寫。三份目錄頁樣板補上寫入語意，明寫禁止整頁覆蓋、 不得改動別人的列。usage-stats.sh 的參數護欄改成明確回傳結束碼 2。 - Why：原本把「讀失敗」與「頁面不存在」當成同一件事。金鑰失效時讀取回 7，技能卻讀成 「這頁還沒有」，於是照樣板建一份新頁蓋回去。整份工作日誌會被這一筆條目取代， 既有教訓會被清成空表，報表則產出一份說「這段期間沒有工作」的假數字。 這些內容只活在 wiki 上，蓋掉就救不回來，所以這是本輪最要緊的一項。 - How：每一處讀取都先看結束碼再決定動作，並在技能文件裡列成表格： 0 接在既有內容後面附加，4 才從樣板建頁，5 缺網址就中止，7 金鑰或權限問題就中止， 8 其他 API 失敗就中止。目錄頁一律先讀整頁再改那一列。 stats 也補上分流，參數錯誤不再被讀成「零次」。 - Who：worklog、learn、report、stats 四支技能的 wiki 讀寫與統計輸出。
63 lines
5.1 KiB
Markdown
63 lines
5.1 KiB
Markdown
---
|
|
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`. Exit 1 means no SHA-1 helper on this machine: stop and report that `sha1sum` or `shasum` has to be installed, and never hand-compute the hash.
|
|
- Wiki repo: run `jsc-gitea/tools/gitea.sh wiki-repo LEARN`. Exit 3 hands the question to `jsc-gitea:wiki`, which owns the resolution order and the wording; exit 2 means the type argument was misspelled, so fix it and rerun.
|
|
- 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` and branch on the exit code the underlying `gitea.sh wiki-get` returned. **Only exit 4 means the page is not there yet**; creating the page from the template on any other code appends this one row to a blank table and drops every lesson already recorded.
|
|
|
|
| Exit | Do |
|
|
| --- | --- |
|
|
| 0 | The table is in hand. APPEND the new row at the end of it and overwrite no existing row. Never rebuild the page from the template on this code |
|
|
| 4 | The page really is absent. Create it from `templates/learn-page.md`, then add the row |
|
|
| 7 | The token is invalid or lacks permission, so the old rows are unknown. Stop and report the token problem, and create no page |
|
|
| 8 | Some other API failure. Stop and report that status, and create no page |
|
|
|
|
- Update `LEARN_CONTENTS` in the same pass (apply `templates/learn-contents.md`; add the repo row if missing, otherwise refresh its 最後更新時間), branching on its read exactly as above: only exit 4 creates the directory page from the template, while 7 and 8 stop the run instead of rebuilding a directory whose other repos' rows were never read. Touch no row that belongs to another repository.
|
|
- A failed `jsc-gitea:wiki` write on either page: retry once. Still failing, stop and report which page was not written (`LEARN_{HASH}` or `LEARN_CONTENTS`) together with the row content that was meant to go in, so the lesson is not lost. Never report a page as written when it was not.
|
|
- Done when the sub agent reports both pages written, the main agent has confirmed the row exists on `LEARN_{HASH}`, and the rows that were there before are still there.
|
|
|
|
## 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`, and branch on the exit code `jsc-gitea/tools/gitea.sh` returned. Only 4 means the page is absent; every other failure code means the read never happened, so an empty page must never be inferred from it.
|
|
|
|
| Exit | Do |
|
|
| --- | --- |
|
|
| 4 | The page does not exist. Report 「無教訓紀錄」 for that page and let the caller proceed |
|
|
| 5 | The page carries no `html_url`. Stop and report it; never assemble the URL by hand and never read it as an empty page |
|
|
| 7 | The Gitea token is invalid or lacks permission (HTTP 401/403). Stop and report that the token has to be fixed. Reading this as 「無教訓紀錄」 is exactly the misread `gitea.sh` separates 7 from 4 to prevent |
|
|
| 8 | Some other API failure, with the HTTP status in the message. Stop and report that status; retry only after the API is back |
|
|
|
|
Done when both pages are read, or reported missing under exit 4, or the run stopped on 5, 7 or 8.
|
|
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.
|