fix/skill-check-compliance-and-flow #15

2026-08-31T03:05:56Z

jiantw83 commented

2026-08-31 03:05:56 +00:00

摘要

需求描述：技能組例行合規稽核指出 jsc-ask 有三處失敗路徑沒有退出碼分流，且規範文件指標仍指向舊位置。本輪一併補上這些合規缺口，收斂重複的完成條件與重複的頁面讀取，並補上目錄頁的寫入語意與相依宣告。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
skills/ask/SKILL.md	產生 HASH、讀取問詢頁、寫入目錄頁三處失敗都沒有指示，技能會硬算雜湊、把失敗當成沒有紀錄，或在讀不回舊內容時整頁覆寫，抹掉別的存取庫的列；規範指標指向已搬走的檔案；兩頁每次呼叫都重讀，wiki 存取庫每次呼叫都重問，而這個問題的答案正要寫進 wiki 才記得住，會永遠問不完；問後三個完成條件重複確認同一件事，主代理得多讀兩次頁面。
templates/question-record.md	規範文件指標指向已搬走的位置，讀者找不到雜湊演算法的來源。
templates/question-contents.md	目錄頁由所有存取庫共用，範本只給表格不給寫法，寫入者容易整頁覆寫；同時規範指標也指向已搬走的位置。
README.md	技能已改成一個工作階段只讀一次，首頁說明沒跟上就會誤導外部讀者。
plugin.json	技能改用 jsc-meta 的規範文件，沒有宣告相依會裝不到或裝到太舊的版本；行為有實質變動，版本必須推進。
.claude-plugin/plugin.json	同上；這份供 Claude 系 CLI 讀取，內容必須與其他兩份一致。
.codex-plugin/plugin.json	同上；這份供 Codex 系 CLI 讀取，內容必須與其他兩份一致。

設計重點

失敗一律分流，不含糊帶過。取得 HASH 分退出碼 0、1 與其他非零；讀頁把「頁面不存在」當成沒有紀錄照常發問，其他失敗停止執行；寫入目錄頁把金鑰無效或無權限、以及其他 API 失敗都當成「舊內容不明」，放棄寫入並回報。
目錄頁改成先讀後改再整頁寫回，明文禁止整頁覆蓋。原因是這頁沒有合併機制也沒有備份，一次盲寫就抹掉所有其他存取庫的列。
新增「Session cache」一節，把「同一個工作階段內只有本技能會寫這兩頁」這個前提寫成規則：首次讀取、後續沿用、寫入後更新副本、隨工作階段結束失效。
wiki 存取庫的位置獨立成一步，並點破它的循環：答案要寫進 wiki 才記得住，而 wiki 位置正是要問的問題。解法是把答案留在工作階段內，收尾再建議使用者設定環境變數，永久結束追問。
問後的兩份寫入交給同一個子代理，收斂成單一回報。主代理確認一次即可，不再回讀頁面驗證，少掉兩次往返。
內容頁先寫、目錄頁後寫，確保目錄頁不會連到一個寫失敗的頁面。
三份 manifest 同步維護，避免各 CLI 看到不同的相依宣告。

測試結果

本輪只改技能文件、範本與 manifest，沒有動到任何可執行程式，存取庫內也沒有腳本或測試檔，因此沒有可跑的測試套件。
改以格式檢查代替：以 python3 的 json.load 逐一解析 plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json，三份皆通過。
文件類改動以人工複核為準：三處退出碼分流與規範指標的四處更新，皆已逐處對照差異確認。

前置 Push Request

無

## 摘要 - 需求描述：技能組例行合規稽核指出 jsc-ask 有三處失敗路徑沒有退出碼分流，且規範文件指標仍指向舊位置。本輪一併補上這些合規缺口，收斂重複的完成條件與重複的頁面讀取，並補上目錄頁的寫入語意與相依宣告。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | skills/ask/SKILL.md | 產生 HASH、讀取問詢頁、寫入目錄頁三處失敗都沒有指示，技能會硬算雜湊、把失敗當成沒有紀錄，或在讀不回舊內容時整頁覆寫，抹掉別的存取庫的列；規範指標指向已搬走的檔案；兩頁每次呼叫都重讀，wiki 存取庫每次呼叫都重問，而這個問題的答案正要寫進 wiki 才記得住，會永遠問不完；問後三個完成條件重複確認同一件事，主代理得多讀兩次頁面。 | | templates/question-record.md | 規範文件指標指向已搬走的位置，讀者找不到雜湊演算法的來源。 | | templates/question-contents.md | 目錄頁由所有存取庫共用，範本只給表格不給寫法，寫入者容易整頁覆寫；同時規範指標也指向已搬走的位置。 | | README.md | 技能已改成一個工作階段只讀一次，首頁說明沒跟上就會誤導外部讀者。 | | plugin.json | 技能改用 jsc-meta 的規範文件，沒有宣告相依會裝不到或裝到太舊的版本；行為有實質變動，版本必須推進。 | | .claude-plugin/plugin.json | 同上；這份供 Claude 系 CLI 讀取，內容必須與其他兩份一致。 | | .codex-plugin/plugin.json | 同上；這份供 Codex 系 CLI 讀取，內容必須與其他兩份一致。 | ## 設計重點 - 失敗一律分流，不含糊帶過。取得 HASH 分退出碼 0、1 與其他非零；讀頁把「頁面不存在」當成沒有紀錄照常發問，其他失敗停止執行；寫入目錄頁把金鑰無效或無權限、以及其他 API 失敗都當成「舊內容不明」，放棄寫入並回報。 - 目錄頁改成先讀後改再整頁寫回，明文禁止整頁覆蓋。原因是這頁沒有合併機制也沒有備份，一次盲寫就抹掉所有其他存取庫的列。 - 新增「Session cache」一節，把「同一個工作階段內只有本技能會寫這兩頁」這個前提寫成規則：首次讀取、後續沿用、寫入後更新副本、隨工作階段結束失效。 - wiki 存取庫的位置獨立成一步，並點破它的循環：答案要寫進 wiki 才記得住，而 wiki 位置正是要問的問題。解法是把答案留在工作階段內，收尾再建議使用者設定環境變數，永久結束追問。 - 問後的兩份寫入交給同一個子代理，收斂成單一回報。主代理確認一次即可，不再回讀頁面驗證，少掉兩次往返。 - 內容頁先寫、目錄頁後寫，確保目錄頁不會連到一個寫失敗的頁面。 - 三份 manifest 同步維護，避免各 CLI 看到不同的相依宣告。 ## 測試結果 - 本輪只改技能文件、範本與 manifest，沒有動到任何可執行程式，存取庫內也沒有腳本或測試檔，因此沒有可跑的測試套件。 - 改以格式檢查代替：以 `python3` 的 `json.load` 逐一解析 `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`，三份皆通過。 - 文件類改動以人工複核為準：三處退出碼分流與規範指標的四處更新，皆已逐處對照差異確認。 ## 前置 Push Request - 無

jiantw83 added 3 commits 2026-08-31 03:05:56 +00:00

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

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 的問前準備、問後紀錄流程，以及問詢紀錄頁範本。

docs(ask): 補上目錄頁寫入語意並更新技能說明 15825a5283

What
- 問詢目錄頁範本新增「寫入語意」說明。
- 問詢目錄頁範本的規範指標改指向 jsc-meta 的 references/guidelines.md。
- README 的 ask 技能說明補上工作階段內只讀一次的行為。

Why
- 目錄頁一列代表一個存取庫，由所有存取庫共用。範本只給表格不給寫法，寫入者容易整頁覆寫，抹掉別的存取庫的列。
- 指標指向的規範檔案已經搬到 jsc-meta，舊指標讓讀者找不到來源。
- README 是外部讀者認識這個技能的第一份文件。技能已經改成一個工作階段只讀一次，說明沒跟上就會誤導讀者。

How
- 在目錄頁範本的說明區塊新增一段寫入語意：先讀回整頁，有列就更新該列，沒有才在文末附加，最後整頁寫回；明文禁止整頁覆蓋，也不得改動別人的列。
- 範本的指標改寫成 jsc-meta 的 references/guidelines.md。
- README 的技能段落補一句：兩頁在同一個工作階段只讀一次，之後沿用手上那份，自己寫入後就更新它，問出來的 wiki 存取庫也留在工作階段內重複使用。

Who
- 問詢目錄頁範本，以及存取庫首頁的 ask 技能說明。

chore(manifest): 宣告 jsc-meta 相依並推進外掛版本 f5ddb808f1

What
- 三份 manifest 的 jsc.requires 新增 jsc-meta 與它的最低版本要求。
- 三份 manifest 的外掛版本各推進一版。

Why
- 這個技能的規範文件指標已經改指 jsc-meta。沒有宣告相依，安裝端可能少裝或裝到太舊的 jsc-meta，指標就指向不存在的檔案。
- 三份 manifest 分別供不同的 CLI 讀取，內容必須一致，只改其中一份會讓各 CLI 看到不同的相依。
- 技能行為這次有實質變動，版本不推進，安裝端不會取得新版。

How
- 在 jsc.requires 既有的 jsc-gitea 之後補上 jsc-meta 一項，三份 manifest 寫法一致。
- 三份 manifest 的 version 欄位同步推進一版。

Who
- jsc-ask 外掛的三份安裝設定檔。

admin approved these changes 2026-08-31 03:16:01 +00:00

admin merged commit 4e205b48ce into develop

2026-08-31 03:16:08 +00:00

admin deleted branch fix/skill-check-compliance-and-flow

2026-08-31 03:16:08 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/ask#15