jiantw83
aee17e45c7
What：LOG_CONTENTS、LEARN_CONTENTS、REPORT_CONTENTS 改由 wiki-repo CONTENTS 解析並透過 wiki-contents.sh upsert 寫入，內容頁仍各走自己的型別。LOG 與 REPORT 的目錄頁新增一欄裸 HASH 當比對鍵。 Why：比對鍵原本是含網址的儲存格，換主機、換存取庫或 URL 編碼有差就比對不到， upsert 會走附加分支，同一頁多出第二列而舊列永遠不再更新。REPORT 更脆：存取庫一換， 雜湊與網址同時變，四個期間的列會一次全部重複。 How：worklog-pending.sh 的 valid_hash 放寬成 40 碼、8 碼與 H 加 7 碼三種形狀。 放寬的是長度不是字元集——先剝字元再比長度的順序保留，路徑穿越與換行注入照樣擋下。 年報不得沿用日誌存取庫那條規則收斂到內容頁，目錄頁同住一庫是另一回事。 Who：jsc-log
79 lines
8.2 KiB
Markdown
79 lines
8.2 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 is the full 40-character uppercase SHA-1 of {owner}/{repo}; LEARN_{HASH} sits in the LEARN wiki repo while LEARN_CONTENTS sits in the separate CONTENTS repo, so the directory row goes through jsc-gitea/tools/wiki-contents.sh upsert and links the lesson page by its absolute wiki-url. 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.
|
|
- The two pages live in different wikis. `LEARN_{HASH}` goes to `jsc-gitea/tools/gitea.sh wiki-repo LEARN`; `LEARN_CONTENTS` goes to `gitea.sh wiki-repo CONTENTS` (`JSC_WIKI_REPO_CONTENTS`, then `JSC_WIKI_REPO`, then exit 3), which never falls back to the LEARN repo. Exit 3 on either 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.
|
|
- Because they sit in different wikis, the directory row links the lesson page by the absolute URL from `gitea.sh wiki-url <LEARN repo> LEARN_{HASH}`. `[[LEARN_{HASH}]]` resolves only inside one wiki and would dead-link from the directory. `wiki-url` exit 4 means the lesson page is not written yet, so write it first; exit 5 means the page carries no `html_url`, so stop and report it and never assemble the URL by hand; exit 7 or 8 means the token or the API failed, so stop and report that status.
|
|
- Compute `{HASH}` from `{owner}/{repo}` with `jsc-gitea/tools/hash-id`. It prints the full 40-character uppercase SHA-1 — no truncation and no prefix rewrite, so never shorten it. 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. Exit 2 means the input was empty, so fix the `{owner}/{repo}` parse and rerun.
|
|
- All wiki reads and writes go through `jsc-gitea:wiki`, except the `LEARN_CONTENTS` row, which goes through `jsc-gitea/tools/wiki-contents.sh`.
|
|
|
|
## 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, and let `jsc-gitea/tools/wiki-contents.sh` do the row work — never hand-edit the directory page. Build one file holding the single row from `templates/learn-contents.md` (the repository name, the absolute link from `gitea.sh wiki-url <LEARN repo> LEARN_{HASH}`, and the update time), then run:
|
|
|
|
`jsc-gitea/tools/wiki-contents.sh upsert LEARN 1 "{owner}/{repo}" {row file} templates/learn-contents.md`
|
|
|
|
Column 1 is the repository name, so the key stays the same string across every run and one repository keeps exactly one row. The script reads the whole page, replaces the matching row and appends when none matches, so every row that belongs to another repository stays as it was.
|
|
|
|
| Exit | Do |
|
|
| --- | --- |
|
|
| 0 | The row is in place. It prints `updated` or `added` plus the page it wrote |
|
|
| 1 | The write failed, or the directory page holds no markdown table. Report `LEARN_CONTENTS` as not written, together with the row content |
|
|
| 2 | An argument was rejected. Fix the argument and rerun this bullet; nothing was written |
|
|
| 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set. The lesson itself is on `LEARN_{HASH}` and stays there |
|
|
| 4 | The directory page is absent and the script received no template. The call above always passes one, so this code means `templates/learn-contents.md` is not at that path — a partial plugin install, not a missing argument. Stop and report the path; rerunning the same command changes nothing. Reinstall the plugin, confirm the file is there, then rerun. A mistyped template path exits 2, not 4 |
|
|
| 7 | The token is invalid or lacks permission, so the other repositories' rows are unknown. Stop and report the token problem; the script wrote nothing, which is what keeps those rows alive |
|
|
| 8 | Some other API failure. Stop and report that status and retry only after the API is back |
|
|
|
|
- A failed 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` from the CONTENTS repo and the repo's `LEARN_{HASH}` from the LEARN repo via `jsc-gitea:wiki` — two `wiki-repo` calls, two different wikis — 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. The rows on `LEARN_CONTENTS` point at lesson pages by absolute URL, and rows for other repositories point outside the LEARN repo resolved here, so follow each link as given rather than treating the page name as local.
|
|
|
|
| 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.
|