Merge pull request '收尾寫一筆 skill-end 事件，執行狀態才回報得到助理' (#27) from feat/status-report into develop
Reviewed-on: #27
This commit was merged in pull request #27.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-ask",
|
||||
"version": "0.1.1",
|
||||
"version": "0.1.2",
|
||||
"description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-ask",
|
||||
"version": "0.1.1",
|
||||
"version": "0.1.2",
|
||||
"description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）",
|
||||
"skills": "./skills",
|
||||
"jsc": {
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-ask",
|
||||
"version": "0.1.1",
|
||||
"version": "0.1.2",
|
||||
"description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）",
|
||||
"skills": "./skills/",
|
||||
"jsc": {
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 任何 jsc 技能需要使用者做決定時叫用。答案已經寫在 `QUESTION_{HASH}` 且意圖相符時不叫用，直接採用舊答案。答案查得到程式碼、設定檔或環境變數時不叫用，自己去查。 |
|
||||
| 關鍵步驟 | 確認目前工作的 `{owner}/{repo}`、執行 `jsc-gitea/tools/hash-id {owner}/{repo}` 取得完整 40 碼大寫 `HASH`、每個工作階段各解析一次 `QUESTION` 與 `CONTENTS` 兩個 wiki 存取庫、讀入 `QUESTION_CONTENTS`（`CONTENTS` 庫）與 `QUESTION_{HASH}`（`QUESTION` 庫）並留成階段副本、把這一輪每一題標成「照紀錄回答」或「要問」、以決策樹選單一次問一個決策點且每個選項標明影響範圍、依答案決定下一題直到沒有疑慮、交一個 sub agent 做兩次寫入：先把新一節要放進 `QUESTION_{HASH}` 的每個連結交給 `jsc-gitea/tools/link-check.sh` 驗證，退 0 才用 `jsc-gitea:wiki` 寫那一節；再用 `jsc-gitea/tools/gitea.sh wiki-url` 取紀錄頁的絕對網址並依結束碼分流（4 是紀錄頁還沒寫上去要重寫、5 是沒有 `html_url`、7 金鑰失效、8 重試一次，其餘非 0 一律停下並註明那一列沒有被索引，網址取不到就不寫那一列）、把該列的連結再交給 `link-check.sh` 驗證，退 0 才用 `jsc-gitea/tools/wiki-contents.sh upsert` 把單列寫進 `QUESTION_CONTENTS` 並依結束碼分流、寫入後同步更新階段副本、把答案交回叫用的技能。頁面裡的連結一律寫成 `[{文字}]({連結})`，wiki 連結取自 `wiki-url` 印出的絕對網址，不自行組路徑。 |
|
||||
| 關鍵步驟 | 確認目前工作的 `{owner}/{repo}`、執行 `jsc-gitea/tools/hash-id {owner}/{repo}` 取得完整 40 碼大寫 `HASH`、每個工作階段各解析一次 `QUESTION` 與 `CONTENTS` 兩個 wiki 存取庫、讀入 `QUESTION_CONTENTS`（`CONTENTS` 庫）與 `QUESTION_{HASH}`（`QUESTION` 庫）並留成階段副本、把這一輪每一題標成「照紀錄回答」或「要問」、以決策樹選單一次問一個決策點且每個選項標明影響範圍、依答案決定下一題直到沒有疑慮、交一個 sub agent 做兩次寫入：先把新一節要放進 `QUESTION_{HASH}` 的每個連結交給 `jsc-gitea/tools/link-check.sh` 驗證，退 0 才用 `jsc-gitea:wiki` 寫那一節；再用 `jsc-gitea/tools/gitea.sh wiki-url` 取紀錄頁的絕對網址並依結束碼分流（4 是紀錄頁還沒寫上去要重寫、5 是沒有 `html_url`、7 金鑰失效、8 重試一次，其餘非 0 一律停下並註明那一列沒有被索引，網址取不到就不寫那一列）、把該列的連結再交給 `link-check.sh` 驗證，退 0 才用 `jsc-gitea/tools/wiki-contents.sh upsert` 把單列寫進 `QUESTION_CONTENTS` 並依結束碼分流、寫入後同步更新階段副本、把答案交回叫用的技能、收尾呼叫 `jsc-hooks/tools/report-status.sh skill-end jsc-ask:ask {status} {結束碼} {detail}` 記下這一輪怎麼結束（腳本路徑比照 `jsc-gitea/tools/hash-id` 的解析方式，檔案不在就安靜跳過，不得讓回報失敗變成問詢失敗）。頁面裡的連結一律寫成 `[{文字}]({連結})`，wiki 連結取自 `wiki-url` 印出的絕對網址，不自行組路徑。 |
|
||||
| 外部呼叫 | `jsc-gitea/tools/hash-id`、`jsc-gitea:wiki`（`wiki-repo QUESTION`、`wiki-repo CONTENTS`、`wiki-get`、寫入）、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/gitea.sh wiki-url`（目錄頁連到紀錄頁的絕對網址）、`jsc-gitea/tools/link-check.sh`（兩頁寫入前各驗證一次連結）、AskUserQuestion 或等效選單、一個負責兩次 wiki 寫入的 sub agent；範本 `templates/question-record.md`、`templates/question-contents.md` |
|
||||
| 完成條件 | 這一輪每一題都有答案，來源是紀錄或使用者；答案交回叫用的技能；有存取庫名稱時，sub agent 回報兩頁都寫成功（`wiki-contents.sh` 退 0），主代理接受那一次回報。沒有存取庫名稱時，問完直接交回答案，不寫任何頁。目錄頁寫不成的另一種完成條件：`wiki-contents.sh` 退 2、退 3、退 7，或 `wiki-url` 取不到網址，四種都算這一步走完——紀錄頁記成「已寫、未被索引」，回報講明結束碼與沒寫成的那一頁，答案照樣交回叫用的技能。退 3 特別要交回答案：`JSC_WIKI_REPO_CONTENTS` 在 `jsc-cli/tools/config-spec.tsv` 是 `fix=ask`，`/jsc-cli:setup` 只能靠這一支問到值，答案在這裡被吞掉，變數就永遠設不起來。退 4 代表範本參數被漏掉了，本技能的呼叫一律帶第五個參數，所以不會出現；範本路徑不存在回的是 2。`link-check.sh` 非 0 也算這一步走完：退 1 就那一頁不寫並回報 DEAD 清單，退 2 補參數重跑，退 3 先設定 `GITEA_HOST` 再驗證，退 7 停下來回報金鑰，四種都不得跳過驗證直接寫入。停止執行並回報的情況：`hash-id` 找不到 SHA-1 工具、wiki 讀取非 exit 4 的失敗、重試後仍寫不進去（`wiki-contents.sh` 退 1 或 8）。寫入失敗一律把答案交回並註明沒有記錄。 |
|
||||
| 可驗證跡象 | `QUESTION` 存取庫的 wiki `QUESTION_{HASH}` 頁尾多一節，頁名是完整 40 碼大寫十六進位，開頭是使用者意圖，底下每題一張選項與影響範圍的表，附答案與時間；`CONTENTS` 存取庫的 wiki `QUESTION_CONTENTS` 該存取庫那一列的「最後更新」變成這次執行的時間戳，沒有該列就新增一列，該列的問詢紀錄欄是 `[QUESTION_{HASH}]({絕對網址})`，網址與 `wiki-url` 印出的一字不差，別的存取庫那幾列一字不動；兩頁寫進去的每個連結都通得過 `link-check.sh`，驗不過那一輪頁面停在舊內容，回報裡有 DEAD 清單或結束碼。沒有 `{owner}/{repo}` 時無寫入跡象，只有回報內容。 |
|
||||
| 完成條件 | 這一輪每一題都有答案，來源是紀錄或使用者；答案交回叫用的技能；有存取庫名稱時，sub agent 回報兩頁都寫成功（`wiki-contents.sh` 退 0），主代理接受那一次回報。沒有存取庫名稱時，問完直接交回答案，不寫任何頁。目錄頁寫不成的另一種完成條件：`wiki-contents.sh` 退 2、退 3、退 7，或 `wiki-url` 取不到網址，四種都算這一步走完——紀錄頁記成「已寫、未被索引」，回報講明結束碼與沒寫成的那一頁，答案照樣交回叫用的技能。退 3 特別要交回答案：`JSC_WIKI_REPO_CONTENTS` 在 `jsc-cli/tools/config-spec.tsv` 是 `fix=ask`，`/jsc-cli:setup` 只能靠這一支問到值，答案在這裡被吞掉，變數就永遠設不起來。退 4 代表範本參數被漏掉了，本技能的呼叫一律帶第五個參數，所以不會出現；範本路徑不存在回的是 2。`link-check.sh` 非 0 也算這一步走完：退 1 就那一頁不寫並回報 DEAD 清單，退 2 補參數重跑，退 3 先設定 `GITEA_HOST` 再驗證，退 7 停下來回報金鑰，四種都不得跳過驗證直接寫入。停止執行並回報的情況：`hash-id` 找不到 SHA-1 工具、wiki 讀取非 exit 4 的失敗、重試後仍寫不進去（`wiki-contents.sh` 退 1 或 8）。寫入失敗一律把答案交回並註明沒有記錄。以上每一條路線都要走完最後一步：呼叫 `report-status.sh skill-end`，狀態五選一——答案齊全且該寫的兩頁都寫成是 `ok`；問詢做完但記錄少了一塊是 `degraded`，涵蓋沒有 `{owner}/{repo}` 因而完全不記錄，以及紀錄頁寫成、目錄頁沒寫成；使用者中止那一輪是 `aborted`；停手而且答案沒交回去是 `failed`。閘門擋下的情形不在這裡出現，被擋的技能根本走不到這一步，所以不用 `blocked`。腳本不在磁碟上就跳過，這一步照樣算走完。 |
|
||||
| 可驗證跡象 | `QUESTION` 存取庫的 wiki `QUESTION_{HASH}` 頁尾多一節，頁名是完整 40 碼大寫十六進位，開頭是使用者意圖，底下每題一張選項與影響範圍的表，附答案與時間；`CONTENTS` 存取庫的 wiki `QUESTION_CONTENTS` 該存取庫那一列的「最後更新」變成這次執行的時間戳，沒有該列就新增一列，該列的問詢紀錄欄是 `[QUESTION_{HASH}]({絕對網址})`，網址與 `wiki-url` 印出的一字不差，別的存取庫那幾列一字不動；兩頁寫進去的每個連結都通得過 `link-check.sh`，驗不過那一輪頁面停在舊內容，回報裡有 DEAD 清單或結束碼。沒有 `{owner}/{repo}` 時無 wiki 寫入跡象，只有回報內容。不論走哪一條路線，`$JSC_HOME/usage/events.jsonl` 尾端都會多一筆 `{kind:skill,phase:end}` 事件，`name` 是 `jsc-ask:ask`，`status` 與這一輪的結局相符，`exit` 是決定結局的那支工具的結束碼；`report-status.sh` 不在那台機器上就沒有這一筆，而問詢結果一字不變。 |
|
||||
|
||||
@@ -43,3 +43,7 @@ Inside one work session this skill is the only writer of `QUESTION_{HASH}` and `
|
||||
- Branch on `wiki-contents.sh`'s exit code, every code its own branch. 0: the row was added or updated, so this round is recorded. 1: the write failed, so retry once per step 3. 2: usage error, so stop and report the arguments that were passed — the same call retried fails the same way. A template path that does not exist lands here too, and means the plugin installation is incomplete. 3: no `CONTENTS` repo is configured, so report that `JSC_WIKI_REPO_CONTENTS` (or `JSC_WIKI_REPO`) must be set, note `QUESTION_{HASH}` as written but unindexed, and hand this round's answers back to the calling skill all the same. **Never withhold the answers over this code.** `JSC_WIKI_REPO_CONTENTS` is a `fix=ask` item in `jsc-cli/tools/config-spec.tsv`, so `/jsc-cli:setup` can only learn its value by asking through this skill; an answer dropped here leaves the variable unset, and the unset variable makes the next round drop the answer again. 4: the page does not exist and no template reached the script. The call form above always passes the template as the fifth argument, so this code cannot come out of it — getting it means that argument was dropped, so restore it and run the same call once more. 7: the key is invalid or has no permission, so stop and report without retrying. 8: any other API failure, so retry once per step 3, then stop and report.
|
||||
- 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. Exit 2, 3 or 7 from `wiki-contents.sh`, any `wiki-url` failure, and any non-zero `link-check.sh` exit on the directory row, close this step the second way: `QUESTION_{HASH}` counts as written and unindexed, the report names the exit code and the page that stayed unwritten, and this round's answers go back to the calling skill regardless. **The answers of a finished questioning round are never lost because the directory page could not be written.**
|
||||
3. On a reported write failure, retry that one page once — a `QUESTION_{HASH}` failure, or `wiki-contents.sh` exit 1 or 8. Exit 2, 3 and 7 are not retried, because the same call fails identically until someone fixes the arguments, the environment or the key; they end the recording, not the round. Every one of these paths ends the same way: the answers go back to the calling skill, and the report names the page that stayed unwritten, the exit code behind it, and what was recorded and what was not. Done when the retry succeeded and step 3 of "Session cache" refreshed that page's copy, or — when the retry also failed, or the code was 2, 3 or 7 — the report above has been printed and the answers have been handed back.
|
||||
4. Record how this run ended. This is the closing step and it runs on every route above, the ones that stopped early included. Run `jsc-hooks/tools/report-status.sh skill-end jsc-ask:ask {status} {exit} "{detail}"`, resolving the script the same sibling-plugin way this skill already resolves `jsc-gitea/tools/hash-id`. The hook that records a skill's start cannot see how it ended — it fires when the skill is loaded, and the work happens in later turns — so a start with no matching end is exactly what an abandoned run looks like, and writing this line is what keeps a finished run from reading as one.
|
||||
- `{status}` is one of five. `ok`: every question of this round carries an answer, the answers went back to the calling skill, and where `{owner}/{repo}` was known both wiki pages were written. `degraded`: the round finished and part of the recording did not — no `{owner}/{repo}` was known so nothing was recorded at all, or `QUESTION_{HASH}` landed while `QUESTION_CONTENTS` did not (`wiki-contents.sh` exit 2, 3 or 7, any `wiki-url` failure, or a non-zero `link-check.sh` on the directory row). Those stay `degraded` rather than `failed` because the answers still reached the caller, which is this skill's own completion condition. `aborted`: the user stopped the questioning round, so the undecided points were never put to them. `failed`: the run stopped and no answers came back — `hash-id` found no SHA-1 helper, a wiki read failed with anything other than exit 4, or the one retry of a page write failed as well. `blocked` does not arise here, because anything that gates this skill stops it before it ever reaches this step.
|
||||
- `{exit}` is the exit code of the tool that decided the outcome where one did, and otherwise 0 for `ok` and 1 for every other status. `{detail}` is optional, one line, at most 200 characters: name the page that stayed unwritten, or the tool and the code that stopped the run. Anything longer belongs in the report to the caller, not on this line.
|
||||
- Reporting never changes the outcome of the round. `report-status.sh` is not on every machine, so a missing file is skipped in silence and nothing else about the run changes; the script swallows its own write failures and always exits 0, so its result is never worth branching on. Done when the call was made, or the script was absent and this step was skipped without a word.
|
||||
|
||||
Reference in New Issue
Block a user