docs(deploy): 同步相依檢查改為照樣更新的行為

What:SKILL.md 第 4 步改寫成四種結束碼的處置,第 7 步的回報清單補上 warn 行。README 的 check-requires.sh 表格列與 deploy 技能段落改寫成同一套說法。

Why:文件還寫著版本不符就跳過該 domain。操作者依文件預期那個 domain 不會動,實際上它已經更新,回報也對不上腳本印出來的行。

How:SKILL.md 逐一寫出 0、1、4、2 或其他四種結束碼各自的處置與理由,完成條件改成 skip 要有檢查腳本出錯或本地樹的原因、warn 要指名還缺哪一版。README 兩處改寫成同樣的四種分流,並寫明真正的阻擋在 version-guard.sh。

Who:相依版本不符的處置。
This commit is contained in:
2026-08-31 13:35:42 +08:00
parent ed4092bb3d
commit 5f1c4cc6d7
2 changed files with 5 additions and 5 deletions
+3 -3
View File
@@ -61,9 +61,9 @@ Nothing passed in → run every step as written below.
| 2 | Usage error — the mode, the CLI name or the domain list is wrong. Report it as a defect in this skill, and do not retry with a guessed argument |
| other | Record that CLI as failed with the exit code and stderr |
On update, `tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. A missing or too-old required jsc plugin prints a `skip` line and leaves that domain untouched. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.
On update, `tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. Exit 0 updates the domain as usual. Exit 1 — a missing or too-old required jsc plugin — prints a `warn` line and the domain **is still updated**: skipping it would leave a behind domain permanently unable to reach the version its dependency needs. The block lives one layer up, at skill invocation time, where `jsc-hooks/hooks/version-guard.sh` stops that domain's skills. Exit 4 — the manifest is unreadable, is not valid JSON, or python3 is missing — prints a `note` line and also still updates the domain: no verdict is not the same fact as behind, so it gets its own line rather than a `warn` that would send the operator hunting for a version problem that is not there. Exit 2 or any other code — a `check-requires.sh` usage error or a broken script — prints a `skip` line and leaves that domain untouched, because a checker that failed outright is not a pass. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.
Done when every detected CLI has reported an exit code and a `result` line, and every skipped domain has a dependency reason or a local-tree reason.
Done when every detected CLI has reported an exit code and a `result` line, every skipped domain has a checker-failure reason or a local-tree reason, and every `warn` domain is named with the version it still has to catch up to.
5. After install or update, call `jsc-hooks:hooks-install` and **hand it the CLI list from step 1.1**, so it does not probe the same five executables a second time. `hooks-install` still detects for itself when it receives no list — that fallback is what keeps it usable on its own.
@@ -82,7 +82,7 @@ Nothing passed in → run every step as written below.
Done when both `wrote` lines are printed, or the failure is reported with the exit code and the paths involved.
7. Report the run and close it, in one block. The result and any failure reason for every CLI × mode, plus every `skip` line, every Codex `compat` line, and every CLI that could not be version-checked in step 2.
7. Report the run and close it, in one block. The result and any failure reason for every CLI × mode, plus every `skip` line, every `warn` line, every Codex `compat` line, and every CLI that could not be version-checked in step 2.
For install or update, the same block ends with the restart instruction, in these words: 「請關閉目前的工作階段並重新啟動,新的技能內容才會載入」. `deploy.sh` recorded this round in `$JSC_HOME/restart-required.d/{cli}` — one file per CLI — and prints its path on a `restart` line; `jsc-hooks` reads only that CLI's own file and keeps reminding until that CLI restarts, with `JSC_RESTART_GATE=off` as the escape hatch. Restarting one CLI clears its own file and leaves the others' gates standing. Name the two guide paths from step 6 in that same closing block, so the operator knows where this machine's update and removal commands now live.