jiantw83
2c085d68ef
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與 「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上 看起來像普通文字或死連結，巡不到也修不了。 連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API， 不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把 好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁 整批判死。
90 lines
9.3 KiB
Markdown
90 lines
9.3 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.
|
|
- Every link this skill writes takes the shape `[{text}]({absolute URL})`. The directory row links the lesson page as `[LEARN_{HASH}](<url>)`, with `<url>` from `gitea.sh wiki-url <LEARN repo> LEARN_{HASH}` — never assembled by hand, and never the same-wiki `[[...]]` form, which resolves inside one wiki only and dead-links from the directory without reporting an error. `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.
|
|
- Check every link before it reaches a page: `jsc-gitea/tools/link-check.sh {url}...`. Only exit 0 permits the write.
|
|
- 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 |
|
|
|
|
- Check the row's link before writing it. Feed the `wiki-url` output to `jsc-gitea/tools/link-check.sh`; it prints one `{OK|DEAD|SKIP}<TAB>{url}<TAB>{note}` line per URL and resolves Gitea URLs through the API, because a private repo answers a logged-out web request with 404 and would fail a page that is there.
|
|
|
|
| Exit | Do |
|
|
| --- | --- |
|
|
| 0 | Every link answered. Write the row |
|
|
| 1 | At least one link is DEAD. Write nothing and report the DEAD lines to the caller |
|
|
| 2 | No URL reached the script. Pass the URLs and rerun |
|
|
| 3 | The list holds a Gitea URL but `GITEA_HOST` is unset. Set it and rerun; never skip the check |
|
|
| 7 | The Gitea token was rejected (HTTP 401/403). Stop and report the token problem. A rejected token makes live pages look missing, and one batch judged on that answer wipes out links that still work |
|
|
|
|
- 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.
|