feat(狀態回報): 收尾寫一筆 skill-end 事件

現行紀錄只記「被叫用」,沒有成敗也沒有結束碼。跑完整輪的技能與開場就
中止的技能,在紀錄裡長得一模一樣。

start 由技能用量 hook 順手發,不必改技能文件。end 只能由技能自己在收尾
步驟寫——hook 接在技能工具呼叫上,而實際工作發生在之後的模型輪次,它在
原理上看不到成敗。有 start 沒有配對的 end,就是那一輪中止了。

status 五選一,每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜
跳過,回報失敗一律不改變技能自己的結論。
This commit is contained in:
2026-09-02 16:01:16 +08:00
parent 03188837d3
commit b87dbb12cd
11 changed files with 240 additions and 37 deletions
+1 -1
View File
@@ -71,7 +71,7 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安
| `tools/ste100-lint.sh` | 語言規則的機檢工具:中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線;命中 exit 1,沒給檢查對象 exit 2 | | `tools/ste100-lint.sh` | 語言規則的機檢工具:中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線;命中 exit 1,沒給檢查對象 exit 2 |
| `tools/lint-scripts.sh` | 一個 domain 的腳本檢查三合一:`sh -n` 語法、執行權限、檔頭結束碼宣告;有不合格 exit 1,沒有腳本可掃 exit 3(**不等於通過**) | | `tools/lint-scripts.sh` | 一個 domain 的腳本檢查三合一:`sh -n` 語法、執行權限、檔頭結束碼宣告;有不合格 exit 1,沒有腳本可掃 exit 3(**不等於通過**) |
| `tools/lint-frontmatter.sh` | 一個 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析檢查:分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」也不以 YAML 特殊字元起頭、引號收得起來。不相依任何 YAML 套件。不合格 exit 1(清單在 stderr),用法錯誤 exit 2,沒有 SKILL.md 可掃 exit 3(**不等於通過**)。frontmatter 壞掉時 Antigravity 會**靜默丟棄整支技能**,沒有任何錯誤訊息 | | `tools/lint-frontmatter.sh` | 一個 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析檢查:分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」也不以 YAML 特殊字元起頭、引號收得起來。不相依任何 YAML 套件。不合格 exit 1(清單在 stderr),用法錯誤 exit 2,沒有 SKILL.md 可掃 exit 3(**不等於通過**)。frontmatter 壞掉時 Antigravity 會**靜默丟棄整支技能**,沒有任何錯誤訊息 |
| `tools/check-behaviors.sh` | 比對一個 domain 的 `references/behaviors.md` 與 `skills/`:節對技能、字典序、每節一張表、五個欄位齊全且內容欄非空;不符 exit 1,用法錯誤 exit 2,找不到清單或找不到技能 exit 3(**不等於通過**) | | `tools/check-behaviors.sh` | 比對一個 domain 的 `references/behaviors.md` 與 `skills/`:節對技能、字典序、每節一張表、五個欄位齊全且內容欄非空,另斷言「可驗證跡象」那一列寫到收尾的 `skill-end` 事件或 `events.jsonl`(技能的成敗只有技能自己寫得出來,hook 觸發時實際工作還在後面的模型輪次;有 start 沒有配對的 end 就是中止);不符 exit 1,用法錯誤 exit 2,找不到清單或找不到技能 exit 3(**不等於通過**) |
| `tools/check-link-format.sh` | 檢查一個 domain 全部 `*.md` 的連結寫法:一律 `[{文字}]({連結})`,不留同 wiki 的雙括號連結。判定前先剝掉行內程式碼與圍籬區塊,所以說明用的字面與 shell 條件測試不會誤判。有命中 exit 1(清單在 stdout),用法錯誤 exit 2,沒有文件可掃 exit 3(**不等於通過**) | | `tools/check-link-format.sh` | 檢查一個 domain 全部 `*.md` 的連結寫法:一律 `[{文字}]({連結})`,不留同 wiki 的雙括號連結。判定前先剝掉行內程式碼與圍籬區塊,所以說明用的字面與 shell 條件測試不會誤判。有命中 exit 1(清單在 stdout),用法錯誤 exit 2,沒有文件可掃 exit 3(**不等於通過**) |
| `tools/check-page-name.sh` | 比對 wiki 頁名樣式三處是否一致:`jsc-gitea/tools/page-name.sh`(正本)、`jsc-hooks/hooks/comment-scope.sh`、`jsc-log/tools/worklog-pending.sh`。三處刻意不共用函式,因為 hook 必須自足;斷言十五種型別、40 碼與 8 碼兩種長度。不一致 exit 1,用法錯誤 exit 2,三處一支都找不到 exit 3(**不等於通過**) | | `tools/check-page-name.sh` | 比對 wiki 頁名樣式三處是否一致:`jsc-gitea/tools/page-name.sh`(正本)、`jsc-hooks/hooks/comment-scope.sh`、`jsc-log/tools/worklog-pending.sh`。三處刻意不共用函式,因為 hook 必須自足;斷言十五種型別、40 碼與 8 碼兩種長度。不一致 exit 1,用法錯誤 exit 2,三處一支都找不到 exit 3(**不等於通過**) |
| `tools/deploy-route.sh` | 判定改動有沒有進存取庫的預設分支,決定走部署路線(exit 0)或工作樹路線(exit 3);判不出來 exit 1,**不等於工作樹路線** | | `tools/deploy-route.sh` | 判定改動有沒有進存取庫的預設分支,決定走部署路線(exit 0)或工作樹路線(exit 3);判不出來 exit 1,**不等於工作樹路線** |
+28 -28
View File
@@ -7,67 +7,67 @@
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 手上沒有異動需求,要對整組技能做例行或臨時稽核時用。帶著異動需求要改多支技能走 skillset-update、只改一支走 skill-update | | 觸發時機 | 手上沒有異動需求,要對整組技能做例行或臨時稽核時用。帶著異動需求要改多支技能走 skillset-update、只改一支走 skill-update |
| 關鍵步驟 | 先跑 sync-domains.sh 同步全部 domain 存取庫、再平行跑三組審查(第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查、連結寫法檢查、wiki 規則檢查、頁名樣式檢查與 hook smoke,第二組以 sub agent 逐 domain 對 guidelines 檢查清單稽核,第三組先用 wiki-repo SKILLSET 與 hash-id 讀回各 domain SKILLSET_{HASH} 上已決議的優化建議再以 sub agent 分六個面向審查流程與成本;讀取回 7、8 或存取庫解不出來時只停掉該 domain 的第三組,第一組、第二組與後續步驟照跑)、合併三組結果並用決策樹逐項確認(第二組留白的九項由第一組的結論補上,其中頁名樣式與 wiki 規則兩項是整輪一份,同一個結論填進每個 domain;優化建議記下決議與決議日期)、以平行 sub agent 套用確認過的修正並跑 sync-skill-manifest.sh、跑 sync-marketplace.sh 同步兩份正本 marketplace、重跑三組驗證直到接受的修正全通過、每個受影響存取庫各開一條 PR、最後以平行 sub agent 逐 domain 把本輪稽核結果附加到 SKILLSET_{HASH},再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS | | 關鍵步驟 | 先跑 sync-domains.sh 同步全部 domain 存取庫、再平行跑三組審查(第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查、連結寫法檢查、wiki 規則檢查、頁名樣式檢查與 hook smoke,第二組以 sub agent 逐 domain 對 guidelines 檢查清單稽核,第三組先用 wiki-repo SKILLSET 與 hash-id 讀回各 domain SKILLSET_{HASH} 上已決議的優化建議再以 sub agent 分六個面向審查流程與成本;讀取回 7、8 或存取庫解不出來時只停掉該 domain 的第三組,第一組、第二組與後續步驟照跑)、合併三組結果並用決策樹逐項確認(第二組留白的九項由第一組的結論補上,其中頁名樣式與 wiki 規則兩項是整輪一份,同一個結論填進每個 domain;優化建議記下決議與決議日期)、以平行 sub agent 套用確認過的修正並跑 sync-skill-manifest.sh、跑 sync-marketplace.sh 同步兩份正本 marketplace、重跑三組驗證直到接受的修正全通過、每個受影響存取庫各開一條 PR、最後以平行 sub agent 逐 domain 把本輪稽核結果附加到 SKILLSET_{HASH},再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-check 寫一筆收尾事件(五種 status 依本輪實際結果選,中途停下的輪次也要寫;腳本不在就安靜跳過,不影響本輪結局) |
| 外部呼叫 | tools/sync-domains.sh、tools/lint-scripts.sh、tools/lint-frontmatter.sh、tools/check-behaviors.sh、tools/ste100-lint.sh、tools/check-link-format.sh、tools/check-page-name.sh、tools/sync-skill-manifest.sh、tools/sync-marketplace.sh、jsc-gitea/tools/check-wiki-rules.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh smoke、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md | | 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/lint-scripts.sh、tools/lint-frontmatter.sh、tools/check-behaviors.sh、tools/ste100-lint.sh、tools/check-link-format.sh、tools/check-page-name.sh、tools/sync-skill-manifest.sh、tools/sync-marketplace.sh、jsc-gitea/tools/check-wiki-rules.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh smoke、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
| 完成條件 | 每個 domain 都有腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查與連結寫法檢查的結論(連結寫法檢查退出 3 是「什麼都沒掃」,不算通過),wiki 規則檢查與頁名樣式檢查各有一次結論(frontmatter 檢查退出 3 是「什麼都沒掃」、頁名樣式檢查退出 3 是「什麼都沒查」,都不算通過)、每個 domain 的檢查清單在合併後補齊且那兩項整輪一份的結論在每個 domain 都填上同一個值、讀不到已決議清單的 domain 記成「本輪未取得已決議清單,優化建議暫不提出」、每項不合規與每項優化建議都有決策紀錄且優化建議帶決議日期、接受的修正重驗通過、每個受影響存取庫都拿到 PR 網址、寫進 wiki 的每個連結都先經 link-check.sh 退出 0、每個受影響 domain 的 wiki 頁都寫成功,或列為未寫入並附完整內容 | | 完成條件 | 每個 domain 都有腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查與連結寫法檢查的結論(連結寫法檢查退出 3 是「什麼都沒掃」,不算通過),wiki 規則檢查與頁名樣式檢查各有一次結論(frontmatter 檢查退出 3 是「什麼都沒掃」、頁名樣式檢查退出 3 是「什麼都沒查」,都不算通過)、每個 domain 的檢查清單在合併後補齊且那兩項整輪一份的結論在每個 domain 都填上同一個值、讀不到已決議清單的 domain 記成「本輪未取得已決議清單,優化建議暫不提出」、每項不合規與每項優化建議都有決策紀錄且優化建議帶決議日期、接受的修正重驗通過、每個受影響存取庫都拿到 PR 網址、寫進 wiki 的每個連結都先經 link-check.sh 退出 0、每個受影響 domain 的 wiki 頁都寫成功,或列為未寫入並附完整內容、本輪的 skill-end 事件已寫入,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | 受影響存取庫留下檔案改動、改到行為的技能連帶改寫該存取庫的 references/behaviors.md、每個 domain 的 lint-frontmatter.sh、ste100-lint.sh 與 check-link-format.sh 退出 0、check-page-name.sh 退出 0、README 的「Skills 目錄」重寫、三份 manifest 版本號提升、兩份 marketplace 檔逐位元一致、每個受影響存取庫一條 PR、每個受影響 domain 的 SKILLSET_{HASH} 各附加一節,並由 wiki-contents.sh upsert 退出 0 在 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁;本輪無 domain 被改動時,改成 plugins/meta 那一頁記「本輪無發現」 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-check 的 skill-end 事件(本輪唯一必留的跡象,腳本不在時才沒有)、受影響存取庫留下檔案改動、改到行為的技能連帶改寫該存取庫的 references/behaviors.md、每個 domain 的 lint-frontmatter.sh、ste100-lint.sh 與 check-link-format.sh 退出 0、check-page-name.sh 退出 0、README 的「Skills 目錄」重寫、三份 manifest 版本號提升、兩份 marketplace 檔逐位元一致、每個受影響存取庫一條 PR、每個受影響 domain 的 SKILLSET_{HASH} 各附加一節,並由 wiki-contents.sh upsert 退出 0 在 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁;本輪無 domain 被改動時,改成 plugins/meta 那一頁記「本輪無發現」 |
## skill-delete ## skill-delete
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 要把一支技能從技能組移除時用。改名不走這支,走 skill-update | | 觸發時機 | 要把一支技能從技能組移除時用。改名不走這支,走 skill-update |
| 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支確認刪除、跑 find-skill-refs.sh 盤點所有引用檔案、以平行 sub agent 逐檔修正到檢查清單全過、刪掉 skills/{name}/ 目錄、移除 references/behaviors.md 對應那一節、跑 sync-skill-manifest.sh、開 PR、依 deploy-verify.md 部署、用新的 CLI 行程驗證、跑 verify-skill-removed.sh 查磁碟殘留、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流 | | 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支確認刪除、跑 find-skill-refs.sh 盤點所有引用檔案、以平行 sub agent 逐檔修正到檢查清單全過、刪掉 skills/{name}/ 目錄、移除 references/behaviors.md 對應那一節、跑 sync-skill-manifest.sh、開 PR、依 deploy-verify.md 部署、用新的 CLI 行程驗證、跑 verify-skill-removed.sh 查磁碟殘留、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-delete 寫一筆收尾事件(五種 status 依本次實際結果選,中途停下也要寫;腳本不在就安靜跳過,不影響本次結局) |
| 外部呼叫 | tools/sync-domains.sh、tools/list-skills.sh、tools/find-skill-refs.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/verify-skill-removed.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md | | 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/list-skills.sh、tools/find-skill-refs.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/verify-skill-removed.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
| 完成條件 | 盤點清單每一檔都有「已修正」或「無需修正」的結論、技能目錄與行為清單那一節都不存在、list-skills.sh 查不到那一列、殘留檢查退出 0 或據實記成「無處可查」並帶進報告、PR 網址到手、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0 | | 完成條件 | 盤點清單每一檔都有「已修正」或「無需修正」的結論、技能目錄與行為清單那一節都不存在、list-skills.sh 查不到那一列、殘留檢查退出 0 或據實記成「無處可查」並帶進報告、PR 網址到手、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0、本次的 skill-end 事件已寫入,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | skills/{name}/ 目錄消失、references/behaviors.md 少一節、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-delete 的 skill-end 事件(本次唯一必留的跡象,腳本不在時才沒有)、skills/{name}/ 目錄消失、references/behaviors.md 少一節、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
## skill-new ## skill-new
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 要在技能組新增一支技能時用。改既有技能走 skill-update | | 觸發時機 | 要在技能組新增一支技能時用。改既有技能走 skill-update |
| 關鍵步驟 | 平行跑 list-skills.sh 與 sync-domains.sh 預取技能清單與 domain 清單、用決策樹問出目標、觸發時機、輸入輸出與所屬 domain、domain 未註冊就先確認存取庫在不在、依 template 結構補齊內容再跑 sync-marketplace.sh 註冊、以 sub agent 產生 skills/{name}/SKILL.md、在 references/behaviors.md 依字典序插入該技能一節、跑 sync-skill-manifest.sh、自查 guidelines 檢查清單並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流 | | 關鍵步驟 | 平行跑 list-skills.sh 與 sync-domains.sh 預取技能清單與 domain 清單、用決策樹問出目標、觸發時機、輸入輸出與所屬 domain、domain 未註冊就先確認存取庫在不在、依 template 結構補齊內容再跑 sync-marketplace.sh 註冊、以 sub agent 產生 skills/{name}/SKILL.md、在 references/behaviors.md 依字典序插入該技能一節、跑 sync-skill-manifest.sh、自查 guidelines 檢查清單並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-new 寫一筆收尾事件(五種 status 依本次實際結果選,中途停下也要寫;腳本不在就安靜跳過,不影響本次結局) |
| 外部呼叫 | tools/list-skills.sh、tools/sync-domains.sh、tools/sync-marketplace.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 clone-url、api、wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md | | 外部呼叫 | tools/list-skills.sh、tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/sync-marketplace.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 clone-url、api、wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
| 完成條件 | 四項提問都有紀錄、SKILL.md 與行為清單那一節都在、README 與三份 manifest 同步、檢查清單全過且 check-behaviors.sh 退出 0、PR 網址到手、deploy-verify.md 第 1 到第 5 節的完成條件全數成立、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0 | | 完成條件 | 四項提問都有紀錄、SKILL.md 與行為清單那一節都在、README 與三份 manifest 同步、檢查清單全過且 check-behaviors.sh 退出 0、PR 網址到手、deploy-verify.md 第 1 到第 5 節的完成條件全數成立、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0、本次的 skill-end 事件已寫入,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | 新增 skills/{name}/SKILL.md、references/behaviors.md 多一節、README 與三份 manifest 更新、新 domain 時兩份 marketplace 檔多一筆 plugin 條目並同步到每個 domain 存取庫、一條 PR、wiki SKILLSET_{HASH} 附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-new 的 skill-end 事件(本次唯一必留的跡象,腳本不在時才沒有)、新增 skills/{name}/SKILL.md、references/behaviors.md 多一節、README 與三份 manifest 更新、新 domain 時兩份 marketplace 檔多一筆 plugin 條目並同步到每個 domain 存取庫、一條 PR、wiki SKILLSET_{HASH} 附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
## skill-update ## skill-update
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 要改一支既有技能時用。新增走 skill-new、刪除走 skill-delete、一次改多支或跨 domain 走 skillset-update | | 觸發時機 | 要改一支既有技能時用。新增走 skill-new、刪除走 skill-delete、一次改多支或跨 domain 走 skillset-update |
| 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支、用決策樹問出改動細節、以 sub agent 改 SKILL.md 與相關檔案、同步更新 references/behaviors.md 該技能那一節、跑 sync-skill-manifest.sh、對 guidelines 檢查清單逐項自查並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流 | | 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支、用決策樹問出改動細節、以 sub agent 改 SKILL.md 與相關檔案、同步更新 references/behaviors.md 該技能那一節、跑 sync-skill-manifest.sh、對 guidelines 檢查清單逐項自查並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-update 寫一筆收尾事件(五種 status 依本次實際結果選,中途停下也要寫;腳本不在就安靜跳過,不影響本次結局) |
| 外部呼叫 | tools/sync-domains.sh、tools/list-skills.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md | | 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/list-skills.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
| 完成條件 | 每個提問都有紀錄、技能檔案帶著改動、行為清單那一節與新行為一致且 check-behaviors.sh 退出 0、三份 manifest 同版、檢查清單全過、PR 網址到手、deploy-verify.md 第 1 到第 5 節的完成條件全數成立、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0 | | 完成條件 | 每個提問都有紀錄、技能檔案帶著改動、行為清單那一節與新行為一致且 check-behaviors.sh 退出 0、三份 manifest 同版、檢查清單全過、PR 網址到手、deploy-verify.md 第 1 到第 5 節的完成條件全數成立、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0、本次的 skill-end 事件已寫入,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | 該技能的 SKILL.md 與相關檔案改動、references/behaviors.md 對應節改寫、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-update 的 skill-end 事件(本次唯一必留的跡象,腳本不在時才沒有)、該技能的 SKILL.md 與相關檔案改動、references/behaviors.md 對應節改寫、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
## skillset-update ## skillset-update
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 一個異動需求橫跨多支技能或多個 domain,要一次做完時用。只改一支走 skill-update、手上沒有異動需求的例行稽核走 skill-check | | 觸發時機 | 一個異動需求橫跨多支技能或多個 domain,要一次做完時用。只改一支走 skill-update、手上沒有異動需求的例行稽核走 skill-check |
| 關鍵步驟 | 平行啟動 sync-domains.sh 與異動細節決策樹、問清楚改哪一條規則、影響哪些技能與 domain,並補問工具化、sub agent、環境變數三項塑形檢查、以每個 domain 一個 sub agent 平行套用改動、同步更新每個受影響 domain 的 references/behaviors.md、逐存取庫跑 sync-skill-manifest.sh、以平行 sub agent 重跑 guidelines 檢查清單與 check-behaviors.sh 直到全過、每個受影響存取庫各開一條 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、以平行 sub agent 逐存取庫用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流 | | 關鍵步驟 | 平行啟動 sync-domains.sh 與異動細節決策樹、問清楚改哪一條規則、影響哪些技能與 domain,並補問工具化、sub agent、環境變數三項塑形檢查、以每個 domain 一個 sub agent 平行套用改動、同步更新每個受影響 domain 的 references/behaviors.md、逐存取庫跑 sync-skill-manifest.sh、以平行 sub agent 重跑 guidelines 檢查清單與 check-behaviors.sh 直到全過、每個受影響存取庫各開一條 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、以平行 sub agent 逐存取庫用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流,最後由主 agent 呼叫一次 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skillset-update 寫一筆收尾事件(整批一筆,不逐 domain 寫;五種 status 依本次實際結果選,中途停下也要寫;腳本不在就安靜跳過,不影響本次結局) |
| 外部呼叫 | tools/sync-domains.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/list-skills.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md | | 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/list-skills.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert(目錄頁那一列)、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
| 完成條件 | 受影響技能清單與三項塑形檢查都跟使用者談定、每個受影響存取庫都帶著改動、README 同步與 manifest 提升、每支動過的技能檢查清單全過且該 domain 的 check-behaviors.sh 退出 0、每個受影響存取庫都有 PR 網址、deploy-verify.md 第 1 到第 5 節對每個存取庫都成立、每個存取庫寫進頁與列的每個連結都經 link-check.sh 退出 0、每個存取庫的 SKILLSET_{HASH} 都附加一節且舊節原樣留著、每個存取庫的 wiki-contents.sh upsert 都退出 0 | | 完成條件 | 受影響技能清單與三項塑形檢查都跟使用者談定、每個受影響存取庫都帶著改動、README 同步與 manifest 提升、每支動過的技能檢查清單全過且該 domain 的 check-behaviors.sh 退出 0、每個受影響存取庫都有 PR 網址、deploy-verify.md 第 1 到第 5 節對每個存取庫都成立、每個存取庫寫進頁與列的每個連結都經 link-check.sh 退出 0、每個存取庫的 SKILLSET_{HASH} 都附加一節且舊節原樣留著、每個存取庫的 wiki-contents.sh upsert 都退出 0、本次整批一筆的 skill-end 事件已寫入,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | 每個受影響存取庫的技能檔案改動、各自的 references/behaviors.md 更新、README 與三份 manifest 更新、每個存取庫一條 PR、每個存取庫的 wiki SKILLSET_{HASH} 各附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 各留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skillset-update 的 skill-end 事件(整批只有一行,本次唯一必留的跡象,腳本不在時才沒有)、每個受影響存取庫的技能檔案改動、各自的 references/behaviors.md 更新、README 與三份 manifest 更新、每個存取庫一條 PR、每個存取庫的 wiki SKILLSET_{HASH} 各附加一節,並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 各留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
## ste100-sync ## ste100-sync
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 定期維護,或上游 speak-human-tw 發佈新版時用。只改本地自訂規則不走這支 | | 觸發時機 | 定期維護,或上游 speak-human-tw 發佈新版時用。只改本地自訂規則不走這支 |
| 關鍵步驟 | 先讀 references/ste100.md 釘住的上游版本、再用 HTTPS 讀上游 SKILL.md frontmatter 的版本比對、同版就回報「上游沒有新版」並停在這裡、有新版才淺層 clone 取 changelog、以 sub agent 蒸餾適用於技術文件與對話的變更、用決策樹逐項確認採用、改寫 references/ste100.md 與「上游版本」行、必要時更新 ste100-lint.sh 的樣式與 jsc-hooks/hooks/simplified.txt、平行對每個 jsc 存取庫重跑 lint、跑 sync-skill-manifest.sh、開 PR | | 關鍵步驟 | 先讀 references/ste100.md 釘住的上游版本、再用 HTTPS 讀上游 SKILL.md frontmatter 的版本比對、同版就回報「上游沒有新版」並停在這裡、有新版才淺層 clone 取 changelog、以 sub agent 蒸餾適用於技術文件與對話的變更、用決策樹逐項確認採用、改寫 references/ste100.md 與「上游版本」行、必要時更新 ste100-lint.sh 的樣式與 jsc-hooks/hooks/simplified.txt、平行對每個 jsc 存取庫重跑 lint、跑 sync-skill-manifest.sh、開 PR、最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:ste100-sync 寫一筆收尾事件(五種 status 依本次實際結果選,上游同版就停下的那一輪照樣要寫,選 ok;腳本不在就安靜跳過,不影響本次結局) |
| 外部呼叫 | 上游 speak-human-tw 的 raw SKILL.md 與 git clone、tools/ste100-lint.sh、tools/sync-domains.sh、tools/sync-skill-manifest.sh、jsc-ask:ask、jsc-git:pr | | 外部呼叫 | 上游 speak-human-tw 的 raw SKILL.md 與 git clone、tools/ste100-lint.sh、tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/sync-skill-manifest.sh、jsc-ask:ask、jsc-git:pr |
| 完成條件 | 上游同版時停在版本比對並回報;有新版時每項蒸餾出來的變更都有決策、`sh -n tools/ste100-lint.sh` 通過且新採用的詞彙在測試字串上命中、本存取庫 lint 退出 0、其他存取庫的命中附 file:line 交給擁有者、三份 manifest 同版、PR 網址到手 | | 完成條件 | 上游同版時停在版本比對並回報;有新版時每項蒸餾出來的變更都有決策、`sh -n tools/ste100-lint.sh` 通過且新採用的詞彙在測試字串上命中、本存取庫 lint 退出 0、其他存取庫的命中附 file:line 交給擁有者、三份 manifest 同版、PR 網址到手;兩條路徑都要寫下本次的 skill-end 事件,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | references/ste100.md 的「上游版本」行換值、tools/ste100-lint.sh 的樣式更新、jsc-hooks/hooks/simplified.txt 更新、三份 manifest 版本號提升、一條 PR;上游同版時無寫入跡象,只有回報內容 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:ste100-sync 的 skill-end 事件(兩條路徑都有,腳本不在時才沒有)、references/ste100.md 的「上游版本」行換值、tools/ste100-lint.sh 的樣式更新、jsc-hooks/hooks/simplified.txt 更新、三份 manifest 版本號提升、一條 PR;上游同版時除了那筆收尾事件沒有其他寫入跡象,只有回報內容 |
## tooling-guide ## tooling-guide
| 項目 | 內容 | | 項目 | 內容 |
| --- | --- | | --- | --- |
| 觸發時機 | 使用者要技能組導覽、工具地圖、支援的 plugin 清單、支援的技能清單、hook 管理概觀或新人上手參考時用。安裝、更新、刪除、稽核、修復都不走這支 | | 觸發時機 | 使用者要技能組導覽、工具地圖、支援的 plugin 清單、支援的技能清單、hook 管理概觀或新人上手參考時用。安裝、更新、刪除、稽核、修復都不走這支 |
| 關鍵步驟 | 跑 plugins-root.sh 確認工作根目錄、跑 sync-domains.sh 取得 domain 與本機路徑、跑 inventory-tooling.sh 產生基準盤點並同時蒐集管理流程事實、需要說明或分組時以 sub agent 綜整導覽草稿、主 agent 逐項核對每個說法的來源、依記錄下來的目標交付、目標是 wiki 頁時才以 sub agent 逐 CLI 算出頁名、先寫內容頁再登記目錄頁 | | 關鍵步驟 | 跑 plugins-root.sh 確認工作根目錄、跑 sync-domains.sh 取得 domain 與本機路徑、跑 inventory-tooling.sh 產生基準盤點並同時蒐集管理流程事實、需要說明或分組時以 sub agent 綜整導覽草稿、主 agent 逐項核對每個說法的來源、依記錄下來的目標交付、目標是 wiki 頁時才以 sub agent 逐 CLI 算出頁名、先寫內容頁再登記目錄頁、最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:tooling-guide 寫一筆收尾事件(五種 status 依本次實際結果選,交付目標是聊天回應的那一輪也要寫;腳本不在就安靜跳過,不影響本次結局) |
| 外部呼叫 | tools/plugins-root.sh、tools/sync-domains.sh、tools/inventory-tooling.sh、jsc-gitea/tools/hash-id、jsc-gitea:wiki、jsc-ask:ask | | 外部呼叫 | tools/plugins-root.sh、tools/sync-domains.sh、tools/inventory-tooling.sh、jsc-hooks/tools/report-status.sh skill-end、jsc-gitea/tools/hash-id、jsc-gitea:wiki、jsc-ask:ask |
| 完成條件 | 每項事實都指得到來源檔案或工具輸出、必填章節都不是空的、收尾回報寫明交付目標、來源新鮮度、過期輸入與未知的 hook 判定;目標是 wiki 時每一頁都確認寫成功,或列為未寫入並附完整內容 | | 完成條件 | 每項事實都指得到來源檔案或工具輸出、必填章節都不是空的、收尾回報寫明交付目標、來源新鮮度、過期輸入與未知的 hook 判定;目標是 wiki 時每一頁都確認寫成功,或列為未寫入並附完整內容;每一種交付目標都要寫下本次的 skill-end 事件,或據實記成腳本不在這台機器上 |
| 可驗證跡象 | 目標是聊天回應時無寫入跡象,只有回報內容;目標是檔案時只產生使用者指定的那一個檔;目標是 wiki 時每支偵測到的 CLI 各一頁 TOOLING_{HASH},並在 TOOLING_CONTENTS 更新自己那一列 | | 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:tooling-guide 的 skill-end 事件,那是這支唯讀技能唯一的寫入跡象;目標是聊天回應時除了那一行沒有其他寫入跡象,只有回報內容;目標是檔案時另外只產生使用者指定的那一個檔;目標是 wiki 時每支偵測到的 CLI 各一頁 TOOLING_{HASH},並在 TOOLING_CONTENTS 更新自己那一列 |
+40 -3
View File
@@ -114,21 +114,57 @@ PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-rep
| 節 | 每支技能一個 `## {技能名}` 節,名稱與 `skills/` 底下的目錄名逐字相同,節數與技能支數一樣,排列照目錄名的字典序 | | 節 | 每支技能一個 `## {技能名}` 節,名稱與 `skills/` 底下的目錄名逐字相同,節數與技能支數一樣,排列照目錄名的字典序 |
| 表格 | 每節恰好一張表,表頭兩欄依序是「項目」與「內容」,五列依序為 觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象,每一列的「內容」欄都不得空白 | | 表格 | 每節恰好一張表,表頭兩欄依序是「項目」與「內容」,五列依序為 觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象,每一列的「內容」欄都不得空白 |
| 寫什麼 | 寫技能實際的行為:什麼情況會用、什麼情況不該用、依序做了哪些事、呼叫哪些腳本與技能、做到什麼程度算跑完、跑完在環境裡留下哪些查得到的跡象。不要抄 `description` 的行銷語 | | 寫什麼 | 寫技能實際的行為:什麼情況會用、什麼情況不該用、依序做了哪些事、呼叫哪些腳本與技能、做到什麼程度算跑完、跑完在環境裡留下哪些查得到的跡象。不要抄 `description` 的行銷語 |
| 純唯讀的技能 | 「可驗證跡象」欄寫「無寫入跡象,只有回報內容」,不得留白 | | 純唯讀的技能 | 「可驗證跡象」欄寫「除了收尾的 `skill-end` 事件以外沒有寫入跡象,只有回報內容」,不得留白。收尾事件是每支技能都有的那一筆,唯讀技能也不例外 |
| 更新時機 | 技能異動時在**同一個 PR 內**一起更新:新增技能就加一節、刪除就移除該節、改行為就改該節 | | 更新時機 | 技能異動時在**同一個 PR 內**一起更新:新增技能就加一節、刪除就移除該節、改行為就改該節 |
| 收尾事件 | 「可驗證跡象」那一列要寫到收尾的 `skill-end` 事件或 `events.jsonl`,規則見「執行狀態回報」一節 |
| 檢查腳本 | `jsc-meta/tools/check-behaviors.sh {domain-path}` | | 檢查腳本 | `jsc-meta/tools/check-behaviors.sh {domain-path}` |
`check-behaviors.sh` 的結束碼分流: `check-behaviors.sh` 的結束碼分流:
| 結束碼 | 意義 | | 結束碼 | 意義 |
| --- | --- | | --- | --- |
| 0 | 行為清單與 `skills/` 相符,五個欄位齊全且內容欄非空 | | 0 | 行為清單與 `skills/` 相符,五個欄位齊全、內容欄非空,且每一節的「可驗證跡象」都寫了收尾的 `skill-end` 事件 |
| 1 | 不符:缺節、多節、順序不對、表格不對、缺欄位或欄位空白,逐項印在 stderr,照著修再重跑 | | 1 | 不符:缺節、多節、順序不對、表格不對、缺欄位、欄位空白,或「可驗證跡象」沒寫到收尾的 `skill-end` 事件,逐項印在 stderr,照著修再重跑 |
| 2 | 用法錯誤:本腳本只吃一個參數 | | 2 | 用法錯誤:本腳本只吃一個參數 |
| 3 | 找不到 `references/behaviors.md`、找不到 `skills/`,或 `skills/` 底下一支 `SKILL.md` 都沒有。**什麼都沒查,不等於通過**,先補齊檔案再重跑 | | 3 | 找不到 `references/behaviors.md`、找不到 `skills/`,或 `skills/` 底下一支 `SKILL.md` 都沒有。**什麼都沒查,不等於通過**,先補齊檔案再重跑 |
**為什麼一個 domain 一份,不集中在 `jsc-meta`。** 技能改動與行為清單放同一個存取庫,才進得了同一個 PR;審的人在一頁 diff 上就看得出行為改了、清單也改了。集中在 meta 的話,改一支技能要開兩條 PR,一條在 domain、一條在 meta,兩條互相等待,先併的那條讓清單與技能對不上,稽核抓到的是自己造出來的漂移。跨存取庫的東西沒有原子性,同一份事實就不要拆兩邊放。 **為什麼一個 domain 一份,不集中在 `jsc-meta`。** 技能改動與行為清單放同一個存取庫,才進得了同一個 PR;審的人在一頁 diff 上就看得出行為改了、清單也改了。集中在 meta 的話,改一支技能要開兩條 PR,一條在 domain、一條在 meta,兩條互相等待,先併的那條讓清單與技能對不上,稽核抓到的是自己造出來的漂移。跨存取庫的東西沒有原子性,同一份事實就不要拆兩邊放。
## 執行狀態回報
技能與 hook 每跑一次都要在本機事件流留下結果,助理巡檢再排空、彙整、寫監控頁。
事件流是 `$JSC_HOME/usage/events.jsonl`,一次一行,只增不改。
| 項目 | 規則 |
| --- | --- |
| 誰寫 `start` | `jsc-hooks/hooks/skill-usage.sh`。技能被叫用的當下就寫,SKILL.md 一個字都不必改 |
| 誰寫 `end` | **技能自己在收尾步驟寫**,一次執行一筆 |
| 怎麼寫 | `{jsc-hooks 路徑}/tools/report-status.sh skill-end jsc-{domain}:{技能名} {status} {結束碼} [detail]` |
| 路徑怎麼解 | 沿用該技能原本呼叫別的 plugin 腳本的那一套,不另外發明一種 |
| 找不到腳本 | 安靜跳過,照常收尾。回報機制不在場,不可以讓被回報的技能跟著失敗 |
| 回報自己失敗 | 一樣吞掉。這支腳本的三個記錄子命令一律回 0,呼叫端不得因為它的結束碼改變自己的結局 |
| `detail` | 選填,單行,最多 200 字。長內容另存別處,不要塞進這一行 |
| 寫進行為清單 | 該技能在 `references/behaviors.md` 的「關鍵步驟」「完成條件」「可驗證跡象」三列都要提到這一筆事件 |
| 檢查腳本 | `jsc-meta/tools/check-behaviors.sh {domain-path}` 斷言「可驗證跡象」那一列寫到 `skill-end` 或 `events.jsonl` |
`status` 五選一,SKILL.md 要逐項寫清楚這支技能什麼情況選哪一個:
| status | 什麼時候用 |
| --- | --- |
| `ok` | 完成條件全部達成 |
| `blocked` | 被閘門或前置條件擋下,沒有做事。例如版本前置檢查擋下、相依 PR 未合併 |
| `failed` | 做到一半失敗。例如 API 回非預期狀態、寫入失敗 |
| `degraded` | 做完了但有部分沒達成。例如內容頁寫成功、目錄頁沒更新 |
| `aborted` | 使用者中止,或前提不成立而主動停止 |
**`end` 為什麼不能由 hook 代勞。** hook 接在技能工具呼叫之後就觸發,那一刻技能的實際工作
還在後面的模型輪次,成敗根本還沒發生。hook 在原理上看不到結果,寫得出來的只有「開始跑了」。
所以 `start` 是免費的,`end` 躲不掉要由技能自己寫。
**有 `start` 沒有配對的 `end`,就是中止。** 這正是這條規則要補的洞:現行紀錄只記「被叫用」,
跑完整輪的技能與開場就停的技能長得一模一樣。收尾少寫這一筆,那支技能每一次都會被算成中止,
而且不會有任何錯誤訊息——助理讀到的是一串沒有結局的技能,看起來像整組技能都在半路死掉。
## 環境變數 ## 環境變數
| 變數 | 用途 | 未設定時 | | 變數 | 用途 | 未設定時 |
@@ -458,6 +494,7 @@ kiro 是唯一真的擋不了的,verdict 據實寫 `degraded`,不寫 `wired`
- [ ] SKILL.md 整份為英文(要原樣輸出的繁中字面除外);README、AGENTS、templates、references 為 STE100 繁中;UTF-8 無亂碼 - [ ] SKILL.md 整份為英文(要原樣輸出的繁中字面除外);README、AGENTS、templates、references 為 STE100 繁中;UTF-8 無亂碼
- [ ] 所有非程式碼輸出(程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件)為繁體中文、UTF-8、無亂碼、無簡體字,且 `tools/ste100-lint.sh` 對該 domain 全綠 - [ ] 所有非程式碼輸出(程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件)為繁體中文、UTF-8、無亂碼、無簡體字,且 `tools/ste100-lint.sh` 對該 domain 全綠
- [ ] 該 domain 的 `references/behaviors.md` 與 `skills/` 相符,`tools/check-behaviors.sh {domain-path}` 對該 domain 退出 0;退出 3 是「什麼都沒查」,不算通過 - [ ] 該 domain 的 `references/behaviors.md` 與 `skills/` 相符,`tools/check-behaviors.sh {domain-path}` 對該 domain 退出 0;退出 3 是「什麼都沒查」,不算通過
- [ ] 每支技能的收尾步驟都呼叫 `{jsc-hooks 路徑}/tools/report-status.sh skill-end jsc-{domain}:{技能名} {status} {結束碼}`,`status` 五選一且 SKILL.md 寫明哪一種情況選哪一個,找不到腳本安靜跳過、不讓技能跟著失敗;該技能的「關鍵步驟」「完成條件」「可驗證跡象」三列都寫到這一筆事件。規則見「執行狀態回報」
- [ ] 該 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析得動,`tools/lint-frontmatter.sh {domain-path}` 對該 domain 退出 0;退出 3 是「什麼都沒掃」,不算通過。frontmatter 有語法錯誤時,Antigravity 會**靜默丟棄整支技能**,沒有任何錯誤訊息,只有這支腳本抓得到 - [ ] 該 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析得動,`tools/lint-frontmatter.sh {domain-path}` 對該 domain 退出 0;退出 3 是「什麼都沒掃」,不算通過。frontmatter 有語法錯誤時,Antigravity 會**靜默丟棄整支技能**,沒有任何錯誤訊息,只有這支腳本抓得到
- [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version
- [ ] PR 的 base 符合「PR 分支階梯」,沒有越級 - [ ] PR 的 base 符合「PR 分支階梯」,沒有越級
+21
View File
@@ -130,3 +130,24 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
- **On a failed write.** Retry once. Still failing, hand the user the page name and the full section that was not written, so the round's result is not lost. **Never close the run reporting a page as written when it was not**, and never close it silently with the content only in the transcript. - **On a failed write.** Retry once. Still failing, hand the user the page name and the full section that was not written, so the round's result is not lost. **Never close the run reporting a page as written when it was not**, and never close it silently with the content only in the transcript.
Completion condition: every changed domain repo has one new section on its `SKILLSET_{HASH}` and one row in `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, or — where nothing changed — the `plugins/meta` page carries the 「本輪無發現」 section and its row on the same terms; every content-page write is confirmed by a successful read-back or reported as not written with its full content handed back. Completion condition: every changed domain repo has one new section on its `SKILLSET_{HASH}` and one row in `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, or — where nothing changed — the `plugins/meta` page carries the 「本輪無發現」 section and its row on the same terms; every content-page write is confirmed by a successful read-back or reported as not written with its full content handed back.
9. Report this round's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-check {status} {exit code} [detail]`
Resolve `jsc-hooks` from the `domain<TAB>path` row step 1 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script. **When that script is not on this machine, skip this step in silence and close the round as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the round actually did:
| status | Use it when |
| --- | --- |
| `ok` | every domain ended with a complete checklist, every accepted fix passed its re-check, every affected repo has a PR URL, and every wiki write exited 0 |
| `blocked` | a gate or a missing prerequisite stopped the round before anything was audited — `sync-domains.sh` never reached exit 0, or the call itself was refused |
| `failed` | the round broke mid-way — a re-check in step 6 kept failing, or a wiki write failed again after its one retry |
| `degraded` | the round finished with a part missing — a domain carries 「本輪未取得已決議清單,優化建議暫不提出」, or a content page was written while its `SKILLSET_CONTENTS` row was not |
| `aborted` | the user stopped the round, or a prerequisite turned out not to hold and this skill stopped on its own |
`{exit code}` is this round's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The audit itself happens in the model turns after that, so no hook can see how the round ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job.
Completion condition: one `skill-end` line for this round is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
+21
View File
@@ -69,3 +69,24 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
| | 8 | Some other API failure. Stop, report that status, and create no page | | | 8 | Some other API failure. Stop, report that status, and create no page |
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL. On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL.
9. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-delete {status} {exit code} [detail]`
Resolve `jsc-hooks` from the `domain<TAB>path` row step 1 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script. **When that script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the run actually did:
| status | Use it when |
| --- | --- |
| `ok` | the skill directory and its behavior-list section are gone, the PR is open, `deploy-verify.md` sections 1 to 5 hold, `verify-skill-removed.sh` exited 0, and both wiki writes exited 0 |
| `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or no skill could be listed to pick from |
| `failed` | the run broke mid-way — a leftover from `verify-skill-removed.sh` exit 1 could not be removed, or a wiki write failed again after its one retry |
| `degraded` | the deletion landed with a part missing — the deep-delete check came back 「無處可查」, or the content page was written while its `SKILLSET_CONTENTS` row was not |
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The deletion itself happens in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job.
Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
+21
View File
@@ -78,3 +78,24 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
| | 8 | Some other API failure. Stop, report that status, and create no page | | | 8 | Some other API failure. Stop, report that status, and create no page |
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL. On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL.
7. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-new {status} {exit code} [detail]`
Resolve `jsc-hooks` from the `domain<TAB>path` row step 1.1 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script. **When that script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the run actually did:
| status | Use it when |
| --- | --- |
| `ok` | the new `SKILL.md` and its behavior-list section are in place, the checklist passes, the PR is open, `deploy-verify.md` sections 1 to 5 hold, and both wiki writes exited 0 |
| `blocked` | a gate or a missing prerequisite stopped the run before any file was created — `sync-domains.sh` never reached exit 0, or Gitea refused the repository creation and nobody created it by hand |
| `failed` | the run broke mid-way — `sync-marketplace.sh` or `sync-skill-manifest.sh` kept failing, or a wiki write failed again after its one retry |
| `degraded` | the skill landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` row was not, or a CLI could not be verified and the reason was recorded |
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The creation itself happens in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job.
Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
+21
View File
@@ -53,3 +53,24 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
| | 8 | Some other API failure. Stop, report that status, and create no page | | | 8 | Some other API failure. Stop, report that status, and create no page |
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL. On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL.
9. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-update {status} {exit code} [detail]`
Resolve `jsc-hooks` from the `domain<TAB>path` row step 1 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script. **When that script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the run actually did:
| status | Use it when |
| --- | --- |
| `ok` | the skill files and the behavior-list section carry the change, the checklist passes, the PR is open, `deploy-verify.md` sections 1 to 5 hold, and both wiki writes exited 0 |
| `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or no skill could be listed to pick from |
| `failed` | the run broke mid-way — the step 6 checklist loop kept failing, or a wiki write failed again after its one retry |
| `degraded` | the update landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` row was not, or a CLI could not be verified and the reason was recorded |
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The update itself happens in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job.
Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
+21
View File
@@ -54,3 +54,24 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
| | 8 | Some other API failure. Stop, report that status, and create no page | | | 8 | Some other API failure. Stop, report that status, and create no page |
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: every affected repo's `SKILLSET_{HASH}` holds the new section plus all earlier sections, and every one of those repos has a row on `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, linking its page by absolute URL. On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: every affected repo's `SKILLSET_{HASH}` holds the new section plus all earlier sections, and every one of those repos has a row on `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, linking its page by absolute URL.
6. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. One event for the whole batch, not one per domain. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skillset-update {status} {exit code} [detail]`
Resolve `jsc-hooks` from the `domain<TAB>path` row step 1.1 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script. **When that script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the run actually did:
| status | Use it when |
| --- | --- |
| `ok` | every affected repo carries the change and its behavior-list update, every checklist passes, every repo has a PR URL, `deploy-verify.md` sections 1 to 5 hold for all of them, and every wiki write exited 0 |
| `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or the affected-skill list was never agreed |
| `failed` | the run broke mid-way — the step 3 checklist loop kept failing for some repo, or a wiki write failed again after its one retry |
| `degraded` | part of the batch landed and part did not — some repos got their PR and others did not, or a content page was written while its `SKILLSET_CONTENTS` row was not. Name the repos in `detail` |
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The batch itself happens in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job.
Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
+21
View File
@@ -27,6 +27,27 @@ Keep `references/ste100.md` in sync with its upstream source, [speak-human-tw](h
7. Run `tools/ste100-lint.sh` over every jsc repo (`tools/sync-domains.sh` prints the repo paths). The repos are independent, so lint them **in parallel**, one run per repo. Route each exit code: 0 — that repo is clean; 1 — hits printed as `{檔案}:{行號}:{類別}:{命中內容}`; 2 — no target was given, so fix the arguments and rerun, never read it as clean. Fix hits in files this repo owns. Completion condition: the lint exits 0 for this repo, and hits in other repos are reported with `file:line` for their owners. 7. Run `tools/ste100-lint.sh` over every jsc repo (`tools/sync-domains.sh` prints the repo paths). The repos are independent, so lint them **in parallel**, one run per repo. Route each exit code: 0 — that repo is clean; 1 — hits printed as `{檔案}:{行號}:{類別}:{命中內容}`; 2 — no target was given, so fix the arguments and rerun, never read it as clean. Fix hits in files this repo owns. Completion condition: the lint exits 0 for this repo, and hits in other repos are reported with `file:line` for their owners.
8. Run `tools/sync-skill-manifest.sh .` to sync the README's 「Skills 目錄」 section and bump the manifests. Route each exit code: 0 — the README block and all three manifests are synced; 1 — `skills/`, `README.md`, the `JSC-SKILLS` markers, a `SKILL.md`, a manifest, or a manifest `version` field is missing, so fix the named cause on stderr and rerun; 2 — usage error, the script takes exactly one argument; any other code — the script runs under `set -e`, so treat it as an environment fault and stop, never as a successful sync. Completion condition: all three manifests show the same new version. 8. Run `tools/sync-skill-manifest.sh .` to sync the README's 「Skills 目錄」 section and bump the manifests. Route each exit code: 0 — the README block and all three manifests are synced; 1 — `skills/`, `README.md`, the `JSC-SKILLS` markers, a `SKILL.md`, a manifest, or a manifest `version` field is missing, so fix the named cause on stderr and rerun; 2 — usage error, the script takes exactly one argument; any other code — the script runs under `set -e`, so treat it as an environment fault and stop, never as a successful sync. Completion condition: all three manifests show the same new version.
9. Open a PR via `jsc-git:pr`. Completion condition: a PR URL comes back and is reported with the table format in [`../../references/pr-report.md`](../../references/pr-report.md). 9. Open a PR via `jsc-git:pr`. Completion condition: a PR URL comes back and is reported with the table format in [`../../references/pr-report.md`](../../references/pr-report.md).
10. Report this run's outcome to the local event stream — the last step of every run, **the step 1.3 early stop included**. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:ste100-sync {status} {exit code} [detail]`
Resolve `jsc-hooks` the same way step 6 resolves `jsc-hooks/hooks/simplified.txt`: the sibling checkout in the workspace. On the step 1.3 early stop, where `tools/sync-domains.sh` has not run, that sibling path is the only source. **When the script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the run actually did:
| status | Use it when |
| --- | --- |
| `ok` | upstream had a new version and every adopted change is in `references/ste100.md`, the lint runs clean here, the manifests are bumped and the PR is open — **and also when step 1.3 stopped the run on 「上游沒有新版」**, because that is this skill's normal ending, not an abort |
| `blocked` | a gate or a missing prerequisite stopped the run before any comparison — the call itself was refused, or neither the raw read nor the clone could reach upstream, so no version could be compared |
| `failed` | the run broke mid-way — `sh -n tools/ste100-lint.sh` kept failing after the pattern edit, or `sync-skill-manifest.sh` could not be resolved |
| `degraded` | the sync landed with a part missing — this repo lints clean but hits in other repos were only handed to their owners, or a simplified-character change reached the lint and not `jsc-hooks/hooks/simplified.txt` |
| `aborted` | the user stopped the run, or the user dropped every distilled change so nothing was left to apply |
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The comparison and the sync happen in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job, and why the 「上游沒有新版」 path must write one too.
Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
## Notes ## Notes
+23
View File
@@ -19,6 +19,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
- Put generated guide text in the response or in the user-requested target only. - Put generated guide text in the response or in the user-requested target only.
- Run detail synthesis as a sub agent when the guide needs explanations, grouping, or onboarding prose. - Run detail synthesis as a sub agent when the guide needs explanations, grouping, or onboarding prose.
- Route every wiki read and write through `jsc-gitea:wiki`, and every `{HASH}` through `jsc-gitea/tools/hash-id`. - Route every wiki read and write through `jsc-gitea:wiki`, and every `{HASH}` through `jsc-gitea/tools/hash-id`.
- Close every run with the step 8 `skill-end` event. That one line in `$JSC_HOME/usage/events.jsonl` is the only thing this skill writes outside the recorded output target, and the rule above about not modifying files does not cover it.
Done when each rule above has a recorded pass, or a recorded exception naming the claim and the reason, checked before the final report. Done when each rule above has a recorded pass, or a recorded exception naming the claim and the reason, checked before the final report.
@@ -98,6 +99,28 @@ Done when the scope and the output target are each written down as one of the va
7.5 **Route a failed write.** Retry the failed `jsc-gitea:wiki` write once. When it fails again, stop the publish and report the page name together with the content that never reached the wiki, so the user can place it by hand. Report a page as written only after its write returned exit 0. Completion condition: every page named in this step is either confirmed written with its page name, or listed as unwritten with its exit code and its full content. 7.5 **Route a failed write.** Retry the failed `jsc-gitea:wiki` write once. When it fails again, stop the publish and report the page name together with the content that never reached the wiki, so the user can place it by hand. Report a page as written only after its write returned exit 0. Completion condition: every page named in this step is either confirmed written with its page name, or listed as unwritten with its exit code and its full content.
8. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included, and the ones whose target was the chat response. Run:
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:tooling-guide {status} {exit code} [detail]`
Resolve `jsc-hooks` from the `domain<TAB>path` row step 2 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script; when step 2 never produced rows, take the sibling checkout under the root step 1 printed. **When the script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.
Pick `{status}` from what the run actually did:
| status | Use it when |
| --- | --- |
| `ok` | the guide holds every required section with a source behind each claim, it reached the recorded target, and — for the wiki target — every page write and the `TOOLING_CONTENTS` registration returned exit 0 |
| `blocked` | a gate or a missing prerequisite stopped the run before any inventory was built — `tools/plugins-root.sh` exited 1, or `sync-domains.sh` exited 2 or 1 |
| `failed` | the run broke mid-way — `inventory-tooling.sh` exited non-zero, or a wiki write failed again after its one retry |
| `degraded` | the guide was delivered with a part missing — stale rows were accepted from `sync-domains.sh` exit 3, a hook verdict stayed unknown, or the content pages were written while `TOOLING_CONTENTS` was not |
| `aborted` | the user stopped the run, or the user refused a guide built on stale input so this skill stopped on its own |
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
The matching `skill-start` comes free from the hook, which fires when the skill loads. The inventory and the delivery happen in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job. This is the one write a read-only skill still makes.
Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.
## Notes ## Notes
- **Removed protection, on purpose.** The flow used to carry three more steps that re-ran `list-skills.sh`, `detect-clis.sh` and `wire-cli.sh status {cli}` after `inventory-tooling.sh` had already called all three. That second pass doubled as an independent cross-check: it read the same three facts straight from the source scripts, so a wrong skill row, a missing CLI, or a stale hook verdict produced by `inventory-tooling.sh` surfaced as a disagreement between the two sets. That cross-check is gone. The guide now takes the skill catalog, the CLI list and the hook wiring status from one `inventory-tooling.sh` run, with no second raw output to compare against, so a bug in that script's own scanning, parsing, or section writing reaches the guide unnoticed and reads as fact. Two things bound the risk: step 5 still rejects any claim with no source section behind it, and `Hook wiring status` carries the per-CLI exit code, so a nonsense verdict stays visible. When a decision rests on the guide's skill, CLI, or hook facts, get the second opinion elsewhere — run the three scripts by hand and compare, or run `jsc-cli:doctor` for an independent wiring verdict. - **Removed protection, on purpose.** The flow used to carry three more steps that re-ran `list-skills.sh`, `detect-clis.sh` and `wire-cli.sh status {cli}` after `inventory-tooling.sh` had already called all three. That second pass doubled as an independent cross-check: it read the same three facts straight from the source scripts, so a wrong skill row, a missing CLI, or a stale hook verdict produced by `inventory-tooling.sh` surfaced as a disagreement between the two sets. That cross-check is gone. The guide now takes the skill catalog, the CLI list and the hook wiring status from one `inventory-tooling.sh` run, with no second raw output to compare against, so a bug in that script's own scanning, parsing, or section writing reaches the guide unnoticed and reads as fact. Two things bound the risk: step 5 still rejects any claim with no source section behind it, and `Hook wiring status` carries the per-CLI exit code, so a nonsense verdict stays visible. When a decision rests on the guide's skill, CLI, or hook facts, get the second opinion elsewhere — run the three scripts by hand and compare, or run `jsc-cli:doctor` for an independent wiring verdict.
+22 -5
View File
@@ -3,21 +3,30 @@
# #
# 用法: check-behaviors.sh <domain-path> # 用法: check-behaviors.sh <domain-path>
# #
# 檢查六項(格式合約見 jsc-meta references/guidelines.md 的「技能行為清單」一節): # 檢查七項(格式合約見 jsc-meta references/guidelines.md 的「技能行為清單」一節):
# 1. 標題 — 第一行是「# jsc-{domain} 技能行為清單」,檔案不得有 UTF-8 BOM。 # 1. 標題 — 第一行是「# jsc-{domain} 技能行為清單」,檔案不得有 UTF-8 BOM。
# 2. 節對技能 — 每支 skills/*/SKILL.md 一個「## {技能名}」節,名稱與目錄名逐字相同,不多不少。 # 2. 節對技能 — 每支 skills/*/SKILL.md 一個「## {技能名}」節,名稱與目錄名逐字相同,不多不少。
# 3. 節順序 — 節的排列照技能目錄名的字典序(LC_ALL=C)。 # 3. 節順序 — 節的排列照技能目錄名的字典序(LC_ALL=C)。
# 4. 表格 — 每節恰好一張表,表頭是「| 項目 | 內容 |」。 # 4. 表格 — 每節恰好一張表,表頭是「| 項目 | 內容 |」。
# 5. 五個欄位 — 依序為 觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象,不多不少。 # 5. 五個欄位 — 依序為 觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象,不多不少。
# 6. 內容 — 每一列的「內容」欄不得空白。 # 6. 內容 — 每一列的「內容」欄不得空白。
# 7. 收尾事件 — 「可驗證跡象」那一列要寫到 skill-end 或 events.jsonl。
# #
# 為什麼要這支: 技能改了行為、清單沒跟著改,兩邊就漂移。漂移靠眼睛比對,10 個 domain 每次稽核 # 為什麼要這支: 技能改了行為、清單沒跟著改,兩邊就漂移。漂移靠眼睛比對,10 個 domain 每次稽核
# 都要重做一遍,還會漏。這六項的輸入輸出固定,交給程式判定才穩。 # 都要重做一遍,還會漏。這七項的輸入輸出固定,交給程式判定才穩。
#
# 為什麼加第 7 項: 技能的成敗只有技能自己寫得出來。hook 接在技能工具呼叫之後就觸發,那一刻
# 實際工作還在後面的模型輪次,看不到結果;有 start 沒有配對的 end 就是中止。收尾少寫這一筆,
# 那支技能每一次都會被算成中止,而且不會有任何錯誤訊息。跡象欄是清單裡唯一寫得下「跑完在
# 環境裡留下什麼」的地方,所以判準放在這一列,而不是另開一項只檢查文字。
# 本腳本是所有 domain 共用的稽核入口,這一項加進來之後,還沒補收尾事件的 domain 會開始回 1。
# 那是預期的結果,不是誤報:要修的是那些 domain 的技能與清單,不是把斷言放寬。
# #
# 輸出: 一行一個不合格項目,格式 {behaviors.md 路徑}:{技能名或 -}:{說明}(stderr); # 輸出: 一行一個不合格項目,格式 {behaviors.md 路徑}:{技能名或 -}:{說明}(stderr);
# 通過時在 stderr 印一行摘要。stdout 不印東西。 # 通過時在 stderr 印一行摘要。stdout 不印東西。
# 結束碼: 0=行為清單與 skills/ 相符,五個欄位齊全且內容欄非空 # 結束碼: 0=行為清單與 skills/ 相符,五個欄位齊全、內容欄非空,且每節都寫了收尾事件
# 1=不符:缺節、多節、順序不對、表格不對、缺欄位或欄位空白,清單在 stderr # 1=不符:缺節、多節、順序不對、表格不對、缺欄位、欄位空白,或跡象欄沒寫收尾事件,
# 清單在 stderr
# 2=用法錯誤(本腳本只吃一個參數) # 2=用法錯誤(本腳本只吃一個參數)
# 3=找不到 {domain-path}/references/behaviors.md,或找不到 {domain-path}/skills/, # 3=找不到 {domain-path}/references/behaviors.md,或找不到 {domain-path}/skills/,
# 或 skills/ 底下一支 SKILL.md 都沒有——**什麼都沒查**,不等於通過 # 或 skills/ 底下一支 SKILL.md 都沒有——**什麼都沒查**,不等於通過
@@ -155,6 +164,14 @@ while IFS= read -r name; do
want=$(echo "$FIELDS" | cut -d' ' -f"$i") want=$(echo "$FIELDS" | cut -d' ' -f"$i")
[ "$item" = "$want" ] || report "$name" "第 $i 列的項目要是「$want」,實際是「$item」" [ "$item" = "$want" ] || report "$name" "第 $i 列的項目要是「$want」,實際是「$item」"
[ -n "$body" ] || report "$name" "「$item」的內容欄空白,請補實際行為" [ -n "$body" ] || report "$name" "「$item」的內容欄空白,請補實際行為"
# 第 7 項只在跡象欄成立。認項目名不認列號: 列號錯位時上面那一行已經報過,
# 這裡再報一次只是同一個缺陷印兩遍,反而蓋掉真正沒寫收尾事件的那幾節。
if [ "$item" = '可驗證跡象' ]; then
case $body in
*skill-end*|*events.jsonl*) ;;
*) report "$name" '「可驗證跡象」沒寫到收尾的 skill-end 事件,請補上這一筆(見準則「執行狀態回報」)' ;;
esac
fi
done < "$TMPD/rows.txt" done < "$TMPD/rows.txt"
done < "$TMPD/skills.txt" done < "$TMPD/skills.txt"
@@ -164,7 +181,7 @@ if awk -F"$TAB" '$2 == "-" { found = 1 } END { exit found ? 0 : 1 }' "$TMPD/pars
fi fi
if [ "$fail" -eq 0 ]; then if [ "$fail" -eq 0 ]; then
echo "行為清單檢查通過:$DOC 對上 $(wc -l < "$TMPD/skills.txt" | tr -d ' ') 支技能,五個欄位齊全" >&2 echo "行為清單檢查通過:$DOC 對上 $(wc -l < "$TMPD/skills.txt" | tr -d ' ') 支技能,五個欄位齊全,跡象欄都寫了收尾事件" >&2
else else
echo "行為清單檢查不符:$DOC 與 $SKILLS 對不起來,逐項見上方" >&2 echo "行為清單檢查不符:$DOC 與 $SKILLS 對不起來,逐項見上方" >&2
fi fi