feat/cli-doctor-and-setup-skills #13

2026-08-26T02:46:53Z

jiantw83 commented

2026-08-26 02:46:53 +00:00

摘要

需求描述：新增兩支技能。一支體檢執行環境（技能版本、Hook 接線、全域設定、自我設定），另一支引導或自動修復體檢找出的問題。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`skills/doctor/SKILL.md`	新增體檢技能：四項檢查各出一張表，只讀不改，結果寫進 wiki `CHECK_{HASH}`
`skills/setup/SKILL.md`	新增設定技能：讀待修清單逐項確認後修復，依修法分流 auto、ask、manual
`tools/config-spec.tsv`	設定規格表。哪些設定必要、哪些選擇，判準集中在這一份，體檢與修復共用
`tools/scan-config.sh`	依規格表盤點設定現況，唯讀。另有 `orphans` 找出原始碼用到卻沒登錄的變數
`tools/apply-config.sh`	把設定寫進 rc 檔的 `# jsc-config` 標記段落或建立目錄，寫前備份、寫後驗證
`templates/check-page.md`	體檢頁 `CHECK_{HASH}` 版面：四張檢查表加一張待修表
`templates/check-contents.md`	體檢目錄 `CHECK_CONTENTS` 版面
`README.md`、三份 manifest	同步工具表、Skills 目錄、環境變數表與版本

設計重點

體檢與修復分成兩支技能。doctor 只讀不寫，setup 才動環境。合成一支會讓「我只是想看看」變成有副作用的操作。
必要性的判準是手寫規格表，不是掃描結果。掃描分不出必要與選擇，也分不出 JSC_SCRIPT_DIR 這種執行期內部變數。規格表登錄全部項目（含 internal），掃描只負責回報漏登錄的，兩邊互相補位。
接線判讀留在 jsc-hooks。doctor 不自己讀各 CLI 的設定檔，改用新加的 wire-cli.sh status。分兩份實作會各自漂移，體檢說沒接、實際上接著。
憑證不進報告。帶 TOKEN 的項目只印 set 或 unset。體檢結果會寫進 wiki。
查不到不等於通過。離線時 Gitea 相關檢查標 skipped，報告寫「未取得結論」；沒有 plugin 註冊檔的 CLI 標「無法驗證」，不併進「最新」。
wiki 寫不了也不算體檢失敗。JSC_WIKI_REPO_CHECK 沒設定時照樣印出報表，並把這個變數列進待修第一項。
apply-config.sh 只重寫自己的標記段落，段落外一律不動；每次寫入前把動到的 rc 檔備份到 $JSC_HOME/backup/config/{時間戳}/，備份失敗就不寫。

測試結果

sh -n 通過：scan-config.sh、apply-config.sh。
scan-config.sh -o scan all：44 項全部走完，summary 印出 missing 1、invalid 0、unset 23、skipped 2，與這台機器的實際狀態相符。
scan-config.sh scan global（連線）：GITEA_HOST 與 GITEA_TOKEN 驗證通過，token 值未出現在輸出中。
scan-config.sh orphans：無輸出，代表原始碼用到的變數都已登錄。
apply-config.sh：以假家目錄實測 set 兩次、unset 一次、mkdir 兩種路徑寫法（$JSC_HOME/plugins 與 ~/.jsc/x）。第二次 set 保留第一個變數，fish 寫成 set -gx、bash 寫成 export，備份目錄與內容都建立成功。
jsc-meta/tools/ste100-lint.sh：無違規。

前置 Push Request

plugins/hooks PR #21：doctor 的 Hook 檢查直接呼叫 wire-cli.sh status，那個子命令在這個 PR 裡。
plugins/gitea PR #20：體檢結果寫進 CHECK_{HASH}，需要 gitea.sh 放行 CHECK 類型。

## 摘要 - 需求描述：新增兩支技能。一支體檢執行環境（技能版本、Hook 接線、全域設定、自我設定），另一支引導或自動修復體檢找出的問題。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/doctor/SKILL.md` | 新增體檢技能：四項檢查各出一張表，只讀不改，結果寫進 wiki `CHECK_{HASH}` | | `skills/setup/SKILL.md` | 新增設定技能：讀待修清單逐項確認後修復，依修法分流 auto、ask、manual | | `tools/config-spec.tsv` | 設定規格表。哪些設定必要、哪些選擇，判準集中在這一份，體檢與修復共用 | | `tools/scan-config.sh` | 依規格表盤點設定現況，唯讀。另有 `orphans` 找出原始碼用到卻沒登錄的變數 | | `tools/apply-config.sh` | 把設定寫進 rc 檔的 `# jsc-config` 標記段落或建立目錄，寫前備份、寫後驗證 | | `templates/check-page.md` | 體檢頁 `CHECK_{HASH}` 版面：四張檢查表加一張待修表 | | `templates/check-contents.md` | 體檢目錄 `CHECK_CONTENTS` 版面 | | `README.md`、三份 manifest | 同步工具表、Skills 目錄、環境變數表與版本 | ## 設計重點 - **體檢與修復分成兩支技能**。doctor 只讀不寫，setup 才動環境。合成一支會讓「我只是想看看」變成有副作用的操作。 - **必要性的判準是手寫規格表，不是掃描結果**。掃描分不出必要與選擇，也分不出 `JSC_SCRIPT_DIR` 這種執行期內部變數。規格表登錄全部項目（含 internal），掃描只負責回報漏登錄的，兩邊互相補位。 - **接線判讀留在 jsc-hooks**。doctor 不自己讀各 CLI 的設定檔，改用新加的 `wire-cli.sh status`。分兩份實作會各自漂移，體檢說沒接、實際上接著。 - **憑證不進報告**。帶 `TOKEN` 的項目只印 `set` 或 `unset`。體檢結果會寫進 wiki。 - **查不到不等於通過**。離線時 Gitea 相關檢查標 `skipped`，報告寫「未取得結論」；沒有 plugin 註冊檔的 CLI 標「無法驗證」，不併進「最新」。 - **wiki 寫不了也不算體檢失敗**。`JSC_WIKI_REPO_CHECK` 沒設定時照樣印出報表，並把這個變數列進待修第一項。 - `apply-config.sh` 只重寫自己的標記段落，段落外一律不動；每次寫入前把動到的 rc 檔備份到 `$JSC_HOME/backup/config/{時間戳}/`，備份失敗就不寫。 ## 測試結果 - `sh -n` 通過：`scan-config.sh`、`apply-config.sh`。 - `scan-config.sh -o scan all`：44 項全部走完，`summary` 印出 missing 1、invalid 0、unset 23、skipped 2，與這台機器的實際狀態相符。 - `scan-config.sh scan global`（連線）：`GITEA_HOST` 與 `GITEA_TOKEN` 驗證通過，token 值未出現在輸出中。 - `scan-config.sh orphans`：無輸出，代表原始碼用到的變數都已登錄。 - `apply-config.sh`：以假家目錄實測 `set` 兩次、`unset` 一次、`mkdir` 兩種路徑寫法（`$JSC_HOME/plugins` 與 `~/.jsc/x`）。第二次 set 保留第一個變數，fish 寫成 `set -gx`、bash 寫成 `export`，備份目錄與內容都建立成功。 - `jsc-meta/tools/ste100-lint.sh`：無違規。 ## 前置 Push Request - [plugins/hooks PR #21](https://gitea.jsc.idv.tw/plugins/hooks/pulls/21)：doctor 的 Hook 檢查直接呼叫 `wire-cli.sh status`，那個子命令在這個 PR 裡。 - [plugins/gitea PR #20](https://gitea.jsc.idv.tw/plugins/gitea/pulls/20)：體檢結果寫進 `CHECK_{HASH}`，需要 `gitea.sh` 放行 CHECK 類型。

jiantw83 added 2 commits 2026-08-26 02:46:54 +00:00

feat(doctor): 新增執行環境體檢技能 2adf9a172e

What: 新增 jsc-cli:doctor，一次體檢技能版本、Hook 接線、全域設定與自我設定，只讀不改，結果寫進 wiki CHECK_{HASH}。
Why: 安裝或更新技能組之後，沒有任何工具說得出這台機器還缺什麼。設定散在環境變數、rc 檔與專案目錄，出錯時只能一個一個猜。
How: 版本比對複用 jsc-hooks 的 version-guard.sh report，接線狀態複用新加的 wire-cli.sh status（唯讀），設定則由 tools/scan-config.sh 比對 tools/config-spec.tsv 判定必要或選擇。規格表是必要性的唯一判準，掃描只負責抓出漏登錄的變數。
Who: 體檢與修復流程，搭配 jsc-cli:setup 收尾。

feat(setup): 新增引導與自動設定技能 e655f9a963

What: 新增 jsc-cli:setup，讀 doctor 的待修清單逐項確認後修復，並新增 tools/apply-config.sh 負責實際寫入。
Why: 體檢找得出問題，修還是得靠人一個一個查文件。修法又分三種：算得出來的、要人給值的、只能手動的，混在一起講不清楚。
How: 依規格表的 fix 欄分流，auto 直接寫、ask 先用決策樹問到值、manual 印步驟。複合修復交回原主（deploy、hooks-install、models）。apply-config.sh 只動 rc 檔的 # jsc-config 標記段落，寫前備份到 $JSC_HOME/backup/config/，寫後重讀驗證，fish 自動改用 set -gx 語法。
Who: 體檢與修復流程，接在 jsc-cli:doctor 之後。

jiantw83 added a new dependency 2026-08-26 02:46:54 +00:00

plugins/hooks#21 - feat/hooks-wire-cli-status

jiantw83 added a new dependency 2026-08-26 02:46:54 +00:00

plugins/gitea#20 - feat/gitea-check-report-wiki-types

admin merged commit 9067c643b2 into develop

2026-08-26 02:51:23 +00:00

admin deleted branch feat/cli-doctor-and-setup-skills

2026-08-26 02:51:23 +00:00

jiantw83 referenced this pull request

2026-08-26 02:57:48 +00:00

release: develop 併入 master（doctor、setup） #14

Sign in to join this conversation.