locivan3win/luu-media

儲存媒體

知識與連結儲存在倉庫中，Cloudinary 則保存大型檔案。每次儲存都會產生一個可開啟的連結，並在 kho-media.md 中加入一筆記錄。

優先順序： 使用者在當前 session 中的指示優先，其次是倉庫的規則檔案，最後是此技能本身。

初次設定（僅在倉庫尚無 kho-media.md 時執行）

1. 詢問使用者是否已有 Cloudinary 帳號。若無，請引導其前往 cloudinary.com 註冊免費方案，並開啟 API Keys 區塊以檢視 Cloud name、API Key、API Secret。

2. 認證資訊儲存在倉庫根目錄的 .env 檔案中。若倉庫尚無 .env，則建立一個包含以下三行的檔案；若已有則僅補上缺少的行，不更動其他行。若機器上已有其他檔案包含這三組認證且使用者想使用該檔案，則將路徑指向該檔案以取代 .env。

   CLOUDINARY_CLOUD_NAME=
   CLOUDINARY_API_KEY=
   CLOUDINARY_API_SECRET=
   

3. 若倉庫使用 Git，請執行 git check-ignore -q .env。若未被忽略，請將 .env 加入 .gitignore 後再繼續。若 .env 已曾被 Git 記錄，則停止並告知使用者。

4. 為使用者開啟 .env：Windows 使用 notepad .env，Mac 使用 open -e .env。請使用者 自行將認證值貼入等號後方，勿添加空格或引號，完成後儲存，切勿貼入對話框。API Secret 如同鑰匙，任何人擁有它都可刪除或修改所有圖片。

5. 使用者回報完成後，檢查三行是否已填入值，僅檢查有無內容，不輸出值。

6. 根據本文末的範本建立 kho-media.md，僅記錄檔案名稱（不含認證值）。並在 index.md 中新增一行。

7. 請使用者提供一張測試圖片，執行以下流程並提供連結。確認可開啟後即完成。

儲存流程

1. 是否需要上雲端

若不明確，詢問圖片的用途。

• 需要公開連結（用於貼文、電子郵件、機器人、文件、其他平台上的網站）：繼續流程。
• 網站已有自己的圖片目錄，且正在從該處載入圖片： 不上傳，以免產生兩個不一致的版本。建議將圖片複製到網站的圖片目錄並取一個乾淨的名稱；使用者同意後再執行複製。在此停止。
• 草稿、測試版、暫存螢幕截圖： 留在本機，並說明原因。若有疑慮則詢問：「您會將此用於何處？」

2. 是否重複

在 kho-media.md 中搜尋檔名與用途。若已存在，則提供舊連結，並詢問使用者是否要上傳新版本。若使用者僅是查詢連結，則直接從此處回應並停止。

3. 是否洩漏個資

公開連結一旦散佈，擁有連結者皆可檢視，且難以完全收回。檢查圖片內容。若包含人臉或客戶姓名、兒童、電話號碼、帳號、證件、私人訊息，則明確指出所見內容，並詢問使用者是否確定要上傳。

4. 分類與命名

資料夾	內容	連結寫入位置
kho-media/thuong-hieu	Logo、肖像、封面照、識別元素	品牌頁面或個人檔案
kho-media/san-pham/<ten-san-pham>	產品圖片、Mockup、介紹影片	該產品頁面
kho-media/noi-dung/<yyyy-MM>	貼文圖片、Banner、縮圖、短影片	內容計劃頁面
kho-media/bang-chung	客戶回饋、前後對比、認證、媒體報導	相關產品頁面
kho-media/su-kien/<ten-su-kien>	活動、課程的圖片、影片	該活動頁面

檔名與資料夾名稱：無重音符號、小寫、以 - 連接、一看即懂，例如 feedback-khach-lan-a。若不確定應歸入哪個資料夾，則提供一個包含兩個選項的簡短問題讓使用者選擇。若有多個檔案，則以表格一次列出檔名與對應資料夾，逐一確認後依序上傳；若某檔案上傳失敗，則記錄錯誤後繼續處理其他檔案。

5. 上傳

從 kho-media.md 取得認證檔案名稱，使用完整路徑。若該認證檔案位於 Git 倉庫中，請先執行 git check-ignore -q <檔案路徑>：若未被忽略則停止並告知使用者。根據作業系統複製正確的指令，僅替換開頭的四個值。請勿將認證輸出到螢幕、回覆內容、頁面或其他檔案。指令會自動將檔案複製到一個無重音符號的暫存檔名，因為含有重音符號或空格的路徑容易導致上傳指令失敗。

Windows (PowerShell)：

$tep='<duong-dan-file>'; $ngan='<ngan>'; $ten='<ten-khong-duoi>'; $fileMa='<duong-dan-file-ma>'
$m=@{}; Get-Content -LiteralPath $fileMa | ForEach-Object { if($_ -match '^\s*(?:CLOUDINARY_)?(CLOUD_NAME|API_KEY|API_SECRET)\s*=\s*(.+?)\s*$'){ $m[$Matches[1]]=$Matches[2] } }
$ts=[DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
$bam=[Security.Cryptography.SHA1]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes("folder=$ngan&overwrite=false&public_id=$ten&timestamp=$ts$($m.API_SECRET)"))
$ky=-join($bam | ForEach-Object { $_.ToString('x2') })
$tenTam="luu-media-$ts"+[IO.Path]::GetExtension($tep); Copy-Item -LiteralPath $tep -Destination (Join-Path $env:TEMP $tenTam)
Push-Location $env:TEMP
try { curl.exe -sS -X POST "https://api.cloudinary.com/v1_1/$($m.CLOUD_NAME)/auto/upload" -F "file=@$tenTam" -F "api_key=$($m.API_KEY)" -F "timestamp=$ts" -F "folder=$ngan" -F "overwrite=false" -F "public_id=$ten" -F "signature=$ky" }
finally { Remove-Item -LiteralPath $tenTam -ErrorAction SilentlyContinue; Pop-Location }

Mac, Linux (bash)：

TEP='<duong-dan-file>'; NGAN='<ngan>'; TEN='<ten-khong-duoi>'; FILE_MA='<duong-dan-file-ma>'
lay() { sed -n -E "s/^[[:space:]]*(CLOUDINARY_)?$1[[:space:]]*=[[:space:]]*//p" "$FILE_MA" | tr -d '\r' | sed -E 's/[[:space:]]+$//' | head -n 1; }
TS=$(date +%s)
KY=$(printf '%s' "folder=$NGAN&overwrite=false&public_id=$TEN&timestamp=$TS$(lay API_SECRET)" | { if command -v shasum >/dev/null; then shasum -a 1; else sha1sum; fi; } | cut -d' ' -f1)
curl -sS -X POST "https://api.cloudinary.com/v1_1/$(lay CLOUD_NAME)/auto/upload" -F "file=@$TEP" -F "api_key=$(lay API_KEY)" -F "timestamp=$TS" -F "folder=$NGAN" -F "overwrite=false" -F "public_id=$TEN" -F "signature=$KY"

回傳結果為 JSON 格式：取出 secure_url。若出現 error 則報告完整錯誤訊息並停止，不自行重寫公式。若檔案超出目前方案大小限制，則告知使用者壓縮後再試。指令使用 overwrite=false 以避免覆蓋同名檔案：若副檔名或回傳內容與剛上傳的檔案不同，則重新命名後再次上傳。

6. 檢查並寫入腦中

1. 測試開啟連結，確認可成功回傳。
2. 在 kho-media.md 中新增一行，時間取自系統。
3. 根據資料夾表格的最後一欄，將連結加入相關頁面的 Media 部分。若該頁面尚不存在，則僅記錄於 kho-media.md 並告知。

7. 回報

提供連結、資料夾、已記錄的兩個頁面。若圖片用於網站或文章，則另外提供加快載入的版本：在 /upload/ 後立即插入 f_auto,q_auto,w_1200/。Cloudinary 會自動選擇格式、品質，並將寬度縮為 1200 px。

禁止事項

• 禁止刪除或修改 Cloudinary 上的檔案。使用者應自行在 Media Library 中操作，或提出特定需求並確認後執行。
• 禁止將圖片、影片檔案放入 Git 倉庫。
• 認證值僅存在於已宣告的認證檔案中。請勿寫入頁面、日誌、技能或對話框。在與他人分享倉庫目錄前，提醒使用者移除 .env 檔案。

kho-media.md 範本

# 媒體庫 - 目錄

雲端服務：Cloudinary。認證檔案：倉庫根目錄的 `.env`，不上傳至 GitHub。

| 日期時間 | 檔案名稱 | 資料夾 | 連結 | 用途 |
|---|---|---|---|---|