釋出部署技能的路徑修正與體檢目錄頁改版至 master，版本 0.2.8 升到 0.3.2 #60

2026-09-03T03:01:48Z

jiantw83 commented

2026-09-03 03:01:48 +00:00

摘要

需求描述：把 develop 累積的變更釋出到 master。部署工具的 git clone 沒有指定分支，抓的是預設分支 master，所以變更沒進 master 就等於沒有到任何一台機器。版本 0.2.8 升到 0.3.2。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

deploy 的腳本呼叫改成字面絕對路徑、開頭解一次根目錄；另含先前累積的體檢目錄頁改條列式版面、收尾寫 skill-end 事件、連結格式統一。

設計重點

這是釋出用的 PR，內容全部來自已經審過並合併進 develop 的變更，這裡不新增任何程式碼。
釋出的動機是路徑修正那一批要生效。無人看管的排程輪次在第一支腳本就被權限層擋下，技能端的修正已經進 develop，但部署抓 master，不釋出就到不了機器。

測試結果

各存放庫的檢查在合併進 develop 前都跑過並回結束碼 0：check-behaviors.sh、ste100-lint.sh、lint-frontmatter.sh、lint-scripts.sh。
端到端的無人看管巡檢回歸尚未實測。要等這批釋出並部署到機器之後才驗得出來，因為目前機器上還缺 link-check.sh 與 report-status.sh 兩支腳本。

前置 Push Request

無

## 摘要 - 需求描述：把 `develop` 累積的變更釋出到 `master`。部署工具的 `git clone` 沒有指定分支，抓的是預設分支 `master`，所以變更沒進 `master` 就等於沒有到任何一台機器。版本 0.2.8 升到 0.3.2。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 deploy 的腳本呼叫改成字面絕對路徑、開頭解一次根目錄；另含先前累積的體檢目錄頁改條列式版面、收尾寫 `skill-end` 事件、連結格式統一。 ## 設計重點 - 這是釋出用的 PR，內容全部來自已經審過並合併進 `develop` 的變更，這裡不新增任何程式碼。 - 釋出的動機是路徑修正那一批要生效。無人看管的排程輪次在第一支腳本就被權限層擋下，技能端的修正已經進 `develop`，但部署抓 `master`，不釋出就到不了機器。 ## 測試結果 - 各存放庫的檢查在合併進 `develop` 前都跑過並回結束碼 0：`check-behaviors.sh`、`ste100-lint.sh`、`lint-frontmatter.sh`、`lint-scripts.sh`。 - 端到端的無人看管巡檢回歸尚未實測。要等這批釋出並部署到機器之後才驗得出來，因為目前機器上還缺 `link-check.sh` 與 `report-status.sh` 兩支腳本。 ## 前置 Push Request - 無

jiantw83 added 12 commits 2026-09-03 03:01:48 +00:00

feat(link): 連結一律寫成 [文字](絕對網址)，寫入前先驗證連得到 c76daa61ca

取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上
看起來像普通文字或死連結，巡不到也修不了。

連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API，
不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把
好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁
整批判死。

chore(plugin 版本): 三份 manifest 升版至 0.2.9 9f4ed977b2

Merge pull request '連結一律寫成 [文字](絕對網址)，並在寫入前驗證連得到' (#56 ) from feat/link-verification/main into develop 936fc5cdaa

Reviewed-on: #56

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

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

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

status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜
跳過，回報失敗一律不改變技能自己的結論。

chore(plugin 版本): 三份 manifest 升版至 0.3.0 db2a2f8206

Merge pull request '收尾寫一筆 skill-end 事件，執行狀態才回報得到助理' (#57 ) from feat/status-report into develop 8444307534

Reviewed-on: #57

feat(wiki): 體檢目錄頁改條列式版面，鍵改用體檢頁頁名 d5bc40be13

What：`templates/check-contents.md` 從 markdown 表格改成一台執行環境一個 H2 區塊，H2 標題就是那一台的體檢頁頁名 `CHECK_{HASH}`，原本的七個欄位改成標題底下一層 `- {欄位名}：{值}` 的條列，頁上不留任何表格。`skills/doctor/SKILL.md` 與 `skills/setup/SKILL.md` 對目錄頁的呼叫從 `wiki-contents.sh upsert CHECK 4 "{HASH}"` 改成 `upsert CHECK 1 "CHECK_{HASH}"`，`references/behaviors.md` 的關鍵步驟、完成條件與可驗證跡象，以及 `README.md` 的兩段技能敘述都跟著對齊。

Why：一列七格的表格，欄位一多就要橫向捲動，讀的人得先數欄位再對照表頭才知道哪一格是什麼；一筆一個 H2 區塊、每一條自己帶欄位名，掃過去就讀得懂。版面換成區塊之後鍵也得跟著換：表格時代的鍵是第 4 欄的裸 `HASH`，區塊沒有欄位可指，唯一能當鍵的是 H2 標題。key-col 與 key 沿用舊值會讓腳本比對不中，同一台機器每體檢一次就在頁尾多附一個區塊，舊區塊從此再也更新不到，而頁面看起來完全正常，錯得無聲無息。頁名只由 `{短主機名}/{登入帳號}` 決定，`GITEA_HOST` 換掉、`JSC_WIKI_REPO_CHECK` 搬到別的存取庫、Gitea 對頁名的編碼有差都動不到它，拿它當鍵比拿任何含網址的值都穩。

How：範本頁首的寫入語意從「一列」改寫成「一個區塊」，並補上四個參數的說明。第三個參數 `<key>` 收 H2 標題文字，也就是 `CHECK_{HASH}`；第四個參數收的是區塊檔而不是列檔，內容為 `## CHECK_{HASH}` 那一行、一個空行，再照範本的欄位順序每欄一條條列，`HASH` 那一欄照樣要寫，標題是鍵不代表欄位可以省，否則下一個讀的人讀不到。第二個參數 `1` 定位成 `<key-col>`，只在頁面還留著舊表格、需要自動轉檔時才用得到，指舊表格裡持有 `[CHECK_{HASH}](網址)` 的第 1 欄，轉檔時取那一格的文字當 H2 標題，頁面已經是條列格式就忽略它。「體檢頁」那一條維持 `[{文字}]({絕對網址})` 的人用連結寫法，H2 標題本身不放連結也不放網址。兩支技能的結束碼分流一併校正：`wiki-contents.sh` 的結束碼 1 從「寫入失敗」改寫成「組不出頁面內容或寫入失敗」，頁上找不到本機那一個區塊不算這一碼，腳本會改成附加。實際的轉檔與 upsert 邏輯都在 `jsc-gitea/tools/wiki-contents.sh`，這個存取庫只改敘述與範本。

Who：屬於「wiki 目錄頁改條列式呈現」這個需求落在 jsc-cli 的部分，也就是 `CHECK_CONTENTS` 這一型目錄頁的去表格化。內容頁維持圖表優先，不在這一輪範圍。

chore(plugin 版本): 三份 manifest 升版至 0.3.1 4479a090a6

What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 三份 manifest 的 `version` 從 `0.3.0` 升到 `0.3.1`，三份一起改、值保持一致，其餘欄位一個字都不動。

Why：版本號是 `jsc-hooks/hooks/version-guard.sh` 判斷機器上的 plugin 落後與否的唯一依據。目錄頁的版面與鍵已經換過，版本號不動的話 version-guard 會把機器上的舊版當成最新版，`jsc-cli:doctor` 不會把它列進待修項目，那台機器就繼續留著以裸 `HASH` 當鍵的舊敘述，寫出來的目錄頁跟新範本對不上。三份分別給不同 CLI 讀，只升其中一份會讓同一支 plugin 在不同 CLI 上報出不同版本，落後判斷跟著失準。

How：只改 `version` 這一個鍵，走修訂號一階。這一輪是既有頁面型別的呈現方式調整，沒有新增技能，也沒有改動任何腳本的呼叫介面，不到次版本號的幅度。三份的值刻意保持一致，version-guard 才比得出單一結論。

Who：屬於「wiki 目錄頁改條列式呈現」這個需求的發版收尾，與同一輪的敘述與範本改動配成一套。獨立成一個 commit 的理由是型別不同：這一組是 chore 而非 feat，改動的檔案與敘述那一組完全不重疊，版號要重切或回退時也不必動到行為契約。

Merge pull request '體檢目錄頁改成大標題加條列，doctor 與 setup 的呼叫同步換鍵' (#58 ) from feat/contents-list/main into develop 9d0e1ea3dd

Reviewed-on: #58

fix(deploy): 腳本呼叫改成字面絕對路徑，開頭先解一次根目錄 b41ceb00d9

技能文件新增路徑守則一節，寫明這支技能的每一次腳本呼叫都要是字面絕對路徑，不留未展開的變數，也不留波浪號。

新增 Step 0：開頭跑一次 readlink -f "$JSC_HOME/current" 解出根目錄，整輪只解這一次，之後每一處都把代稱換成那個目錄。解出來的路徑要用 [ -d ] 查過存在才算數——JSC_HOME 沒設時那道指令會印出 /current、結束碼 0，非空又是絕對路徑，只看前三項會直接放行，而那個目錄並不存在。文件同時明講解到 current 這一層就停，不要再往下解一層，因為再解就落到帶版本號的快取路徑，而那種路徑放不進允許清單。

四處跨外掛呼叫改成字面路徑寫法。其中三處原本寫成相對路徑，那才是模型自己補成帶變數路徑的源頭。技能自己的四支腳本另外處理：jsc-cli 不在 current 底下，那裡只有另外三個外掛，所以改用 CLI 載入技能時講明的外掛基底目錄，原樣照抄、不跑指令。

無人看管的輪次在第一支腳本就被權限層擋下，整輪一個外掛都沒部署。2026-09-02 到 09-03 用非互動模式比照排程環境實測多種寫法：權限層拿未展開的字面字串做靜態比對，帶變數或波浪號的路徑對不上任何允許規則，只有允許清單上的完整字面指令跑得動，連 readlink、ls 這種讀取指令都要各自有規則。放寬允許清單解不掉，因為規則本身也是靜態比對，而且路徑中段的萬用字元不匹配。

deploy 是人在現場跑的技能，開頭那一次核准詢問有人可以按，所以保留自己解路徑的做法。守則另外寫下一句擋回頭路：為了看起來整齊而把字面路徑改回帶變數的寫法，等於再一次弄壞每一個無人看管的輪次。

行為說明表的 deploy 四列同步改寫，觸發時機沒動。

影響排程觸發的無人看管輪次，它們現在才跑得完第一支腳本。現場執行部署的操作者只多出開頭那一次核准詢問。

chore(plugin): 三份 manifest 升版至 0.3.2 bd23690aa5

三份外掛 manifest 的版本欄從 0.3.1 升到 0.3.2，內容由同步腳本產生，其餘欄位未動。

deploy 技能的路徑守則與 Step 0 已經改完，版號要跟著動，版本守衛才判定得出這台機器落後，更新輪次才會把新的技能內容拉下來。

交給 manifest 同步腳本一次寫三份，避免三份手改而版號不一致。

影響每一台裝了這組技能的機器：版本比對與部署更新都讀這個欄位。

Merge pull request 'deploy 的腳本呼叫全改成字面絕對路徑，開頭解一次根目錄，無人看管的輪次不再停在第一支腳本' (#59 ) from fix/literal-absolute-paths-for-deploy into develop 253443e94e

Reviewed-on: #59

admin approved these changes 2026-09-03 03:17:18 +00:00

admin merged commit 4e0d56fbc3 into master

2026-09-03 03:17:21 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/cli#60