fix(ask): 補上失敗退出碼分流並改正規範指標

What
- 產生 HASH 的指令失敗時,依退出碼分流處理。
- 讀取問詢頁失敗時,依退出碼分流處理。
- 寫入目錄頁失敗時,依退出碼分流處理。
- 規範文件的指標改指向 jsc-meta 的 references/guidelines.md。
- 新增「Session cache」一節,兩頁在同一個工作階段只讀一次。
- wiki 存取庫在同一個工作階段只解析一次。
- 問後的三重完成條件收斂成一次確認。

Why
- 原本只寫「執行指令取得 HASH」。指令失敗時沒有指示,技能會自行硬算雜湊或猜測頁名,寫錯頁面。
- 「讀取失敗」與「頁面不存在」意義不同。不分流就把失敗當成沒有紀錄,重問使用者已經回答過的問題。
- 目錄頁由所有存取庫共用。讀不回舊內容還照樣整頁覆寫,會抹掉別的存取庫的列,而且沒有備份可救。
- 指標指向的規範檔案已經搬到 jsc-meta,舊指標讓讀者找不到來源。
- 兩頁在一個工作階段內只有本技能會寫。重複讀取只是多花往返時間。
- wiki 位置本身就是要問的問題,答案卻要寫進 wiki 才記得住。不把答案留在工作階段內,每次呼叫都得再問一次,永遠問不完。
- 完成條件重複確認同一件事,主代理得多讀兩次頁面才敢往下走。

How
- 取得 HASH 一步列明退出碼 0 與 1 的處理;其他非零退出碼一律停止執行,並回報退出碼與指令的錯誤輸出。
- 讀取一步把「頁面不存在」視為沒有紀錄,照常發問;其他失敗停止執行,並回報失敗頁名與退出碼。
- 寫入目錄頁一步依退出碼分流:正常就讀回整頁後更新單列,金鑰無效或無權限、以及其他 API 失敗都放棄寫入並回報。
- 新增「Session cache」一節,訂出首次讀取、後續沿用、寫入後更新副本、隨工作階段結束失效四個步驟。
- 解析 wiki 存取庫獨立成一步,答案留在工作階段內重複使用,收尾再建議使用者設定環境變數,永久結束追問。
- 兩份寫入交給同一個子代理,收斂成單一回報,主代理確認一次即可,不再回讀頁面驗證。
- 寫入失敗只重試該頁一次;再失敗就停止執行,回報未寫入的頁面與退出碼,答案仍交還呼叫端。
- 兩份範本的指標同步改指 jsc-meta。

Who
- 決策樹問詢技能 ask 的問前準備、問後紀錄流程,以及問詢紀錄頁範本。
This commit is contained in:
2026-08-31 11:05:09 +08:00
parent b88d07037e
commit 232eb36158
2 changed files with 16 additions and 7 deletions
+15 -6
View File
@@ -7,11 +7,21 @@ description: Decision-tree questioning until no doubt remains. Checks wiki QUEST
Every jsc skill that needs user input MUST follow the rules in this skill. Every jsc skill that needs user input MUST follow the rules in this skill.
## Session cache
Inside one work session this skill is the only writer of `QUESTION_{HASH}` and `QUESTION_CONTENTS`, so both pages are read once and reused.
1. First call of the session: read both pages and keep them as the session copy. Done when the session holds each page's content, or the note that the page does not exist yet.
2. Every later call of the session: answer from the session copy. Done when this round's questions are matched against the session copy with no new wiki read.
3. Right after this skill writes either page: overwrite that page's session copy with the content just written. Done when the session copy equals the written content.
4. The cache expires with the work session, and only with it. Done when a new session starts again at step 1.
## Before asking ## Before asking
1. Confirm the repository name `{owner}/{repo}` of the current work. Done when `{owner}/{repo}` is known, or when it is settled that none exists — then skip steps 2 and 3, ask directly, and do NOT record. 1. Confirm the repository name `{owner}/{repo}` of the current work. Done when `{owner}/{repo}` is known, or when it is settled that none exists — then skip steps 2 to 4, ask directly, and do NOT record.
2. Compute `HASH` by running `jsc-gitea/tools/hash-id {owner}/{repo}` (the shared wiki hash rule — see guidelines.md for the algorithm). Done when the 8-character `HASH` is known. 2. Compute `HASH` by running `jsc-gitea/tools/hash-id {owner}/{repo}` (the shared wiki hash rule — see `jsc-meta/references/guidelines.md` for the algorithm). Exit 0: take the printed 8-character `HASH`. Exit 1 (no SHA-1 helper on this machine): stop the run and report that `sha1sum` or `shasum` must be installed first; never hand-compute the hash and never guess a page name. Any other non-zero exit: stop the same way and report the exit code with the command's stderr. Done when the 8-character `HASH` is known, or the run stopped with that report.
3. Read `QUESTION_CONTENTS` and `QUESTION_{HASH}` via `jsc-gitea:wiki`. Never re-ask a question already answered in the record; use the recorded answer directly. When reusing an answer, read the section's recorded intent: reuse it when that intent matches the current situation, and ask again when it differs, instead of forcing the old answer. An answer whose intent covers a similar undecided question in this round answers that one too. Done when every question in this round is marked either answered-from-record with the citing section named, or to-be-asked. 3. Resolve the `QUESTION` wiki repo once per session through `jsc-gitea:wiki`. When that skill reports exit 3 for `wiki-repo QUESTION` (neither `JSC_WIKI_REPO_QUESTION` nor `JSC_WIKI_REPO` is set), ask the user for that `{owner}/{repo}`, then keep the answer in the session and reuse it for every later call — this one answer cannot come from the record, because the wiki location is the question itself, so asking again each call would loop forever. Close the run by advising the user to set `JSC_WIKI_REPO_QUESTION` (or `JSC_WIKI_REPO`) in the environment, which ends the asking permanently. Done when the session holds one `{owner}/{repo}` for `QUESTION` and no later call in this session asked for it again.
4. Load `QUESTION_CONTENTS` and `QUESTION_{HASH}` per "Session cache". A page reported missing (`wiki-get` exit 4) counts as "no record yet": keep going and ask every question of this round. Any other `jsc-gitea:wiki` failure stops the run with a report of the failing page and the underlying exit code; do not ask on a half-read record, because an answer already on file would be asked again. Never re-ask a question already answered in the record; use the recorded answer directly. When reusing an answer, read the section's recorded intent: reuse it when that intent matches the current situation, and ask again when it differs, instead of forcing the old answer. An answer whose intent covers a similar undecided question in this round answers that one too. Done when every question in this round is marked either answered-from-record with the citing section named, or to-be-asked.
## Questioning rules ## Questioning rules
@@ -24,6 +34,5 @@ Every jsc skill that needs user input MUST follow the rules in this skill.
## After asking ## After asking
1. Without a repository name, do not record; stop here. Done when the answers are handed back to the calling skill and no wiki page was touched. 1. Without a repository name, do not record; stop here. Done when the answers are handed back to the calling skill and no wiki page was touched.
2. After each Q&A round, apply `templates/question-record.md` to create or update `QUESTION_{HASH}` (append new entries; never overwrite old records). Each section MUST open with the user's original intent (why this questioning round happened), per the template; it lets a later reader judge why the user chose as they did and whether the answer still applies. Done when a section for this round exists on `QUESTION_{HASH}`, carries this round's intent and every answer, and every section written by an earlier round is still there. 2. After each Q&A round, hand both wiki writes to one sub agent. That sub agent MUST write through `jsc-gitea:wiki` — it owns the `JSC_WIKI_REPO_QUESTION` → `JSC_WIKI_REPO` resolution and the tea-token fallback, which a hand-rolled Gitea API call loses. It writes `QUESTION_{HASH}` first, applying `templates/question-record.md`: append this round as a new section, keep every earlier section, and open the section with the user's original intent (why this questioning round happened), which lets a later reader judge why the user chose as they did and whether the answer still applies. It then writes `QUESTION_CONTENTS`, applying `templates/question-contents.md`: read the page back, add the `{owner}/{repo}` row when missing, otherwise set 最後更新 to this run's timestamp, then write the whole page. `QUESTION_CONTENTS` is a directory shared by every repository, so it is never overwritten wholesale and no other repository's row is touched; `QUESTION_{HASH}` belongs to this one repository, which is why appending a section to it is the right shape there. Its read branches by exit code, and only exit 4 creates the directory from the template: exit 0 upserts into the content that came back, while exit 7 (key invalid or no permission) and exit 8 (any other API failure) both mean the old rows are unknown, so the write is abandoned and reported instead — a fresh template over a directory whose rows were never read erases every other repository's row, with no merge and no backup behind it. Content page first, contents page second, so the contents page never links a page that failed to write. Done when the sub agent has reported both writes as succeeded and the main agent has accepted that one report — this single confirmation covers both pages and both templates; do not re-read the pages to prove it.
3. Apply `templates/question-contents.md` to create or update `QUESTION_CONTENTS` (add the repository row if missing; otherwise refresh its last-updated time). Done when the row for `{owner}/{repo}` carries 最後更新 equal to this run's timestamp. 3. On a reported write failure, retry that one page once. Done when the retry succeeded and step 3 of "Session cache" refreshed that page's copy, or — when the retry also failed — the run stops with a report naming the page that stayed unwritten and the exit code behind it, while the answers still go back to the calling skill and the report states plainly that nothing was recorded.
4. The wiki writes above MUST run as a sub agent, and that sub agent MUST write both `QUESTION_{HASH}` and `QUESTION_CONTENTS` through `jsc-gitea:wiki` — it owns the `JSC_WIKI_REPO_QUESTION` → `JSC_WIKI_REPO` resolution and the tea-token fallback, which a hand-rolled Gitea API call loses. Completion condition: the main agent has confirmed both writes succeeded.
+1 -1
View File
@@ -1,6 +1,6 @@
# 問詢紀錄 — {owner}/{repo} # 問詢紀錄 — {owner}/{repo}
> 由 `jsc-ask:ask` 維護。這是問詢紀錄頁 `QUESTION_{HASH}`;`HASH` 執行 `jsc-gitea/tools/hash-id {owner}/{repo}` 取得(共用 wiki hash 規則,演算法見 guidelines.md)。新問答**附加**在文末,不覆蓋舊紀錄。相同問題再次出現時,直接採用此處答案,不再詢問。 > 由 `jsc-ask:ask` 維護。這是問詢紀錄頁 `QUESTION_{HASH}`;`HASH` 執行 `jsc-gitea/tools/hash-id {owner}/{repo}` 取得(共用 wiki hash 規則,演算法見 `jsc-meta` 的 `references/guidelines.md`)。新問答**附加**在文末,不覆蓋舊紀錄。相同問題再次出現時,直接採用此處答案,不再詢問。
## {yyyy-MM-dd HH:mm} {問詢主題} ## {yyyy-MM-dd HH:mm} {問詢主題}