From 762c28c52244dc7b26975ae702babba9bbc0f74d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 15:46:47 +0000 Subject: [PATCH] =?UTF-8?q?=E9=9B=B2=E7=AB=AF=20setup=EF=BC=9Agit=20?= =?UTF-8?q?=E8=AA=8D=E8=AD=89=E6=94=B9=E7=94=A8=E8=AE=80=E7=92=B0=E5=A2=83?= =?UTF-8?q?=E8=AE=8A=E6=95=B8=E7=9A=84=20credential=20helper=EF=BC=8C?= =?UTF-8?q?=E4=B8=A6=E8=AE=93=E9=A9=97=E8=AD=89=E6=9C=89=E8=83=BD=E5=8A=9B?= =?UTF-8?q?=E8=AE=8A=E7=B4=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 雲端實測（真的雲端 session，不是本機模擬）： - session 是 root/HOME=/root，setup 階段寫進 $HOME 的三個機制一個都沒到 （沒有 insteadOf、沒有 ~/.git-credentials、沒有 /etc/gitconfig） - 薄殼 settings.json 的 extraKnownMarketplaces + enabledPlugins 宣告了也沒用： Claude Code 是裸 URL clone marketplace，沒有 credential helper 就靜默失敗 → 'No marketplaces configured' 改法： - credential helper 當場讀 GITEA_TOKEN_CLAUDE_CODE，磁碟不落明文（token 輪替不用重拍快照） - 寫進所有 session 可能讀到的 gitconfig，並印出實際寫進哪幾份 - 驗證先跑裸探針（GIT_CONFIG_GLOBAL/SYSTEM=/dev/null），它必須紅；紅不了就說明綠燈不算數 - 加驗 plugin 本身（只驗 marketplace 會漏掉「marketplace 有、plugin 沒有」） 在雲端容器內實跑過：裸環境正確失敗 → 補 helper 後 marketplace 就位、 isep@inkstone 0.3.1 installed/enabled，腳本 exit 0。 --- docs/cloud-session-bootstrap.md | 45 +++++++++++++ docs/cloud-setup-script.sh | 112 ++++++++++++++++++++++++-------- 2 files changed, 129 insertions(+), 28 deletions(-) diff --git a/docs/cloud-session-bootstrap.md b/docs/cloud-session-bootstrap.md index 5ca9858..fc0e6da 100644 --- a/docs/cloud-session-bootstrap.md +++ b/docs/cloud-session-bootstrap.md @@ -52,6 +52,51 @@ git config --global url."https://x-access-token:${GITEA_TOKEN_CLAUDE_CODE}@git.u 完整腳本：`docs/cloud-setup-script.sh`（貼進 code-on-web 的 Setup script 欄位用）。 +### 🔴 2026-08-20 雲端實測訂正：上面那條 `url.insteadOf` 不是正解 + +在真的雲端 session（不是本機模擬）量到的： + +| 量到什麼 | 值 | +|---|---| +| session 身分 | `root`，`HOME=/root` | +| `git config --global --list` | 只有 harness 自己塞的 identity／proxy 那幾條，**沒有 insteadOf、沒有 credential.helper** | +| `~/.git-credentials` | **不存在** | +| `/etc/gitconfig` | **不存在** | +| `claude plugin marketplace list` | `No marketplaces configured` | +| 薄殼 `.claude/settings.json` | `extraKnownMarketplaces` ＋ `enabledPlugins` **都宣告了** | + +⇒ 兩個結論： + +1. **setup 階段寫進 `$HOME` 的東西沒有到 session 手上。** + 舊版三個機制（insteadOf／`~/.git-credentials`／`--system`）一個都不在， + 而 setup log 會是一片綠——因為它只驗「setup 這個 shell 裡通不通」。 +2. **光在薄殼 settings.json 宣告 `extraKnownMarketplaces` 沒有用。** + Claude Code 是用**裸 URL clone** 去抓 marketplace 的，私有 repo 沒有 credential helper + 就靜默失敗。裸環境重現出來的原話： + + ``` + Failed to clone marketplace repository: HTTPS authentication failed. + Please ensure your git credential helper has valid credentials for git.uncle6.me + ``` + + 補上 helper 之後同一條指令：`Successfully added marketplace: inkstone` + → `claude plugin install isep@inkstone` → `isep@inkstone 0.3.1 · enabled`。 + **紅過也綠過，不是只看到綠。** + +⇒ 改法（已落在 `docs/cloud-setup-script.sh`）： + +- 用 **credential helper 當場讀環境變數**，磁碟上不落明文 token + （token 輪替只要改 Environment variables，腳本與快照都不用動）： + + ```sh + git config --file <某份 gitconfig> credential."https://git.uncle6.me".helper \ + '!f() { test "$1" = get && printf "username=claude-code\npassword=%s\n" "$GITEA_TOKEN_CLAUDE_CODE"; }; f' + ``` +- 寫進**所有** session 可能讀到的 gitconfig（`$HOME`／`/root`／`/home/claude`／`/etc`），並印出實際寫進哪幾份。 +- 驗證要**先讓它失敗一次**：用 `GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null` 跑裸探針， + 它必須紅；紅不了代表環境裡另有憑證捷徑，後面的綠燈就不能當證據。 + + ## 已驗（本機，隔離環境，不影響本機正在跑的任何 session） 🔴 **怎麼保證沒有干擾**：全程把 `$HOME` 指到 scratchpad 底下的隔離目錄 diff --git a/docs/cloud-setup-script.sh b/docs/cloud-setup-script.sh index fa3a602..dccc24c 100644 --- a/docs/cloud-setup-script.sh +++ b/docs/cloud-setup-script.sh @@ -8,11 +8,11 @@ # 不要新造一把。值本身不寫在這支腳本或任何檔案裡。 # # 這支腳本做兩件事： -# 1. 設定 git URL 重寫，讓任何對 git.uncle6.me 的 clone 都能用 GITEA_TOKEN_CLAUDE_CODE 認證 -# （官方文件對「CI/CD 裝私有 marketplace」建議的寫法，見 references 段）。 -# 2. 直接把 ISEP 裝成 user-scope plugin ——不是「複製一份」，是跟本機一樣走 -# `claude plugin marketplace add` + `claude plugin install`，裝的東西 -# 100% 來自 inkstone/ISEP 這個 repo 本身，沒有第二份內容。 +# 1. 讓 session 裡任何對 git.uncle6.me 的 clone 都認得出憑證 +# —— Claude Code 拉 marketplace 是用**裸 URL clone**，走的就是 git credential helper +# （2026-08-20 雲端實測的原始錯誤訊息：「HTTPS authentication failed. Please ensure +# your git credential helper has valid credentials for git.uncle6.me」）。 +# 2. 把 ISEP 裝成 user-scope plugin —— 裝的東西 100% 來自 inkstone/ISEP 本身，沒有第二份內容。 # # 何時跑：只在「這個 Cloud environment 第一次開 session」時跑一次， # 跑完 Anthropic 會把整個檔案系統拍成快照，之後的 session 直接沿用快照 @@ -27,46 +27,102 @@ if [ -z "${GITEA_TOKEN_CLAUDE_CODE:-}" ]; then exit 1 fi -# ── git 認證：三個機制都設，因為它們失效的方式不同 ──────────────── -# ① URL 重寫（global） ② 憑證存檔（global） ③ 系統層（HOME 無關，best effort） -# 2026-08-20 雲端實測：session 裡 git 是「匿名」的 ⇒ setup 設的東西沒生效到 session。 -# 原因未定（沒跑到／HOME 不同／快照沒帶），所以三條都設，並在下面自我驗證。 -git config --global url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \ - "https://git.uncle6.me/" -git config --global credential.helper store -printf 'https://claude-code:%s@git.uncle6.me\n' "$GITEA_TOKEN_CLAUDE_CODE" > "$HOME/.git-credentials" -chmod 600 "$HOME/.git-credentials" -git config --system url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \ - "https://git.uncle6.me/" 2>/dev/null || echo "（system 層設不了，只靠 global——非致命）" +# ── git 認證 ──────────────────────────────────────────────────────────── +# +# 🔴 舊版（2026-08-20 之前）在這裡踩了兩個坑，兩個都是「不出聲的」： +# +# ① 把 token 明文寫進 `~/.git-credentials`。 +# —— 換 token 那天起這份就是壞的，而且壞法是「認證失敗」不是「檔案不見」，很難聯想。 +# 改法：credential helper **當場讀環境變數**，磁碟上不落任何明文。 +# （token 輪替時只要改 Environment variables，這支腳本不用動、快照也不用重拍。） +# +# ② 只寫 `$HOME`。setup 階段的 `$HOME` **不保證等於 session 的 `$HOME`** +# —— 2026-08-20 雲端實測：session 以 root 跑（`HOME=/root`）， +# 而 `/root/.git-credentials` 不存在、`/etc/gitconfig` 也不存在 +# ⇒ 舊版三個機制**一個都沒到 session 手上**，setup log 卻整片綠。 +# 改法：把同一段 helper 寫進所有「session 可能會讀」的 gitconfig，並印出實際寫進哪幾份。 +# +# helper 內容不含 token，只含「去讀 $GITEA_TOKEN_CLAUDE_CODE」這個動作。 +HELPER='!f() { test "$1" = get && printf "username=claude-code\npassword=%s\n" "$GITEA_TOKEN_CLAUDE_CODE"; }; f' -# ── 🔴 自我驗證一：認證真的通了嗎 ────────────────────────── -# 這一步是 2026-08-20 事故的直接產物：舊版設完就結束，token 沒生效也不出聲， -# 於是雲端 session 開起來才發現 marketplace 拉不下來，而 setup log 一片綠。 +echo "── 寫 git credential helper（不落地明文 token）──" +wrote=0 +seen="" +for cfg in "${HOME:-/root}/.gitconfig" /root/.gitconfig /home/claude/.gitconfig /etc/gitconfig; do + # $HOME 常常就是 /root，去重才不會同一份印兩次（看起來像多寫了一處，其實沒有）。 + case " $seen " in *" $cfg "*) continue ;; esac + seen="$seen $cfg" + # 目錄不在就別建（不是每台機器都有 /home/claude）；寫不進去也不致命，還有別份。 + [ -d "$(dirname "$cfg")" ] || { echo " ．跳過 $cfg（目錄不存在）"; continue; } + if git config --file "$cfg" credential."https://git.uncle6.me".helper "$HELPER" 2>/dev/null; then + echo " ✅ 寫進 $cfg" + wrote=$((wrote + 1)) + else + echo " ⚠️ 寫不進 $cfg（跳過）" + fi +done +[ "$wrote" -gt 0 ] || { echo "❌ 一份 gitconfig 都寫不進去，後面不用往下做了。" >&2; exit 1; } + +# ── 🔴 自我驗證一：這個測試有沒有能力變紅 ──────────────────────────── +# 先在「什麼設定都不讀」的條件下跑一次，**它必須失敗**。 +# 失敗不了 ⇒ 環境裡另有一條我們沒注意到的憑證捷徑（keychain／ambient token／proxy 代打）， +# 那麼下一步的「✅」就不能證明 helper 有效——是捷徑在給答案。 +# （2026-08-20 同一天在這個形狀上連摔三次，見 InkStoneCo mistakes.md「隔離環境沒有隔離系統層」。） echo "── 驗證 git 認證 ──" +if GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null GIT_TERMINAL_PROMPT=0 \ + git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then + echo "⚠️ 裸環境竟然也拉得到 —— 這個環境有別的憑證來源，下面的綠燈不能當成 helper 生效的證據。" >&2 +else + echo " ✅ 裸環境正確地失敗了（這個測試有能力變紅）" +fi + +# ── 🔴 自我驗證二：認證真的通了嗎 ──────────────────────────────────── if GIT_TERMINAL_PROMPT=0 git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then - echo "✅ git 認證通：拉得到 inkstone/ISEP" + echo " ✅ git 認證通：拉得到 inkstone/ISEP" else echo "❌ git 認證不通——marketplace 一定裝不起來，後面不用往下做了。" >&2 echo " 檢查：GITEA_TOKEN_CLAUDE_CODE 的值對不對、那把 token 有沒有被撤銷。" >&2 exit 1 fi -# ── 安裝（user scope 只是備援）───────────────────────────── +# ── 安裝 ──────────────────────────────────────────────────────────────── # 🔴 官方文件（cloud-environments 的 what-carries-over 表）明文： # 「Plugins enabled only in your user settings」→ **不會**帶到雲端 session。 -# 真正生效的是薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces。 -# 這兩行留著當本地備援，不是主要路徑——不要以為裝完就等於雲端有了。 +# 薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces 才是主要路徑。 +# 但 2026-08-20 雲端實測證明：**那兩個 key 宣告了也沒用，如果 git 認證不在。** +# Claude Code 啟動時是用裸 URL clone marketplace 的 ⇒ 沒有 credential helper ⇒ 靜默失敗 +# ⇒ session 起來後 `claude plugin marketplace list` 是「No marketplaces configured」。 +# ⇒ **上面那段 credential helper 才是主要路徑；下面兩行是備援。** +echo "── 安裝 marketplace / plugin ──" claude plugin marketplace add https://git.uncle6.me/inkstone/ISEP.git --scope user 2>/dev/null || true claude plugin install isep@inkstone --scope user 2>/dev/null || true -# ── 🔴 自我驗證二：marketplace 真的拉下來了嗎 ──────────────── -echo "── 驗證 marketplace ──" +# ── 🔴 自我驗證三：marketplace 與 plugin 都真的就位了嗎 ────────────── +# 只驗 marketplace 不夠：marketplace 列得出來、plugin 沒裝起來， +# session 啟動時 enabledPlugins 一樣是一張跳票的支票。 +echo "── 驗證 marketplace / plugin ──" if claude plugin marketplace list 2>/dev/null | grep -q "inkstone"; then - echo "✅ marketplace inkstone 已就位" + echo " ✅ marketplace inkstone 已就位" else echo "❌ marketplace 沒就位——session 啟動時 enabledPlugins 會是一張跳票的支票。" >&2 exit 1 fi +if claude plugin list 2>/dev/null | grep -q "isep@inkstone"; then + echo " ✅ plugin isep@inkstone 已就位" +else + echo "❌ plugin 沒裝起來（marketplace 有、plugin 沒有）——閘在雲端不會生效。" >&2 + exit 1 +fi -echo "✅ setup 完成。session 啟動後請用「有鑑別力的探針」驗閘，" -echo " 不要用 git tag（它在三支閘的白名單裡，閘死了也會過）。" +cat <<'EOF' +✅ setup 完成。 + +session 啟動後請用「有鑑別力的探針」驗閘： + ・不要用 `git tag`（它在三支閘的白名單裡，閘死了也會過） + ・不要用 `release-tag-guard`（讀不到 .claude-plugin/plugin.json 就按設計 exit 0） + ・先確認你挑的那支閘「在這個情境下的設計行為」是擋，不是放行 + +驗閘之外，也順手確認這兩件（任一為否 ⇒ 這個 session 沒有 plugin，別當成有）： + claude plugin marketplace list # 要看到 inkstone + claude plugin list # 要看到 isep@inkstone · enabled +EOF