jiantw83
df317adad8
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
5.5 KiB
5.5 KiB
jsc-ask 技能行為清單
本頁記錄 jsc-ask 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
ask
| 項目 | 內容 |
|---|---|
| 觸發時機 | 任何 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 並依結束碼分流、寫入後同步更新階段副本、把答案交回叫用的技能、收尾呼叫 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）。寫入失敗一律把答案交回並註明沒有記錄。以上每一條路線都要走完最後一步：呼叫 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 不在那台機器上就沒有這一筆，而問詢結果一字不變。 |